Version: | 2.0.13

home

Table of contents

- peer_info
  - i2p_destination()
- piece_block
- info_hash_t
  - info_hash_t()
  - has_v2() has() has_v1()
  - get()
  - get_best()
- peer_request
  - operator==()
- torrent_peer_equal()
- load_torrent_file() load_torrent_buffer() load_torrent_parsed()
- version()
- make_magnet_uri()
- parse_magnet_uri()
- truncate_files()
- enum socket_type_t
- enum connection_type
- enum portmap_transport
- enum portmap_protocol
- enum event_t
- enum protocol_version
- int
- char const*
- std::uint64_t
- pex_flags_t
- torrent_flags_t
- download_priority_t

[report issue]

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

[report issue]

## i2p_destination()

    sha256_hash i2p_destination () const;

If this peer is an i2p peer, this function returns the destination address of the peer

[report issue]

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

[report issue]

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

[report issue]

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

[report issue]

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

[report issue]

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

[report issue]

interesting
  we are interested in pieces from this peer.

[report issue]

choked
  we have choked this peer.

[report issue]

remote_interested
  the peer is interested in us

[report issue]

remote_choked
  the peer has choked us.

[report issue]

supports_extensions
  means that this peer supports the extension protocol.

[report issue]

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

[report issue]

local_connection
  deprecated synonym for outgoing_connection

[report issue]

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

[report issue]

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

[report issue]

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

[report issue]

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

[report issue]

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

[report issue]

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

[report issue]

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

[report issue]

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

[report issue]

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

[report issue]

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

[report issue]

utp_socket
  indicates that this socket is a uTP socket

[report issue]

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

[report issue]

rc4_encrypted
  this connection is obfuscated with RC4

[report issue]

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

[report issue]

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

[report issue]

tracker
  The peer was received from the tracker.

[report issue]

dht
  The peer was received from the kademlia DHT.

[report issue]

pex
  The peer was received from the peer exchange extension.

[report issue]

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

[report issue]

resume_data
  The peer was added from the fast resume data.

[report issue]

incoming
  we received an incoming connection from this peer

[report issue]

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

[report issue]

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

[report issue]

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

[report issue]

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

[report issue]

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

[report issue]

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

[report issue]

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

[report issue]

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

[report issue]

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

[report issue]

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

[report issue]

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

[report issue]

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

[report issue]

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

[report issue]

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

[report issue]

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

[report issue]

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

[report issue]

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

[report issue]

standard_bittorrent
  Regular bittorrent connection

[report issue]

web_seed
  HTTP connection using the BEP 19 protocol

[report issue]

http_seed
  HTTP connection using the BEP 17 protocol

[report issue]

connection_type
  the kind of connection this peer uses. See connection_type_t.

[report issue]

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

[report issue]

pending_disk_read_bytes
  number of outstanding bytes to read from disk

[report issue]

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

[report issue]

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

[report issue]

num_pieces
  the number of pieces this peer has.

[report issue]

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

[report issue]

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

[report issue]

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

[report issue]

ip
  the IP-address to this peer. The type is an asio endpoint. For more info, see the asio documentation. This field is not valid for i2p peers. Instead use the i2p_destination() function.

[report issue]

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

[report issue]

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

[report issue]

bw_limit
  The peer is waiting for the rate limiter.

[report issue]

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

[report issue]

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

[report issue]

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

[report issue]

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

[report issue]

# 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.

Note

If `has_v2()` is false then the v1 hash might actually be a truncated v2 hash

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

[report issue]

## info_hash_t()

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

The default constructor creates an object that has neither a v1 or v2 hash.

For backwards compatibility, make it possible to construct directly from a v1 hash. This constructor allows implicit conversion from a v1 hash, but the implicitness is deprecated.

[report issue]

## has_v2() has() has_v1()

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

returns true if the corresponding info hash is present in this object.

[report issue]

## get()

    sha1_hash get (protocol_version v) const;

returns the has for the specified protocol version

[report issue]

## get_best()

    sha1_hash get_best () const;

returns the v2 (truncated) info-hash, if there is one, otherwise returns the v1 info-hash

[report issue]

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

[report issue]

## operator==()

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

returns true if the right hand side peer_request refers to the same range as this does.

[report issue]

piece
  The index of the piece in which the range starts.

[report issue]

start
  The byte offset within that piece where the range starts.

[report issue]

length
  The size of the range, in bytes.

[report issue]

# torrent_peer_equal()

Declared in "libtorrent/torrent_peer.hpp"

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

[report issue]

# load_torrent_file() load_torrent_buffer() load_torrent_parsed()

Declared in "libtorrent/load_torrent.hpp"

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

[report issue]

# version()

Declared in "libtorrent/version.hpp"

    char const* version ();

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

[report issue]

# make_magnet_uri()

Declared in "libtorrent/magnet_uri.hpp"

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

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.

[report issue]

# parse_magnet_uri()

Declared in "libtorrent/magnet_uri.hpp"

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

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

[report issue]

# 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.

[report issue]

# enum socket_type_t

Declared in "libtorrent/socket_type.hpp"

name | value | description
--- | --- | ---
tcp | 0 |
socks5 | 1 |
http | 2 |
utp | 3 |
i2p | 4 |
tcp_ssl | 5 |
socks5_ssl | 6 |
http_ssl | 7 |
utp_ssl | 8 |

[report issue]

# enum connection_type

Declared in "libtorrent/peer_connection.hpp"

name | value | description
--- | --- | ---
bittorrent | 0 |
url_seed | 1 |
http_seed | 2 |

[report issue]

# enum portmap_transport

Declared in "libtorrent/portmap.hpp"

name | value | description
--- | --- | ---
natpmp | 0 | natpmp can be NAT-PMP or PCP
upnp | 1 |

[report issue]

# enum portmap_protocol

Declared in "libtorrent/portmap.hpp"

name | value | description
--- | --- | ---
none | 0 |
tcp | 1 |
udp | 2 |

[report issue]

# enum event_t

Declared in "libtorrent/tracker_manager.hpp"

name | value | description
--- | --- | ---
none | 0 |
completed | 1 |
started | 2 |
stopped | 3 |
paused | 4 |

[report issue]

# enum protocol_version

Declared in "libtorrent/info_hash.hpp"

name | value | description
--- | --- | ---
V1 | 0 | The original BitTorrent version, using SHA-1 hashes
V2 | 1 | Version 2 of the BitTorrent protocol, using SHA-256 hashes
NUM | 2 |

[report issue]

# 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

[report issue]

# char const*

Declared in "libtorrent/version.hpp"

version_str
  the libtorrent version in string form

[report issue]

# std::uint64_t

Declared in "libtorrent/version.hpp"

version_revision
  the git commit of this libtorrent version

[report issue]

# 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

[report issue]

# 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

[report issue]

# 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.