Version: 2.0.0

home

[report issue]

client_data_t

Declared in "libtorrent/client_data.hpp"

A thin wrapper around a void pointer used as "user data". i.e. an opaque cookie passed in to libtorrent and returned on demand. It adds type-safety by requiring the same type be requested out of it as was assigned to it.

struct client_data_t
{
   client_data_t () = default;
   explicit client_data_t (T* v);
   client_data_t& operator= (T* v);
   explicit operator T () const;
   T* get () const;
   client_data_t& operator= (void const*) = delete;
   operator void* () const = delete;
   client_data_t& operator= (void*) = delete;
   operator void const* () const = delete;
};
[report issue]

client_data_t()

client_data_t () = default;

construct a nullptr client data

[report issue]

void*() operator=() const*()

client_data_t& operator= (void const*) = delete;
operator void* () const = delete;
client_data_t& operator= (void*) = delete;
operator void const* () const = delete;

we don't allow type-unsafe operations

[report issue]

add_torrent_params

Declared in "libtorrent/add_torrent_params.hpp"

The add_torrent_params is a parameter pack for adding torrents to a session. The key fields when adding a torrent are:

  • ti - when you have loaded a .torrent file into a torrent_info object
  • info_hash - when you don't have the metadata (.torrent file) but. This is set when adding a magnet link.

one of those fields must be set. Another mandatory field is save_path. The add_torrent_params object is passed into one of the session::add_torrent() overloads or session::async_add_torrent().

If you only specify the info-hash, the torrent file will be downloaded from peers, which requires them to support the metadata extension. For the metadata extension to work, libtorrent must be built with extensions enabled (TORRENT_DISABLE_EXTENSIONS must not be defined). It also takes an optional name argument. This may be left empty in case no name should be assigned to the torrent. In case it's not, the name is used for the torrent as long as it doesn't have metadata. See torrent_handle::name.

The add_torrent_params is also used when requesting resume data for a torrent. It can be saved to and restored from a file and added back to a new session. For serialization and de-serialization of add_torrent_params objects, see read_resume_data() and write_resume_data().

struct add_torrent_params
{
   int version  = LIBTORRENT_VERSION_NUM;
   std::shared_ptr<torrent_info> ti;
   aux::noexcept_movable<std::vector<std::string>> trackers;
   aux::noexcept_movable<std::vector<int>> tracker_tiers;
   aux::noexcept_movable<std::vector<std::pair<std::string, int>>> dht_nodes;
   std::string name;
   std::string save_path;
   storage_mode_t storage_mode  = storage_mode_sparse;
   client_data_t userdata;
   aux::noexcept_movable<std::vector<download_priority_t>> file_priorities;
   std::string trackerid;
   torrent_flags_t flags  = torrent_flags::default_flags;
   info_hash_t info_hashes;
   int max_uploads  = -1;
   int max_connections  = -1;
   int upload_limit  = -1;
   int download_limit  = -1;
   std::int64_t total_uploaded  = 0;
   std::int64_t total_downloaded  = 0;
   int active_time  = 0;
   int finished_time  = 0;
   int seeding_time  = 0;
   std::time_t added_time  = 0;
   std::time_t completed_time  = 0;
   std::time_t last_seen_complete  = 0;
   int num_complete  = -1;
   int num_incomplete  = -1;
   int num_downloaded  = -1;
   aux::noexcept_movable<std::vector<std::string>> http_seeds;
   aux::noexcept_movable<std::vector<std::string>> url_seeds;
   aux::noexcept_movable<std::vector<tcp::endpoint>> peers;
   aux::noexcept_movable<std::vector<tcp::endpoint>> banned_peers;
   aux::noexcept_movable<std::map<piece_index_t, bitfield>> unfinished_pieces;
   typed_bitfield<piece_index_t> have_pieces;
   typed_bitfield<piece_index_t> verified_pieces;
   aux::noexcept_movable<std::vector<download_priority_t>> piece_priorities;
   aux::vector<std::vector<sha256_hash>, file_index_t> merkle_trees;
   aux::vector<std::vector<bool>, file_index_t> merkle_tree_mask;
   aux::vector<std::vector<bool>, file_index_t> verified_leaf_hashes;
   aux::noexcept_movable<std::map<file_index_t, std::string>> renamed_files;
   std::time_t last_download  = 0;
   std::time_t last_upload  = 0;
};
[report issue]
version
filled in by the constructor and should be left untouched. It is used for forward binary compatibility.
[report issue]
ti
torrent_info object with the torrent to add. Unless the info_hash is set, this is required to be initialized.
[report issue]
trackers
If the torrent doesn't have a tracker, but relies on the DHT to find peers, the trackers can specify tracker URLs for the torrent.
[report issue]
tracker_tiers
the tiers the URLs in trackers belong to. Trackers belonging to different tiers may be treated differently, as defined by the multi tracker extension. This is optional, if not specified trackers are assumed to be part of tier 0, or whichever the last tier was as iterating over the trackers.
[report issue]
dht_nodes
a list of hostname and port pairs, representing DHT nodes to be added to the session (if DHT is enabled). The hostname may be an IP address.
[report issue]
name
in case there's no other name in this torrent, this name will be used. The name out of the torrent_info object takes precedence if available.
[report issue]
save_path

the path where the torrent is or will be stored.

Note

On windows this path (and other paths) are interpreted as UNC paths. This means they must use backslashes as directory separators and may not contain the special directories "." or "..".

Setting this to an absolute path performs slightly better than a relative path.

[report issue]
storage_mode
One of the values from storage_mode_t. For more information, see storage allocation.
[report issue]
userdata
The userdata parameter is optional and will be passed on to the extension constructor functions, if any (see torrent_handle::add_extension()). It will also be stored in the torrent object and can be retrieved by calling userdata().
[report issue]
file_priorities
can be set to control the initial file priorities when adding a torrent. The semantics are the same as for torrent_handle::prioritize_files(). The file priorities specified in here take precedence over those specified in the resume data, if any.
[report issue]
trackerid
the default tracker id to be used when announcing to trackers. By default this is empty, and no tracker ID is used, since this is an optional argument. If a tracker returns a tracker ID, that ID is used instead of this.
[report issue]
flags

flags controlling aspects of this torrent and how it's added. See torrent_flags_t for details.

Note

The flags field is initialized with default flags by the constructor. In order to preserve default behavior when clearing or setting other flags, make sure to bitwise OR or in a flag or bitwise AND the inverse of a flag to clear it.

[report issue]
info_hashes
set this to the info hash of the torrent to add in case the info-hash is the only known property of the torrent. i.e. you don't have a .torrent file nor a magnet link. To add a magnet link, use parse_magnet_uri() to populate fields in the add_torrent_params object.
[report issue]
max_uploads max_connections

max_uploads, max_connections, upload_limit, download_limit correspond to the set_max_uploads(), set_max_connections(), set_upload_limit() and set_download_limit() functions on torrent_handle. These values let you initialize these settings when the torrent is added, instead of calling these functions immediately following adding it.

-1 means unlimited on these settings just like their counterpart functions on torrent_handle

For fine grained control over rate limits, including making them apply to local peers, see peer classes.

[report issue]
upload_limit download_limit
the upload and download rate limits for this torrent, specified in bytes per second. -1 means unlimited.
[report issue]
total_uploaded total_downloaded
the total number of bytes uploaded and downloaded by this torrent so far.
[report issue]
active_time finished_time seeding_time
the number of seconds this torrent has spent in started, finished and seeding state so far, respectively.
[report issue]
added_time completed_time
if set to a non-zero value, this is the posix time of when this torrent was first added, including previous runs/sessions. If set to zero, the internal added_time will be set to the time of when add_torrent() is called.
[report issue]
last_seen_complete
if set to non-zero, initializes the time (expressed in posix time) when we last saw a seed or peers that together formed a complete copy of the torrent. If left set to zero, the internal counterpart to this field will be updated when we see a seed or a distributed copies >= 1.0.
[report issue]
num_complete num_incomplete num_downloaded

these field can be used to initialize the torrent's cached scrape data. The scrape data is high level metadata about the current state of the swarm, as returned by the tracker (either when announcing to it or by sending a specific scrape request). num_complete is the number of peers in the swarm that are seeds, or have every piece in the torrent. num_incomplete is the number of peers in the swarm that do not have every piece. num_downloaded is the number of times the torrent has been downloaded (not initiated, but the number of times a download has completed).

Leaving any of these values set to -1 indicates we don't know, or we have not received any scrape data.

[report issue]
http_seeds url_seeds

URLs can be added to these two lists to specify additional web seeds to be used by the torrent. If the flag_override_web_seeds is set, these will be the _only_ ones to be used. i.e. any web seeds found in the .torrent file will be overridden.

http_seeds expects URLs to web servers implementing the original HTTP seed specification BEP 17.

url_seeds expects URLs to regular web servers, aka "get right" style, specified in BEP 19.

[report issue]
peers
peers to add to the torrent, to be tried to be connected to as bittorrent peers.
[report issue]
banned_peers
peers banned from this torrent. The will not be connected to
[report issue]
unfinished_pieces
this is a map of partially downloaded piece. The key is the piece index and the value is a bitfield where each bit represents a 16 kiB block. A set bit means we have that block.
[report issue]
have_pieces
this is a bitfield indicating which pieces we already have of this torrent.
[report issue]
verified_pieces
when in seed_mode, pieces with a set bit in this bitfield have been verified to be valid. Other pieces will be verified the first time a peer requests it.
[report issue]
piece_priorities
this sets the priorities for each individual piece in the torrent. Each element in the vector represent the piece with the same index. If you set both file- and piece priorities, file priorities will take precedence.
[report issue]
merkle_trees
v2 hashes, if known
[report issue]
merkle_tree_mask
if set, indicates which hashes are included in the corresponding vector of merkle_trees. These bitmasks always cover the full tree, a cleared bit means the hash is all zeros (i.e. not set) and set bit means the next hash in the corresponding vector in merkle_trees is the hash for that node. This is an optimization to avoid storing a lot of zeros.
[report issue]
verified_leaf_hashes
bit-fields indicating which v2 leaf hashes have been verified against the root hash. If this vector is empty and merkle_trees is non-empty it implies that all hashes in merkle_trees are verified.
[report issue]
renamed_files
this is a map of file indices in the torrent and new filenames to be applied before the torrent is added.
[report issue]
last_download last_upload
the posix time of the last time payload was received or sent for this torrent, respectively.