torrent_info()

explicit torrent_info (info_hash_t const& info_hash);

constructs an empty torrent_info containing only an info-hash. Useful for magnet links: the resulting object has no metadata (no file list, no piece hashes) but the info-hash is set so it can be passed to session::add_torrent().

This object is not filled in once metadata is received from peers. The torrent installs a new torrent_info instance internally rather than updating this one. Retrieve the populated metadata via torrent_handle::torrent_file().

torrent_info()

torrent_info (bdecode_node const& info_section, error_code& ec
      , load_torrent_limits const& cfg
      , from_info_section_t);

Construct a torrent_info object from the parsed info-section pointed to by info_section. The info-section buffer will be copied into torrent_info.

~torrent_info()

~torrent_info ();

frees all storage associated with this torrent_info object

layout()

file_storage const& layout () const;

The file_storage object contains the information on how to map the pieces to files. It is separated from the torrent_info object as the disk I/O subsystem only needs access to file names and sizes. The file_storage object is immutable, renamed files are recorded separately. layout() returns the original filenames, as found in the .torrent file. Files may be renamed to de-duplicate names, or to correct invalid filenames.

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

collections() similar_torrents()

std::vector<std::string> collections () const;
std::vector<sha1_hash> similar_torrents () 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.

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.

size_on_disk()

std::int64_t size_on_disk () const;

returns the sum of all non-pad file sizes. i.e. the files that will actually be saved to disk by this torrent.

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.

blocks_per_piece()

int blocks_per_piece () const;

returns the number of blocks there are in the typical piece. There may be fewer in the last piece)

piece_range() end_piece() last_piece()

piece_index_t end_piece () const;
piece_index_t last_piece () const;
index_range<piece_index_t> piece_range () 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.

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

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.

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.

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.

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().

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.

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.

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.

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. This is not reliably set for torrents created via resume data or magnet links. Prefer using torrent::is_i2p() instead.

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.

piece_size_for_req()

int piece_size_for_req (piece_index_t index) const;

returns the piece size appropriate for computing request lengths. for v2-only torrents, pieces at the end of files may be shorter than the main piece size. For v1 and hybrid torrents, piece sizes must be full (except for the last piece) in order to correctly compute the piece hash. Note: this is not a trivial accessor. For v2-only torrents it calls file_storage::piece_size2(), which performs an O(log n) upper_bound over the file list to find the file boundary that may shorten the piece. Cache the result when calling it repeatedly for the same piece in a hot path.

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. hash_for_piece_ptr() returns a pointer to the 20 byte sha1 digest for the piece. Note that the string is not 0-terminated.

is_loaded()

bool is_loaded () const;

returns true if the metadata for this torrent has been loaded (i.e. the file list is populated). For a torrent_info constructed from just an info-hash this returns false.

name()

const std::string& name () const;

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

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