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
{
   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_v1 () const;
   bool has (protocol_version v) const;
   bool has_v2 () 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_v1 () const;
bool has (protocol_version v) const;
bool has_v2 () 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 (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;
};

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_parsed() load_torrent_buffer() load_torrent_file()

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_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);
add_torrent_params load_torrent_file (
   std::string const& filename, load_torrent_limits const& cfg);

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

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"

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

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