Version: | 2.0.10 |
---|
Table of contents
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]
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]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 (sha1_hash h1) noexcept; info_hash_t () noexcept = default; explicit info_hash_t (sha256_hash h2) noexcept; info_hash_t (sha1_hash h1, sha256_hash h2) noexcept; bool has_v2 () const; bool has_v1 () const; bool has (protocol_version v) 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; };[report issue]
explicit info_hash_t (sha1_hash h1) noexcept; info_hash_t () noexcept = default; explicit info_hash_t (sha256_hash h2) noexcept; 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]bool has_v2 () const; bool has_v1 () const; bool has (protocol_version v) const;
returns true if the corresponding info hash is present in this object.
[report issue]sha1_hash get (protocol_version v) const;
returns the has for the specified protocol version
[report issue]sha1_hash get_best () const;
returns the v2 (truncated) info-hash, if there is one, otherwise returns the v1 info-hash
[report issue]template <typename F> void for_each (F f) const;
calls the function object f for each hash that is available. starting with v1. The signature of F is:
void(sha1_hash const&, protocol_version);[report issue]
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]
sha256_hash i2p_destination () const;
If this peer is an i2p peer, this function returns the destination address of the peer
[report issue]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]
Declared in "libtorrent/version.hpp"
char const* version ();
returns the libtorrent version as string form in this format: "<major>.<minor>.<tiny>.<tag>"
[report issue]Declared in "libtorrent/load_torrent.hpp"
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_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_buffer ( span<char const> buffer);
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:
[report issue]
- 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()
Declared in "libtorrent/torrent_peer.hpp"
inline bool torrent_peer_equal (torrent_peer const* lhs, torrent_peer const* rhs);[report issue]
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]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.
[report issue]Declared in "libtorrent/magnet_uri.hpp"
add_torrent_params parse_magnet_uri (string_view uri); void parse_magnet_uri (string_view uri, add_torrent_params& p, error_code& ec); 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.
[report issue]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 |
Declared in "libtorrent/tracker_manager.hpp"
name | value | description |
---|---|---|
none | 0 | |
completed | 1 | |
started | 2 | |
stopped | 3 | |
paused | 4 |
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 |
Declared in "libtorrent/portmap.hpp"
name | value | description |
---|---|---|
natpmp | 0 | natpmp can be NAT-PMP or PCP |
upnp | 1 |
Declared in "libtorrent/portmap.hpp"
name | value | description |
---|---|---|
none | 0 | |
tcp | 1 | |
udp | 2 |
Declared in "libtorrent/peer_connection.hpp"
name | value | description |
---|---|---|
bittorrent | 0 | |
url_seed | 1 | |
http_seed | 2 |
Declared in "libtorrent/download_priority.hpp"
Declared in "libtorrent/version.hpp"
Declared in "libtorrent/version.hpp"
Declared in "libtorrent/version.hpp"
Declared in "libtorrent/pex_flags.hpp"
Declared in "libtorrent/torrent_flags.hpp"
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.
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.
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.
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.
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
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.