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;
   operator void const* () const = delete;
   operator void* () const = delete;
   client_data_t& operator= (void*) = delete;
   client_data_t& operator= (void const*) = delete;

   template <typename T, typename U  = typename std::enable_if<std::is_pointer<T>::value>::type>
};

client_data_t () = default;

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

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;
};

version

filled in by the constructor and should be left untouched. It is used for forward binary compatibility.

ti

torrent_info object with the torrent to add. Unless the info_hash is set, this is required to be initialized.

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.

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.

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.

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.

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.

storage_mode

One of the values from storage_mode_t. For more information, see storage allocation.

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

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.

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.

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.

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.

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.

upload_limit download_limit

the upload and download rate limits for this torrent, specified in bytes per second. -1 means unlimited.

total_uploaded total_downloaded

the total number of bytes uploaded and downloaded by this torrent so far.

active_time finished_time seeding_time

the number of seconds this torrent has spent in started, finished and seeding state so far, respectively.

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.

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.

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.

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.

peers

peers to add to the torrent, to be tried to be connected to as bittorrent peers.

banned_peers

peers banned from this torrent. The will not be connected to

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.

have_pieces

this is a bitfield indicating which pieces we already have of this torrent.

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.

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.

merkle_trees

v2 hashes, if known

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.

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.

renamed_files

this is a map of file indices in the torrent and new filenames to be applied before the torrent is added.

last_download last_upload

the posix time of the last time payload was received or sent for this torrent, respectively.

counters

Declared in "libtorrent/performance_counters.hpp"

struct counters
{
   counters () ;
   counters& operator= (counters const&) & ;
   counters (counters const&) ;
   std::int64_t operator[] (int i) const ;
   std::int64_t inc_stats_counter (int c, std::int64_t value = 1) ;
   void set_value (int c, std::int64_t value) ;
   void blend_stats_counter (int c, std::int64_t value, int ratio) ;
};

std::int64_t operator[] (int i) const ;
std::int64_t inc_stats_counter (int c, std::int64_t value = 1) ;

stats_metric

Declared in "libtorrent/session_stats.hpp"

describes one statistics metric from the session. For more information, see the session statistics section.

struct stats_metric
{
   char const* name;
   int value_index;
   metric_type_t type;
};

name

the name of the counter or gauge

value_index type

the index into the session stats array, where the underlying value of this counter or gauge is found. The session stats array is part of the session_stats_alert object.

session_stats_metrics()

Declared in "libtorrent/session_stats.hpp"

std::vector<stats_metric> session_stats_metrics ();

This free function returns the list of available metrics exposed by libtorrent's statistics API. Each metric has a name and a value index. The value index is the index into the array in session_stats_alert where this metric's value can be found when the session stats is sampled (by calling post_session_stats()).

find_metric_idx()

Declared in "libtorrent/session_stats.hpp"

int find_metric_idx (string_view name);

given a name of a metric, this function returns the counter index of it, or -1 if it could not be found. The counter index is the index into the values array returned by session_stats_alert.

enum metric_type_t

Declared in "libtorrent/session_stats.hpp"

storage_error

Declared in "libtorrent/error_code.hpp"

used by storage to return errors also includes which underlying file the error happened on

struct storage_error
{
   explicit operator bool () const;
   file_index_t file () const;
   void file (file_index_t f);

   error_code ec;
   operation_t operation;
};

explicit operator bool () const;

file_index_t file () const;
void file (file_index_t f);

libtorrent_category()

Declared in "libtorrent/error_code.hpp"

boost::system::error_category& libtorrent_category ();

return the instance of the libtorrent_error_category which maps libtorrent error codes to human readable error messages.

http_category()

Declared in "libtorrent/error_code.hpp"

boost::system::error_category& http_category ();

returns the error_category for HTTP errors

pcp_category()

Declared in "libtorrent/natpmp.hpp"

boost::system::error_category& pcp_category ();

upnp_category()

Declared in "libtorrent/upnp.hpp"

boost::system::error_category& upnp_category ();

the boost.system error category for UPnP errors

gzip_category()

Declared in "libtorrent/gzip.hpp"

boost::system::error_category& gzip_category ();

get the error_category for zip errors

bdecode_category()

Declared in "libtorrent/bdecode.hpp"

boost::system::error_category& bdecode_category ();

socks_category()

Declared in "libtorrent/socks5_stream.hpp"

boost::system::error_category& socks_category ();

returns the error_category for SOCKS5 errors

i2p_category()

Declared in "libtorrent/i2p_stream.hpp"

boost::system::error_category& i2p_category ();

returns the error category for I2P errors

enum error_code_enum

Declared in "libtorrent/error_code.hpp"

enum http_errors

Declared in "libtorrent/error_code.hpp"

enum pcp_errors

Declared in "libtorrent/natpmp.hpp"

enum error_code_enum

Declared in "libtorrent/upnp.hpp"

enum error_code_enum

Declared in "libtorrent/gzip.hpp"

enum error_code_enum

Declared in "libtorrent/bdecode.hpp"

enum socks_error_code

Declared in "libtorrent/socks5_stream.hpp"

enum i2p_error_code

Declared in "libtorrent/i2p_stream.hpp"

session_params

Declared in "libtorrent/session_params.hpp"

The session_params is a parameters pack for configuring the session before it's started.

struct session_params
{
   session_params ();
   session_params (settings_pack&& sp);
   session_params (settings_pack const& sp);
   session_params (settings_pack&& sp
      , std::vector<std::shared_ptr<plugin>> exts);
   session_params (settings_pack const& sp
      , std::vector<std::shared_ptr<plugin>> exts);

   settings_pack settings;
   std::vector<std::shared_ptr<plugin>> extensions;
   dht::dht_state dht_state;
   dht::dht_storage_constructor_type dht_storage_constructor;
   disk_io_constructor_type disk_io_constructor;
   std::map<std::string, std::string> ext_state;
   libtorrent::ip_filter ip_filter;
};

session_params ();
session_params (settings_pack&& sp);
session_params (settings_pack const& sp);

session_params (settings_pack&& sp
      , std::vector<std::shared_ptr<plugin>> exts);
session_params (settings_pack const& sp
      , std::vector<std::shared_ptr<plugin>> exts);

session_handle

Declared in "libtorrent/session_handle.hpp"

this class provides a non-owning handle to a session and a subset of the interface of the session class. If the underlying session is destructed any handle to it will no longer be valid. is_valid() will return false and any operation on it will throw a system_error exception, with error code invalid_session_handle.

struct session_handle
{
   bool is_valid () const;
   session_params session_state (save_state_flags_t flags = save_state_flags_t::all()) const;
   std::vector<torrent_status> get_torrent_status (
      std::function<bool(torrent_status const&)> const& pred
      , status_flags_t flags = {}) const;
   void refresh_torrent_status (std::vector<torrent_status>* ret
      , status_flags_t flags = {}) const;
   void post_torrent_updates (status_flags_t flags = status_flags_t::all());
   void post_session_stats ();
   void post_dht_stats ();
   void set_dht_state (dht::dht_state&& st);
   void set_dht_state (dht::dht_state const& st);
   torrent_handle find_torrent (sha1_hash const& info_hash) const;
   std::vector<torrent_handle> get_torrents () const;
   torrent_handle add_torrent (add_torrent_params const& params);
   void async_add_torrent (add_torrent_params const& params);
   torrent_handle add_torrent (add_torrent_params&& params, error_code& ec);
   torrent_handle add_torrent (add_torrent_params const& params, error_code& ec);
   torrent_handle add_torrent (add_torrent_params&& params);
   void async_add_torrent (add_torrent_params&& params);
   void pause ();
   void resume ();
   bool is_paused () const;
   bool is_dht_running () const;
   void set_dht_storage (dht::dht_storage_constructor_type sc);
   void add_dht_node (std::pair<std::string, int> const& node);
   void dht_get_item (sha1_hash const& target);
   void dht_get_item (std::array<char, 32> key
      , std::string salt = std::string());
   sha1_hash dht_put_item (entry data);
   void dht_put_item (std::array<char, 32> key
      , std::function<void(entry&, std::array<char, 64>&
      , std::int64_t&, std::string const&)> cb
      , std::string salt = std::string());
   void dht_announce (sha1_hash const& info_hash, int port = 0, dht::announce_flags_t flags = {});
   void dht_get_peers (sha1_hash const& info_hash);
   void dht_live_nodes (sha1_hash const& nid);
   void dht_sample_infohashes (udp::endpoint const& ep, sha1_hash const& target);
   void dht_direct_request (udp::endpoint const& ep, entry const& e, client_data_t userdata = {});
   void add_extension (std::shared_ptr<plugin> ext);
   void add_extension (std::function<std::shared_ptr<torrent_plugin>(
      torrent_handle const&, client_data_t)> ext);
   ip_filter get_ip_filter () const;
   void set_ip_filter (ip_filter f);
   void set_port_filter (port_filter const& f);
   unsigned short listen_port () const;
   unsigned short ssl_listen_port () const;
   bool is_listening () const;
   void set_peer_class_filter (ip_filter const& f);
   ip_filter get_peer_class_filter () const;
   void set_peer_class_type_filter (peer_class_type_filter const& f);
   peer_class_type_filter get_peer_class_type_filter () const;
   peer_class_t create_peer_class (char const* name);
   void delete_peer_class (peer_class_t cid);
   peer_class_info get_peer_class (peer_class_t cid) const;
   void set_peer_class (peer_class_t cid, peer_class_info const& pci);
   void remove_torrent (const torrent_handle&, remove_flags_t = {});
   void apply_settings (settings_pack&&);
   settings_pack get_settings () const;
   void apply_settings (settings_pack const&);
   void pop_alerts (std::vector<alert*>* alerts);
   void set_alert_notify (std::function<void()> const& fun);
   alert* wait_for_alert (time_duration max_wait);
   std::vector<port_mapping_t> add_port_mapping (portmap_protocol t, int external_port, int local_port);
   void delete_port_mapping (port_mapping_t handle);
   void reopen_network_sockets (reopen_network_flags_t options = reopen_map_ports);
   std::shared_ptr<aux::session_impl> native_handle () const;

   static constexpr save_state_flags_t save_settings  = 0_bit;
   static constexpr save_state_flags_t save_dht_state  = 2_bit;
   static constexpr save_state_flags_t save_extension_state  = 11_bit;
   static constexpr save_state_flags_t save_ip_filter  = 12_bit;
   static constexpr peer_class_t global_peer_class_id {0};
   static constexpr peer_class_t tcp_peer_class_id {1};
   static constexpr peer_class_t local_peer_class_id {2};
   static constexpr remove_flags_t delete_files  = 0_bit;
   static constexpr remove_flags_t delete_partfile  = 1_bit;
   static constexpr session_flags_t paused  = 2_bit;
   static constexpr portmap_protocol udp  = portmap_protocol::udp;
   static constexpr portmap_protocol tcp  = portmap_protocol::tcp;
   static constexpr reopen_network_flags_t reopen_map_ports  = 0_bit;
};

bool is_valid () const;

session_params session_state (save_state_flags_t flags = save_state_flags_t::all()) const;

std::vector<torrent_status> get_torrent_status (
      std::function<bool(torrent_status const&)> const& pred
      , status_flags_t flags = {}) const;
void refresh_torrent_status (std::vector<torrent_status>* ret
      , status_flags_t flags = {}) const;

void post_torrent_updates (status_flags_t flags = status_flags_t::all());

void post_session_stats ();

void post_dht_stats ();

void set_dht_state (dht::dht_state&& st);
void set_dht_state (dht::dht_state const& st);

torrent_handle find_torrent (sha1_hash const& info_hash) const;
std::vector<torrent_handle> get_torrents () const;

torrent_handle add_torrent (add_torrent_params const& params);
void async_add_torrent (add_torrent_params const& params);
torrent_handle add_torrent (add_torrent_params&& params, error_code& ec);
torrent_handle add_torrent (add_torrent_params const& params, error_code& ec);
torrent_handle add_torrent (add_torrent_params&& params);
void async_add_torrent (add_torrent_params&& params);

void pause ();
void resume ();
bool is_paused () const;

bool is_dht_running () const;

void set_dht_storage (dht::dht_storage_constructor_type sc);

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

void dht_get_item (sha1_hash const& target);

void dht_get_item (std::array<char, 32> key
      , std::string salt = std::string());

sha1_hash dht_put_item (entry data);

void dht_put_item (std::array<char, 32> key
      , std::function<void(entry&, std::array<char, 64>&
      , std::int64_t&, std::string const&)> cb
      , std::string salt = std::string());

void dht_announce (sha1_hash const& info_hash, int port = 0, dht::announce_flags_t flags = {});
void dht_get_peers (sha1_hash const& info_hash);

void dht_live_nodes (sha1_hash const& nid);

void dht_sample_infohashes (udp::endpoint const& ep, sha1_hash const& target);

void dht_direct_request (udp::endpoint const& ep, entry const& e, client_data_t userdata = {});

void add_extension (std::shared_ptr<plugin> ext);
void add_extension (std::function<std::shared_ptr<torrent_plugin>(
      torrent_handle const&, client_data_t)> ext);

#include <libtorrent/extensions/ut_metadata.hpp>
ses.add_extension(&lt::create_ut_metadata_plugin);

#include <libtorrent/extensions/ut_pex.hpp>
ses.add_extension(&lt::create_ut_pex_plugin);

#include <libtorrent/extensions/smart_ban.hpp>
ses.add_extension(&lt::create_smart_ban_plugin);

ip_filter get_ip_filter () const;
void set_ip_filter (ip_filter f);

void set_port_filter (port_filter const& f);

unsigned short listen_port () const;
unsigned short ssl_listen_port () const;
bool is_listening () const;

void set_peer_class_filter (ip_filter const& f);
ip_filter get_peer_class_filter () const;

ip_filter f = ses.get_peer_class_filter();
peer_class_t my_class = ses.create_peer_class("200.1.x.x IP range");
f.add_rule(make_address("200.1.1.0"), make_address("200.1.255.255")
        , 1 << static_cast<std::uint32_t>(my_class));
ses.set_peer_class_filter(f);

void set_peer_class_type_filter (peer_class_type_filter const& f);
peer_class_type_filter get_peer_class_type_filter () const;

peer_class_t create_peer_class (char const* name);

void delete_peer_class (peer_class_t cid);

peer_class_info get_peer_class (peer_class_t cid) const;
void set_peer_class (peer_class_t cid, peer_class_info const& pci);

void remove_torrent (const torrent_handle&, remove_flags_t = {});

void apply_settings (settings_pack&&);
settings_pack get_settings () const;
void apply_settings (settings_pack const&);

void pop_alerts (std::vector<alert*>* alerts);
void set_alert_notify (std::function<void()> const& fun);
alert* wait_for_alert (time_duration max_wait);

std::vector<port_mapping_t> add_port_mapping (portmap_protocol t, int external_port, int local_port);
void delete_port_mapping (port_mapping_t handle);

void reopen_network_sockets (reopen_network_flags_t options = reopen_map_ports);

std::shared_ptr<aux::session_impl> native_handle () const;

session_proxy

Declared in "libtorrent/session.hpp"

this is a holder for the internal session implementation object. Once the session destruction is explicitly initiated, this holder is used to synchronize the completion of the shutdown. The lifetime of this object may outlive session, causing the session destructor to not block. The session_proxy destructor will block however, until the underlying session is done shutting down.

struct session_proxy
{
   session_proxy (session_proxy const&);
   session_proxy& operator= (session_proxy&&) & noexcept;
   session_proxy (session_proxy&&) noexcept;
   session_proxy& operator= (session_proxy const&) &;
   session_proxy ();
   ~session_proxy ();
};

session_proxy (session_proxy const&);
session_proxy& operator= (session_proxy&&) & noexcept;
session_proxy (session_proxy&&) noexcept;
session_proxy& operator= (session_proxy const&) &;
session_proxy ();
~session_proxy ();

session

Declared in "libtorrent/session.hpp"

The session holds all state that spans multiple torrents. Among other things it runs the network loop and manages all torrents. Once it's created, the session object will spawn the main thread that will do all the work. The main thread will be idle as long it doesn't have any torrents to participate in.

You have some control over session configuration through the session_handle::apply_settings() member function. To change one or more configuration options, create a settings_pack. object and fill it with the settings to be set and pass it in to session::apply_settings().

see apply_settings().

struct session : session_handle
{
   explicit session (session_params const& params);
   session (session_params const& params, session_flags_t flags);
   session ();
   session (session_params&& params, session_flags_t flags);
   explicit session (session_params&& params);
   session (session_params&& params, io_context& ios);
   session (session_params const& params, io_context& ios);
   session (session_params const& params, io_context& ios, session_flags_t);
   session (session_params&& params, io_context& ios, session_flags_t);
   ~session ();
   session_proxy abort ();
};

explicit session (session_params const& params);
session (session_params const& params, session_flags_t flags);
session ();
session (session_params&& params, session_flags_t flags);
explicit session (session_params&& params);

session (session_params&& params, io_context& ios);
session (session_params const& params, io_context& ios);
session (session_params const& params, io_context& ios, session_flags_t);
session (session_params&& params, io_context& ios, session_flags_t);

~session ();

session_proxy abort ();

struct session_proxy {};

read_session_params() write_session_params() write_session_params_buf()

Declared in "libtorrent/session_params.hpp"

std::vector<char> write_session_params_buf (session_params const& sp
   , save_state_flags_t flags = save_state_flags_t::all());
session_params read_session_params (bdecode_node const& e
   , save_state_flags_t flags = save_state_flags_t::all());
session_params read_session_params (span<char const> buf
   , save_state_flags_t flags = save_state_flags_t::all());
entry write_session_params (session_params const& sp
   , save_state_flags_t flags = save_state_flags_t::all());

These functions serialize and de-serialize a session_params object to and from bencoded form. The session_params object is used to initialize a new session using the state from a previous one (or by programmatically configure the session up-front). The flags parameter can be used to only save and load certain aspects of the session's state. The _buf suffix indicates the function operates on buffer rather than the bencoded structure. The torrents in a session are not part of the session_params state, they have to be restored separately.

peer_class_info

Declared in "libtorrent/peer_class.hpp"

holds settings for a peer class. Used in set_peer_class() and get_peer_class() calls.

struct peer_class_info
{
   bool ignore_unchoke_slots;
   int connection_limit_factor;
   std::string label;
   int upload_limit;
   int download_limit;
   int upload_priority;
   int download_priority;
};

ignore_unchoke_slots

ignore_unchoke_slots determines whether peers should always unchoke a peer, regardless of the choking algorithm, or if it should honor the unchoke slot limits. It's used for local peers by default. If any of the peer classes a peer belongs to has this set to true, that peer will be unchoked at all times.

connection_limit_factor

adjusts the connection limit (global and per torrent) that applies to this peer class. By default, local peers are allowed to exceed the normal connection limit for instance. This is specified as a percent factor. 100 makes the peer class apply normally to the limit. 200 means as long as there are fewer connections than twice the limit, we accept this peer. This factor applies both to the global connection limit and the per-torrent limit. Note that if not used carefully one peer class can potentially completely starve out all other over time.

label

not used by libtorrent. It's intended as a potentially user-facing identifier of this peer class.

upload_limit download_limit

transfer rates limits for the whole peer class. They are specified in bytes per second and apply to the sum of all peers that are members of this class.

upload_priority download_priority

relative priorities used by the bandwidth allocator in the rate limiter. If no rate limits are in use, the priority is not used either. Priorities start at 1 (0 is not a valid priority) and may not exceed 255.

peer_class_type_filter

Declared in "libtorrent/peer_class_type_filter.hpp"

peer_class_type_filter is a simple container for rules for adding and subtracting peer-classes from peers. It is applied after the peer class filter is applied (which is based on the peer's IP address).

struct peer_class_type_filter
{
   void remove (socket_type_t const st, peer_class_t const peer_class);
   void add (socket_type_t const st, peer_class_t const peer_class);
   void disallow (socket_type_t const st, peer_class_t const peer_class);
   void allow (socket_type_t const st, peer_class_t const peer_class);
   std::uint32_t apply (socket_type_t const st, std::uint32_t peer_class_mask);
   friend bool operator== (peer_class_type_filter const& lhs
      , peer_class_type_filter const& rhs);

   enum socket_type_t
   {
      tcp_socket,
      utp_socket,
      ssl_tcp_socket,
      ssl_utp_socket,
      i2p_socket,
      num_socket_types,
   };
};

void remove (socket_type_t const st, peer_class_t const peer_class);
void add (socket_type_t const st, peer_class_t const peer_class);

void disallow (socket_type_t const st, peer_class_t const peer_class);
void allow (socket_type_t const st, peer_class_t const peer_class);

std::uint32_t apply (socket_type_t const st, std::uint32_t peer_class_mask);

a word of caution

Writing your own plugin is a very easy way to introduce serious bugs such as dead locks and race conditions. Since a plugin has access to internal structures it is also quite easy to sabotage libtorrent's operation.

All the callbacks are always called from the libtorrent network thread. In case portions of your plugin are called from other threads, typically the main thread, you cannot use any of the member functions on the internal structures in libtorrent, since those require being called from the libtorrent network thread . Furthermore, you also need to synchronize your own shared data within the plugin, to make sure it is not accessed at the same time from the libtorrent thread (through a callback). If you need to send out a message from another thread, it is advised to use an internal queue, and do the actual sending in tick().

Since the plugin interface gives you easy access to internal structures, it is not supported as a stable API. Plugins should be considered specific to a specific version of libtorrent. Although, in practice the internals mostly don't change that dramatically.

plugin-interface

The plugin interface consists of three base classes that the plugin may implement. These are called plugin, torrent_plugin and peer_plugin. They are found in the <libtorrent/extensions.hpp> header.

These plugins are instantiated for each session, torrent and possibly each peer, respectively.

For plugins that only need per torrent state, it is enough to only implement torrent_plugin and pass a constructor function or function object to session::add_extension() or torrent_handle::add_extension() (if the torrent has already been started and you want to hook in the extension at run-time).

The signature of the function is:

std::shared_ptr<torrent_plugin> (*)(torrent_handle const&, client_data_t);

The second argument is the userdata passed to session::add_torrent() or torrent_handle::add_extension().

The function should return a std::shared_ptr<torrent_plugin> which may or may not be 0. If it is a nullptr, the extension is simply ignored for this torrent. If it is a valid pointer (to a class inheriting torrent_plugin), it will be associated with this torrent and callbacks will be made on torrent events.

For more elaborate plugins which require session wide state, you would implement plugin, construct an object (in a std::shared_ptr) and pass it in to session::add_extension().

custom alerts

Since plugins are running within internal libtorrent threads, one convenient way to communicate with the client is to post custom alerts.

The expected interface of any alert, apart from deriving from the alert base class, looks like this:

static const int alert_type = <unique alert ID>;
virtual int type() const { return alert_type; }

virtual std::string message() const;

static const alert_category_t static_category = <bitmask of alert::category_t flags>;
virtual alert_category_t category() const { return static_category; }

virtual char const* what() const { return <string literal of the name of this alert>; }

The alert_type is used for the type-checking in alert_cast. It must not collide with any other alert. The built-in alerts in libtorrent will not use alert type IDs greater than user_alert_id. When defining your own alert, make sure it's greater than this constant.

type() is the run-time equivalence of the alert_type.

The message() virtual function is expected to construct a useful string representation of the alert and the event or data it represents. Something convenient to put in a log file for instance.

clone() is used internally to copy alerts. The suggested implementation of simply allocating a new instance as a copy of *this is all that's expected.

The static category is required for checking whether or not the category for a specific alert is enabled or not, without instantiating the alert. The category virtual function is the run-time equivalence.

The what() virtual function may simply be a string literal of the class name of your alert.

For more information, see the alert section.

plugin

Declared in "libtorrent/extensions.hpp"

this is the base class for a session plugin. One primary feature is that it is notified of all torrents that are added to the session, and can add its own torrent_plugins.

struct plugin
{
   virtual feature_flags_t implemented_features ();
   virtual std::shared_ptr<torrent_plugin> new_torrent (torrent_handle const&, client_data_t);
   virtual void added (session_handle const&);
   virtual void abort ();
   virtual bool on_dht_request (string_view /* query */
      , udp::endpoint const& /* source */, bdecode_node const& /* message */
      , entry& /* response */);
   virtual void on_alert (alert const*);
   virtual bool on_unknown_torrent (info_hash_t const& /* info_hash */
      , peer_connection_handle const& /* pc */, add_torrent_params& /* p */);
   virtual void on_tick ();
   virtual uint64_t get_unchoke_priority (peer_connection_handle const& /* peer */);
   virtual std::map<std::string, std::string> save_state () const;
   virtual void load_state (std::map<std::string, std::string> const&);

   static constexpr feature_flags_t optimistic_unchoke_feature  = 1_bit;
   static constexpr feature_flags_t tick_feature  = 2_bit;
   static constexpr feature_flags_t dht_request_feature  = 3_bit;
   static constexpr feature_flags_t alert_feature  = 4_bit;
};

virtual feature_flags_t implemented_features ();

virtual std::shared_ptr<torrent_plugin> new_torrent (torrent_handle const&, client_data_t);

virtual void added (session_handle const&);

virtual void abort ();

virtual bool on_dht_request (string_view /* query */
      , udp::endpoint const& /* source */, bdecode_node const& /* message */
      , entry& /* response */);

virtual void on_alert (alert const*);

virtual bool on_unknown_torrent (info_hash_t const& /* info_hash */
      , peer_connection_handle const& /* pc */, add_torrent_params& /* p */);

virtual void on_tick ();

virtual uint64_t get_unchoke_priority (peer_connection_handle const& /* peer */);

virtual void load_state (std::map<std::string, std::string> const&);

torrent_plugin

Declared in "libtorrent/extensions.hpp"

Torrent plugins are associated with a single torrent and have a number of functions called at certain events. Many of its functions have the ability to change or override the default libtorrent behavior.

struct torrent_plugin
{
   virtual std::shared_ptr<peer_plugin> new_connection (peer_connection_handle const&);
   virtual void on_piece_pass (piece_index_t);
   virtual void on_piece_failed (piece_index_t);
   virtual void tick ();
   virtual bool on_resume ();
   virtual bool on_pause ();
   virtual void on_files_checked ();
   virtual void on_state (torrent_status::state_t);
   virtual void on_add_peer (tcp::endpoint const&,
      peer_source_flags_t, add_peer_flags_t);

   static constexpr add_peer_flags_t first_time  = 1_bit;
   static constexpr add_peer_flags_t filtered  = 2_bit;
};

virtual std::shared_ptr<peer_plugin> new_connection (peer_connection_handle const&);

virtual void on_piece_pass (piece_index_t);
virtual void on_piece_failed (piece_index_t);

virtual void tick ();

virtual bool on_resume ();
virtual bool on_pause ();

virtual void on_files_checked ();

virtual void on_state (torrent_status::state_t);

virtual void on_add_peer (tcp::endpoint const&,
      peer_source_flags_t, add_peer_flags_t);

peer_plugin

Declared in "libtorrent/extensions.hpp"

peer plugins are associated with a specific peer. A peer could be both a regular bittorrent peer (bt_peer_connection) or one of the web seed connections (web_peer_connection or http_seed_connection). In order to only attach to certain peers, make your torrent_plugin::new_connection only return a plugin for certain peer connection types

struct peer_plugin
{
   virtual string_view type () const;
   virtual void add_handshake (entry&);
   virtual void on_disconnect (error_code const&);
   virtual void on_connected ();
   virtual bool on_handshake (span<char const>);
   virtual bool on_extension_handshake (bdecode_node const&);
   virtual bool on_have_all ();
   virtual bool on_not_interested ();
   virtual bool on_request (peer_request const&);
   virtual bool on_have (piece_index_t);
   virtual bool on_allowed_fast (piece_index_t);
   virtual bool on_dont_have (piece_index_t);
   virtual bool on_choke ();
   virtual bool on_have_none ();
   virtual bool on_bitfield (bitfield const& /*bitfield*/);
   virtual bool on_unchoke ();
   virtual bool on_interested ();
   virtual bool on_piece (peer_request const& /*piece*/
      , span<char const> /*buf*/);
   virtual bool on_cancel (peer_request const&);
   virtual bool on_reject (peer_request const&);
   virtual bool on_suggest (piece_index_t);
   virtual void sent_choke ();
   virtual void sent_reject_request (peer_request const&);
   virtual void sent_have_none ();
   virtual void sent_allow_fast (piece_index_t);
   virtual void sent_request (peer_request const&);
   virtual void sent_cancel (peer_request const&);
   virtual void sent_have_all ();
   virtual void sent_suggest (piece_index_t);
   virtual void sent_unchoke ();
   virtual void sent_have (piece_index_t);
   virtual void sent_piece (peer_request const&);
   virtual void sent_not_interested ();
   virtual void sent_interested ();
   virtual void sent_payload (int /* bytes */);
   virtual bool can_disconnect (error_code const& /*ec*/);
   virtual bool on_extended (int /*length*/, int /*msg*/,
      span<char const> /*body*/);
   virtual bool on_unknown_message (int /*length*/, int /*msg*/,
      span<char const> /*body*/);
   virtual void on_piece_pass (piece_index_t);
   virtual void on_piece_failed (piece_index_t);
   virtual void tick ();
   virtual bool write_request (peer_request const&);
};

virtual string_view type () const;

virtual void add_handshake (entry&);

virtual void on_disconnect (error_code const&);

virtual void on_connected ();

virtual bool on_handshake (span<char const>);

virtual bool on_extension_handshake (bdecode_node const&);

virtual bool on_have_all ();
virtual bool on_not_interested ();
virtual bool on_request (peer_request const&);
virtual bool on_have (piece_index_t);
virtual bool on_allowed_fast (piece_index_t);
virtual bool on_dont_have (piece_index_t);
virtual bool on_choke ();
virtual bool on_have_none ();
virtual bool on_bitfield (bitfield const& /*bitfield*/);
virtual bool on_unchoke ();
virtual bool on_interested ();

virtual bool on_piece (peer_request const& /*piece*/
      , span<char const> /*buf*/);

virtual void sent_unchoke ();
virtual void sent_have (piece_index_t);
virtual void sent_piece (peer_request const&);
virtual void sent_not_interested ();
virtual void sent_interested ();

virtual void sent_payload (int /* bytes */);

virtual bool can_disconnect (error_code const& /*ec*/);

virtual bool on_extended (int /*length*/, int /*msg*/,
      span<char const> /*body*/);

virtual bool on_unknown_message (int /*length*/, int /*msg*/,
      span<char const> /*body*/);

virtual void on_piece_pass (piece_index_t);
virtual void on_piece_failed (piece_index_t);

virtual void tick ();

virtual bool write_request (peer_request const&);

crypto_plugin

Declared in "libtorrent/extensions.hpp"

struct crypto_plugin
{
   virtual void set_incoming_key (span<char const> key) = 0;
   virtual void set_outgoing_key (span<char const> key) = 0;
   encrypt (span<span<char>> /*send_vec*/) = 0;
   virtual std::tuple<int, int, int> decrypt (span<span<char>> /*receive_vec*/) = 0;
};

virtual std::tuple<int, int, int> decrypt (span<span<char>> /*receive_vec*/) = 0;

peer_connection_handle

Declared in "libtorrent/peer_connection_handle.hpp"

the peer_connection_handle class provides a handle to the internal peer connection object, to be used by plugins. This is a low level interface that may not be stable across libtorrent versions

struct peer_connection_handle
{
   explicit peer_connection_handle (std::weak_ptr<peer_connection> impl);
   connection_type type () const;
   void add_extension (std::shared_ptr<peer_plugin>);
   peer_plugin const* find_plugin (string_view type) const;
   bool is_seed () const;
   bool upload_only () const;
   peer_id const& pid () const;
   bool has_piece (piece_index_t i) const;
   bool is_interesting () const;
   bool is_choked () const;
   bool is_peer_interested () const;
   bool has_peer_choked () const;
   void choke_this_peer ();
   void maybe_unchoke_this_peer ();
   void get_peer_info (peer_info& p) const;
   torrent_handle associated_torrent () const;
   tcp::endpoint const& remote () const;
   tcp::endpoint local_endpoint () const;
   bool is_connecting () const;
   bool is_disconnecting () const;
   void disconnect (error_code const& ec, operation_t op
      , disconnect_severity_t = peer_connection_interface::normal);
   bool is_outgoing () const;
   bool ignore_unchoke_slots () const;
   bool on_local_network () const;
   bool failed () const;
   bool should_log (peer_log_alert::direction_t direction) const;
   void peer_log (peer_log_alert::direction_t direction
      , char const* event, char const* fmt = "", ...) const TORRENT_FORMAT(4,5);
   bool can_disconnect (error_code const& ec) const;
   bool has_metadata () const;
   bool in_handshake () const;
   void send_buffer (char const* begin, int size);
   std::time_t last_seen_complete () const;
   time_point time_of_last_unchoke () const;
   bool operator== (peer_connection_handle const& o) const;
   bool operator< (peer_connection_handle const& o) const;
   bool operator!= (peer_connection_handle const& o) const;
   std::shared_ptr<peer_connection> native_handle () const;
};

bt_peer_connection_handle

Declared in "libtorrent/peer_connection_handle.hpp"

The bt_peer_connection_handle provides a handle to the internal bittorrent peer connection object to plugins. It's low level and may not be a stable API across libtorrent versions.

struct bt_peer_connection_handle : peer_connection_handle
{
   explicit bt_peer_connection_handle (peer_connection_handle pc);
   bool packet_finished () const;
   bool support_extensions () const;
   bool supports_encryption () const;
   void switch_send_crypto (std::shared_ptr<crypto_plugin> crypto);
   void switch_recv_crypto (std::shared_ptr<crypto_plugin> crypto);
   std::shared_ptr<bt_peer_connection> native_handle () const;
};

create_ut_metadata_plugin()

Declared in "libtorrent/extensions/ut_metadata.hpp"

std::shared_ptr<torrent_plugin> create_ut_metadata_plugin (torrent_handle const&, client_data_t);

constructor function for the ut_metadata extension. The ut_metadata extension allows peers to request the .torrent file (or more specifically the info-dictionary of the .torrent file) from each other. This is the main building block in making magnet links work. This extension is enabled by default unless explicitly disabled in the session constructor.

This can either be passed in the add_torrent_params::extensions field, or via torrent_handle::add_extension().

create_smart_ban_plugin()

Declared in "libtorrent/extensions/smart_ban.hpp"

std::shared_ptr<torrent_plugin> create_smart_ban_plugin (torrent_handle const&, client_data_t);

constructor function for the smart ban extension. The extension keeps track of the data peers have sent us for failing pieces and once the piece completes and passes the hash check bans the peers that turned out to have sent corrupt data. This function can either be passed in the add_torrent_params::extensions field, or via torrent_handle::add_extension().

create_ut_pex_plugin()

Declared in "libtorrent/extensions/ut_pex.hpp"

std::shared_ptr<torrent_plugin> create_ut_pex_plugin (torrent_handle const&, client_data_t);

constructor function for the ut_pex extension. The ut_pex extension allows peers to gossip about their connections, allowing the swarm stay well connected and peers aware of more peers in the swarm. This extension is enabled by default unless explicitly disabled in the session constructor.

This can either be passed in the add_torrent_params::extensions field, or via torrent_handle::add_extension().

info_hash_t

Declared in "libtorrent/info_hash.hpp"

class holding the info-hash of a torrent. It can hold a v1 info-hash (SHA-1) or a v2 info-hash (SHA-256) or both.

struct info_hash_t
{
   info_hash_t () noexcept = default;
   explicit info_hash_t (sha1_hash h1) noexcept;
   explicit info_hash_t (sha256_hash h2) noexcept;
   info_hash_t (sha1_hash h1, sha256_hash h2) noexcept;
   bool has (protocol_version v) const;
   bool has_v2 () const;
   bool has_v1 () const;
   sha1_hash get (protocol_version v) const;
   sha1_hash get_best () const;
   friend bool operator!= (info_hash_t const& lhs, info_hash_t const& rhs);
   friend bool operator== (info_hash_t const& lhs, info_hash_t const& rhs) noexcept;
   template <typename F> void for_each (F f) const;
   bool operator< (info_hash_t const& o) const;
   friend std::ostream& operator<< (std::ostream& os, info_hash_t const& ih);

   sha1_hash v1;
   sha256_hash v2;
};

info_hash_t () noexcept = default;
explicit info_hash_t (sha1_hash h1) noexcept;
explicit info_hash_t (sha256_hash h2) noexcept;
info_hash_t (sha1_hash h1, sha256_hash h2) noexcept;

bool has (protocol_version v) const;
bool has_v2 () const;
bool has_v1 () const;

sha1_hash get (protocol_version v) const;

sha1_hash get_best () const;

template <typename F> void for_each (F f) const;

void(sha1_hash, protocol_version);

piece_block

Declared in "libtorrent/piece_block.hpp"

struct piece_block
{
   piece_block (piece_index_t p_index, int b_index);
   piece_block () = default;
   bool operator< (piece_block const& b) const;
   bool operator== (piece_block const& b) const;
   bool operator!= (piece_block const& b) const;

   static const piece_block invalid;
   piece_index_t piece_index {0};
   int block_index  = 0;
};

peer_info

Declared in "libtorrent/peer_info.hpp"

holds information and statistics about one peer that libtorrent is connected to

struct peer_info
{
   std::string client;
   typed_bitfield<piece_index_t> pieces;
   std::int64_t total_download;
   std::int64_t total_upload;
   time_duration last_request;
   time_duration last_active;
   time_duration download_queue_time;
   static constexpr peer_flags_t interesting  = 0_bit;
   static constexpr peer_flags_t choked  = 1_bit;
   static constexpr peer_flags_t remote_interested  = 2_bit;
   static constexpr peer_flags_t remote_choked  = 3_bit;
   static constexpr peer_flags_t supports_extensions  = 4_bit;
   static constexpr peer_flags_t outgoing_connection  = 5_bit;
   static constexpr peer_flags_t local_connection  = 5_bit;
   static constexpr peer_flags_t handshake  = 6_bit;
   static constexpr peer_flags_t connecting  = 7_bit;
   static constexpr peer_flags_t on_parole  = 9_bit;
   static constexpr peer_flags_t seed  = 10_bit;
   static constexpr peer_flags_t optimistic_unchoke  = 11_bit;
   static constexpr peer_flags_t snubbed  = 12_bit;
   static constexpr peer_flags_t upload_only  = 13_bit;
   static constexpr peer_flags_t endgame_mode  = 14_bit;
   static constexpr peer_flags_t holepunched  = 15_bit;
   static constexpr peer_flags_t i2p_socket  = 16_bit;
   static constexpr peer_flags_t utp_socket  = 17_bit;
   static constexpr peer_flags_t ssl_socket  = 18_bit;
   static constexpr peer_flags_t rc4_encrypted  = 19_bit;
   static constexpr peer_flags_t plaintext_encrypted  = 20_bit;
   peer_flags_t flags;
   static constexpr peer_source_flags_t tracker  = 0_bit;
   static constexpr peer_source_flags_t dht  = 1_bit;
   static constexpr peer_source_flags_t pex  = 2_bit;
   static constexpr peer_source_flags_t lsd  = 3_bit;
   static constexpr peer_source_flags_t resume_data  = 4_bit;
   static constexpr peer_source_flags_t incoming  = 5_bit;
   peer_source_flags_t source;
   int up_speed;
   int down_speed;
   int payload_up_speed;
   int payload_down_speed;
   peer_id pid;
   int queue_bytes;
   int request_timeout;
   int send_buffer_size;
   int used_send_buffer;
   int receive_buffer_size;
   int used_receive_buffer;
   int receive_buffer_watermark;
   int num_hashfails;
   int download_queue_length;
   int timed_out_requests;
   int busy_requests;
   int requests_in_buffer;
   int target_dl_queue_length;
   int upload_queue_length;
   int failcount;
   piece_index_t downloading_piece_index;
   int downloading_block_index;
   int downloading_progress;
   int downloading_total;
   static constexpr connection_type_t standard_bittorrent  = 0_bit;
   static constexpr connection_type_t web_seed  = 1_bit;
   static constexpr connection_type_t http_seed  = 2_bit;
   connection_type_t connection_type;
   int pending_disk_bytes;
   int pending_disk_read_bytes;
   int send_quota;
   int receive_quota;
   int rtt;
   int num_pieces;
   int download_rate_peak;
   int upload_rate_peak;
   float progress;
   int progress_ppm;
   tcp::endpoint ip;
   tcp::endpoint local_endpoint;
   static constexpr bandwidth_state_flags_t bw_idle  = 0_bit;
   static constexpr bandwidth_state_flags_t bw_limit  = 1_bit;
   static constexpr bandwidth_state_flags_t bw_network  = 2_bit;
   static constexpr bandwidth_state_flags_t bw_disk  = 4_bit;
   bandwidth_state_flags_t read_state;
   bandwidth_state_flags_t write_state;
};

client

a string describing the software at the other end of the connection. In some cases this information is not available, then it will contain a string that may give away something about which software is running in the other end. In the case of a web seed, the server type and version will be a part of this string.

pieces

a bitfield, with one bit per piece in the torrent. Each bit tells you if the peer has that piece (if it's set to 1) or if the peer miss that piece (set to 0).

total_download total_upload

the total number of bytes downloaded from and uploaded to this peer. These numbers do not include the protocol chatter, but only the payload data.

last_request last_active

the time since we last sent a request to this peer and since any transfer occurred with this peer

download_queue_time

the time until all blocks in the request queue will be downloaded

interesting

we are interested in pieces from this peer.

choked

we have choked this peer.

remote_interested

the peer is interested in us

remote_choked

the peer has choked us.

supports_extensions

means that this peer supports the extension protocol.

outgoing_connection

The connection was initiated by us, the peer has a listen port open, and that port is the same as in the address of this peer. If this flag is not set, this peer connection was opened by this peer connecting to us.

local_connection

deprecated synonym for outgoing_connection

handshake

The connection is opened, and waiting for the handshake. Until the handshake is done, the peer cannot be identified.

connecting

The connection is in a half-open state (i.e. it is being connected).

on_parole

The peer has participated in a piece that failed the hash check, and is now "on parole", which means we're only requesting whole pieces from this peer until it either fails that piece or proves that it doesn't send bad data.

seed

This peer is a seed (it has all the pieces).

optimistic_unchoke

This peer is subject to an optimistic unchoke. It has been unchoked for a while to see if it might unchoke us in return an earn an upload/unchoke slot. If it doesn't within some period of time, it will be choked and another peer will be optimistically unchoked.

snubbed

This peer has recently failed to send a block within the request timeout from when the request was sent. We're currently picking one block at a time from this peer.

upload_only

This peer has either explicitly (with an extension) or implicitly (by becoming a seed) told us that it will not downloading anything more, regardless of which pieces we have.

endgame_mode

This means the last time this peer picket a piece, it could not pick as many as it wanted because there were not enough free ones. i.e. all pieces this peer has were already requested from other peers.

holepunched

This flag is set if the peer was in holepunch mode when the connection succeeded. This typically only happens if both peers are behind a NAT and the peers connect via the NAT holepunch mechanism.

i2p_socket

indicates that this socket is running on top of the I2P transport.

utp_socket

indicates that this socket is a uTP socket

ssl_socket

indicates that this socket is running on top of an SSL (TLS) channel

rc4_encrypted

this connection is obfuscated with RC4

plaintext_encrypted

the handshake of this connection was obfuscated with a Diffie-Hellman exchange

flags

tells you in which state the peer is in. It is set to any combination of the peer_flags_t flags above.

tracker

The peer was received from the tracker.

dht

The peer was received from the kademlia DHT.

pex

The peer was received from the peer exchange extension.

lsd

The peer was received from the local service discovery (The peer is on the local network).

resume_data

The peer was added from the fast resume data.

incoming

we received an incoming connection from this peer

source

a combination of flags describing from which sources this peer was received. A combination of the peer_source_flags_t above.

up_speed down_speed

the current upload and download speed we have to and from this peer (including any protocol messages). updated about once per second

payload_up_speed payload_down_speed

The transfer rates of payload data only updated about once per second

pid

the peer's id as used in the bit torrent protocol. This id can be used to extract 'fingerprints' from the peer. Sometimes it can tell you which client the peer is using. See identify_client()_

queue_bytes

the number of bytes we have requested from this peer, but not yet received.

request_timeout

the number of seconds until the current front piece request will time out. This timeout can be adjusted through settings_pack::request_timeout. -1 means that there is not outstanding request.

send_buffer_size used_send_buffer

the number of bytes allocated and used for the peer's send buffer, respectively.

receive_buffer_size used_receive_buffer receive_buffer_watermark

the number of bytes allocated and used as receive buffer, respectively.

num_hashfails

the number of pieces this peer has participated in sending us that turned out to fail the hash check.

download_queue_length

this is the number of requests we have sent to this peer that we haven't got a response for yet

timed_out_requests

the number of block requests that have timed out, and are still in the download queue

busy_requests

the number of busy requests in the download queue. A busy request is a request for a block we've also requested from a different peer

requests_in_buffer

the number of requests messages that are currently in the send buffer waiting to be sent.

target_dl_queue_length

the number of requests that is tried to be maintained (this is typically a function of download speed)

upload_queue_length

the number of piece-requests we have received from this peer that we haven't answered with a piece yet.

failcount

the number of times this peer has "failed". i.e. failed to connect or disconnected us. The failcount is decremented when we see this peer in a tracker response or peer exchange message.

downloading_piece_index downloading_block_index downloading_progress downloading_total

You can know which piece, and which part of that piece, that is currently being downloaded from a specific peer by looking at these four members. downloading_piece_index is the index of the piece that is currently being downloaded. This may be set to -1 if there's currently no piece downloading from this peer. If it is >= 0, the other three members are valid. downloading_block_index is the index of the block (or sub-piece) that is being downloaded. downloading_progress is the number of bytes of this block we have received from the peer, and downloading_total is the total number of bytes in this block.

standard_bittorrent

Regular bittorrent connection

web_seed

HTTP connection using the BEP 19 protocol

http_seed

HTTP connection using the BEP 17 protocol

connection_type

the kind of connection this peer uses. See connection_type_t.

pending_disk_bytes

the number of bytes this peer has pending in the disk-io thread. Downloaded and waiting to be written to disk. This is what is capped by settings_pack::max_queued_disk_bytes.

pending_disk_read_bytes

number of outstanding bytes to read from disk

send_quota receive_quota

the number of bytes this peer has been assigned to be allowed to send and receive until it has to request more quota from the bandwidth manager.

rtt

an estimated round trip time to this peer, in milliseconds. It is estimated by timing the TCP connect(). It may be 0 for incoming connections.

num_pieces

the number of pieces this peer has.

download_rate_peak upload_rate_peak

the highest download and upload rates seen on this connection. They are given in bytes per second. This number is reset to 0 on reconnect.

progress

the progress of the peer in the range [0, 1]. This is always 0 when floating point operations are disabled, instead use progress_ppm.

progress_ppm

indicates the download progress of the peer in the range [0, 1000000] (parts per million).

ip

the IP-address to this peer. The type is an asio endpoint. For more info, see the asio documentation.

local_endpoint

the IP and port pair the socket is bound to locally. i.e. the IP address of the interface it's going out over. This may be useful for multi-homed clients with multiple interfaces to the internet.

bw_idle

The peer is not waiting for any external events to send or receive data.

bw_limit

The peer is waiting for the rate limiter.

bw_network

The peer has quota and is currently waiting for a network read or write operation to complete. This is the state all peers are in if there are no bandwidth limits.

bw_disk

The peer is waiting for the disk I/O thread to catch up writing buffers to disk before downloading more.

read_state write_state

bitmasks indicating what state this peer is in with regards to sending and receiving data. The states are defined as independent flags of type bandwidth_state_flags_t, in this class.

peer_request

Declared in "libtorrent/peer_request.hpp"

represents a byte range within a piece. Internally this is is used for incoming piece requests.

struct peer_request
{
   bool operator== (peer_request const& r) const;

   piece_index_t piece;
   int start;
   int length;
};

bool operator== (peer_request const& r) const;

make_magnet_uri()

Declared in "libtorrent/magnet_uri.hpp"

std::string make_magnet_uri (torrent_handle const& handle);
std::string make_magnet_uri (torrent_info const& info);

Generates a magnet URI from the specified torrent. If the torrent handle is invalid, an empty string is returned.

For more information about magnet links, see magnet links.

parse_magnet_uri()

Declared in "libtorrent/magnet_uri.hpp"

add_torrent_params parse_magnet_uri (string_view uri);
add_torrent_params parse_magnet_uri (string_view uri, error_code& ec);
void parse_magnet_uri (string_view uri, add_torrent_params& p, error_code& ec);

This function parses out information from the magnet link and populates the add_torrent_params object. The overload that does not take an error_code reference will throw a system_error on error The overload taking an add_torrent_params reference will fill in the fields specified in the magnet URI.

version()

Declared in "libtorrent/version.hpp"

char const* version ();

returns the libtorrent version as string form in this format: "<major>.<minor>.<tiny>.<tag>"

enum connection_type

Declared in "libtorrent/peer_connection.hpp"

enum protocol_version

Declared in "libtorrent/info_hash.hpp"

enum socket_type_t

Declared in "libtorrent/socket_type.hpp"

enum portmap_transport

Declared in "libtorrent/portmap.hpp"

enum portmap_protocol

Declared in "libtorrent/portmap.hpp"

enum event_t

Declared in "libtorrent/tracker_manager.hpp"

torrent_flags_t

Declared in "libtorrent/torrent_flags.hpp"

seed_mode

If seed_mode is set, libtorrent will assume that all files are present for this torrent and that they all match the hashes in the torrent file. Each time a peer requests to download a block, the piece is verified against the hash, unless it has been verified already. If a hash fails, the torrent will automatically leave the seed mode and recheck all the files. The use case for this mode is if a torrent is created and seeded, or if the user already know that the files are complete, this is a way to avoid the initial file checks, and significantly reduce the startup time.

Setting seed_mode on a torrent without metadata (a .torrent file) is a no-op and will be ignored.

It is not possible to set the seed_mode flag on a torrent after it has been added to a session. It is possible to clear it though.

upload_mode

If upload_mode is set, the torrent will be initialized in upload-mode, which means it will not make any piece requests. This state is typically entered on disk I/O errors, and if the torrent is also auto managed, it will be taken out of this state periodically (see settings_pack::optimistic_disk_retry).

This mode can be used to avoid race conditions when adjusting priorities of pieces before allowing the torrent to start downloading.

If the torrent is auto-managed (auto_managed), the torrent will eventually be taken out of upload-mode, regardless of how it got there. If it's important to manually control when the torrent leaves upload mode, don't make it auto managed.

share_mode

determines if the torrent should be added in share mode or not. Share mode indicates that we are not interested in downloading the torrent, but merely want to improve our share ratio (i.e. increase it). A torrent started in share mode will do its best to never download more than it uploads to the swarm. If the swarm does not have enough demand for upload capacity, the torrent will not download anything. This mode is intended to be safe to add any number of torrents to, without manual screening, without the risk of downloading more than is uploaded.

A torrent in share mode sets the priority to all pieces to 0, except for the pieces that are downloaded, when pieces are decided to be downloaded. This affects the progress bar, which might be set to "100% finished" most of the time. Do not change file or piece priorities for torrents in share mode, it will make it not work.

The share mode has one setting, the share ratio target, see settings_pack::share_mode_target for more info.

apply_ip_filter

determines if the IP filter should apply to this torrent or not. By default all torrents are subject to filtering by the IP filter (i.e. this flag is set by default). This is useful if certain torrents needs to be exempt for some reason, being an auto-update torrent for instance.

paused

specifies whether or not the torrent is paused. i.e. it won't connect to the tracker or any of the peers until it's resumed. Note that a paused torrent that also has the auto_managed flag set can be started at any time by libtorrent's queuing logic. See queuing.

auto_managed

If the torrent is auto-managed (auto_managed), the torrent may be resumed at any point, regardless of how it paused. If it's important to manually control when the torrent is paused and resumed, don't make it auto managed.

If auto_managed is set, the torrent will be queued, started and seeded automatically by libtorrent. When this is set, the torrent should also be started as paused. The default queue order is the order the torrents were added. They are all downloaded in that order. For more details, see queuing.

duplicate_is_error

used in add_torrent_params to indicate that it's an error to attempt to add a torrent that's already in the session. If it's not considered an error, a handle to the existing torrent is returned. This flag is not saved by write_resume_data(), since it is only meant for adding torrents.

update_subscribe

on by default and means that this torrent will be part of state updates when calling post_torrent_updates(). This flag is not saved by write_resume_data().

super_seeding

sets the torrent into super seeding/initial seeding mode. If the torrent is not a seed, this flag has no effect.

sequential_download

sets the sequential download state for the torrent. In this mode the piece picker will pick pieces with low index numbers before pieces with high indices. The actual pieces that are picked depend on other factors still, such as which pieces a peer has and whether it is in parole mode or "prefer whole pieces"-mode. Sequential mode is not ideal for streaming media. For that, see set_piece_deadline() instead.

stop_when_ready

When this flag is set, the torrent will force stop whenever it transitions from a non-data-transferring state into a data-transferring state (referred to as being ready to download or seed). This is useful for torrents that should not start downloading or seeding yet, but want to be made ready to do so. A torrent may need to have its files checked for instance, so it needs to be started and possibly queued for checking (auto-managed and started) but as soon as it's done, it should be stopped.

Force stopped means auto-managed is set to false and it's paused. As if the auto_manages flag is cleared and the paused flag is set on the torrent.

Note that the torrent may transition into a downloading state while setting this flag, and since the logic is edge triggered you may miss the edge. To avoid this race, if the torrent already is in a downloading state when this call is made, it will trigger the stop-when-ready immediately.

When the stop-when-ready logic fires, the flag is cleared. Any subsequent transitions between downloading and non-downloading states will not be affected, until this flag is set again.

The behavior is more robust when setting this flag as part of adding the torrent. See add_torrent_params.

The stop-when-ready flag fixes the inherent race condition of waiting for the state_changed_alert and then call pause(). The download/seeding will most likely start in between posting the alert and receiving the call to pause.

A downloading state is one where peers are being connected. Which means just downloading the metadata via the ut_metadata extension counts as a downloading state. In order to stop a torrent once the metadata has been downloaded, instead set all file priorities to dont_download

override_trackers

when this flag is set, the tracker list in the add_torrent_params object override any trackers from the torrent file. If the flag is not set, the trackers from the add_torrent_params object will be added to the list of trackers used by the torrent. This flag is set by read_resume_data() if there are trackers present in the resume data file. This effectively makes the trackers saved in the resume data take precedence over the original trackers. This includes if there's an empty list of trackers, to support the case where they were explicitly removed in the previous session. This flag is not saved by write_resume_data()

override_web_seeds

If this flag is set, the web seeds from the add_torrent_params object will override any web seeds in the torrent file. If it's not set, web seeds in the add_torrent_params object will be added to the list of web seeds used by the torrent. This flag is set by read_resume_data() if there are web seeds present in the resume data file. This effectively makes the web seeds saved in the resume data take precedence over the original ones. This includes if there's an empty list of web seeds, to support the case where they were explicitly removed in the previous session. This flag is not saved by write_resume_data()

need_save_resume

if this flag is set (which it is by default) the torrent will be considered needing to save its resume data immediately as it's added. New torrents that don't have any resume data should do that. This flag is cleared by a successful call to save_resume_data() This flag is not saved by write_resume_data(), since it represents an ephemeral state of a running torrent.

disable_dht

set this flag to disable DHT for this torrent. This lets you have the DHT enabled for the whole client, and still have specific torrents not participating in it. i.e. not announcing to the DHT nor picking up peers from it.

disable_lsd

set this flag to disable local service discovery for this torrent.

disable_pex

set this flag to disable peer exchange for this torrent.

no_verify_files

if this flag is set, the resume data will be assumed to be correct without validating it against any files on disk. This may be used when restoring a session by loading resume data from disk. It will save time and also delay any hard disk errors until files are actually needed. If the resume data cannot be trusted, or if a torrent is added for the first time to some save path that may already have some of the files, this flag should not be set.

all

all torrent flags combined. Can conveniently be used when creating masks for flags

download_priority_t

Declared in "libtorrent/download_priority.hpp"

dont_download

Don't download the file or piece. Partial pieces may still be downloaded when setting file priorities.

default_priority

The default priority for files and pieces.

low_priority

The lowest priority for files and pieces.

top_priority

The highest priority for files and pieces.

pex_flags_t

Declared in "libtorrent/pex_flags.hpp"

pex_encryption

the peer supports protocol encryption

pex_seed

the peer is a seed

pex_utp

the peer supports the uTP, transport protocol over UDP.

pex_holepunch

the peer supports the holepunch extension If this flag is received from a peer, it can be used as a rendezvous point in case direct connections to the peer fail

pex_lt_v2

protocol v2 this is not a standard flag, it is only used internally

int

Declared in "libtorrent/version.hpp"

version_major

the major, minor and tiny versions of libtorrent

version_minor

the major, minor and tiny versions of libtorrent

version_tiny

the major, minor and tiny versions of libtorrent

char const*

Declared in "libtorrent/version.hpp"

version_str

the libtorrent version in string form

std::uint64_t

Declared in "libtorrent/version.hpp"

version_revision

the git commit of this libtorrent version

bdecode_node

Declared in "libtorrent/bdecode.hpp"

Sometimes it's important to get a non-owning reference to the root node ( to be able to copy it as a reference for instance). For that, use the non_owning() member function.

There are 5 different types of nodes, see type_t.

struct bdecode_node
{
   bdecode_node () = default;
   bdecode_node (bdecode_node const&);
   bdecode_node& operator= (bdecode_node const&) &;
   bdecode_node& operator= (bdecode_node&&) & = default;
   bdecode_node (bdecode_node&&) noexcept;
   type_t type () const noexcept;
   explicit operator bool () const noexcept;
   bdecode_node non_owning () const;
   span<char const> data_section () const noexcept;
   std::ptrdiff_t data_offset () const noexcept;
   int list_size () const;
   std::int64_t list_int_value_at (int i
      , std::int64_t default_val = 0) const;
   bdecode_node list_at (int i) const;
   string_view list_string_value_at (int i
      , string_view default_val = string_view()) const;
   bdecode_node dict_find (string_view key) const;
   string_view dict_find_string_value (string_view key
      , string_view default_value = string_view()) const;
   bdecode_node dict_find_string (string_view key) const;
   std::pair<bdecode_node, bdecode_node> dict_at_node (int i) const;
   bdecode_node dict_find_dict (string_view key) const;
   bdecode_node dict_find_list (string_view key) const;
   std::pair<string_view, bdecode_node> dict_at (int i) const;
   std::int64_t dict_find_int_value (string_view key
      , std::int64_t default_val = 0) const;
   int dict_size () const;
   bdecode_node dict_find_int (string_view key) const;
   std::int64_t int_value () const;
   int string_length () const;
   std::ptrdiff_t string_offset () const;
   string_view string_value () const;
   char const* string_ptr () const;
   void clear ();
   void swap (bdecode_node& n);
   void reserve (int tokens);
   void switch_underlying_buffer (char const* buf) noexcept;
   bool has_soft_error (span<char> error) const;

   enum type_t
   {
      none_t,
      dict_t,
      list_t,
      string_t,
      int_t,
   };
};

bdecode_node () = default;

bdecode_node (bdecode_node const&);
bdecode_node& operator= (bdecode_node const&) &;
bdecode_node& operator= (bdecode_node&&) & = default;
bdecode_node (bdecode_node&&) noexcept;

type_t type () const noexcept;

explicit operator bool () const noexcept;

bdecode_node non_owning () const;

span<char const> data_section () const noexcept;
std::ptrdiff_t data_offset () const noexcept;

int list_size () const;
std::int64_t list_int_value_at (int i
      , std::int64_t default_val = 0) const;
bdecode_node list_at (int i) const;
string_view list_string_value_at (int i
      , string_view default_val = string_view()) const;

bdecode_node dict_find (string_view key) const;
string_view dict_find_string_value (string_view key
      , string_view default_value = string_view()) const;
bdecode_node dict_find_string (string_view key) const;
std::pair<bdecode_node, bdecode_node> dict_at_node (int i) const;
bdecode_node dict_find_dict (string_view key) const;
bdecode_node dict_find_list (string_view key) const;
std::pair<string_view, bdecode_node> dict_at (int i) const;
std::int64_t dict_find_int_value (string_view key
      , std::int64_t default_val = 0) const;
int dict_size () const;
bdecode_node dict_find_int (string_view key) const;

std::int64_t int_value () const;

int string_length () const;
std::ptrdiff_t string_offset () const;
string_view string_value () const;
char const* string_ptr () const;

void clear ();

void swap (bdecode_node& n);

void reserve (int tokens);

void switch_underlying_buffer (char const* buf) noexcept;

bool has_soft_error (span<char> error) const;

print_entry()

Declared in "libtorrent/bdecode.hpp"

std::string print_entry (bdecode_node const& e
   , bool single_line = false, int indent = 0);

print the bencoded structure in a human-readable format to a string that's returned.

bdecode()

Declared in "libtorrent/bdecode.hpp"

bdecode_node bdecode (span<char const> buffer
   , int depth_limit = 100, int token_limit = 2000000);
bdecode_node bdecode (span<char const> buffer
   , error_code& ec, int* error_pos = nullptr, int depth_limit = 100
   , int token_limit = 2000000);
int bdecode (char const* start, char const* end, bdecode_node& ret
   , error_code& ec, int* error_pos = nullptr, int depth_limit = 100
   , int token_limit = 2000000);

This function decodes/parses bdecoded data (for example a .torrent file). The data structure is returned in the ret argument. the buffer to parse is specified by the start of the buffer as well as the end, i.e. one byte past the end. If the buffer fails to parse, the function returns a non-zero value and fills in ec with the error code. The optional argument error_pos, if set to non-nullptr, will be set to the byte offset into the buffer where the parse failure occurred.

depth_limit specifies the max number of nested lists or dictionaries are allowed in the data structure. (This affects the stack usage of the function, be careful not to set it too high).

token_limit is the max number of tokens allowed to be parsed from the buffer. This is simply a sanity check to not have unbounded memory usage.

The resulting bdecode_node is an owning node. That means it will be holding the whole parsed tree. When iterating lists and dictionaries, those bdecode_node objects will simply have references to the root or owning bdecode_node. If the root node is destructed, all other nodes that refer to anything in that tree become invalid.

However, the underlying buffer passed in to this function (start, end) must also remain valid while the bdecoded tree is used. The parsed tree produced by this function does not copy any data out of the buffer, but simply produces references back into it.

The disk I/O can be customized in libtorrent. In previous versions, the customization was at the level of each torrent. Now, the customization point is at the session level. All torrents added to a session will use the same disk I/O subsystem, as determined by the disk_io_constructor (in session_params).

This allows the disk subsystem to also customize threading and disk job management.

To customize the disk subsystem, implement disk_interface and provide a factory function to the session constructor (via session_params).

Example use:

struct temp_storage
{
  explicit temp_storage(lt::file_storage const& fs) : m_files(fs) {}

  lt::span<char const> readv(lt::peer_request const r, lt::storage_error& ec) const
  {
    auto const i = m_file_data.find(r.piece);
    if (i == m_file_data.end())
    {
      ec.operation = lt::operation_t::file_read;
      ec.ec = boost::asio::error::eof;
      return {};
    }
    if (int(i->second.size()) <= r.start)
    {
      ec.operation = lt::operation_t::file_read;
      ec.ec = boost::asio::error::eof;
      return {};
    }
    return { i->second.data() + r.start, std::min(r.length, int(i->second.size()) - r.start) };
  }
  void writev(lt::span<char const> const b, lt::piece_index_t const piece, int const offset)
  {
    auto& data = m_file_data[piece];
    if (data.empty())
    {
      // allocate the whole piece, otherwise we'll invalidate the pointers
      // we have returned back to libtorrent
      int const size = piece_size(piece);
      data.resize(std::size_t(size));
    }
    TORRENT_ASSERT(offset + b.size() <= int(data.size()));
    std::memcpy(data.data() + offset, b.data(), std::size_t(b.size()));
  }
  lt::sha1_hash hash(lt::piece_index_t const piece
    , lt::span<lt::sha256_hash> const block_hashes, lt::storage_error& ec) const
  {
    auto const i = m_file_data.find(piece);
    if (i == m_file_data.end())
    {
      ec.operation = lt::operation_t::file_read;
      ec.ec = boost::asio::error::eof;
      return {};
    }
    if (!block_hashes.empty())
    {
      int const piece_size2 = m_files.piece_size2(piece);
      int const blocks_in_piece2 = m_files.blocks_in_piece2(piece);
      char const* buf = i->second.data();
      std::int64_t offset = 0;
      for (int k = 0; k < blocks_in_piece2; ++k)
      {
        lt::hasher256 h2;
        std::ptrdiff_t const len2 = std::min(lt::default_block_size, int(piece_size2 - offset));
        h2.update({ buf, len2 });
        buf += len2;
        offset += len2;
        block_hashes[k] = h2.final();
      }
    }
    return lt::hasher(i->second).final();
  }
  lt::sha256_hash hash2(lt::piece_index_t const piece, int const offset, lt::storage_error& ec)
  {
    auto const i = m_file_data.find(piece);
    if (i == m_file_data.end())
    {
      ec.operation = lt::operation_t::file_read;
      ec.ec = boost::asio::error::eof;
      return {};
    }

    int const piece_size = m_files.piece_size2(piece);

    std::ptrdiff_t const len = std::min(lt::default_block_size, piece_size - offset);

    lt::span<char const> b = {i->second.data() + offset, len};
    return lt::hasher256(b).final();
  }

private:
  int piece_size(lt::piece_index_t piece) const
  {
    int const num_pieces = static_cast<int>((m_files.total_size() + m_files.piece_length() - 1) / m_files.piece_length());
    return static_cast<int>(piece) < num_pieces - 1
      ? m_files.piece_length() : static_cast<int>(m_files.total_size() - (num_pieces - 1) * m_files.piece_length());
  }

  lt::file_storage const& m_files;
  std::map<lt::piece_index_t, std::vector<char>> m_file_data;
};

lt::storage_index_t pop(std::vector<lt::storage_index_t>& q)
{
  TORRENT_ASSERT(!q.empty());
  lt::storage_index_t const ret = q.back();
  q.pop_back();
  return ret;
}

struct temp_disk_io final : lt::disk_interface
  , lt::buffer_allocator_interface
{
  explicit temp_disk_io(lt::io_context& ioc): m_ioc(ioc) {}

  void settings_updated() override {}

  lt::storage_holder new_torrent(lt::storage_params const& params
    , std::shared_ptr<void> const&) override
  {
    lt::storage_index_t const idx = m_free_slots.empty()
      ? m_torrents.end_index()
      : pop(m_free_slots);
    auto storage = std::make_unique<temp_storage>(params.files);
    if (idx == m_torrents.end_index()) m_torrents.emplace_back(std::move(storage));
    else m_torrents[idx] = std::move(storage);
    return lt::storage_holder(idx, *this);
  }

  void remove_torrent(lt::storage_index_t const idx) override
  {
    m_torrents[idx].reset();
    m_free_slots.push_back(idx);
  }

  void abort(bool) override {}

  void async_read(lt::storage_index_t storage, lt::peer_request const& r
    , std::function<void(lt::disk_buffer_holder block, lt::storage_error const& se)> handler
    , lt::disk_job_flags_t) override
  {
    // this buffer is owned by the storage. It will remain valid for as
    // long as the torrent remains in the session. We don't need any lifetime
    // management of it.
    lt::storage_error error;
    lt::span<char const> b = m_torrents[storage]->readv(r, error);

    post(m_ioc, [handler, error, b, this]
      { handler(lt::disk_buffer_holder(*this, const_cast<char*>(b.data()), int(b.size())), error); });
  }

  bool async_write(lt::storage_index_t storage, lt::peer_request const& r
    , char const* buf, std::shared_ptr<lt::disk_observer>
    , std::function<void(lt::storage_error const&)> handler
    , lt::disk_job_flags_t) override
  {
    lt::span<char const> const b = { buf, r.length };

    m_torrents[storage]->writev(b, r.piece, r.start);

    post(m_ioc, [=]{ handler(lt::storage_error()); });
    return false;
  }

  void async_hash(lt::storage_index_t storage, lt::piece_index_t const piece
    , lt::span<lt::sha256_hash> block_hashes, lt::disk_job_flags_t
    , std::function<void(lt::piece_index_t, lt::sha1_hash const&, lt::storage_error const&)> handler) override
  {
    lt::storage_error error;
    lt::sha1_hash const hash = m_torrents[storage]->hash(piece, block_hashes, error);
    post(m_ioc, [=]{ handler(piece, hash, error); });
  }

  void async_hash2(lt::storage_index_t storage, lt::piece_index_t const piece
    , int const offset, lt::disk_job_flags_t
    , std::function<void(lt::piece_index_t, lt::sha256_hash const&, lt::storage_error const&)> handler) override
  {
    lt::storage_error error;
    lt::sha256_hash const hash = m_torrents[storage]->hash2(piece, offset, error);
    post(m_ioc, [=]{ handler(piece, hash, error); });
  }

  void async_move_storage(lt::storage_index_t, std::string p, lt::move_flags_t
    , std::function<void(lt::status_t, std::string const&, lt::storage_error const&)> handler) override
  {
    post(m_ioc, [=]{
      handler(lt::status_t::fatal_disk_error, p
        , lt::storage_error(lt::error_code(boost::system::errc::operation_not_supported, lt::system_category())));
    });
  }

  void async_release_files(lt::storage_index_t, std::function<void()>) override {}

  void async_delete_files(lt::storage_index_t, lt::remove_flags_t
    , std::function<void(lt::storage_error const&)> handler) override
  {
    post(m_ioc, [=]{ handler(lt::storage_error()); });
  }

  void async_check_files(lt::storage_index_t
    , lt::add_torrent_params const*
    , lt::aux::vector<std::string, lt::file_index_t>
    , std::function<void(lt::status_t, lt::storage_error const&)> handler) override
  {
    post(m_ioc, [=]{ handler(lt::status_t::no_error, lt::storage_error()); });
  }

  void async_rename_file(lt::storage_index_t
    , lt::file_index_t const idx
    , std::string const name
    , std::function<void(std::string const&, lt::file_index_t, lt::storage_error const&)> handler) override
  {
    post(m_ioc, [=]{ handler(name, idx, lt::storage_error()); });
  }

  void async_stop_torrent(lt::storage_index_t, std::function<void()> handler) override
  {
    post(m_ioc, handler);
  }

  void async_set_file_priority(lt::storage_index_t
    , lt::aux::vector<lt::download_priority_t, lt::file_index_t> prio
    , std::function<void(lt::storage_error const&
      , lt::aux::vector<lt::download_priority_t, lt::file_index_t>)> handler) override
  {
    post(m_ioc, [=]{
      handler(lt::storage_error(lt::error_code(
        boost::system::errc::operation_not_supported, lt::system_category())), std::move(prio));
    });
  }

  void async_clear_piece(lt::storage_index_t, lt::piece_index_t index
    , std::function<void(lt::piece_index_t)> handler) override
  {
    post(m_ioc, [=]{ handler(index); });
  }

  // implements buffer_allocator_interface
  void free_disk_buffer(char*) override
  {
    // never free any buffer. We only return buffers owned by the storage
    // object
  }

  void update_stats_counters(lt::counters&) const override {}

  std::vector<lt::open_file_state> get_status(lt::storage_index_t) const override
  { return {}; }

  void submit_jobs() override {}

private:

  lt::aux::vector<std::shared_ptr<temp_storage>, lt::storage_index_t> m_torrents;

  // slots that are unused in the m_torrents vector
  std::vector<lt::storage_index_t> m_free_slots;

  // callbacks are posted on this
  lt::io_context& m_ioc;
};

std::unique_ptr<lt::disk_interface> temp_disk_constructor(
  lt::io_context& ioc, lt::settings_interface const&, lt::counters&)
{
  return std::make_unique<temp_disk_io>(ioc);
}