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;

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
{
   explicit info_hash_t (sha256_hash h2) noexcept;
   info_hash_t (sha1_hash h1, sha256_hash h2) noexcept;
   explicit info_hash_t (sha1_hash h1) noexcept;
   info_hash_t () noexcept = default;
   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;
};

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

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 const&, protocol_version);

peer_info

Declared in "libtorrent/peer_info.hpp"

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

struct peer_info
{
   sha256_hash i2p_destination () const;

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

sha256_hash i2p_destination () const;

piece_block

Declared in "libtorrent/piece_block.hpp"

struct piece_block
{
   piece_block () = default;
   piece_block (piece_index_t p_index, int b_index);
   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;
};

version()

Declared in "libtorrent/version.hpp"

char const* version ();

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

load_torrent_buffer() load_torrent_file() load_torrent_parsed()

Declared in "libtorrent/load_torrent.hpp"

add_torrent_params load_torrent_file (
   std::string const& filename);
add_torrent_params load_torrent_parsed (
   bdecode_node const& torrent_file, load_torrent_limits const& cfg);
add_torrent_params load_torrent_file (
   std::string const& filename, load_torrent_limits const& cfg);
add_torrent_params load_torrent_buffer (
   span<char const> buffer);
add_torrent_params load_torrent_buffer (
   span<char const> buffer, load_torrent_limits const& cfg);
add_torrent_params load_torrent_parsed (
   bdecode_node const& torrent_file);

These functions load the content of a .torrent file into an add_torrent_params object. The immutable part of a torrent file (the info-dictionary) is stored in the ti field in the add_torrent_params object (as a torrent_info object). The returned object is suitable to be:

• added to a session via add_torrent() or async_add_torrent()
• saved as a .torrent_file via write_torrent_file()
• turned into a magnet link via make_magnet_uri()

torrent_peer_equal()

Declared in "libtorrent/torrent_peer.hpp"

inline bool torrent_peer_equal (torrent_peer const* lhs, torrent_peer const* rhs);

truncate_files()

Declared in "libtorrent/truncate.hpp"

void truncate_files (file_storage const& fs, std::string const& save_path, storage_error& ec);

Truncates files larger than specified in the file_storage, saved under the specified save_path.

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);
std::string make_magnet_uri (add_torrent_params const& atp);

Generates a magnet URI from the specified torrent.

Several fields from the add_torrent_params objects are recorded in the magnet link. In order to not include them, they have to be cleared before calling make_magnet_uri(). These fields are used:

ti, info_hashes, url_seeds, dht_nodes, file_priorities, trackers, name, peers.

Depending on what the use case for the resulting magnet link is, clearing peers and dht_nodes is probably a good idea if the add_torrent_params came from a running torrent. Those lists may be long and be ephemeral.

If none of the info_hashes or ti fields are set, there is not info-hash available, and a magnet link cannot be created. In this case make_magnet_uri() returns an empty string.

The recommended way to generate a magnet link from a torrent_handle is to call save_resume_data(), which will post a save_resume_data_alert containing an add_torrent_params object. This can then be passed to make_magnet_uri().

The overload that takes a torrent_handle will make blocking calls to query information about the 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"

void parse_magnet_uri (string_view uri, add_torrent_params& p, error_code& ec);
add_torrent_params parse_magnet_uri (string_view uri);
add_torrent_params parse_magnet_uri (string_view uri, 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.

enum protocol_version

Declared in "libtorrent/info_hash.hpp"

enum event_t

Declared in "libtorrent/tracker_manager.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 connection_type

Declared in "libtorrent/peer_connection.hpp"

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.

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

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

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, in the category if_metadata_changed. See resume_data_flags_t and save_resume_data() for details.

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.

default_dont_download

default all file priorities to dont_download. This is useful for adding magnet links where the number of files is unknown, but the file_priorities is still set for some files. Any file not covered by the file_priorities list will be set to normal download priority, unless this flag is set, in which case they will be set to 0 (dont_download).

i2p_torrent

this flag makes the torrent be considered an "i2p torrent" for purposes of the allow_i2p_mixed setting. When mixing regular peers and i2p peers is disabled, i2p torrents won't add normal peers to its peer list. Note that non i2p torrents may still allow i2p peers (on the off-chance that a tracker return them and the session is configured with a SAM connection). This flag is set automatically when adding a torrent that has at least one tracker whose hostname ends with .i2p. It's also set by parse_magnet_uri() if the tracker list contains such URL.

all

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

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 allow (socket_type_t const st, peer_class_t const peer_class);
   void disallow (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 allow (socket_type_t const st, peer_class_t const peer_class);
void disallow (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.

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_choked () const;
   bool is_interesting () 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;
   void disconnect (error_code const& ec, operation_t op
      , disconnect_severity_t = peer_connection_interface::normal);
   bool is_outgoing () const;
   bool is_disconnecting () const;
   bool is_connecting () 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;
};

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_failed (piece_index_t);
   virtual void on_piece_pass (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_failed (piece_index_t);
virtual void on_piece_pass (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_dont_have (piece_index_t);
   virtual bool on_not_interested ();
   virtual bool on_request (peer_request const&);
   virtual bool on_choke ();
   virtual bool on_interested ();
   virtual bool on_allowed_fast (piece_index_t);
   virtual bool on_have_all ();
   virtual bool on_have (piece_index_t);
   virtual bool on_unchoke ();
   virtual bool on_bitfield (bitfield const& /*bitfield*/);
   virtual bool on_have_none ();
   virtual bool on_piece (peer_request const& /*piece*/
      , span<char const> /*buf*/);
   virtual bool on_reject (peer_request const&);
   virtual bool on_suggest (piece_index_t);
   virtual bool on_cancel (peer_request const&);
   virtual void sent_request (peer_request const&);
   virtual void sent_suggest (piece_index_t);
   virtual void sent_reject_request (peer_request const&);
   virtual void sent_choke ();
   virtual void sent_have_none ();
   virtual void sent_allow_fast (piece_index_t);
   virtual void sent_have_all ();
   virtual void sent_cancel (peer_request const&);
   virtual void sent_piece (peer_request const&);
   virtual void sent_have (piece_index_t);
   virtual void sent_not_interested ();
   virtual void sent_unchoke ();
   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_failed (piece_index_t);
   virtual void on_piece_pass (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_dont_have (piece_index_t);
virtual bool on_not_interested ();
virtual bool on_request (peer_request const&);
virtual bool on_choke ();
virtual bool on_interested ();
virtual bool on_allowed_fast (piece_index_t);
virtual bool on_have_all ();
virtual bool on_have (piece_index_t);
virtual bool on_unchoke ();
virtual bool on_bitfield (bitfield const& /*bitfield*/);
virtual bool on_have_none ();

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

virtual void sent_piece (peer_request const&);
virtual void sent_have (piece_index_t);
virtual void sent_not_interested ();
virtual void sent_unchoke ();
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_failed (piece_index_t);
virtual void on_piece_pass (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;

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

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

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

client_data_t () = default;

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

add_torrent_params

Declared in "libtorrent/add_torrent_params.hpp"

The add_torrent_params contains all the information in a .torrent file along with all information necessary to add that torrent to a session. The key fields when adding a torrent are:

• ti - the immutable info-dict part of the torrent
• info_hash - when you don't have the metadata (.torrent file). This uniquely identifies the torrent and can validate the info-dict when received from the swarm.

In order to add a torrent to a session, one of those fields must be set in addition to save_path. The add_torrent_params object can then be 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().

The add_torrent_params is also used to represent a parsed .torrent file. It can be loaded via load_torrent_file(), load_torrent_buffer() and load_torrent_parsed(). It can be saved via write_torrent_file().

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. If this vector of file priorities is shorter than the number of files in the torrent, the remaining files (not covered by this) will still have the default download priority. This default can be changed by setting the default_dont_download torrent_flag.

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. A value of 0 means we don't know when we last uploaded or downloaded, or we have never uploaded or downloaded any payload for this torrent.

announce_infohash

Declared in "libtorrent/announce_entry.hpp"

struct announce_infohash
{
   std::string message;
   error_code last_error;
   int scrape_incomplete  = -1;
   int scrape_complete  = -1;
   int scrape_downloaded  = -1;
   std::uint8_t fails : 7;
   bool updating : 1;
   bool start_sent : 1;
   bool complete_sent : 1;
};

message

if this tracker has returned an error or warning message that message is stored here

last_error

if this tracker failed the last time it was contacted this error code specifies what error occurred

scrape_incomplete scrape_complete scrape_downloaded

if this tracker has returned scrape data, these fields are filled in with valid numbers. Otherwise they are set to -1. incomplete counts the number of current downloaders. complete counts the number of current peers completed the download, or "seeds". downloaded is the cumulative number of completed downloads.

fails

the number of times in a row we have failed to announce to this tracker.

updating

true while we're waiting for a response from the tracker.

start_sent

set to true when we get a valid response from an announce with event=started. If it is set, we won't send start in the subsequent announces.

complete_sent

set to true when we send a event=completed.

announce_endpoint

Declared in "libtorrent/announce_entry.hpp"

announces are sent to each tracker using every listen socket this class holds information about one listen socket for one tracker

struct announce_endpoint
{
   announce_endpoint ();

   tcp::endpoint local_endpoint;
   aux::array<announce_infohash, num_protocols, protocol_version> info_hashes;
   bool enabled  = true;
};

local_endpoint

the local endpoint of the listen interface associated with this endpoint

info_hashes

info_hashes[0] is the v1 info hash (SHA1) info_hashes[1] is the v2 info hash (truncated SHA-256)

enabled

set to false to not announce from this endpoint

announce_entry

Declared in "libtorrent/announce_entry.hpp"

this class holds information about one bittorrent tracker, as it relates to a specific torrent.

struct announce_entry
{
   ~announce_entry ();
   announce_entry& operator= (announce_entry const&) &;
   explicit announce_entry (string_view u);
   announce_entry (announce_entry const&);
   announce_entry ();

   enum tracker_source
   {
      source_torrent,
      source_client,
      source_magnet_link,
      source_tex,
   };

   std::string url;
   std::string trackerid;
   std::vector<announce_endpoint> endpoints;
   std::uint8_t tier  = 0;
   std::uint8_t fail_limit  = 0;
   std::uint8_t source:4;
   bool verified:1;
};

~announce_entry ();
announce_entry& operator= (announce_entry const&) &;
explicit announce_entry (string_view u);
announce_entry (announce_entry const&);
announce_entry ();

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() - std::int64_t(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);
}

settings_interface

Declared in "libtorrent/settings_pack.hpp"

the common interface to settings_pack and the internal representation of settings.

struct settings_interface
{
   virtual bool has_val (int name) const = 0;
   virtual void set_int (int name, int val) = 0;
   virtual void set_bool (int name, bool val) = 0;
   virtual void set_str (int name, std::string val) = 0;
   virtual bool get_bool (int name) const = 0;
   virtual int get_int (int name) const = 0;
   virtual std::string const& get_str (int name) const = 0;
};

disk_observer

Declared in "libtorrent/disk_observer.hpp"

struct disk_observer
{
   virtual void on_disk () = 0;
};

virtual void on_disk () = 0;

open_file_state

Declared in "libtorrent/disk_interface.hpp"

this contains information about a file that's currently open by the libtorrent disk I/O subsystem. It's associated with a single torrent.

struct open_file_state
{
   file_index_t file_index;
   file_open_mode_t open_mode;
   time_point last_use;
};

file_index

the index of the file this entry refers to into the file_storage file list of this torrent. This starts indexing at 0.

open_mode

open_mode is a bitmask of the file flags this file is currently opened with. For possible flags, see file_open_mode_t.

Note that the read/write mode is not a bitmask. The two least significant bits are used to represent the read/write mode. Those bits can be masked out using the rw_mask constant.

last_use

a (high precision) timestamp of when the file was last used.

disk_interface

Declared in "libtorrent/disk_interface.hpp"

The disk_interface is the customization point for disk I/O in libtorrent. implement this interface and provide a factory function to the session constructor use custom disk I/O. All functions on the disk subsystem (implementing disk_interface) are called from within libtorrent's network thread. For disk I/O to be performed in a separate thread, the disk subsystem has to manage that itself.

Although the functions are called async_*, they do not technically have to be asynchronous, but they support being asynchronous, by expecting the result passed back into a callback. The callbacks must be posted back onto the network thread via the io_context object passed into the constructor. The callbacks will be run in the network thread.

struct disk_interface
{
   virtual storage_holder new_torrent (storage_params const& p
      , std::shared_ptr<void> const& torrent) = 0;
   virtual void remove_torrent (storage_index_t) = 0;
   virtual void async_read (storage_index_t storage, peer_request const& r
      , std::function<void(disk_buffer_holder, storage_error const&)> handler
      , disk_job_flags_t flags = {}) = 0;
   virtual bool async_write (storage_index_t storage, peer_request const& r
      , char const* buf, std::shared_ptr<disk_observer> o
      , std::function<void(storage_error const&)> handler
      , disk_job_flags_t flags = {}) = 0;
   virtual void async_hash (storage_index_t storage, piece_index_t piece, span<sha256_hash> v2
      , disk_job_flags_t flags
      , std::function<void(piece_index_t, sha1_hash const&, storage_error const&)> handler) = 0;
   virtual void async_hash2 (storage_index_t storage, piece_index_t piece, int offset, disk_job_flags_t flags
      , std::function<void(piece_index_t, sha256_hash const&, storage_error const&)> handler) = 0;
   virtual void async_move_storage (storage_index_t storage, std::string p, move_flags_t flags
      , std::function<void(status_t, std::string const&, storage_error const&)> handler) = 0;
   virtual void async_release_files (storage_index_t storage
      , std::function<void()> handler = std::function<void()>()) = 0;
   virtual void async_check_files (storage_index_t storage
      , add_torrent_params const* resume_data
      , aux::vector<std::string, file_index_t> links
      , std::function<void(status_t, storage_error const&)> handler) = 0;
   virtual void async_stop_torrent (storage_index_t storage
      , std::function<void()> handler = std::function<void()>()) = 0;
   virtual void async_rename_file (storage_index_t storage
      , file_index_t index, std::string name
      , std::function<void(std::string const&, file_index_t, storage_error const&)> handler) = 0;
   virtual void async_delete_files (storage_index_t storage, remove_flags_t options
      , std::function<void(storage_error const&)> handler) = 0;
   virtual void async_set_file_priority (storage_index_t storage
      , aux::vector<download_priority_t, file_index_t> prio
      , std::function<void(storage_error const&
      , aux::vector<download_priority_t, file_index_t>)> handler) = 0;
   virtual void async_clear_piece (storage_index_t storage, piece_index_t index
      , std::function<void(piece_index_t)> handler) = 0;
   virtual void update_stats_counters (counters& c) const = 0;
   virtual std::vector<open_file_state> get_status (storage_index_t) const = 0;
   virtual void abort (bool wait) = 0;
   virtual void submit_jobs () = 0;
   virtual void settings_updated () = 0;

   static constexpr disk_job_flags_t force_copy  = 0_bit;
   static constexpr disk_job_flags_t sequential_access  = 3_bit;
   static constexpr disk_job_flags_t volatile_read  = 4_bit;
   static constexpr disk_job_flags_t v1_hash  = 5_bit;
   static constexpr disk_job_flags_t flush_piece  = 7_bit;
};

virtual storage_holder new_torrent (storage_params const& p
      , std::shared_ptr<void> const& torrent) = 0;

virtual void remove_torrent (storage_index_t) = 0;

virtual void async_read (storage_index_t storage, peer_request const& r
      , std::function<void(disk_buffer_holder, storage_error const&)> handler
      , disk_job_flags_t flags = {}) = 0;
virtual bool async_write (storage_index_t storage, peer_request const& r
      , char const* buf, std::shared_ptr<disk_observer> o
      , std::function<void(storage_error const&)> handler
      , disk_job_flags_t flags = {}) = 0;

virtual void async_hash (storage_index_t storage, piece_index_t piece, span<sha256_hash> v2
      , disk_job_flags_t flags
      , std::function<void(piece_index_t, sha1_hash const&, storage_error const&)> handler) = 0;

virtual void async_hash2 (storage_index_t storage, piece_index_t piece, int offset, disk_job_flags_t flags
      , std::function<void(piece_index_t, sha256_hash const&, storage_error const&)> handler) = 0;

virtual void async_move_storage (storage_index_t storage, std::string p, move_flags_t flags
      , std::function<void(status_t, std::string const&, storage_error const&)> handler) = 0;

virtual void async_release_files (storage_index_t storage
      , std::function<void()> handler = std::function<void()>()) = 0;

virtual void async_check_files (storage_index_t storage
      , add_torrent_params const* resume_data
      , aux::vector<std::string, file_index_t> links
      , std::function<void(status_t, storage_error const&)> handler) = 0;

virtual void async_stop_torrent (storage_index_t storage
      , std::function<void()> handler = std::function<void()>()) = 0;

virtual void async_rename_file (storage_index_t storage
      , file_index_t index, std::string name
      , std::function<void(std::string const&, file_index_t, storage_error const&)> handler) = 0;

virtual void async_delete_files (storage_index_t storage, remove_flags_t options
      , std::function<void(storage_error const&)> handler) = 0;

virtual void async_set_file_priority (storage_index_t storage
      , aux::vector<download_priority_t, file_index_t> prio
      , std::function<void(storage_error const&
      , aux::vector<download_priority_t, file_index_t>)> handler) = 0;

virtual void async_clear_piece (storage_index_t storage, piece_index_t index
      , std::function<void(piece_index_t)> handler) = 0;

virtual void update_stats_counters (counters& c) const = 0;

virtual std::vector<open_file_state> get_status (storage_index_t) const = 0;

virtual void abort (bool wait) = 0;

virtual void submit_jobs () = 0;

virtual void settings_updated () = 0;

storage_holder

Declared in "libtorrent/disk_interface.hpp"

a unique, owning, reference to the storage of a torrent in a disk io subsystem (class that implements disk_interface). This is held by the internal libtorrent torrent object to tie the storage object allocated for a torrent to the lifetime of the internal torrent object. When a torrent is removed from the session, this holder is destructed and will inform the disk object.

struct storage_holder
{
   storage_holder () = default;
   ~storage_holder ();
   storage_holder (storage_index_t idx, disk_interface& disk_io);
   explicit operator bool () const;
   operator storage_index_t () const;
   void reset ();
   storage_holder& operator= (storage_holder const&) = delete;
   storage_holder (storage_holder const&) = delete;
   storage_holder (storage_holder&& rhs) noexcept;
   storage_holder& operator= (storage_holder&& rhs) noexcept;
};

buffer_allocator_interface

Declared in "libtorrent/disk_buffer_holder.hpp"

the interface for freeing disk buffers, used by the disk_buffer_holder. when implementing disk_interface, this must also be implemented in order to return disk buffers back to libtorrent

struct buffer_allocator_interface
{
   virtual void free_disk_buffer (char* b) = 0;
};

disk_buffer_holder

Declared in "libtorrent/disk_buffer_holder.hpp"

The disk buffer holder acts like a unique_ptr that frees a disk buffer when it's destructed

If this buffer holder is moved-from, default constructed or reset, data() will return nullptr.

struct disk_buffer_holder
{
   disk_buffer_holder (disk_buffer_holder&&) noexcept;
   disk_buffer_holder& operator= (disk_buffer_holder&&) & noexcept;
   disk_buffer_holder& operator= (disk_buffer_holder const&) = delete;
   disk_buffer_holder (disk_buffer_holder const&) = delete;
   disk_buffer_holder (buffer_allocator_interface& alloc
      , char* buf, int sz) noexcept;
   disk_buffer_holder () noexcept = default;
   ~disk_buffer_holder ();
   char* data () const noexcept;
   void reset ();
   void swap (disk_buffer_holder& h) noexcept;
   bool is_mutable () const noexcept;
   explicit operator bool () const noexcept;
   std::ptrdiff_t size () const;
};

disk_buffer_holder (buffer_allocator_interface& alloc
      , char* buf, int sz) noexcept;

disk_buffer_holder () noexcept = default;

~disk_buffer_holder ();

char* data () const noexcept;

void reset ();

void swap (disk_buffer_holder& h) noexcept;

bool is_mutable () const noexcept;

explicit operator bool () const noexcept;

file_open_mode_t

Declared in "libtorrent/disk_interface.hpp"

read_only

open the file for reading only

write_only

open the file for writing only

read_write

open the file for reading and writing

rw_mask

the mask for the bits determining read or write mode

sparse

open the file in sparse mode (if supported by the filesystem).

no_atime

don't update the access timestamps on the file (if supported by the operating system and filesystem). this generally improves disk performance.

random_access

open the file for random access. This disables read-ahead logic

mmapped

the file is memory mapped

You have some control over session configuration through the session::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().

The settings_pack object is a collection of settings updates that are applied to the session when passed to session::apply_settings(). It's empty when constructed.

You have control over proxy and authorization settings and also the user-agent that will be sent to the tracker. The user-agent will also be used to identify the client with other peers.

Each configuration option is named with an enum value inside the settings_pack class. These are the available settings:

settings_pack

Declared in "libtorrent/settings_pack.hpp"

The settings_pack struct, contains the names of all settings as enum values. These values are passed in to the set_str(), set_int(), set_bool() functions, to specify the setting to change.

The settings_pack only stores values for settings that have been explicitly set on this object. However, it can still be queried for settings that have not been set and returns the default value for those settings.

this is the client identification to the tracker. The recommended format of this string is: "client-name/client-version libtorrent/libtorrent-version". This name will not only be used when making HTTP requests, but also when sending extended headers to peers that support that extension. It may not contain r or n

announce_ip is the ip address passed along to trackers as the &ip= parameter. If left as the default, that parameter is omitted.

this is the client name and version identifier sent to peers in the handshake message. If this is an empty string, the user_agent is used instead. This string must be a UTF-8 encoded unicode string.

This controls which IP address outgoing TCP peer connections are bound to, in addition to controlling whether such connections are also bound to a specific network interface/adapter (bind-to-device).

This string is a comma-separated list of IP addresses and interface names. An empty string will not bind TCP sockets to a device, and let the network stack assign the local address.

A list of names will be used to bind outgoing TCP sockets in a round-robin fashion. An IP address will simply be used to bind() the socket. An interface name will attempt to bind the socket to that interface. If that fails, or is unsupported, one of the IP addresses configured for that interface is used to bind() the socket to. If the interface or adapter doesn't exist, the outgoing peer connection will fail with an error message suggesting the device cannot be found. Adapter names on Unix systems are of the form "eth0", "eth1", "tun0", etc. This may be useful for clients that are multi-homed. Binding an outgoing connection to a local IP does not necessarily make the connection via the associated NIC/Adapter.

When outgoing interfaces are specified, incoming connections or packets sent to a local interface or IP that's not in this list will be rejected with a peer_blocked_alert with invalid_local_interface as the reason.

Note that these are just interface/adapter names or IP addresses. There are no ports specified in this list. IPv6 addresses without port should be specified without enclosing [, ].

a comma-separated list of (IP or device name, port) pairs. These are the listen ports that will be opened for accepting incoming uTP and TCP peer connections. These are also used for outgoing uTP and UDP tracker connections and DHT nodes.

It is possible to listen on multiple interfaces and multiple ports. Binding to port 0 will make the operating system pick the port.

A port that has an "s" suffix will accept SSL peer connections. (note that SSL sockets are only available in builds with SSL support)

A port that has an "l" suffix will be considered a local network. i.e. it's assumed to only be able to reach hosts in the same local network as the IP address (based on the netmask associated with the IP, queried from the operating system).

if binding fails, the listen_failed_alert is posted. Once a socket binding succeeds (if it does), the listen_succeeded_alert is posted. There may be multiple failures before a success.

If a device name that does not exist is configured, no listen socket will be opened for that interface. If this is the only interface configured, it will be as if no listen ports are configured.

If no listen ports are configured (e.g. listen_interfaces is an empty string), networking will be disabled. No DHT will start, no outgoing uTP or tracker connections will be made. No incoming TCP or uTP connections will be accepted. (outgoing TCP connections will still be possible, depending on settings_pack::outgoing_interfaces).

For example: [::1]:8888 - will only accept connections on the IPv6 loopback address on port 8888.

eth0:4444,eth1:4444 - will accept connections on port 4444 on any IP address bound to device eth0 or eth1.

[::]:0s - will accept SSL connections on a port chosen by the OS. And not accept non-SSL connections at all.

0.0.0.0:6881,[::]:6881 - binds to all interfaces on port 6881.

10.0.1.13:6881l - binds to the local IP address, port 6881, but only allow talking to peers on the same local network. The netmask is queried from the operating system. Interfaces marked l are not announced to trackers, unless the tracker is also on the same local network.

Windows OS network adapter device name must be specified with GUID. It can be obtained from "netsh lan show interfaces" command output. GUID must be uppercased string embraced in curly brackets. {E4F0B674-0DFC-48BB-98A5-2AA730BDB6D6}:7777 - will accept connections on port 7777 on adapter with this GUID.

For more information, see the Multi-homed hosts section.

when using a proxy, this is the hostname where the proxy is running see proxy_type. Note that when using a proxy, the settings_pack::listen_interfaces setting is overridden and only a single interface is created, just to contact the proxy. This means a proxy cannot be combined with SSL torrents or multiple listen interfaces. This proxy listen interface will not accept incoming TCP connections, will not map ports with any gateway and will not enable local service discovery. All traffic is supposed to be channeled through the proxy.

when using a proxy, these are the credentials (if any) to use when connecting to it. see proxy_type

sets the i2p SAM bridge to connect to. set the port with the i2p_port setting. Unless this is set, i2p torrents are not supported. This setting is separate from the other proxy settings since i2p torrents and their peers are orthogonal. You can have i2p peers as well as regular peers via a proxy.

this is the fingerprint for the client. It will be used as the prefix to the peer_id. If this is 20 bytes (or longer) it will be truncated to 20 bytes and used as the entire peer-id

There is a utility function, generate_fingerprint() that can be used to generate a standard client peer ID fingerprint prefix.

This is a comma-separated list of IP port-pairs. They will be added to the DHT node (if it's enabled) as back-up nodes in case we don't know of any.

Changing these after the DHT has been started may not have any effect until the DHT is restarted.

determines if connections from the same IP address as existing connections should be rejected or not. Rejecting multiple connections from the same IP address will prevent abusive behavior by peers. The logic for determining whether connections are to the same peer is more complicated with this enabled, and more likely to fail in some edge cases. It is not recommended to enable this feature.

send_redundant_have controls if have messages will be sent to peers that already have the piece. This is typically not necessary, but it might be necessary for collecting statistics in some cases.

use_dht_as_fallback determines how the DHT is used. If this is true, the DHT will only be used for torrents where all trackers in its tracker list has failed. Either by an explicit error message or a time out. If this is false, the DHT is used regardless of if the trackers fail or not.

upnp_ignore_nonrouters indicates whether or not the UPnP implementation should ignore any broadcast response from a device whose address is not on our subnet. i.e. it's a way to not talk to other people's routers by mistake.

use_parole_mode specifies if parole mode should be used. Parole mode means that peers that participate in pieces that fail the hash check are put in a mode where they are only allowed to download whole pieces. If the whole piece a peer in parole mode fails the hash check, it is banned. If a peer participates in a piece that passes the hash check, it is taken out of parole mode.

if true, prefer seeding torrents when determining which torrents to give active slots to. If false, give preference to downloading torrents

if dont_count_slow_torrents is true, torrents without any payload transfers are not subject to the active_seeds and active_downloads limits. This is intended to make it more likely to utilize all available bandwidth, and avoid having torrents that don't transfer anything block the active slots.

close_redundant_connections specifies whether libtorrent should close connections where both ends have no utility in keeping the connection open. For instance if both ends have completed their downloads, there's no point in keeping it open.

If prioritize_partial_pieces is true, partial pieces are picked before pieces that are more rare. If false, rare pieces are always prioritized, unless the number of partial pieces is growing out of proportion.

if set to true, the estimated TCP/IP overhead is drained from the rate limiters, to avoid exceeding the limits with the total traffic

announce_to_all_trackers controls how multi tracker torrents are treated. If this is set to true, all trackers in the same tier are announced to in parallel. If all trackers in tier 0 fails, all trackers in tier 1 are announced as well. If it's set to false, the behavior is as defined by the multi tracker specification.

announce_to_all_tiers also controls how multi tracker torrents are treated. When this is set to true, one tracker from each tier is announced to. This is the uTorrent behavior. To be compliant with the Multi-tracker specification, set it to false.

prefer_udp_trackers: true means that trackers may be rearranged in a way that udp trackers are always tried before http trackers for the same hostname. Setting this to false means that the tracker's tier is respected and there's no preference of one protocol over another.

when set to true, all data downloaded from peers will be assumed to be correct, and not tested to match the hashes in the torrent this is only useful for simulation and testing purposes (typically combined with disabled_storage)

if this is true, i2p torrents are allowed to also get peers from other sources than the tracker, and connect to regular IPs, not providing any anonymization. This may be useful if the user is not interested in the anonymization of i2p, but still wants to be able to connect to i2p peers.

no_atime_storage this is a Linux-only option and passes in the O_NOATIME to open() when opening files. This may lead to some disk performance improvements.

incoming_starts_queued_torrents. If a torrent has been paused by the auto managed feature in libtorrent, i.e. the torrent is paused and auto managed, this feature affects whether or not it is automatically started on an incoming connection. The main reason to queue torrents, is not to make them unavailable, but to save on the overhead of announcing to the trackers, the DHT and to avoid spreading one's unchoke slots too thin. If a peer managed to find us, even though we're no in the torrent anymore, this setting can make us start the torrent and serve it.

when set to true, the downloaded counter sent to trackers will include the actual number of payload bytes downloaded including redundant bytes. If set to false, it will not include any redundancy bytes

strict_end_game_mode controls when a block may be requested twice. If this is true, a block may only be requested twice when there's at least one request to every piece that's left to download in the torrent. This may slow down progress on some pieces sometimes, but it may also avoid downloading a lot of redundant bytes. If this is false, libtorrent attempts to use each peer connection to its max, by always requesting something, even if it means requesting something that has been requested from another peer already.

Enables incoming and outgoing, TCP and uTP peer connections. false is disabled and true is enabled. When outgoing connections are disabled, libtorrent will simply not make outgoing peer connections with the specific transport protocol. Disabled incoming peer connections will simply be rejected. These options only apply to peer connections, not tracker- or any other kinds of connections.

no_recheck_incomplete_resume determines if the storage should check the whole files when resume data is incomplete or missing or whether it should simply assume we don't have any of the data. If false, any existing files will be checked. By setting this setting to true, the files won't be checked, but will go straight to download mode.

anonymous_mode: When set to true, the client tries to hide its identity to a certain degree.

• A generic user-agent will be used for trackers (except for private torrents).
• Your local IPv4 and IPv6 address won't be sent as query string parameters to private trackers.
• If announce_ip is configured, it will not be sent to trackers
• The client version will not be sent to peers in the extension handshake.

specifies whether downloads from web seeds is reported to the tracker or not. Turning it off also excludes web seed traffic from other stats and download rate reporting via the libtorrent API.

seeding_outgoing_connections determines if seeding (and finished) torrents should attempt to make outgoing connections or not. It may be set to false in very specific applications where the cost of making outgoing connections is high, and there are no or small benefits of doing so. For instance, if no nodes are behind a firewall or a NAT, seeds don't need to make outgoing connections.

when this is true, libtorrent will not attempt to make outgoing connections to peers whose port is < 1024. This is a safety precaution to avoid being part of a DDoS attack

smooth_connects means the number of connection attempts per second may be limited to below the connection_speed, in case we're close to bump up against the limit of number of connections. The intention of this setting is to more evenly distribute our connection attempts over time, instead of attempting to connect in batches, and timing them out in batches.

always send user-agent in every web seed request. If false, only the first request per http connection will include the user agent

apply_ip_filter_to_trackers determines whether the IP filter applies to trackers as well as peers. If this is set to false, trackers are exempt from the IP filter (if there is one). If no IP filter is set, this setting is irrelevant.

when true, web seeds sending bad data will be banned

if false, prevents libtorrent to advertise share-mode support

if this is true, the number of redundant bytes is sent to the tracker

if this is true, libtorrent will fall back to listening on a port chosen by the operating system (i.e. binding to port 0). If a failure is preferred, set this to false.

when this is true, and incoming encrypted connections are enabled, &supportcrypt=1 is included in http tracker announces

Starts and stops the UPnP service. When started, the listen port and the DHT port are attempted to be forwarded on local UPnP router devices.

The upnp object returned by start_upnp() can be used to add and remove arbitrary port mappings. Mapping status is returned through the portmap_alert and the portmap_error_alert. The object will be valid until stop_upnp() is called. See upnp and nat pmp.

Starts and stops the NAT-PMP service. When started, the listen port and the DHT port are attempted to be forwarded on the router through NAT-PMP.

The natpmp object returned by start_natpmp() can be used to add and remove arbitrary port mappings. Mapping status is returned through the portmap_alert and the portmap_error_alert. The object will be valid until stop_natpmp() is called. See upnp and nat pmp.

Starts and stops Local Service Discovery. This service will broadcast the info-hashes of all the non-private torrents on the local network to look for peers on the same swarm within multicast reach.