libtorrent
Description: A feature complete BitTorrent protocol implementation as a C++ library

Version: | 2.0.8

home

Table of contents

- web_seed_entry
  - operator==()
  - operator<()
  - enum type_t
- load_torrent_limits
- torrent_info
  - torrent_info()
  - ~torrent_info()
  - orig_files() files()
  - rename_file()
  - remap_files()
  - clear_trackers() trackers() add_tracker()
  - similar_torrents() collections()
  - add_http_seed() add_url_seed() web_seeds() set_web_seeds()
  - total_size()
  - num_pieces() piece_length()
  - end_piece() last_piece() piece_range()
  - info_hashes() info_hash()
  - v2() v1()
  - num_files()
  - map_block()
  - map_file()
  - ssl_cert()
  - is_valid()
  - priv()
  - is_i2p()
  - piece_size()
  - hash_for_piece() hash_for_piece_ptr()
  - name()
  - creation_date()
  - creator()
  - comment()
  - nodes()
  - add_node()
  - parse_info_section()
  - info()
  - info_section()
  - piece_layer()
  - free_piece_layers()

[report issue]

# web_seed_entry

Declared in "libtorrent/torrent_info.hpp"

the web_seed_entry holds information about a web seed (also known as URL seed or HTTP seed). It is essentially a URL with some state associated with it. For more information, see BEP 17 and BEP 19.

    struct web_seed_entry
    {
       bool operator== (web_seed_entry const& e) const;
       bool operator< (web_seed_entry const& e) const;

       enum type_t
       {
          url_seed,
          http_seed,
       };

       std::string url;
       std::string auth;
       headers_t extra_headers;
       std::uint8_t type;
    };

[report issue]

## operator==()

    bool operator== (web_seed_entry const& e) const;

URL and type comparison

[report issue]

## operator<()

    bool operator< (web_seed_entry const& e) const;

URL and type less-than comparison

[report issue]

## enum type_t

Declared in "libtorrent/torrent_info.hpp"

name | value | description
--- | --- | ---
url_seed | 0 |
http_seed | 1 |

[report issue]

url
  The URL of the web seed

[report issue]

auth
  Optional authentication. If this is set, it's passed in as HTTP basic auth to the web seed. The format is: username:password.

[report issue]

extra_headers
  Any extra HTTP headers that need to be passed to the web seed

[report issue]

type
  The type of web seed (see type_t)

[report issue]

# load_torrent_limits

Declared in "libtorrent/torrent_info.hpp"

this object holds configuration options for limits to use when loading torrents. They are meant to prevent loading potentially malicious torrents that cause excessive memory allocations.

    struct load_torrent_limits
    {
       int max_buffer_size  = 10000000;
       int max_pieces  = 0x200000;
       int max_decode_depth  = 100;
       int max_decode_tokens  = 3000000;
    };

[report issue]

max_buffer_size
  the max size of a .torrent file to load into RAM

[report issue]

max_pieces
  the max number of pieces allowed in the torrent

[report issue]

max_decode_depth
  the max recursion depth in the bdecoded structure

[report issue]

max_decode_tokens
  the max number of bdecode tokens

[report issue]

# torrent_info

Declared in "libtorrent/torrent_info.hpp"

the torrent_info class holds the information found in a .torrent file.

    class torrent_info
    {
       explicit torrent_info (bdecode_node const& torrent_file);
       torrent_info (char const* buffer, int size);
       torrent_info (std::string const& filename, load_torrent_limits const& cfg);
       explicit torrent_info (span<char const> buffer, from_span_t);
       torrent_info (torrent_info const& t);
       torrent_info (span<char const> buffer, error_code& ec, from_span_t);
       torrent_info (std::string const& filename, error_code& ec);
       explicit torrent_info (std::string const& filename);
       explicit torrent_info (info_hash_t const& info_hash);
       torrent_info (bdecode_node const& torrent_file, error_code& ec);
       torrent_info (bdecode_node const& torrent_file, load_torrent_limits const& cfg);
       torrent_info (char const* buffer, int size, error_code& ec);
       torrent_info (span<char const> buffer, load_torrent_limits const& cfg, from_span_t);
       ~torrent_info ();
       file_storage const& files () const;
       file_storage const& orig_files () const;
       void rename_file (file_index_t index, std::string const& new_filename);
       void remap_files (file_storage const& f);
       std::vector<announce_entry> const& trackers () const;
       void add_tracker (std::string const& url, int tier = 0);
       void add_tracker (std::string const& url, int tier
          , announce_entry::tracker_source source);
       void clear_trackers ();
       std::vector<sha1_hash> similar_torrents () const;
       std::vector<std::string> collections () const;
       void add_http_seed (std::string const& url
          , std::string const& extern_auth = std::string()
          , web_seed_entry::headers_t const& extra_headers = web_seed_entry::headers_t());
       void add_url_seed (std::string const& url
          , std::string const& ext_auth = std::string()
          , web_seed_entry::headers_t const& ext_headers = web_seed_entry::headers_t());
       std::vector<web_seed_entry> const& web_seeds () const;
       void set_web_seeds (std::vector<web_seed_entry> seeds);
       std::int64_t total_size () const;
       int piece_length () const;
       int num_pieces () const;
       piece_index_t last_piece () const;
       index_range<piece_index_t> piece_range () const;
       piece_index_t end_piece () const;
       info_hash_t const& info_hashes () const;
       sha1_hash info_hash () const noexcept;
       bool v1 () const;
       bool v2 () const;
       int num_files () const;
       std::vector<file_slice> map_block (piece_index_t const piece
          , std::int64_t offset, int size) const;
       peer_request map_file (file_index_t const file, std::int64_t offset, int size) const;
       string_view ssl_cert () const;
       bool is_valid () const;
       bool priv () const;
       bool is_i2p () const;
       int piece_size (piece_index_t index) const;
       char const* hash_for_piece_ptr (piece_index_t const index) const;
       sha1_hash hash_for_piece (piece_index_t index) const;
       bool is_loaded () const;
       const std::string& name () const;
       std::time_t creation_date () const;
       const std::string& creator () const;
       const std::string& comment () const;
       std::vector<std::pair<std::string, int>> const& nodes () const;
       void add_node (std::pair<std::string, int> const& node);
       bool parse_info_section (bdecode_node const& info, error_code& ec, int max_pieces);
       bdecode_node info (char const* key) const;
       span<char const> info_section () const;
       span<char const> piece_layer (file_index_t) const;
       void free_piece_layers ();
    };

[report issue]

## torrent_info()

    explicit torrent_info (bdecode_node const& torrent_file);
    torrent_info (char const* buffer, int size);
    torrent_info (std::string const& filename, load_torrent_limits const& cfg);
    explicit torrent_info (span<char const> buffer, from_span_t);
    torrent_info (torrent_info const& t);
    torrent_info (span<char const> buffer, error_code& ec, from_span_t);
    torrent_info (std::string const& filename, error_code& ec);
    explicit torrent_info (std::string const& filename);
    explicit torrent_info (info_hash_t const& info_hash);
    torrent_info (bdecode_node const& torrent_file, error_code& ec);
    torrent_info (bdecode_node const& torrent_file, load_torrent_limits const& cfg);
    torrent_info (char const* buffer, int size, error_code& ec);
    torrent_info (span<char const> buffer, load_torrent_limits const& cfg, from_span_t);

The constructor that takes an info-hash will initialize the info-hash to the given value, but leave all other fields empty. This is used internally when downloading torrents without the metadata. The metadata will be created by libtorrent as soon as it has been downloaded from the swarm.

The constructor that takes a bdecode_node will create a torrent_info object from the information found in the given torrent_file. The bdecode_node represents a tree node in an bencoded file. To load an ordinary .torrent file into a bdecode_node, use bdecode().

The version that takes a buffer pointer and a size will decode it as a .torrent file and initialize the torrent_info object for you.

The version that takes a filename will simply load the torrent file and decode it inside the constructor, for convenience. This might not be the most suitable for applications that want to be able to report detailed errors on what might go wrong.

There is an upper limit on the size of the torrent file that will be loaded by the overload taking a filename. If it's important that even very large torrent files are loaded, use one of the other overloads.

The overloads that takes an `error_code const&` never throws if an error occur, they will simply set the error code to describe what went wrong and not fully initialize the torrent_info object. The overloads that do not take the extra error_code parameter will always throw if an error occurs. These overloads are not available when building without exception support.

The overload that takes a `span` also needs an extra parameter of type `from_span_t` to disambiguate the `std::string` overload for string literals. There is an object in the libtorrent namespace of this type called `from_span`.

[report issue]

## ~torrent_info()

    ~torrent_info ();

frees all storage associated with this torrent_info object

[report issue]

## orig_files() files()

    file_storage const& files () const;
    file_storage const& orig_files () const;

The file_storage object contains the information on how to map the pieces to files. It is separated from the torrent_info object because when creating torrents a storage object needs to be created without having a torrent file. When renaming files in a storage, the storage needs to make its own copy of the file_storage in order to make its mapping differ from the one in the torrent file.

`orig_files()` returns the original (unmodified) file storage for this torrent. This is used by the web server connection, which needs to request files with the original names. Filename may be changed using `torrent_info::rename_file()`.

For more information on the file_storage object, see the separate document on how to create torrents.

[report issue]

## rename_file()

    void rename_file (file_index_t index, std::string const& new_filename);

Renames the file with the specified index to the new name. The new filename is reflected by the `file_storage` returned by `files()` but not by the one returned by `orig_files()`.

If you want to rename the base name of the torrent (for a multi file torrent), you can copy the `file_storage` (see files() and orig_files() ), change the name, and then use remap_files().

The `new_filename` can both be a relative path, in which case the file name is relative to the `save_path` of the torrent. If the `new_filename` is an absolute path (i.e. `is_complete(new_filename) == true`), then the file is detached from the `save_path` of the torrent. In this case the file is not moved when move_storage() is invoked.

[report issue]

## remap_files()

    void remap_files (file_storage const& f);

Warning

Using remap_files() is discouraged as it's incompatible with v2 torrents. This is because the piece boundaries and piece hashes in v2 torrents are intimately tied to the file boundaries. Instead, just rename individual files, or implement a custom disk_interface to customize how to store files.

Remaps the file storage to a new file layout. This can be used to, for instance, download all data in a torrent to a single file, or to a number of fixed size sector aligned files, regardless of the number and sizes of the files in the torrent.

The new specified `file_storage` must have the exact same size as the current one.

[report issue]

## clear_trackers() trackers() add_tracker()

    std::vector<announce_entry> const& trackers () const;
    void add_tracker (std::string const& url, int tier = 0);
    void add_tracker (std::string const& url, int tier
          , announce_entry::tracker_source source);
    void clear_trackers ();

`add_tracker()` adds a tracker to the announce-list. The `tier` determines the order in which the trackers are to be tried. The `trackers()` function will return a sorted vector of announce_entry. Each announce entry contains a string, which is the tracker url, and a tier index. The tier index is the high-level priority. No matter which trackers that works or not, the ones with lower tier will always be tried before the one with higher tier number. For more information, see announce_entry.

`trackers()` returns all entries from announce-list.

`clear_trackers()` removes all trackers from announce-list.

[report issue]

## similar_torrents() collections()

    std::vector<sha1_hash> similar_torrents () const;
    std::vector<std::string> collections () const;

These two functions are related to BEP 38 (mutable torrents). The vectors returned from these correspond to the "similar" and "collections" keys in the .torrent file. Both info-hashes and collections from within the info-dict and from outside of it are included.

[report issue]

## add_http_seed() add_url_seed() web_seeds() set_web_seeds()

    void add_http_seed (std::string const& url
          , std::string const& extern_auth = std::string()
          , web_seed_entry::headers_t const& extra_headers = web_seed_entry::headers_t());
    void add_url_seed (std::string const& url
          , std::string const& ext_auth = std::string()
          , web_seed_entry::headers_t const& ext_headers = web_seed_entry::headers_t());
    std::vector<web_seed_entry> const& web_seeds () const;
    void set_web_seeds (std::vector<web_seed_entry> seeds);

`web_seeds()` returns all url seeds and http seeds in the torrent. Each entry is a `web_seed_entry` and may refer to either a url seed or http seed.

`add_url_seed()` and `add_http_seed()` adds one url to the list of url/http seeds.

`set_web_seeds()` replaces all web seeds with the ones specified in the `seeds` vector.

The `extern_auth` argument can be used for other authorization schemes than basic HTTP authorization. If set, it will override any username and password found in the URL itself. The string will be sent as the HTTP authorization header's value (without specifying "Basic").

The `extra_headers` argument defaults to an empty list, but can be used to insert custom HTTP headers in the requests to a specific web seed.

See http seeding for more information.

[report issue]

## total_size()

    std::int64_t total_size () const;

`total_size()` returns the total number of bytes the torrent-file represents. Note that this is the number of pieces times the piece size (modulo the last piece possibly being smaller). With pad files, the total size will be larger than the sum of all (regular) file sizes.

[report issue]

## num_pieces() piece_length()

    int piece_length () const;
    int num_pieces () const;

`piece_length()` and `num_pieces()` returns the number of byte for each piece and the total number of pieces, respectively. The difference between `piece_size()` and `piece_length()` is that `piece_size()` takes the piece index as argument and gives you the exact size of that piece. It will always be the same as `piece_length()` except in the case of the last piece, which may be smaller.

[report issue]

## end_piece() last_piece() piece_range()

    piece_index_t last_piece () const;
    index_range<piece_index_t> piece_range () const;
    piece_index_t end_piece () const;

`last_piece()` returns the index to the last piece in the torrent and `end_piece()` returns the index to the one-past-end piece in the torrent `piece_range()` returns an implementation-defined type that can be used as the container in a range-for loop. Where the values are the indices of all pieces in the file_storage.

[report issue]

## info_hashes() info_hash()

    info_hash_t const& info_hashes () const;
    sha1_hash info_hash () const noexcept;

returns the info-hash of the torrent. For BitTorrent v2 support, use `info_hashes()` to get an object that may hold both a v1 and v2 info-hash

[report issue]

## v2() v1()

    bool v1 () const;
    bool v2 () const;

returns whether this torrent has v1 and/or v2 metadata, respectively. Hybrid torrents have both. These are shortcuts for info_hashes().has_v1() and info_hashes().has_v2() calls.

[report issue]

## num_files()

    int num_files () const;

If you need index-access to files you can use the `num_files()` along with the `file_path()`, `file_size()`-family of functions to access files using indices.

[report issue]

## map_block()

    std::vector<file_slice> map_block (piece_index_t const piece
          , std::int64_t offset, int size) const;

This function will map a piece index, a byte offset within that piece and a size (in bytes) into the corresponding files with offsets where that data for that piece is supposed to be stored. See file_slice.

[report issue]

## map_file()

    peer_request map_file (file_index_t const file, std::int64_t offset, int size) const;

This function will map a range in a specific file into a range in the torrent. The `file_offset` parameter is the offset in the file, given in bytes, where 0 is the start of the file. See peer_request.

The input range is assumed to be valid within the torrent. `file_offset` + `size` is not allowed to be greater than the file size. `file_index` must refer to a valid file, i.e. it cannot be >= `num_files()`.

[report issue]

## ssl_cert()

    string_view ssl_cert () const;

Returns the SSL root certificate for the torrent, if it is an SSL torrent. Otherwise returns an empty string. The certificate is the public certificate in x509 format.

[report issue]

## is_valid()

    bool is_valid () const;

returns true if this torrent_info object has a torrent loaded. This is primarily used to determine if a magnet link has had its metadata resolved yet or not.

[report issue]

## priv()

    bool priv () const;

returns true if this torrent is private. i.e., the client should not advertise itself on the trackerless network (the Kademlia DHT) for this torrent.

[report issue]

## is_i2p()

    bool is_i2p () const;

returns true if this is an i2p torrent. This is determined by whether or not it has a tracker whose URL domain name ends with ".i2p". i2p torrents disable the DHT and local peer discovery as well as talking to peers over anything other than the i2p network.

[report issue]

## piece_size()

    int piece_size (piece_index_t index) const;

returns the piece size of file with `index`. This will be the same as piece_length(), except for the last piece, which may be shorter.

[report issue]

## hash_for_piece() hash_for_piece_ptr()

    char const* hash_for_piece_ptr (piece_index_t const index) const;
    sha1_hash hash_for_piece (piece_index_t index) const;

`hash_for_piece()` takes a piece-index and returns the 20-bytes sha1-hash for that piece and `info_hash()` returns the 20-bytes sha1-hash for the info-section of the torrent file. `hash_for_piece_ptr()` returns a pointer to the 20 byte sha1 digest for the piece. Note that the string is not 0-terminated.

[report issue]

## name()

    const std::string& name () const;

`name()` returns the name of the torrent. name contains UTF-8 encoded string.

[report issue]

## creation_date()

    std::time_t creation_date () const;

`creation_date()` returns the creation date of the torrent as time_t (posix time). If there's no time stamp in the torrent file, 0 is returned. .. posix time: http://www.opengroup.org/onlinepubs/009695399/functions/time.html

[report issue]

## creator()

    const std::string& creator () const;

`creator()` returns the creator string in the torrent. If there is no creator string it will return an empty string.

[report issue]

## comment()

    const std::string& comment () const;

`comment()` returns the comment associated with the torrent. If there's no comment, it will return an empty string. comment contains UTF-8 encoded string.

[report issue]

## nodes()

    std::vector<std::pair<std::string, int>> const& nodes () const;

If this torrent contains any DHT nodes, they are put in this vector in their original form (host name and port number).

[report issue]

## add_node()

    void add_node (std::pair<std::string, int> const& node);

This is used when creating torrent. Use this to add a known DHT node. It may be used, by the client, to bootstrap into the DHT network.

[report issue]

## parse_info_section()

    bool parse_info_section (bdecode_node const& info, error_code& ec, int max_pieces);

populates the torrent_info by providing just the info-dict buffer. This is used when loading a torrent from a magnet link for instance, where we only have the info-dict. The bdecode_node `e` points to a parsed info-dictionary. `ec` returns an error code if something fails (typically if the info dictionary is malformed). The max_pieces parameter allows limiting the amount of memory dedicated to loading the torrent, and fails for torrents that exceed the limit. To load large torrents, this limit may also need to be raised in settings_pack::max_piece_count and in calls to read_resume_data().

[report issue]

## info()

    bdecode_node info (char const* key) const;

This function looks up keys from the info-dictionary of the loaded torrent file. It can be used to access extension values put in the .torrent file. If the specified key cannot be found, it returns nullptr.

[report issue]

## info_section()

    span<char const> info_section () const;

returns a the raw info section of the torrent file. The underlying buffer is still owned by the torrent_info object

[report issue]

## piece_layer()

    span<char const> piece_layer (file_index_t) const;

return the bytes of the piece layer hashes for the specified file. If the file doesn't have a piece layer, an empty span is returned. The span size is divisible by 32, the size of a SHA-256 hash. If the size of the file is smaller than or equal to the piece size, the files "root hash" is the hash of the file and is not saved separately in the "piece layers" field, but this function still returns the root hash of the file in that case.

[report issue]

## free_piece_layers()

    void free_piece_layers ();

clears the piece layers from the torrent_info. This is done by the session when a torrent is added, to avoid storing it twice. The piece layer (or other hashes part of the merkle tree) are stored in the internal torrent object.