DOCSEARCHbyAlgolia
Submit Docs

BencodeNET

repository·master·Indexed 41 days ago

https://github.com/krusen/bencodenet

A lightweight and fast .NET library for encoding and decoding the bencode format used in BitTorrent protocols and torrent files. Version 2.3.0 provides tools for parsing bencode strings and streams via BencodeParser, encoding IBObject implementations, and manipulating torrent files using a dedicated Torrent class.

Tokens
1.6K
Snippets
5
Records
6
Agent score
1%

What's inside BencodeNET

  1. Understand Torrent file modes and extra fields

    master

    When working with the Torrent object, be aware of how file data is structured and how to handle non-standard metadata:

    File Modes

    • Single-file torrents: The File property contains the file info; the Files property is null.
    • Multi-file torrents: The Files property contains a list of file info and the directory name; the File property is null.

    Non-standard fields

    Use the ExtraFields property to access or add fields that are not part of the standard torrent specification. Any data added to ExtraFields will overwrite existing data from the Torrent object when the object is encoded back to bencode.

  2. Handle string character encoding in Bencode

    master

    By default, BencodeNET uses Encoding.UTF8.

    Parsing with custom encoding

    If your bencoded data uses a different encoding (like ISO-8859-1), you must specify it when creating the BencodeParser. This ensures BString objects use the correct encoding when calling ToString().

    Rendering strings

    • BString.ToString() uses the encoding the BString was created with.
    • BString.ToString(Encoding) allows you to override the rendering encoding.
    • IBObject.EncodeAsString() uses the BString's internal encoding for contained strings, or Encoding.UTF8 if no encoding is specified.

    Warning: If you parse non-UTF8 data without specifying the encoding in the parser, ToString() and EncodeAsString() will default to UTF8, likely resulting in corrupted characters (e.g., ???).

    // Using a specific encoding for the parser
var parser = new BencodeParser(Encoding.GetEncoding("ISO-8859-1"));
var bstring = parser.Parse<BString>(bytes);

// ToString() will now use ISO-8859-1 by default
bstring.ToString(); 

// Explicitly override during rendering
bstring.ToString(Encoding.UTF8);

  3. Install BencodeNET via NuGet

    master

    You can install BencodeNET using the .NET CLI or by adding a <PackageReference> to your .csproj file.

    <!-- .csproj using PackageReference -->
<PackageReference Include="BencodeNET" Version="2.3.0" />
    # .NET CLI
> dotnet add package BencodeNET

  4. Work with Torrent files

    master

    The library provides a Torrent class to easily manipulate torrent files. You can parse a torrent from a file path or a stream, and extract metadata like the Info Hash or Magnet Link.

    using BencodeNET.Objects;
using BencodeNET.Parsing;
using BencodeNET.Torrents;

var parser = new BencodeParser();

// Parse from file or stream
Torrent torrent = parser.Parse<Torrent>("C:\\ubuntu.torrent");

// Extract metadata
string infoHash = torrent.GetInfoHash();
byte[] infoHashBytes = torrent.GetInfoHashBytes();
string magnetLink = torrent.GetMagnetLink();

// Convert to BDictionary for manual manipulation
BDictionary bdictionary = torrent.ToBDictionary();

  5. Encode bencode objects

    master

    Encoding is performed on IBObject implementations. You can encode to a string, a byte array, a file, a stream, or a PipeWriter.

    var bstring = new BString("Hello World!");

bstring.EncodeAsString();    // "12:Hello World!"
bstring.EncodeAsBytes();     // [ 49, 50, 58, 72, ... ]

bstring.EncodeTo("C:\\data.bencode"); // Writes to file
bstring.EncodeTo(stream);
await bstring.EncodeToAsync(stream);
bstring.EncodeTo(pipeWriter);
await bstring.EncodeToAsync(pipeWriter);

  6. Parse bencode strings and streams

    master

    Use BencodeParser to decode bencode data. You can parse raw strings directly or work with Stream and PipeReader objects for better performance in .NET Core applications.

    When parsing strings, you can use the generic ParseString<T>() method if you know the expected type (e.g., BString, BNumber, BList, or BDictionary).

    using BencodeNET.Parsing;
using BencodeNET.Objects;

var parser = new BencodeParser();

// Parse unknown type
IBObject bstring = parser.ParseString("12:Hellow World!");

// Parse known types using generics
BString bstring = parser.ParseString<BString>("12:Hello World!");
BNumber bnumber = parser.ParseString<BNumber>("i42e");
BList blist = parser.ParseString<BList>("l3:foo3:bari42ee");
BDictionary bdictionary = parser.ParseString<BDictionary>("d3:fooi42e5:Hello6:World!e");

// Parsing from streams or PipeReaders
BDictionary bdictionary = parser.Parse<BDictionary>(stream);
BDictionary bdictionary = await parser.ParseAsync<BDictionary>(stream);
BDictionary bdictionary = await parser.ParseAsync<BDictionary>(pipeReader);