--- /srv/reproducible-results/rbuild-debian/r-b-build.TfX4sa1x/b1/libtorrent-rasterbar_2.0.8-1_i386.changes +++ /srv/reproducible-results/rbuild-debian/r-b-build.TfX4sa1x/b2/libtorrent-rasterbar_2.0.8-1_i386.changes ├── Files │ @@ -1,7 +1,7 @@ │ │ ca4eaa506fdaf16efe0f4e25204e2d69 360876 libdevel optional libtorrent-rasterbar-dev_2.0.8-1_i386.deb │ - bbbba924c859bb217b1264d730ec9336 1605400 doc optional libtorrent-rasterbar-doc_2.0.8-1_all.deb │ + fb09736113d01318ed62b6a64677c47e 1605456 doc optional libtorrent-rasterbar-doc_2.0.8-1_all.deb │ 90f55a27da21b3f872d4e8e7ae3c264b 51219292 debug optional libtorrent-rasterbar2.0-dbgsym_2.0.8-1_i386.deb │ 851b3393141f98e5fe278da79d0627b6 1697800 libs optional libtorrent-rasterbar2.0_2.0.8-1_i386.deb │ 488e2f4cf7820921525252a58b0e5f46 12736700 debug optional python3-libtorrent-dbgsym_2.0.8-1_i386.deb │ - 7b5df70d421f9a723ecbd2f96a36fdf3 702280 python optional python3-libtorrent_2.0.8-1_i386.deb │ + ade52be24c0beda7158d57166d719879 702276 python optional python3-libtorrent_2.0.8-1_i386.deb ├── libtorrent-rasterbar-doc_2.0.8-1_all.deb │ ├── file list │ │ @@ -1,3 +1,3 @@ │ │ -rw-r--r-- 0 0 0 4 2022-10-23 15:10:21.000000 debian-binary │ │ -rw-r--r-- 0 0 0 3632 2022-10-23 15:10:21.000000 control.tar.xz │ │ --rw-r--r-- 0 0 0 1601576 2022-10-23 15:10:21.000000 data.tar.xz │ │ +-rw-r--r-- 0 0 0 1601632 2022-10-23 15:10:21.000000 data.tar.xz │ ├── control.tar.xz │ │ ├── control.tar │ │ │ ├── ./control │ │ │ │ @@ -1,13 +1,13 @@ │ │ │ │ Package: libtorrent-rasterbar-doc │ │ │ │ Source: libtorrent-rasterbar │ │ │ │ Version: 2.0.8-1 │ │ │ │ Architecture: all │ │ │ │ Maintainer: Christian Marillat │ │ │ │ -Installed-Size: 5793 │ │ │ │ +Installed-Size: 5709 │ │ │ │ Section: doc │ │ │ │ Priority: optional │ │ │ │ Multi-Arch: foreign │ │ │ │ Homepage: https://libtorrent.org/ │ │ │ │ Description: Documentation for libtorrent-rasterbar │ │ │ │ Bittorrent library by Rasterbar Software (Arvid Norberg). │ │ │ │ libtorrent-rasterbar is a C++ library that aims to be a good alternative to │ │ │ ├── ./md5sums │ │ │ │ ├── ./md5sums │ │ │ │ │┄ Files differ │ ├── data.tar.xz │ │ ├── data.tar │ │ │ ├── file list │ │ │ │ @@ -101,15 +101,15 @@ │ │ │ │ -rw-r--r-- 0 root (0) root (0) 54531 2022-10-23 15:10:21.000000 ./usr/share/doc/libtorrent-rasterbar-doc/html/reference-Torrent_Info.html │ │ │ │ -rw-r--r-- 0 root (0) root (0) 48252 2022-10-23 15:10:21.000000 ./usr/share/doc/libtorrent-rasterbar-doc/html/reference-Torrent_Status.html │ │ │ │ -rw-r--r-- 0 root (0) root (0) 16422 2022-10-23 15:10:21.000000 ./usr/share/doc/libtorrent-rasterbar-doc/html/reference-Trackers.html │ │ │ │ -rw-r--r-- 0 root (0) root (0) 24490 2022-10-23 15:10:21.000000 ./usr/share/doc/libtorrent-rasterbar-doc/html/reference-Utility.html │ │ │ │ -rw-r--r-- 0 root (0) root (0) 9085 2022-10-23 15:10:21.000000 ./usr/share/doc/libtorrent-rasterbar-doc/html/reference-ed25519.html │ │ │ │ -rw-r--r-- 0 root (0) root (0) 33602 2022-10-23 15:10:21.000000 ./usr/share/doc/libtorrent-rasterbar-doc/html/reference.html │ │ │ │ -rw-r--r-- 0 root (0) root (0) 29147 2022-10-23 15:10:21.000000 ./usr/share/doc/libtorrent-rasterbar-doc/html/security-audit.html │ │ │ │ --rw-r--r-- 0 root (0) root (0) 1334381 2022-10-23 15:10:21.000000 ./usr/share/doc/libtorrent-rasterbar-doc/html/single-page-ref.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 1248308 2022-10-23 15:10:21.000000 ./usr/share/doc/libtorrent-rasterbar-doc/html/single-page-ref.html │ │ │ │ -rw-r--r-- 0 root (0) root (0) 10121 2022-10-23 15:10:21.000000 ./usr/share/doc/libtorrent-rasterbar-doc/html/streaming.html │ │ │ │ -rw-r--r-- 0 root (0) root (0) 6746 2022-10-23 11:28:40.000000 ./usr/share/doc/libtorrent-rasterbar-doc/html/style.css │ │ │ │ -rw-r--r-- 0 root (0) root (0) 520020 2022-10-23 15:10:21.000000 ./usr/share/doc/libtorrent-rasterbar-doc/html/todo.html │ │ │ │ -rw-r--r-- 0 root (0) root (0) 3021 2022-10-23 15:10:21.000000 ./usr/share/doc/libtorrent-rasterbar-doc/html/troubleshooting.html │ │ │ │ -rw-r--r-- 0 root (0) root (0) 25025 2022-10-23 15:10:21.000000 ./usr/share/doc/libtorrent-rasterbar-doc/html/tuning-ref.html │ │ │ │ -rw-r--r-- 0 root (0) root (0) 132588 2022-10-23 15:10:21.000000 ./usr/share/doc/libtorrent-rasterbar-doc/html/tutorial-ref.html │ │ │ │ -rw-r--r-- 0 root (0) root (0) 16305 2022-10-23 15:10:21.000000 ./usr/share/doc/libtorrent-rasterbar-doc/html/udp_tracker_protocol.html │ │ │ ├── ./usr/share/doc/libtorrent-rasterbar-doc/html/single-page-ref.html │ │ │ │ @@ -28,4179 +28,1829 @@ │ │ │ │ 2.0.8 │ │ │ │ │ │ │ │ │ │ │ │

home

│ │ │ │
│ │ │ │

Table of contents

│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -

bdecode_node

│ │ │ │ -

Declared in "libtorrent/bdecode.hpp"

│ │ │ │ -

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

│ │ │ │ -

There are 5 different types of nodes, see type_t.

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

bdecode_node()

│ │ │ │ -
│ │ │ │ -bdecode_node () = default;
│ │ │ │ -
│ │ │ │ -

creates a default constructed node, it will have the type none_t.

│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

bdecode_node() operator=()

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

For owning nodes, the copy will create a copy of the tree, but the │ │ │ │ -underlying buffer remains the same.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

type()

│ │ │ │ -
│ │ │ │ -type_t type () const noexcept;
│ │ │ │ -
│ │ │ │ -

the type of this node. See type_t.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

bool()

│ │ │ │ -
│ │ │ │ -explicit operator bool () const noexcept;
│ │ │ │ -
│ │ │ │ -

returns true if type() != none_t.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

non_owning()

│ │ │ │ -
│ │ │ │ -bdecode_node non_owning () const;
│ │ │ │ -
│ │ │ │ -

return a non-owning reference to this node. This is useful to refer to │ │ │ │ -the root node without copying it in assignments.

│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

data_offset() data_section()

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

returns the buffer and length of the section in the original bencoded │ │ │ │ -buffer where this node is defined. For a dictionary for instance, this │ │ │ │ -starts with d and ends with e, and has all the content of the │ │ │ │ -dictionary in between. │ │ │ │ -the data_offset() function returns the byte-offset to this node in, │ │ │ │ -starting from the beginning of the buffer that was parsed.

│ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

list_int_value_at() list_size() list_at() list_string_value_at()

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

functions with the list_ prefix operate on lists. These functions are │ │ │ │ -only valid if type() == list_t. list_at() returns the item │ │ │ │ -in the list at index i. i may not be greater than or equal to the │ │ │ │ -size of the list. size() returns the size of the list.

│ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

dict_at() dict_find_dict() dict_find_int_value() dict_find() dict_find_int() dict_at_node() dict_find_string() dict_find_string_value() dict_find_list() dict_size()

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

Functions with the dict_ prefix operates on dictionaries. They are │ │ │ │ -only valid if type() == dict_t. In case a key you're looking up │ │ │ │ -contains a 0 byte, you cannot use the 0-terminated string overloads, │ │ │ │ -but have to use string_view instead. dict_find_list will return a │ │ │ │ -valid bdecode_node if the key is found _and_ it is a list. Otherwise │ │ │ │ -it will return a default-constructed bdecode_node.

│ │ │ │ -

Functions with the _value suffix return the value of the node │ │ │ │ -directly, rather than the nodes. In case the node is not found, or it has │ │ │ │ -a different type, a default value is returned (which can be specified).

│ │ │ │ -

dict_at() returns the (key, value)-pair at the specified index in a │ │ │ │ -dictionary. Keys are only allowed to be strings. dict_at_node() also │ │ │ │ -returns the (key, value)-pair, but the key is returned as a │ │ │ │ -bdecode_node (and it will always be a string).

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

int_value()

│ │ │ │ -
│ │ │ │ -std::int64_t int_value () const;
│ │ │ │ -
│ │ │ │ -

this function is only valid if type() == int_t. It returns the │ │ │ │ -value of the integer.

│ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

string_ptr() string_length() string_offset() string_value()

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

these functions are only valid if type() == string_t. They return │ │ │ │ -the string values. Note that string_ptr() is not 0-terminated. │ │ │ │ -string_length() returns the number of bytes in the string. │ │ │ │ -string_offset() returns the byte offset from the start of the parsed │ │ │ │ -bencoded buffer this string can be found.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

clear()

│ │ │ │ -
│ │ │ │ -void clear ();
│ │ │ │ -
│ │ │ │ -

resets the bdecoded_node to a default constructed state. If this is │ │ │ │ -an owning node, the tree is freed and all child nodes are invalidated.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

swap()

│ │ │ │ -
│ │ │ │ -void swap (bdecode_node& n);
│ │ │ │ -
│ │ │ │ -

Swap contents.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

reserve()

│ │ │ │ -
│ │ │ │ -void reserve (int tokens);
│ │ │ │ -
│ │ │ │ -

preallocate memory for the specified numbers of tokens. This is │ │ │ │ -useful if you know approximately how many tokens are in the file │ │ │ │ -you are about to parse. Doing so will save realloc operations │ │ │ │ -while parsing. You should only call this on the root node, before │ │ │ │ -passing it in to bdecode().

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

switch_underlying_buffer()

│ │ │ │ -
│ │ │ │ -void switch_underlying_buffer (char const* buf) noexcept;
│ │ │ │ -
│ │ │ │ -

this buffer MUST be identical to the one originally parsed. This │ │ │ │ -operation is only defined on owning root nodes, i.e. the one passed in to │ │ │ │ -decode().

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

has_soft_error()

│ │ │ │ -
│ │ │ │ -bool has_soft_error (span<char> error) const;
│ │ │ │ -
│ │ │ │ -

returns true if there is a non-fatal error in the bencoding of this node │ │ │ │ -or its children

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

enum type_t

│ │ │ │ -

Declared in "libtorrent/bdecode.hpp"

│ │ │ │ - │ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ -
namevaluedescription
none_t0uninitialized or default constructed. This is also used │ │ │ │ -to indicate that a node was not found in some cases.
dict_t1a dictionary node. The dict_find_ functions are valid.
list_t2a list node. The list_ functions are valid.
string_t3a string node, the string_ functions are valid.
int_t4an integer node. The int_ functions are valid.
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -

print_entry()

│ │ │ │ -

Declared in "libtorrent/bdecode.hpp"

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

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

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

bdecode()

│ │ │ │ -

Declared in "libtorrent/bdecode.hpp"

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

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

│ │ │ │ -

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

│ │ │ │ -

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

│ │ │ │ -

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

│ │ │ │ -

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

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

web_seed_entry

│ │ │ │ -

Declared in "libtorrent/torrent_info.hpp"

│ │ │ │ -

the web_seed_entry holds information about a web seed (also known │ │ │ │ -as URL seed or HTTP seed). It is essentially a URL with some state │ │ │ │ -associated with it. For more information, see BEP 17 and BEP 19.

│ │ │ │ +[report issue]
│ │ │ │ +

session_proxy

│ │ │ │ +

Declared in "libtorrent/session.hpp"

│ │ │ │ +

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

│ │ │ │ 
│ │ │ │ -struct web_seed_entry
│ │ │ │ +struct session_proxy
│ │ │ │  {
│ │ │ │ -   bool operator== (web_seed_entry const& e) const;
│ │ │ │ -   bool operator< (web_seed_entry const& e) const;
│ │ │ │ -
│ │ │ │ -   enum type_t
│ │ │ │ -   {
│ │ │ │ -      url_seed,
│ │ │ │ -      http_seed,
│ │ │ │ -   };
│ │ │ │ -
│ │ │ │ -   std::string url;
│ │ │ │ -   std::string auth;
│ │ │ │ -   headers_t extra_headers;
│ │ │ │ -   std::uint8_t type;
│ │ │ │ +   session_proxy ();
│ │ │ │ +   session_proxy (session_proxy const&);
│ │ │ │ +   session_proxy (session_proxy&&) noexcept;
│ │ │ │ +   ~session_proxy ();
│ │ │ │ +   session_proxy& operator= (session_proxy&&) & noexcept;
│ │ │ │ +   session_proxy& operator= (session_proxy const&) &;
│ │ │ │  };
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -

operator==()

│ │ │ │ -
│ │ │ │ -bool operator== (web_seed_entry const& e) const;
│ │ │ │ -
│ │ │ │ -

URL and type comparison

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

operator<()

│ │ │ │ + │ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +

session_proxy() ~session_proxy() operator=()

│ │ │ │ 
│ │ │ │ -bool operator< (web_seed_entry const& e) const;
│ │ │ │ +session_proxy ();
│ │ │ │ +session_proxy (session_proxy const&);
│ │ │ │ +session_proxy (session_proxy&&) noexcept;
│ │ │ │ +~session_proxy ();
│ │ │ │ +session_proxy& operator= (session_proxy&&) & noexcept;
│ │ │ │ +session_proxy& operator= (session_proxy const&) &;
│ │ │ │
│ │ │ │ -

URL and type less-than comparison

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

enum type_t

│ │ │ │ -

Declared in "libtorrent/torrent_info.hpp"

│ │ │ │ - │ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ -
namevaluedescription
url_seed0 
http_seed1 
│ │ │ │ -[report issue]
│ │ │ │ -
url
│ │ │ │ -
The URL of the web seed
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
auth
│ │ │ │ -
Optional authentication. If this is set, it's passed │ │ │ │ -in as HTTP basic auth to the web seed. The format is: │ │ │ │ -username:password.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
extra_headers
│ │ │ │ -
Any extra HTTP headers that need to be passed to the web seed
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
type
│ │ │ │ -
The type of web seed (see type_t)
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ +

default constructor, does not refer to any session │ │ │ │ +implementation object.

│ │ │ │ +[report issue]
│ │ │ │
│ │ │ │ -
│ │ │ │ -

load_torrent_limits

│ │ │ │ -

Declared in "libtorrent/torrent_info.hpp"

│ │ │ │ -

this object holds configuration options for limits to use when loading │ │ │ │ -torrents. They are meant to prevent loading potentially malicious torrents │ │ │ │ -that cause excessive memory allocations.

│ │ │ │ -
│ │ │ │ -struct load_torrent_limits
│ │ │ │ -{
│ │ │ │ -   int max_buffer_size  = 10000000;
│ │ │ │ -   int max_pieces  = 0x200000;
│ │ │ │ -   int max_decode_depth  = 100;
│ │ │ │ -   int max_decode_tokens  = 3000000;
│ │ │ │ -};
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
max_buffer_size
│ │ │ │ -
the max size of a .torrent file to load into RAM
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
max_pieces
│ │ │ │ -
the max number of pieces allowed in the torrent
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
max_decode_depth
│ │ │ │ -
the max recursion depth in the bdecoded structure
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
max_decode_tokens
│ │ │ │ -
the max number of bdecode tokens
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

torrent_info

│ │ │ │ -

Declared in "libtorrent/torrent_info.hpp"

│ │ │ │ -

the torrent_info class holds the information found in a .torrent file.

│ │ │ │ +
│ │ │ │ +

session

│ │ │ │ +

Declared in "libtorrent/session.hpp"

│ │ │ │ +

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

│ │ │ │ +

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

│ │ │ │ +

see apply_settings().

│ │ │ │ 
│ │ │ │ -class torrent_info
│ │ │ │ +struct session : session_handle
│ │ │ │  {
│ │ │ │ -   explicit torrent_info (bdecode_node const& torrent_file);
│ │ │ │ -   torrent_info (std::string const& filename, load_torrent_limits const& cfg);
│ │ │ │ -   torrent_info (span<char const> buffer, load_torrent_limits const& cfg, from_span_t);
│ │ │ │ -   torrent_info (char const* buffer, int size);
│ │ │ │ -   torrent_info (char const* buffer, int size, error_code& ec);
│ │ │ │ -   explicit torrent_info (std::string const& filename);
│ │ │ │ -   explicit torrent_info (info_hash_t const& info_hash);
│ │ │ │ -   torrent_info (std::string const& filename, error_code& ec);
│ │ │ │ -   explicit torrent_info (span<char const> buffer, from_span_t);
│ │ │ │ -   torrent_info (torrent_info const& t);
│ │ │ │ -   torrent_info (span<char const> buffer, error_code& ec, from_span_t);
│ │ │ │ -   torrent_info (bdecode_node const& torrent_file, error_code& ec);
│ │ │ │ -   torrent_info (bdecode_node const& torrent_file, load_torrent_limits const& cfg);
│ │ │ │ -   ~torrent_info ();
│ │ │ │ -   file_storage const& orig_files () const;
│ │ │ │ -   file_storage const& files () const;
│ │ │ │ -   void rename_file (file_index_t index, std::string const& new_filename);
│ │ │ │ -   void remap_files (file_storage const& f);
│ │ │ │ -   void add_tracker (std::string const& url, int tier = 0);
│ │ │ │ -   void clear_trackers ();
│ │ │ │ -   std::vector<announce_entry> const& trackers () const;
│ │ │ │ -   void add_tracker (std::string const& url, int tier
│ │ │ │ -      , announce_entry::tracker_source source);
│ │ │ │ -   std::vector<std::string> collections () const;
│ │ │ │ -   std::vector<sha1_hash> similar_torrents () const;
│ │ │ │ -   void add_url_seed (std::string const& url
│ │ │ │ -      , std::string const& ext_auth = std::string()
│ │ │ │ -      , web_seed_entry::headers_t const& ext_headers = web_seed_entry::headers_t());
│ │ │ │ -   void set_web_seeds (std::vector<web_seed_entry> seeds);
│ │ │ │ -   std::vector<web_seed_entry> const& web_seeds () const;
│ │ │ │ -   void add_http_seed (std::string const& url
│ │ │ │ -      , std::string const& extern_auth = std::string()
│ │ │ │ -      , web_seed_entry::headers_t const& extra_headers = web_seed_entry::headers_t());
│ │ │ │ -   std::int64_t total_size () const;
│ │ │ │ -   int piece_length () const;
│ │ │ │ -   int num_pieces () const;
│ │ │ │ -   index_range<piece_index_t> piece_range () const;
│ │ │ │ -   piece_index_t end_piece () const;
│ │ │ │ -   piece_index_t last_piece () const;
│ │ │ │ -   info_hash_t const& info_hashes () const;
│ │ │ │ -   sha1_hash info_hash () const noexcept;
│ │ │ │ -   bool v2 () const;
│ │ │ │ -   bool v1 () const;
│ │ │ │ -   int num_files () const;
│ │ │ │ -   std::vector<file_slice> map_block (piece_index_t const piece
│ │ │ │ -      , std::int64_t offset, int size) const;
│ │ │ │ -   peer_request map_file (file_index_t const file, std::int64_t offset, int size) const;
│ │ │ │ -   string_view ssl_cert () const;
│ │ │ │ -   bool is_valid () const;
│ │ │ │ -   bool priv () const;
│ │ │ │ -   bool is_i2p () const;
│ │ │ │ -   int piece_size (piece_index_t index) const;
│ │ │ │ -   char const* hash_for_piece_ptr (piece_index_t const index) const;
│ │ │ │ -   sha1_hash hash_for_piece (piece_index_t index) const;
│ │ │ │ -   bool is_loaded () const;
│ │ │ │ -   const std::string& name () const;
│ │ │ │ -   std::time_t creation_date () const;
│ │ │ │ -   const std::string& creator () const;
│ │ │ │ -   const std::string& comment () const;
│ │ │ │ -   std::vector<std::pair<std::string, int>> const& nodes () const;
│ │ │ │ -   void add_node (std::pair<std::string, int> const& node);
│ │ │ │ -   bool parse_info_section (bdecode_node const& info, error_code& ec, int max_pieces);
│ │ │ │ -   bdecode_node info (char const* key) const;
│ │ │ │ -   span<char const> info_section () const;
│ │ │ │ -   span<char const> piece_layer (file_index_t) const;
│ │ │ │ -   void free_piece_layers ();
│ │ │ │ +   explicit session (session_params&& params);
│ │ │ │ +   session ();
│ │ │ │ +   explicit session (session_params const& params);
│ │ │ │ +   session (session_params&& params, session_flags_t flags);
│ │ │ │ +   session (session_params const& params, session_flags_t flags);
│ │ │ │ +   session (session_params&& params, io_context& ios);
│ │ │ │ +   session (session_params const& params, io_context& ios, session_flags_t);
│ │ │ │ +   session (session_params&& params, io_context& ios, session_flags_t);
│ │ │ │ +   session (session_params const& params, io_context& ios);
│ │ │ │ +   ~session ();
│ │ │ │ +   session_proxy abort ();
│ │ │ │  };
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -

torrent_info()

│ │ │ │ -
│ │ │ │ -explicit torrent_info (bdecode_node const& torrent_file);
│ │ │ │ -torrent_info (std::string const& filename, load_torrent_limits const& cfg);
│ │ │ │ -torrent_info (span<char const> buffer, load_torrent_limits const& cfg, from_span_t);
│ │ │ │ -torrent_info (char const* buffer, int size);
│ │ │ │ -torrent_info (char const* buffer, int size, error_code& ec);
│ │ │ │ -explicit torrent_info (std::string const& filename);
│ │ │ │ -explicit torrent_info (info_hash_t const& info_hash);
│ │ │ │ -torrent_info (std::string const& filename, error_code& ec);
│ │ │ │ -explicit torrent_info (span<char const> buffer, from_span_t);
│ │ │ │ -torrent_info (torrent_info const& t);
│ │ │ │ -torrent_info (span<char const> buffer, error_code& ec, from_span_t);
│ │ │ │ -torrent_info (bdecode_node const& torrent_file, error_code& ec);
│ │ │ │ -torrent_info (bdecode_node const& torrent_file, load_torrent_limits const& cfg);
│ │ │ │ -
│ │ │ │ -

The constructor that takes an info-hash will initialize the info-hash │ │ │ │ -to the given value, but leave all other fields empty. This is used │ │ │ │ -internally when downloading torrents without the metadata. The │ │ │ │ -metadata will be created by libtorrent as soon as it has been │ │ │ │ -downloaded from the swarm.

│ │ │ │ -

The constructor that takes a bdecode_node will create a torrent_info │ │ │ │ -object from the information found in the given torrent_file. The │ │ │ │ -bdecode_node represents a tree node in an bencoded file. To load an │ │ │ │ -ordinary .torrent file into a bdecode_node, use bdecode().

│ │ │ │ -

The version that takes a buffer pointer and a size will decode it as a │ │ │ │ -.torrent file and initialize the torrent_info object for you.

│ │ │ │ -

The version that takes a filename will simply load the torrent file │ │ │ │ -and decode it inside the constructor, for convenience. This might not │ │ │ │ -be the most suitable for applications that want to be able to report │ │ │ │ -detailed errors on what might go wrong.

│ │ │ │ -

There is an upper limit on the size of the torrent file that will be │ │ │ │ -loaded by the overload taking a filename. If it's important that even │ │ │ │ -very large torrent files are loaded, use one of the other overloads.

│ │ │ │ -

The overloads that takes an error_code const& never throws if an │ │ │ │ -error occur, they will simply set the error code to describe what went │ │ │ │ -wrong and not fully initialize the torrent_info object. The overloads │ │ │ │ -that do not take the extra error_code parameter will always throw if │ │ │ │ -an error occurs. These overloads are not available when building │ │ │ │ -without exception support.

│ │ │ │ -

The overload that takes a span also needs an extra parameter of │ │ │ │ -type from_span_t to disambiguate the std::string overload for │ │ │ │ -string literals. There is an object in the libtorrent namespace of this │ │ │ │ -type called from_span.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

~torrent_info()

│ │ │ │ -
│ │ │ │ -~torrent_info ();
│ │ │ │ -
│ │ │ │ -

frees all storage associated with this torrent_info object

│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

files() orig_files()

│ │ │ │ -
│ │ │ │ -file_storage const& orig_files () const;
│ │ │ │ -file_storage const& files () const;
│ │ │ │ -
│ │ │ │ -

The file_storage object contains the information on how to map the │ │ │ │ -pieces to files. It is separated from the torrent_info object because │ │ │ │ -when creating torrents a storage object needs to be created without │ │ │ │ -having a torrent file. When renaming files in a storage, the storage │ │ │ │ -needs to make its own copy of the file_storage in order to make its │ │ │ │ -mapping differ from the one in the torrent file.

│ │ │ │ -

orig_files() returns the original (unmodified) file storage for │ │ │ │ -this torrent. This is used by the web server connection, which needs │ │ │ │ -to request files with the original names. Filename may be changed using │ │ │ │ -torrent_info::rename_file().

│ │ │ │ -

For more information on the file_storage object, see the separate │ │ │ │ -document on how to create torrents.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

rename_file()

│ │ │ │ +[report issue]
│ │ │ │ +

session()

│ │ │ │ 
│ │ │ │ -void rename_file (file_index_t index, std::string const& new_filename);
│ │ │ │ +explicit session (session_params&& params);
│ │ │ │ +session ();
│ │ │ │ +explicit session (session_params const& params);
│ │ │ │ +session (session_params&& params, session_flags_t flags);
│ │ │ │ +session (session_params const& params, session_flags_t flags);
│ │ │ │
│ │ │ │ -

Renames the file with the specified index to the new name. The new │ │ │ │ -filename is reflected by the file_storage returned by files() │ │ │ │ -but not by the one returned by orig_files().

│ │ │ │ -

If you want to rename the base name of the torrent (for a multi file │ │ │ │ -torrent), you can copy the file_storage (see files() and │ │ │ │ -orig_files() ), change the name, and then use remap_files().

│ │ │ │ -

The new_filename can both be a relative path, in which case the │ │ │ │ -file name is relative to the save_path of the torrent. If the │ │ │ │ -new_filename is an absolute path (i.e. is_complete(new_filename) │ │ │ │ -== true), then the file is detached from the save_path of the │ │ │ │ -torrent. In this case the file is not moved when move_storage() is │ │ │ │ -invoked.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

remap_files()

│ │ │ │ +

Constructs the session objects which acts as the container of torrents. │ │ │ │ +In order to avoid a race condition between starting the session and │ │ │ │ +configuring it, you can pass in a session_params object. Its settings │ │ │ │ +will take effect before the session starts up.

│ │ │ │ +

The overloads taking flags can be used to start a session in │ │ │ │ +paused mode (by passing in session::paused). Note that │ │ │ │ +add_default_plugins do not have an affect on constructors that │ │ │ │ +take a session_params object. It already contains the plugins to use.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

session()

│ │ │ │ 
│ │ │ │ -void remap_files (file_storage const& f);
│ │ │ │ +session (session_params&& params, io_context& ios);
│ │ │ │ +session (session_params const& params, io_context& ios, session_flags_t);
│ │ │ │ +session (session_params&& params, io_context& ios, session_flags_t);
│ │ │ │ +session (session_params const& params, io_context& ios);
│ │ │ │
│ │ │ │ +

Overload of the constructor that takes an external io_context to run │ │ │ │ +the session object on. This is primarily useful for tests that may want │ │ │ │ +to run multiple sessions on a single io_context, or low resource │ │ │ │ +systems where additional threads are expensive and sharing an │ │ │ │ +io_context with other events is fine.

│ │ │ │
│ │ │ │

Warning

│ │ │ │ -

Using remap_files() is discouraged as it's incompatible with v2 │ │ │ │ -torrents. This is because the piece boundaries and piece hashes in │ │ │ │ -v2 torrents are intimately tied to the file boundaries. Instead, │ │ │ │ -just rename individual files, or implement a custom disk_interface │ │ │ │ -to customize how to store files.

│ │ │ │ +

The session object does not cleanly terminate with an external │ │ │ │ +io_context. The io_context::run() call must have returned │ │ │ │ +before it's safe to destruct the session. Which means you MUST │ │ │ │ +call session::abort() and save the session_proxy first, then │ │ │ │ +destruct the session object, then sync with the io_context, then │ │ │ │ +destruct the session_proxy object.

│ │ │ │
│ │ │ │ -

Remaps the file storage to a new file layout. This can be used to, for │ │ │ │ -instance, download all data in a torrent to a single file, or to a │ │ │ │ -number of fixed size sector aligned files, regardless of the number │ │ │ │ -and sizes of the files in the torrent.

│ │ │ │ -

The new specified file_storage must have the exact same size as │ │ │ │ -the current one.

│ │ │ │ - │ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

trackers() clear_trackers() add_tracker()

│ │ │ │ -
│ │ │ │ -void add_tracker (std::string const& url, int tier = 0);
│ │ │ │ -void clear_trackers ();
│ │ │ │ -std::vector<announce_entry> const& trackers () const;
│ │ │ │ -void add_tracker (std::string const& url, int tier
│ │ │ │ -      , announce_entry::tracker_source source);
│ │ │ │ -
│ │ │ │ -

add_tracker() adds a tracker to the announce-list. The tier │ │ │ │ -determines the order in which the trackers are to be tried. │ │ │ │ -The trackers() function will return a sorted vector of │ │ │ │ -announce_entry. Each announce entry contains a string, which is │ │ │ │ -the tracker url, and a tier index. The tier index is the high-level │ │ │ │ -priority. No matter which trackers that works or not, the ones with │ │ │ │ -lower tier will always be tried before the one with higher tier │ │ │ │ -number. For more information, see announce_entry.

│ │ │ │ -

trackers() returns all entries from announce-list.

│ │ │ │ -

clear_trackers() removes all trackers from announce-list.

│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

collections() similar_torrents()

│ │ │ │ -
│ │ │ │ -std::vector<std::string> collections () const;
│ │ │ │ -std::vector<sha1_hash> similar_torrents () const;
│ │ │ │ -
│ │ │ │ -

These two functions are related to BEP 38 (mutable torrents). The │ │ │ │ -vectors returned from these correspond to the "similar" and │ │ │ │ -"collections" keys in the .torrent file. Both info-hashes and │ │ │ │ -collections from within the info-dict and from outside of it are │ │ │ │ -included.

│ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

add_url_seed() set_web_seeds() add_http_seed() web_seeds()

│ │ │ │ -
│ │ │ │ -void add_url_seed (std::string const& url
│ │ │ │ -      , std::string const& ext_auth = std::string()
│ │ │ │ -      , web_seed_entry::headers_t const& ext_headers = web_seed_entry::headers_t());
│ │ │ │ -void set_web_seeds (std::vector<web_seed_entry> seeds);
│ │ │ │ -std::vector<web_seed_entry> const& web_seeds () const;
│ │ │ │ -void add_http_seed (std::string const& url
│ │ │ │ -      , std::string const& extern_auth = std::string()
│ │ │ │ -      , web_seed_entry::headers_t const& extra_headers = web_seed_entry::headers_t());
│ │ │ │ -
│ │ │ │ -

web_seeds() returns all url seeds and http seeds in the torrent. │ │ │ │ -Each entry is a web_seed_entry and may refer to either a url seed │ │ │ │ -or http seed.

│ │ │ │ -

add_url_seed() and add_http_seed() adds one url to the list of │ │ │ │ -url/http seeds.

│ │ │ │ -

set_web_seeds() replaces all web seeds with the ones specified in │ │ │ │ -the seeds vector.

│ │ │ │ -

The extern_auth argument can be used for other authorization │ │ │ │ -schemes than basic HTTP authorization. If set, it will override any │ │ │ │ -username and password found in the URL itself. The string will be sent │ │ │ │ -as the HTTP authorization header's value (without specifying "Basic").

│ │ │ │ -

The extra_headers argument defaults to an empty list, but can be │ │ │ │ -used to insert custom HTTP headers in the requests to a specific web │ │ │ │ -seed.

│ │ │ │ -

See http seeding for more information.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

total_size()

│ │ │ │ -
│ │ │ │ -std::int64_t total_size () const;
│ │ │ │ -
│ │ │ │ -

total_size() returns the total number of bytes the torrent-file │ │ │ │ -represents. Note that this is the number of pieces times the piece │ │ │ │ -size (modulo the last piece possibly being smaller). With pad files, │ │ │ │ -the total size will be larger than the sum of all (regular) file │ │ │ │ -sizes.

│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

num_pieces() piece_length()

│ │ │ │ -
│ │ │ │ -int piece_length () const;
│ │ │ │ -int num_pieces () const;
│ │ │ │ -
│ │ │ │ -

piece_length() and num_pieces() returns the number of byte │ │ │ │ -for each piece and the total number of pieces, respectively. The │ │ │ │ -difference between piece_size() and piece_length() is that │ │ │ │ -piece_size() takes the piece index as argument and gives you the │ │ │ │ -exact size of that piece. It will always be the same as │ │ │ │ -piece_length() except in the case of the last piece, which may be │ │ │ │ -smaller.

│ │ │ │ - │ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

last_piece() end_piece() piece_range()

│ │ │ │ -
│ │ │ │ -index_range<piece_index_t> piece_range () const;
│ │ │ │ -piece_index_t end_piece () const;
│ │ │ │ -piece_index_t last_piece () const;
│ │ │ │ -
│ │ │ │ -

last_piece() returns the index to the last piece in the torrent and │ │ │ │ -end_piece() returns the index to the one-past-end piece in the │ │ │ │ -torrent │ │ │ │ -piece_range() returns an implementation-defined type that can be │ │ │ │ -used as the container in a range-for loop. Where the values are the │ │ │ │ -indices of all pieces in the file_storage.

│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

info_hash() info_hashes()

│ │ │ │ -
│ │ │ │ -info_hash_t const& info_hashes () const;
│ │ │ │ -sha1_hash info_hash () const noexcept;
│ │ │ │ -
│ │ │ │ -

returns the info-hash of the torrent. For BitTorrent v2 support, use │ │ │ │ -info_hashes() to get an object that may hold both a v1 and v2 │ │ │ │ -info-hash

│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

v2() v1()

│ │ │ │ -
│ │ │ │ -bool v2 () const;
│ │ │ │ -bool v1 () const;
│ │ │ │ -
│ │ │ │ -

returns whether this torrent has v1 and/or v2 metadata, respectively. │ │ │ │ -Hybrid torrents have both. These are shortcuts for │ │ │ │ -info_hashes().has_v1() and info_hashes().has_v2() calls.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

num_files()

│ │ │ │ -
│ │ │ │ -int num_files () const;
│ │ │ │ -
│ │ │ │ -

If you need index-access to files you can use the num_files() along │ │ │ │ -with the file_path(), file_size()-family of functions to access │ │ │ │ -files using indices.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

map_block()

│ │ │ │ -
│ │ │ │ -std::vector<file_slice> map_block (piece_index_t const piece
│ │ │ │ -      , std::int64_t offset, int size) const;
│ │ │ │ -
│ │ │ │ -

This function will map a piece index, a byte offset within that piece │ │ │ │ -and a size (in bytes) into the corresponding files with offsets where │ │ │ │ -that data for that piece is supposed to be stored. See file_slice.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

map_file()

│ │ │ │ -
│ │ │ │ -peer_request map_file (file_index_t const file, std::int64_t offset, int size) const;
│ │ │ │ -
│ │ │ │ -

This function will map a range in a specific file into a range in the │ │ │ │ -torrent. The file_offset parameter is the offset in the file, │ │ │ │ -given in bytes, where 0 is the start of the file. See peer_request.

│ │ │ │ -

The input range is assumed to be valid within the torrent. │ │ │ │ -file_offset + size is not allowed to be greater than the file │ │ │ │ -size. file_index must refer to a valid file, i.e. it cannot be >= │ │ │ │ -num_files().

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

ssl_cert()

│ │ │ │ -
│ │ │ │ -string_view ssl_cert () const;
│ │ │ │ -
│ │ │ │ -

Returns the SSL root certificate for the torrent, if it is an SSL │ │ │ │ -torrent. Otherwise returns an empty string. The certificate is │ │ │ │ -the public certificate in x509 format.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

is_valid()

│ │ │ │ -
│ │ │ │ -bool is_valid () const;
│ │ │ │ -
│ │ │ │ -

returns true if this torrent_info object has a torrent loaded. │ │ │ │ -This is primarily used to determine if a magnet link has had its │ │ │ │ -metadata resolved yet or not.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

priv()

│ │ │ │ -
│ │ │ │ -bool priv () const;
│ │ │ │ -
│ │ │ │ -

returns true if this torrent is private. i.e., the client should not │ │ │ │ -advertise itself on the trackerless network (the Kademlia DHT) for this torrent.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

is_i2p()

│ │ │ │ -
│ │ │ │ -bool is_i2p () const;
│ │ │ │ -
│ │ │ │ -

returns true if this is an i2p torrent. This is determined by whether │ │ │ │ -or not it has a tracker whose URL domain name ends with ".i2p". i2p │ │ │ │ -torrents disable the DHT and local peer discovery as well as talking │ │ │ │ -to peers over anything other than the i2p network.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

piece_size()

│ │ │ │ -
│ │ │ │ -int piece_size (piece_index_t index) const;
│ │ │ │ -
│ │ │ │ -

returns the piece size of file with index. This will be the same as piece_length(), │ │ │ │ -except for the last piece, which may be shorter.

│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

hash_for_piece() hash_for_piece_ptr()

│ │ │ │ -
│ │ │ │ -char const* hash_for_piece_ptr (piece_index_t const index) const;
│ │ │ │ -sha1_hash hash_for_piece (piece_index_t index) const;
│ │ │ │ -
│ │ │ │ -

hash_for_piece() takes a piece-index and returns the 20-bytes │ │ │ │ -sha1-hash for that piece and info_hash() returns the 20-bytes │ │ │ │ -sha1-hash for the info-section of the torrent file. │ │ │ │ -hash_for_piece_ptr() returns a pointer to the 20 byte sha1 digest │ │ │ │ -for the piece. Note that the string is not 0-terminated.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

name()

│ │ │ │ -
│ │ │ │ -const std::string& name () const;
│ │ │ │ -
│ │ │ │ -

name() returns the name of the torrent. │ │ │ │ -name contains UTF-8 encoded string.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

creation_date()

│ │ │ │ -
│ │ │ │ -std::time_t creation_date () const;
│ │ │ │ -
│ │ │ │ -

creation_date() returns the creation date of the torrent as time_t │ │ │ │ -(posix time). If there's no time stamp in the torrent file, 0 is │ │ │ │ -returned. │ │ │ │ -.. posix time: http://www.opengroup.org/onlinepubs/009695399/functions/time.html

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

creator()

│ │ │ │ -
│ │ │ │ -const std::string& creator () const;
│ │ │ │ -
│ │ │ │ -

creator() returns the creator string in the torrent. If there is │ │ │ │ -no creator string it will return an empty string.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

comment()

│ │ │ │ -
│ │ │ │ -const std::string& comment () const;
│ │ │ │ -
│ │ │ │ -

comment() returns the comment associated with the torrent. If │ │ │ │ -there's no comment, it will return an empty string. │ │ │ │ -comment contains UTF-8 encoded string.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

nodes()

│ │ │ │ -
│ │ │ │ -std::vector<std::pair<std::string, int>> const& nodes () const;
│ │ │ │ -
│ │ │ │ -

If this torrent contains any DHT nodes, they are put in this vector in │ │ │ │ -their original form (host name and port number).

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

add_node()

│ │ │ │ -
│ │ │ │ -void add_node (std::pair<std::string, int> const& node);
│ │ │ │ -
│ │ │ │ -

This is used when creating torrent. Use this to add a known DHT node. │ │ │ │ -It may be used, by the client, to bootstrap into the DHT network.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

parse_info_section()

│ │ │ │ -
│ │ │ │ -bool parse_info_section (bdecode_node const& info, error_code& ec, int max_pieces);
│ │ │ │ -
│ │ │ │ -

populates the torrent_info by providing just the info-dict buffer. │ │ │ │ -This is used when loading a torrent from a magnet link for instance, │ │ │ │ -where we only have the info-dict. The bdecode_node e points to a │ │ │ │ -parsed info-dictionary. ec returns an error code if something │ │ │ │ -fails (typically if the info dictionary is malformed). │ │ │ │ -The max_pieces parameter allows limiting the amount of memory │ │ │ │ -dedicated to loading the torrent, and fails for torrents that exceed │ │ │ │ -the limit. To load large torrents, this limit may also need to be │ │ │ │ -raised in settings_pack::max_piece_count and in calls to │ │ │ │ -read_resume_data().

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

info()

│ │ │ │ -
│ │ │ │ -bdecode_node info (char const* key) const;
│ │ │ │ -
│ │ │ │ -

This function looks up keys from the info-dictionary of the loaded │ │ │ │ -torrent file. It can be used to access extension values put in the │ │ │ │ -.torrent file. If the specified key cannot be found, it returns nullptr.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

info_section()

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

~session()

│ │ │ │ 
│ │ │ │ -span<char const> info_section () const;
│ │ │ │ +~session ();
│ │ │ │
│ │ │ │ -

returns a the raw info section of the torrent file. │ │ │ │ -The underlying buffer is still owned by the torrent_info object

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

piece_layer()

│ │ │ │ +

The destructor of session will notify all trackers that our torrents │ │ │ │ +have been shut down. If some trackers are down, they will time out. │ │ │ │ +All this before the destructor of session returns. So, it's advised │ │ │ │ +that any kind of interface (such as windows) are closed before │ │ │ │ +destructing the session object. Because it can take a few second for │ │ │ │ +it to finish. The timeout can be set with apply_settings().

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

abort()

│ │ │ │ 
│ │ │ │ -span<char const> piece_layer (file_index_t) const;
│ │ │ │ +session_proxy abort ();
│ │ │ │
│ │ │ │ -

return the bytes of the piece layer hashes for the specified file. If │ │ │ │ -the file doesn't have a piece layer, an empty span is returned. │ │ │ │ -The span size is divisible by 32, the size of a SHA-256 hash. │ │ │ │ -If the size of the file is smaller than or equal to the piece size, │ │ │ │ -the files "root hash" is the hash of the file and is not saved │ │ │ │ -separately in the "piece layers" field, but this function still │ │ │ │ -returns the root hash of the file in that case.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

free_piece_layers()

│ │ │ │ +

In case you want to destruct the session asynchronously, you can │ │ │ │ +request a session destruction proxy. If you don't do this, the │ │ │ │ +destructor of the session object will block while the trackers are │ │ │ │ +contacted. If you keep one session_proxy to the session when │ │ │ │ +destructing it, the destructor will not block, but start to close down │ │ │ │ +the session, the destructor of the proxy will then synchronize the │ │ │ │ +threads. So, the destruction of the session is performed from the │ │ │ │ +session destructor call until the session_proxy destructor │ │ │ │ +call. The session_proxy does not have any operations on it (since │ │ │ │ +the session is being closed down, no operations are allowed on it). │ │ │ │ +The only valid operation is calling the destructor:

│ │ │ │ 
│ │ │ │ -void free_piece_layers ();
│ │ │ │ +struct session_proxy {};
│ │ │ │
│ │ │ │ -

clears the piece layers from the torrent_info. This is done by the │ │ │ │ -session when a torrent is added, to avoid storing it twice. The piece │ │ │ │ -layer (or other hashes part of the merkle tree) are stored in the │ │ │ │ -internal torrent object.

│ │ │ │ -

Bencoding is a common representation in bittorrent used for dictionary, │ │ │ │ -list, int and string hierarchies. It's used to encode .torrent files and │ │ │ │ -some messages in the network protocol. libtorrent also uses it to store │ │ │ │ -settings, resume data and other session state.

│ │ │ │ -

Strings in bencoded structures do not necessarily represent text. │ │ │ │ -Strings are raw byte buffers of a certain length. If a string is meant to be │ │ │ │ -interpreted as text, it is required to be UTF-8 encoded. See BEP 3.

│ │ │ │ -

The function for decoding bencoded data bdecode(), returning a bdecode_node. │ │ │ │ -This function builds a tree that points back into the original buffer. The │ │ │ │ -returned bdecode_node will not be valid once the buffer it was parsed out of │ │ │ │ -is discarded.

│ │ │ │ -

It's possible to construct an entry from a bdecode_node, if a structure needs │ │ │ │ -to be altered and re-encoded.

│ │ │ │ -[report issue]
│ │ │ │ +[report issue]
│ │ │ │
│ │ │ │ -
│ │ │ │ -

entry

│ │ │ │ -

Declared in "libtorrent/entry.hpp"

│ │ │ │ -

The entry class represents one node in a bencoded hierarchy. It works as a │ │ │ │ -variant type, it can be either a list, a dictionary (std::map), an integer │ │ │ │ -or a string.

│ │ │ │ +
│ │ │ │ +

session_params

│ │ │ │ +

Declared in "libtorrent/session_params.hpp"

│ │ │ │ +

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

│ │ │ │ 
│ │ │ │ -class entry
│ │ │ │ +struct session_params
│ │ │ │  {
│ │ │ │ -   data_type type () const;
│ │ │ │ -   entry (dictionary_type);
│ │ │ │ -   entry (span<char const>);
│ │ │ │ -   entry (integer_type);
│ │ │ │ -   entry (preformatted_type);
│ │ │ │ -   entry (list_type);
│ │ │ │ -   entry (U v);
│ │ │ │ -   entry (data_type t);
│ │ │ │ -   entry (bdecode_node const& n);
│ │ │ │ -   entry& operator= (dictionary_type) &;
│ │ │ │ -   entry& operator= (integer_type) &;
│ │ │ │ -   entry& operator= (bdecode_node const&) &;
│ │ │ │ -   entry& operator= (entry&&) & noexcept;
│ │ │ │ -   entry& operator= (span<char const>) &;
│ │ │ │ -   entry& operator= (list_type) &;
│ │ │ │ -   entry& operator= (entry const&) &;
│ │ │ │ -   entry& operator= (preformatted_type) &;
│ │ │ │ -   entry& operator= (U v) &;
│ │ │ │ -   string_type const& string () const;
│ │ │ │ -   preformatted_type const& preformatted () const;
│ │ │ │ -   integer_type& integer ();
│ │ │ │ -   dictionary_type& dict ();
│ │ │ │ -   integer_type const& integer () const;
│ │ │ │ -   dictionary_type const& dict () const;
│ │ │ │ -   list_type const& list () const;
│ │ │ │ -   list_type& list ();
│ │ │ │ -   string_type& string ();
│ │ │ │ -   preformatted_type& preformatted ();
│ │ │ │ -   void swap (entry& e);
│ │ │ │ -   entry const& operator[] (string_view key) const;
│ │ │ │ -   entry& operator[] (string_view key);
│ │ │ │ -   entry const* find_key (string_view key) const;
│ │ │ │ -   entry* find_key (string_view key);
│ │ │ │ -   std::string to_string (bool single_line = false) const;
│ │ │ │ -
│ │ │ │ -   enum data_type
│ │ │ │ -   {
│ │ │ │ -      int_t,
│ │ │ │ -      string_t,
│ │ │ │ -      list_t,
│ │ │ │ -      dictionary_t,
│ │ │ │ -      undefined_t,
│ │ │ │ -      preformatted_t,
│ │ │ │ -   };
│ │ │ │ -};
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -

type()

│ │ │ │ -
│ │ │ │ -data_type type () const;
│ │ │ │ -
│ │ │ │ -

returns the concrete type of the entry

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

entry()

│ │ │ │ -
│ │ │ │ -entry (dictionary_type);
│ │ │ │ -entry (span<char const>);
│ │ │ │ -entry (integer_type);
│ │ │ │ -entry (preformatted_type);
│ │ │ │ -entry (list_type);
│ │ │ │ -
│ │ │ │ -

constructors directly from a specific type. │ │ │ │ -The content of the argument is copied into the │ │ │ │ -newly constructed entry

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

entry()

│ │ │ │ -
│ │ │ │ -entry (data_type t);
│ │ │ │ -
│ │ │ │ -

construct an empty entry of the specified type. │ │ │ │ -see data_type enum.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

entry()

│ │ │ │ -
│ │ │ │ -entry (bdecode_node const& n);
│ │ │ │ -
│ │ │ │ -

construct from bdecode_node parsed form (see bdecode())

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

operator=()

│ │ │ │ -
│ │ │ │ -entry& operator= (dictionary_type) &;
│ │ │ │ -entry& operator= (integer_type) &;
│ │ │ │ -entry& operator= (bdecode_node const&) &;
│ │ │ │ -entry& operator= (entry&&) & noexcept;
│ │ │ │ -entry& operator= (span<char const>) &;
│ │ │ │ -entry& operator= (list_type) &;
│ │ │ │ -entry& operator= (entry const&) &;
│ │ │ │ -entry& operator= (preformatted_type) &;
│ │ │ │ -
│ │ │ │ -

copies the structure of the right hand side into this │ │ │ │ -entry.

│ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

dict() string() list() integer() preformatted()

│ │ │ │ -
│ │ │ │ -string_type const& string () const;
│ │ │ │ -preformatted_type const& preformatted () const;
│ │ │ │ -integer_type& integer ();
│ │ │ │ -dictionary_type& dict ();
│ │ │ │ -integer_type const& integer () const;
│ │ │ │ -dictionary_type const& dict () const;
│ │ │ │ -list_type const& list () const;
│ │ │ │ -list_type& list ();
│ │ │ │ -string_type& string ();
│ │ │ │ -preformatted_type& preformatted ();
│ │ │ │ -
│ │ │ │ -

The integer(), string(), list() and dict() functions │ │ │ │ -are accessors that return the respective type. If the entry object │ │ │ │ -isn't of the type you request, the accessor will throw │ │ │ │ -system_error. You can ask an entry for its type through the │ │ │ │ -type() function.

│ │ │ │ -

If you want to create an entry you give it the type you want it to │ │ │ │ -have in its constructor, and then use one of the non-const accessors │ │ │ │ -to get a reference which you then can assign the value you want it to │ │ │ │ -have.

│ │ │ │ -

The typical code to get info from a torrent file will then look like │ │ │ │ -this:

│ │ │ │ -
│ │ │ │ -entry torrent_file;
│ │ │ │ -// ...
│ │ │ │ -
│ │ │ │ -// throws if this is not a dictionary
│ │ │ │ -entry::dictionary_type const& dict = torrent_file.dict();
│ │ │ │ -entry::dictionary_type::const_iterator i;
│ │ │ │ -i = dict.find("announce");
│ │ │ │ -if (i != dict.end())
│ │ │ │ -{
│ │ │ │ -        std::string tracker_url = i->second.string();
│ │ │ │ -        std::cout << tracker_url << "\n";
│ │ │ │ -}
│ │ │ │ -
│ │ │ │ -

The following code is equivalent, but a little bit shorter:

│ │ │ │ -
│ │ │ │ -entry torrent_file;
│ │ │ │ -// ...
│ │ │ │ -
│ │ │ │ -// throws if this is not a dictionary
│ │ │ │ -if (entry* i = torrent_file.find_key("announce"))
│ │ │ │ -{
│ │ │ │ -        std::string tracker_url = i->string();
│ │ │ │ -        std::cout << tracker_url << "\n";
│ │ │ │ -}
│ │ │ │ -
│ │ │ │ -

To make it easier to extract information from a torrent file, the │ │ │ │ -class torrent_info exists.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

swap()

│ │ │ │ -
│ │ │ │ -void swap (entry& e);
│ │ │ │ -
│ │ │ │ -

swaps the content of this with e.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

operator[]()

│ │ │ │ -
│ │ │ │ -entry const& operator[] (string_view key) const;
│ │ │ │ -entry& operator[] (string_view key);
│ │ │ │ -
│ │ │ │ -

All of these functions requires the entry to be a dictionary, if it │ │ │ │ -isn't they will throw system_error.

│ │ │ │ -

The non-const versions of the operator[] will return a reference │ │ │ │ -to either the existing element at the given key or, if there is no │ │ │ │ -element with the given key, a reference to a newly inserted element at │ │ │ │ -that key.

│ │ │ │ -

The const version of operator[] will only return a reference to an │ │ │ │ -existing element at the given key. If the key is not found, it will │ │ │ │ -throw system_error.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

find_key()

│ │ │ │ -
│ │ │ │ -entry const* find_key (string_view key) const;
│ │ │ │ -entry* find_key (string_view key);
│ │ │ │ -
│ │ │ │ -

These functions requires the entry to be a dictionary, if it isn't │ │ │ │ -they will throw system_error.

│ │ │ │ -

They will look for an element at the given key in the dictionary, if │ │ │ │ -the element cannot be found, they will return nullptr. If an element │ │ │ │ -with the given key is found, the return a pointer to it.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

to_string()

│ │ │ │ -
│ │ │ │ -std::string to_string (bool single_line = false) const;
│ │ │ │ -
│ │ │ │ -

returns a pretty-printed string representation │ │ │ │ -of the bencoded structure, with JSON-style syntax

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

enum data_type

│ │ │ │ -

Declared in "libtorrent/entry.hpp"

│ │ │ │ - │ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ -
namevaluedescription
int_t0 
string_t1 
list_t2 
dictionary_t3 
undefined_t4 
preformatted_t5 
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -

operator<<()

│ │ │ │ -

Declared in "libtorrent/entry.hpp"

│ │ │ │ -
│ │ │ │ -inline std::ostream& operator<< (std::ostream& os, const entry& e);
│ │ │ │ -
│ │ │ │ -

prints the bencoded structure to the ostream as a JSON-style structure.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

bencode()

│ │ │ │ -

Declared in "libtorrent/bencode.hpp"

│ │ │ │ -
│ │ │ │ -template<class OutIt> int bencode (OutIt out, const entry& e);
│ │ │ │ -
│ │ │ │ -

This function will encode data to bencoded form.

│ │ │ │ -

The entry class is the internal representation of the bencoded data │ │ │ │ -and it can be used to retrieve information, an entry can also be build by │ │ │ │ -the program and given to bencode() to encode it into the OutIt │ │ │ │ -iterator.

│ │ │ │ -

OutIt is an OutputIterator. It's a template and usually │ │ │ │ -instantiated as ostream_iterator or back_insert_iterator. This │ │ │ │ -function assumes the value_type of the iterator is a char. │ │ │ │ -In order to encode entry e into a buffer, do:

│ │ │ │ -
│ │ │ │ -std::vector<char> buffer;
│ │ │ │ -bencode(std::back_inserter(buf), e);
│ │ │ │ -
│ │ │ │ -

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

│ │ │ │ -

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

│ │ │ │ -

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

│ │ │ │ -

Example use:

│ │ │ │ -
│ │ │ │ -struct temp_storage
│ │ │ │ -{
│ │ │ │ -  explicit temp_storage(lt::file_storage const& fs) : m_files(fs) {}
│ │ │ │ -
│ │ │ │ -  lt::span<char const> readv(lt::peer_request const r, lt::storage_error& ec) const
│ │ │ │ -  {
│ │ │ │ -    auto const i = m_file_data.find(r.piece);
│ │ │ │ -    if (i == m_file_data.end())
│ │ │ │ -    {
│ │ │ │ -      ec.operation = lt::operation_t::file_read;
│ │ │ │ -      ec.ec = boost::asio::error::eof;
│ │ │ │ -      return {};
│ │ │ │ -    }
│ │ │ │ -    if (int(i->second.size()) <= r.start)
│ │ │ │ -    {
│ │ │ │ -      ec.operation = lt::operation_t::file_read;
│ │ │ │ -      ec.ec = boost::asio::error::eof;
│ │ │ │ -      return {};
│ │ │ │ -    }
│ │ │ │ -    return { i->second.data() + r.start, std::min(r.length, int(i->second.size()) - r.start) };
│ │ │ │ -  }
│ │ │ │ -  void writev(lt::span<char const> const b, lt::piece_index_t const piece, int const offset)
│ │ │ │ -  {
│ │ │ │ -    auto& data = m_file_data[piece];
│ │ │ │ -    if (data.empty())
│ │ │ │ -    {
│ │ │ │ -      // allocate the whole piece, otherwise we'll invalidate the pointers
│ │ │ │ -      // we have returned back to libtorrent
│ │ │ │ -      int const size = piece_size(piece);
│ │ │ │ -      data.resize(std::size_t(size));
│ │ │ │ -    }
│ │ │ │ -    TORRENT_ASSERT(offset + b.size() <= int(data.size()));
│ │ │ │ -    std::memcpy(data.data() + offset, b.data(), std::size_t(b.size()));
│ │ │ │ -  }
│ │ │ │ -  lt::sha1_hash hash(lt::piece_index_t const piece
│ │ │ │ -    , lt::span<lt::sha256_hash> const block_hashes, lt::storage_error& ec) const
│ │ │ │ -  {
│ │ │ │ -    auto const i = m_file_data.find(piece);
│ │ │ │ -    if (i == m_file_data.end())
│ │ │ │ -    {
│ │ │ │ -      ec.operation = lt::operation_t::file_read;
│ │ │ │ -      ec.ec = boost::asio::error::eof;
│ │ │ │ -      return {};
│ │ │ │ -    }
│ │ │ │ -    if (!block_hashes.empty())
│ │ │ │ -    {
│ │ │ │ -      int const piece_size2 = m_files.piece_size2(piece);
│ │ │ │ -      int const blocks_in_piece2 = m_files.blocks_in_piece2(piece);
│ │ │ │ -      char const* buf = i->second.data();
│ │ │ │ -      std::int64_t offset = 0;
│ │ │ │ -      for (int k = 0; k < blocks_in_piece2; ++k)
│ │ │ │ -      {
│ │ │ │ -        lt::hasher256 h2;
│ │ │ │ -        std::ptrdiff_t const len2 = std::min(lt::default_block_size, int(piece_size2 - offset));
│ │ │ │ -        h2.update({ buf, len2 });
│ │ │ │ -        buf += len2;
│ │ │ │ -        offset += len2;
│ │ │ │ -        block_hashes[k] = h2.final();
│ │ │ │ -      }
│ │ │ │ -    }
│ │ │ │ -    return lt::hasher(i->second).final();
│ │ │ │ -  }
│ │ │ │ -  lt::sha256_hash hash2(lt::piece_index_t const piece, int const offset, lt::storage_error& ec)
│ │ │ │ -  {
│ │ │ │ -    auto const i = m_file_data.find(piece);
│ │ │ │ -    if (i == m_file_data.end())
│ │ │ │ -    {
│ │ │ │ -      ec.operation = lt::operation_t::file_read;
│ │ │ │ -      ec.ec = boost::asio::error::eof;
│ │ │ │ -      return {};
│ │ │ │ -    }
│ │ │ │ -
│ │ │ │ -    int const piece_size = m_files.piece_size2(piece);
│ │ │ │ -
│ │ │ │ -    std::ptrdiff_t const len = std::min(lt::default_block_size, piece_size - offset);
│ │ │ │ -
│ │ │ │ -    lt::span<char const> b = {i->second.data() + offset, len};
│ │ │ │ -    return lt::hasher256(b).final();
│ │ │ │ -  }
│ │ │ │ -
│ │ │ │ -private:
│ │ │ │ -  int piece_size(lt::piece_index_t piece) const
│ │ │ │ -  {
│ │ │ │ -    int const num_pieces = static_cast<int>((m_files.total_size() + m_files.piece_length() - 1) / m_files.piece_length());
│ │ │ │ -    return static_cast<int>(piece) < num_pieces - 1
│ │ │ │ -      ? m_files.piece_length() : static_cast<int>(m_files.total_size() - 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;
│ │ │ │ -};
│ │ │ │ +   session_params (settings_pack const& sp);
│ │ │ │ +   session_params (settings_pack&& sp);
│ │ │ │ +   session_params ();
│ │ │ │ +   session_params (settings_pack&& sp
│ │ │ │ +      , std::vector<std::shared_ptr<plugin>> exts);
│ │ │ │ +   session_params (settings_pack const& sp
│ │ │ │ +      , std::vector<std::shared_ptr<plugin>> exts);
│ │ │ │  
│ │ │ │ -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);
│ │ │ │ -}
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

disk_observer

│ │ │ │ -

Declared in "libtorrent/disk_observer.hpp"

│ │ │ │ -
│ │ │ │ -struct disk_observer
│ │ │ │ -{
│ │ │ │ -   virtual void on_disk () = 0;
│ │ │ │ -};
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -

on_disk()

│ │ │ │ -
│ │ │ │ -virtual void on_disk () = 0;
│ │ │ │ -
│ │ │ │ -

called when the disk cache size has dropped │ │ │ │ -below the low watermark again and we can │ │ │ │ -resume downloading from peers

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -

settings_interface

│ │ │ │ -

Declared in "libtorrent/settings_pack.hpp"

│ │ │ │ -

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

│ │ │ │ -
│ │ │ │ -struct settings_interface
│ │ │ │ -{
│ │ │ │ -   virtual void set_str (int name, std::string val) = 0;
│ │ │ │ -   virtual void set_int (int name, int val) = 0;
│ │ │ │ -   virtual bool has_val (int name) const = 0;
│ │ │ │ -   virtual void set_bool (int name, bool 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;
│ │ │ │ -};
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

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;
│ │ │ │ -};
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

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;
│ │ │ │ +   settings_pack settings;
│ │ │ │ +   std::vector<std::shared_ptr<plugin>> extensions;
│ │ │ │ +   dht::dht_state dht_state;
│ │ │ │ +   dht::dht_storage_constructor_type dht_storage_constructor;
│ │ │ │ +   disk_io_constructor_type disk_io_constructor;
│ │ │ │ +   std::map<std::string, std::string> ext_state;
│ │ │ │ +   libtorrent::ip_filter ip_filter;
│ │ │ │  };
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -

disk_buffer_holder()

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

construct a buffer holder that will free the held buffer │ │ │ │ -using a disk buffer pool directly (there's only one │ │ │ │ -disk_buffer_pool per session)

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

disk_buffer_holder()

│ │ │ │ -
│ │ │ │ -disk_buffer_holder () noexcept = default;
│ │ │ │ -
│ │ │ │ -

default construct a holder that does not own any buffer

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

~disk_buffer_holder()

│ │ │ │ -
│ │ │ │ -~disk_buffer_holder ();
│ │ │ │ -
│ │ │ │ -

frees disk buffer held by this object

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

data()

│ │ │ │ -
│ │ │ │ -char* data () const noexcept;
│ │ │ │ -
│ │ │ │ -

return a pointer to the held buffer, if any. Otherwise returns nullptr.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

reset()

│ │ │ │ -
│ │ │ │ -void reset ();
│ │ │ │ -
│ │ │ │ -

free the held disk buffer, if any, and clear the holder. This sets the │ │ │ │ -holder object to a default-constructed state

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

swap()

│ │ │ │ -
│ │ │ │ -void swap (disk_buffer_holder& h) noexcept;
│ │ │ │ -
│ │ │ │ -

swap pointers of two disk buffer holders.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

is_mutable()

│ │ │ │ -
│ │ │ │ -bool is_mutable () const noexcept;
│ │ │ │ -
│ │ │ │ -

if this returns true, the buffer may not be modified in place

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

bool()

│ │ │ │ +[report issue]
│ │ │ │ +

session_params()

│ │ │ │ 
│ │ │ │ -explicit operator bool () const noexcept;
│ │ │ │ +session_params (settings_pack const& sp);
│ │ │ │ +session_params (settings_pack&& sp);
│ │ │ │ +session_params ();
│ │ │ │
│ │ │ │ -

implicitly convertible to true if the object is currently holding a │ │ │ │ -buffer

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -

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.

│ │ │ │ +

This constructor can be used to start with the default plugins │ │ │ │ +(ut_metadata, ut_pex and smart_ban). Pass a settings_pack to set the │ │ │ │ +initial settings when the session starts.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

session_params()

│ │ │ │ 
│ │ │ │ -struct open_file_state
│ │ │ │ -{
│ │ │ │ -   file_index_t file_index;
│ │ │ │ -   file_open_mode_t open_mode;
│ │ │ │ -   time_point last_use;
│ │ │ │ -};
│ │ │ │ +session_params (settings_pack&& sp
│ │ │ │ +      , std::vector<std::shared_ptr<plugin>> exts);
│ │ │ │ +session_params (settings_pack const& sp
│ │ │ │ +      , std::vector<std::shared_ptr<plugin>> exts);
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
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.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
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.

│ │ │ │ -
│ │ │ │ +

This constructor helps to configure the set of initial plugins │ │ │ │ +to be added to the session before it's started.

│ │ │ │ +[report issue]
│ │ │ │ +
settings
│ │ │ │ +
The settings to configure the session with
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
last_use
│ │ │ │ -
a (high precision) timestamp of when the file was last used.
│ │ │ │ +[report issue]
│ │ │ │ +
extensions
│ │ │ │ +
the plugins to add to the session as it is constructed
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

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;
│ │ │ │ -};
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -

new_torrent()

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

this is called when a new torrent is added. The shared_ptr can be │ │ │ │ -used to hold the internal torrent object alive as long as there are │ │ │ │ -outstanding disk operations on the storage. │ │ │ │ -The returned storage_holder is an owning reference to the underlying │ │ │ │ -storage that was just created. It is fundamentally a storage_index_t

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

remove_torrent()

│ │ │ │ -
│ │ │ │ -virtual void remove_torrent (storage_index_t) = 0;
│ │ │ │ -
│ │ │ │ -

remove the storage with the specified index. This is not expected to │ │ │ │ -delete any files from disk, just to clean up any resources associated │ │ │ │ -with the specified storage.

│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

async_read() async_write()

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

perform a read or write operation from/to the specified storage │ │ │ │ -index and the specified request. When the operation completes, call │ │ │ │ -handler possibly with a disk_buffer_holder, holding the buffer with │ │ │ │ -the result. Flags may be set to affect the read operation. See │ │ │ │ -disk_job_flags_t.

│ │ │ │ -

The disk_observer is a callback to indicate that │ │ │ │ -the store buffer/disk write queue is below the watermark to let peers │ │ │ │ -start writing buffers to disk again. When async_write() returns │ │ │ │ -true, indicating the write queue is full, the peer will stop │ │ │ │ -further writes and wait for the passed-in disk_observer to be │ │ │ │ -notified before resuming.

│ │ │ │ -

Note that for async_read, the peer_request (r) is not │ │ │ │ -necessarily aligned to blocks (but it is most of the time). However, │ │ │ │ -all writes (passed to async_write) are guaranteed to be block │ │ │ │ -aligned.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

async_hash()

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

Compute hash(es) for the specified piece. Unless the v1_hash flag is │ │ │ │ -set (in flags), the SHA-1 hash of the whole piece does not need │ │ │ │ -to be computed.

│ │ │ │ -

The v2 span is optional and can be empty, which means v2 hashes │ │ │ │ -should not be computed. If v2 is non-empty it must be at least large │ │ │ │ -enough to hold all v2 blocks in the piece, and this function will │ │ │ │ -fill in the span with the SHA-256 block hashes of the piece.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

async_hash2()

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

computes the v2 hash (SHA-256) of a single block. The block at │ │ │ │ -offset in piece piece.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

async_move_storage()

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

called to request the files for the specified storage/torrent be │ │ │ │ -moved to a new location. It is the disk I/O object's responsibility │ │ │ │ -to synchronize this with any currently outstanding disk operations to │ │ │ │ -the storage. Whether files are replaced at the destination path or │ │ │ │ -not is controlled by flags (see move_flags_t).

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

async_release_files()

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

This is called on disk I/O objects to request they close all open │ │ │ │ -files for the specified storage/torrent. If file handles are not │ │ │ │ -pooled/cached, it can be a no-op. For truly asynchronous disk I/O, │ │ │ │ -this should provide at least one point in time when all files are │ │ │ │ -closed. It is possible that later asynchronous operations will │ │ │ │ -re-open some of the files, by the time this completion handler is │ │ │ │ -called, that's fine.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

async_check_files()

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

this is called when torrents are added to validate their resume data │ │ │ │ -against the files on disk. This function is expected to do a few things:

│ │ │ │ -

if links is non-empty, it contains a string for each file in the │ │ │ │ -torrent. The string being a path to an existing identical file. The │ │ │ │ -default behavior is to create hard links of those files into the │ │ │ │ -storage of the new torrent (specified by storage). An empty │ │ │ │ -string indicates that there is no known identical file. This is part │ │ │ │ -of the "mutable torrent" feature, where files can be reused from │ │ │ │ -other torrents.

│ │ │ │ -

The resume_data points the resume data passed in by the client.

│ │ │ │ -

If the resume_data->flags field has the seed_mode flag set, all │ │ │ │ -files/pieces are expected to be on disk already. This should be │ │ │ │ -verified. Not just the existence of the file, but also that it has │ │ │ │ -the correct size.

│ │ │ │ -

Any file with a piece set in the resume_data->have_pieces bitmask │ │ │ │ -should exist on disk, this should be verified. Pad files and files │ │ │ │ -with zero priority may be skipped.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

async_stop_torrent()

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

This is called when a torrent is stopped. It gives the disk I/O │ │ │ │ -object an opportunity to flush any data to disk that's currently kept │ │ │ │ -cached. This function should at least do the same thing as │ │ │ │ -async_release_files().

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

async_rename_file()

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

This function is called when the name of a file in the specified │ │ │ │ -storage has been requested to be renamed. The disk I/O object is │ │ │ │ -responsible for renaming the file without racing with other │ │ │ │ -potentially outstanding operations against the file (such as read, │ │ │ │ -write, move, etc.).

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

async_delete_files()

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

This function is called when some file(s) on disk have been requested │ │ │ │ -to be removed by the client. storage indicates which torrent is │ │ │ │ -referred to. See session_handle for remove_flags_t flags │ │ │ │ -indicating which files are to be removed. │ │ │ │ -e.g. session_handle::delete_files - delete all files │ │ │ │ -session_handle::delete_partfile - only delete part file.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

async_set_file_priority()

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

This is called to set the priority of some or all files. Changing the │ │ │ │ -priority from or to 0 may involve moving data to and from the │ │ │ │ -partfile. The disk I/O object is responsible for correctly │ │ │ │ -synchronizing this work to not race with any potentially outstanding │ │ │ │ -asynchronous operations affecting these files.

│ │ │ │ -

prio is a vector of the file priority for all files. If it's │ │ │ │ -shorter than the total number of files in the torrent, they are │ │ │ │ -assumed to be set to the default priority.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

async_clear_piece()

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

This is called when a piece fails the hash check, to ensure there are │ │ │ │ -no outstanding disk operations to the piece before blocks are │ │ │ │ -re-requested from peers to overwrite the existing blocks. The disk I/O │ │ │ │ -object does not need to perform any action other than synchronize │ │ │ │ -with all outstanding disk operations to the specified piece before │ │ │ │ -posting the result back.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

update_stats_counters()

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

update_stats_counters() is called to give the disk storage an │ │ │ │ -opportunity to update gauges in the c stats counters, that aren't │ │ │ │ -updated continuously as operations are performed. This is called │ │ │ │ -before a snapshot of the counters are passed to the client.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

get_status()

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

Return a list of all the files that are currently open for the │ │ │ │ -specified storage/torrent. This is is just used for the client to │ │ │ │ -query the currently open files, and which modes those files are open │ │ │ │ -in.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

abort()

│ │ │ │ -
│ │ │ │ -virtual void abort (bool wait) = 0;
│ │ │ │ -
│ │ │ │ -

this is called when the session is starting to shut down. The disk │ │ │ │ -I/O object is expected to flush any outstanding write jobs, cancel │ │ │ │ -hash jobs and initiate tearing down of any internal threads. If │ │ │ │ -wait is true, this should be asynchronous. i.e. this call should │ │ │ │ -not return until all threads have stopped and all jobs have either │ │ │ │ -been aborted or completed and the disk I/O object is ready to be │ │ │ │ -destructed.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

submit_jobs()

│ │ │ │ -
│ │ │ │ -virtual void submit_jobs () = 0;
│ │ │ │ -
│ │ │ │ -

This will be called after a batch of disk jobs has been issues (via │ │ │ │ -the async_* ). It gives the disk I/O object an opportunity to │ │ │ │ -notify any potential condition variables to wake up the disk │ │ │ │ -thread(s). The async_* calls can of course also notify condition │ │ │ │ -variables, but doing it in this call allows for batching jobs, by │ │ │ │ -issuing the notification once for a collection of jobs.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

settings_updated()

│ │ │ │ -
│ │ │ │ -virtual void settings_updated () = 0;
│ │ │ │ -
│ │ │ │ -

This is called to notify the disk I/O object that the settings have │ │ │ │ -been updated. In the disk io constructor, a settings_interface │ │ │ │ -reference is passed in. Whenever these settings are updated, this │ │ │ │ -function is called to allow the disk I/O object to react to any │ │ │ │ -changed settings relevant to its operations.

│ │ │ │ -[report issue]
│ │ │ │ -
force_copy
│ │ │ │ -
force making a copy of the cached block, rather than getting a │ │ │ │ -reference to a block already in the cache. This is used the block is │ │ │ │ -expected to be overwritten very soon, by async_write()`, and we need │ │ │ │ -access to the previous content.
│ │ │ │ +[report issue]
│ │ │ │ +
dht_state
│ │ │ │ +
DHT node ID and node addresses to bootstrap the DHT with.
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
sequential_access
│ │ │ │ -
hint that there may be more disk operations with sequential access to │ │ │ │ -the file
│ │ │ │ +[report issue]
│ │ │ │ +
dht_storage_constructor
│ │ │ │ +
function object to construct the storage object for DHT items.
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
volatile_read
│ │ │ │ -
don't keep the read block in cache. This is a hint that this block is │ │ │ │ -unlikely to be read again anytime soon, and caching it would be │ │ │ │ -wasteful.
│ │ │ │ +[report issue]
│ │ │ │ +
disk_io_constructor
│ │ │ │ +
function object to create the disk I/O subsystem. Defaults to │ │ │ │ +default_disk_io_constructor.
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
v1_hash
│ │ │ │ -
compute a v1 piece hash. This is only used by the async_hash() call. │ │ │ │ -If this flag is not set in the async_hash() call, the SHA-1 piece │ │ │ │ -hash does not need to be computed.
│ │ │ │ +[report issue]
│ │ │ │ +
ext_state
│ │ │ │ +
this container can be used by extensions/plugins to store settings. It's │ │ │ │ +primarily here to make it convenient to save and restore state across │ │ │ │ +sessions, using read_session_params() and write_session_params().
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
flush_piece
│ │ │ │ -
this flag instructs a hash job that we just completed this piece, and │ │ │ │ -it should be flushed to disk
│ │ │ │ +[report issue]
│ │ │ │ +
ip_filter
│ │ │ │ +
the IP filter to use for the session. This restricts which peers are allowed │ │ │ │ +to connect. As if passed to set_ip_filter().
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ +[report issue]
│ │ │ │
│ │ │ │ -
│ │ │ │ -

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 (storage_index_t idx, disk_interface& disk_io);
│ │ │ │ -   ~storage_holder ();
│ │ │ │ -   storage_holder () = default;
│ │ │ │ -   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;
│ │ │ │ -};
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

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
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

counters

│ │ │ │ -

Declared in "libtorrent/performance_counters.hpp"

│ │ │ │ +
│ │ │ │ +

session_handle

│ │ │ │ +

Declared in "libtorrent/session_handle.hpp"

│ │ │ │ +

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

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

inc_stats_counter() operator[]()

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

returns the new value

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -

stats_metric

│ │ │ │ -

Declared in "libtorrent/session_stats.hpp"

│ │ │ │ -

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

│ │ │ │ +[report issue]
│ │ │ │ +

is_valid()

│ │ │ │ 
│ │ │ │ -struct stats_metric
│ │ │ │ -{
│ │ │ │ -   char const* name;
│ │ │ │ -   int value_index;
│ │ │ │ -   metric_type_t type;
│ │ │ │ -};
│ │ │ │ +bool is_valid () const;
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
name
│ │ │ │ -
the name of the counter or gauge
│ │ │ │ -
│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
value_index type
│ │ │ │ -
the index into the session stats array, where the underlying value of │ │ │ │ -this counter or gauge is found. The session stats array is part of the │ │ │ │ -session_stats_alert object.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

session_stats_metrics()

│ │ │ │ -

Declared in "libtorrent/session_stats.hpp"

│ │ │ │ +

returns true if this handle refers to a valid session object. If the │ │ │ │ +session has been destroyed, all session_handle objects will expire and │ │ │ │ +not be valid.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

session_state()

│ │ │ │ 
│ │ │ │ -std::vector<stats_metric> session_stats_metrics ();
│ │ │ │ +session_params session_state (save_state_flags_t flags = save_state_flags_t::all()) const;
│ │ │ │
│ │ │ │ -

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

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

find_metric_idx()

│ │ │ │ -

Declared in "libtorrent/session_stats.hpp"

│ │ │ │ +

returns the current session state. This can be passed to │ │ │ │ +write_session_params() to save the state to disk and restored using │ │ │ │ +read_session_params() when constructing a new session. The kind of │ │ │ │ +state that's included is all settings, the DHT routing table, possibly │ │ │ │ +plugin-specific state. │ │ │ │ +the flags parameter can be used to only save certain parts of the │ │ │ │ +session state

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

refresh_torrent_status() get_torrent_status()

│ │ │ │ 
│ │ │ │ -int find_metric_idx (string_view name);
│ │ │ │ -
│ │ │ │ -

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

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

enum metric_type_t

│ │ │ │ -

Declared in "libtorrent/session_stats.hpp"

│ │ │ │ - │ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ -
namevaluedescription
counter0 
gauge1 
│ │ │ │ -

libtorrent has a plugin interface for implementing extensions to the protocol. │ │ │ │ -These can be general extensions for transferring metadata or peer exchange │ │ │ │ -extensions, or it could be used to provide a way to customize the protocol │ │ │ │ -to fit a particular (closed) network.

│ │ │ │ -

In short, the plugin interface makes it possible to:

│ │ │ │ -
    │ │ │ │ -
  • register extension messages (sent in the extension handshake), see │ │ │ │ -extensions.
    • │ │ │ │ -
  • add data and parse data from the extension handshake.
    • │ │ │ │ -
  • send extension messages and standard bittorrent messages.
    • │ │ │ │ -
  • override or block the handling of standard bittorrent messages.
    • │ │ │ │ -
  • save and restore state via the session state
    • │ │ │ │ -
  • see all alerts that are posted
    • │ │ │ │ -
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -

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);
│ │ │ │ +void refresh_torrent_status (std::vector<torrent_status>* ret
│ │ │ │ +      , status_flags_t flags = {}) const;
│ │ │ │ +std::vector<torrent_status> get_torrent_status (
│ │ │ │ +      std::function<bool(torrent_status const&)> const& pred
│ │ │ │ +      , status_flags_t flags = {}) const;
│ │ │ │
│ │ │ │ -

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

│ │ │ │ +
│ │ │ │ +

Note

│ │ │ │ +

these calls are potentially expensive and won't scale well with │ │ │ │ +lots of torrents. If you're concerned about performance, consider │ │ │ │ +using post_torrent_updates() instead.

│ │ │ │
│ │ │ │ -
│ │ │ │ -

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:

│ │ │ │ +

get_torrent_status returns a vector of the torrent_status for │ │ │ │ +every torrent which satisfies pred, which is a predicate function │ │ │ │ +which determines if a torrent should be included in the returned set │ │ │ │ +or not. Returning true means it should be included and false means │ │ │ │ +excluded. The flags argument is the same as to │ │ │ │ +torrent_handle::status(). Since pred is guaranteed to be │ │ │ │ +called for every torrent, it may be used to count the number of │ │ │ │ +torrents of different categories as well.

│ │ │ │ +

refresh_torrent_status takes a vector of torrent_status structs │ │ │ │ +(for instance the same vector that was returned by │ │ │ │ +get_torrent_status() ) and refreshes the status based on the │ │ │ │ +handle member. It is possible to use this function by first │ │ │ │ +setting up a vector of default constructed torrent_status objects, │ │ │ │ +only initializing the handle member, in order to request the │ │ │ │ +torrent status for multiple torrents in a single call. This can save a │ │ │ │ +significant amount of time if you have a lot of torrents.

│ │ │ │ +

Any torrent_status object whose handle member is not referring to │ │ │ │ +a valid torrent are ignored.

│ │ │ │ +

The intended use of these functions is to start off by calling │ │ │ │ +get_torrent_status() to get a list of all torrents that match your │ │ │ │ +criteria. Then call refresh_torrent_status() on that list. This │ │ │ │ +will only refresh the status for the torrents in your list, and thus │ │ │ │ +ignore all other torrents you might be running. This may save a │ │ │ │ +significant amount of time, especially if the number of torrents you're │ │ │ │ +interested in is small. In order to keep your list of interested │ │ │ │ +torrents up to date, you can either call get_torrent_status() from │ │ │ │ +time to time, to include torrents you might have become interested in │ │ │ │ +since the last time. In order to stop refreshing a certain torrent, │ │ │ │ +simply remove it from the list.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

post_torrent_updates()

│ │ │ │ 
│ │ │ │ -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>; }
│ │ │ │ +void post_torrent_updates (status_flags_t flags = status_flags_t::all());
│ │ │ │
│ │ │ │ -

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.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

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

│ │ │ │ +

This functions instructs the session to post the state_update_alert, │ │ │ │ +containing the status of all torrents whose state changed since the │ │ │ │ +last time this function was called.

│ │ │ │ +

Only torrents who has the state subscription flag set will be │ │ │ │ +included. This flag is on by default. See add_torrent_params. │ │ │ │ +the flags argument is the same as for torrent_handle::status(). │ │ │ │ +see status_flags_t in torrent_handle.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

post_session_stats()

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

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.

│ │ │ │ +

This function will post a session_stats_alert object, containing a │ │ │ │ +snapshot of the performance counters from the internals of libtorrent. │ │ │ │ +To interpret these counters, query the session via │ │ │ │ +session_stats_metrics().

│ │ │ │ +

For more information, see the session statistics section.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

post_dht_stats()

│ │ │ │ 
│ │ │ │ -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;
│ │ │ │ -};
│ │ │ │ +void post_dht_stats ();
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

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.

│ │ │ │ +

This will cause a dht_stats_alert to be posted.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

set_dht_state()

│ │ │ │ 
│ │ │ │ -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;
│ │ │ │ -};
│ │ │ │ +void set_dht_state (dht::dht_state const& st);
│ │ │ │ +void set_dht_state (dht::dht_state&& st);
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -

implemented_features()

│ │ │ │ +

set the DHT state for the session. This will be taken into account the │ │ │ │ +next time the DHT is started, as if it had been passed in via the │ │ │ │ +session_params on startup.

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

find_torrent() get_torrents()

│ │ │ │ 
│ │ │ │ -virtual feature_flags_t implemented_features ();
│ │ │ │ +torrent_handle find_torrent (sha1_hash const& info_hash) const;
│ │ │ │ +std::vector<torrent_handle> get_torrents () const;
│ │ │ │
│ │ │ │ -

This function is expected to return a bitmask indicating which features │ │ │ │ -this plugin implements. Some callbacks on this object may not be called │ │ │ │ -unless the corresponding feature flag is returned here. Note that │ │ │ │ -callbacks may still be called even if the corresponding feature is not │ │ │ │ -specified in the return value here. See feature_flags_t for possible │ │ │ │ -flags to return.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

new_torrent()

│ │ │ │ +

find_torrent() looks for a torrent with the given info-hash. In │ │ │ │ +case there is such a torrent in the session, a torrent_handle to that │ │ │ │ +torrent is returned. In case the torrent cannot be found, an invalid │ │ │ │ +torrent_handle is returned.

│ │ │ │ +

See torrent_handle::is_valid() to know if the torrent was found or │ │ │ │ +not.

│ │ │ │ +

get_torrents() returns a vector of torrent_handles to all the │ │ │ │ +torrents currently in the session.

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

add_torrent() async_add_torrent()

│ │ │ │ 
│ │ │ │ -virtual std::shared_ptr<torrent_plugin> new_torrent (torrent_handle const&, client_data_t);
│ │ │ │ +torrent_handle add_torrent (add_torrent_params const& params, error_code& ec);
│ │ │ │ +void async_add_torrent (add_torrent_params&& params);
│ │ │ │ +void async_add_torrent (add_torrent_params const& params);
│ │ │ │ +torrent_handle add_torrent (add_torrent_params&& params, error_code& ec);
│ │ │ │ +torrent_handle add_torrent (add_torrent_params const& params);
│ │ │ │ +torrent_handle add_torrent (add_torrent_params&& params);
│ │ │ │
│ │ │ │ -

this is called by the session every time a new torrent is added. │ │ │ │ -The torrent* points to the internal torrent object created │ │ │ │ -for the new torrent. The client_data_t is the userdata pointer as │ │ │ │ -passed in via add_torrent_params.

│ │ │ │ -

If the plugin returns a torrent_plugin instance, it will be added │ │ │ │ -to the new torrent. Otherwise, return an empty shared_ptr to a │ │ │ │ -torrent_plugin (the default).

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

added()

│ │ │ │ +

You add torrents through the add_torrent() function where you give an │ │ │ │ +object with all the parameters. The add_torrent() overloads will block │ │ │ │ +until the torrent has been added (or failed to be added) and returns │ │ │ │ +an error code and a torrent_handle. In order to add torrents more │ │ │ │ +efficiently, consider using async_add_torrent() which returns │ │ │ │ +immediately, without waiting for the torrent to add. Notification of │ │ │ │ +the torrent being added is sent as add_torrent_alert.

│ │ │ │ +

The overload that does not take an error_code throws an exception on │ │ │ │ +error and is not available when building without exception support. │ │ │ │ +The torrent_handle returned by add_torrent() can be used to retrieve │ │ │ │ +information about the torrent's progress, its peers etc. It is also │ │ │ │ +used to abort a torrent.

│ │ │ │ +

If the torrent you are trying to add already exists in the session (is │ │ │ │ +either queued for checking, being checked or downloading) │ │ │ │ +add_torrent() will throw system_error which derives from │ │ │ │ +std::exception unless duplicate_is_error is set to false. In that │ │ │ │ +case, add_torrent() will return the handle to the existing torrent.

│ │ │ │ +

The add_torrent_params class has a flags field. It can be used to │ │ │ │ +control what state the new torrent will be added in. Common flags to │ │ │ │ +want to control are torrent_flags::paused and │ │ │ │ +torrent_flags::auto_managed. In order to add a magnet link that will │ │ │ │ +just download the metadata, but no payload, set the │ │ │ │ +torrent_flags::upload_mode flag.

│ │ │ │ +

Special consideration has to be taken when adding hybrid torrents │ │ │ │ +(i.e. torrents that are BitTorrent v2 torrents that are backwards │ │ │ │ +compatible with v1). For more details, see BitTorrent v2 torrents.

│ │ │ │ + │ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

pause() is_paused() resume()

│ │ │ │ 
│ │ │ │ -virtual void added (session_handle const&);
│ │ │ │ +void pause ();
│ │ │ │ +void resume ();
│ │ │ │ +bool is_paused () const;
│ │ │ │
│ │ │ │ -

called when plugin is added to a session

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

abort()

│ │ │ │ +

Pausing the session has the same effect as pausing every torrent in │ │ │ │ +it, except that torrents will not be resumed by the auto-manage │ │ │ │ +mechanism. Resuming will restore the torrents to their previous paused │ │ │ │ +state. i.e. the session pause state is separate from the torrent pause │ │ │ │ +state. A torrent is inactive if it is paused or if the session is │ │ │ │ +paused.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

is_dht_running()

│ │ │ │ 
│ │ │ │ -virtual void abort ();
│ │ │ │ +bool is_dht_running () const;
│ │ │ │
│ │ │ │ -

called when the session is aborted │ │ │ │ -the plugin should perform any cleanup necessary to allow the session's │ │ │ │ -destruction (e.g. cancel outstanding async operations)

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

on_dht_request()

│ │ │ │ +

is_dht_running() returns true if the DHT support has been started │ │ │ │ +and false otherwise.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

set_dht_storage()

│ │ │ │ 
│ │ │ │ -virtual bool on_dht_request (string_view /* query */
│ │ │ │ -      , udp::endpoint const& /* source */, bdecode_node const& /* message */
│ │ │ │ -      , entry& /* response */);
│ │ │ │ +void set_dht_storage (dht::dht_storage_constructor_type sc);
│ │ │ │
│ │ │ │ -

called when a dht request is received. │ │ │ │ -If your plugin expects this to be called, make sure to include the flag │ │ │ │ -dht_request_feature in the return value from implemented_features().

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

on_alert()

│ │ │ │ +

set_dht_storage set a dht custom storage constructor function │ │ │ │ +to be used internally when the dht is created.

│ │ │ │ +

Since the dht storage is a critical component for the dht behavior, │ │ │ │ +this function will only be effective the next time the dht is started. │ │ │ │ +If you never touch this feature, a default map-memory based storage │ │ │ │ +is used.

│ │ │ │ +

If you want to make sure the dht is initially created with your │ │ │ │ +custom storage, create a session with the setting │ │ │ │ +settings_pack::enable_dht to false, set your constructor function │ │ │ │ +and call apply_settings with settings_pack::enable_dht to true.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

add_dht_node()

│ │ │ │ 
│ │ │ │ -virtual void on_alert (alert const*);
│ │ │ │ +void add_dht_node (std::pair<std::string, int> const& node);
│ │ │ │
│ │ │ │ -

called when an alert is posted alerts that are filtered are not posted. │ │ │ │ -If your plugin expects this to be called, make sure to include the flag │ │ │ │ -alert_feature in the return value from implemented_features().

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

on_unknown_torrent()

│ │ │ │ +

add_dht_node takes a host name and port pair. That endpoint will be │ │ │ │ +pinged, and if a valid DHT reply is received, the node will be added to │ │ │ │ +the routing table.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

dht_get_item()

│ │ │ │ 
│ │ │ │ -virtual bool on_unknown_torrent (info_hash_t const& /* info_hash */
│ │ │ │ -      , peer_connection_handle const& /* pc */, add_torrent_params& /* p */);
│ │ │ │ +void dht_get_item (sha1_hash const& target);
│ │ │ │
│ │ │ │ -

return true if the add_torrent_params should be added

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

on_tick()

│ │ │ │ +

query the DHT for an immutable item at the target hash. │ │ │ │ +the result is posted as a dht_immutable_item_alert.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

dht_get_item()

│ │ │ │ 
│ │ │ │ -virtual void on_tick ();
│ │ │ │ +void dht_get_item (std::array<char, 32> key
│ │ │ │ +      , std::string salt = std::string());
│ │ │ │
│ │ │ │ -

called once per second. │ │ │ │ -If your plugin expects this to be called, make sure to include the flag │ │ │ │ -tick_feature in the return value from implemented_features().

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

get_unchoke_priority()

│ │ │ │ +

query the DHT for a mutable item under the public key key. │ │ │ │ +this is an ed25519 key. salt is optional and may be left │ │ │ │ +as an empty string if no salt is to be used. │ │ │ │ +if the item is found in the DHT, a dht_mutable_item_alert is │ │ │ │ +posted.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

dht_put_item()

│ │ │ │ 
│ │ │ │ -virtual uint64_t get_unchoke_priority (peer_connection_handle const& /* peer */);
│ │ │ │ +sha1_hash dht_put_item (entry data);
│ │ │ │
│ │ │ │ -

called when choosing peers to optimistically unchoke. The return value │ │ │ │ -indicates the peer's priority for unchoking. Lower return values │ │ │ │ -correspond to higher priority. Priorities above 2^63-1 are reserved. │ │ │ │ -If your plugin has no priority to assign a peer it should return 2^64-1. │ │ │ │ -If your plugin expects this to be called, make sure to include the flag │ │ │ │ -optimistic_unchoke_feature in the return value from implemented_features(). │ │ │ │ -If multiple plugins implement this function the lowest return value │ │ │ │ -(i.e. the highest priority) is used.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

load_state()

│ │ │ │ +

store the given bencoded data as an immutable item in the DHT. │ │ │ │ +the returned hash is the key that is to be used to look the item │ │ │ │ +up again. It's just the SHA-1 hash of the bencoded form of the │ │ │ │ +structure.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

dht_put_item()

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

called on startup while loading settings state from the session_params

│ │ │ │ -[report issue]
│ │ │ │ -
optimistic_unchoke_feature
│ │ │ │ -
include this bit if your plugin needs to alter the order of the │ │ │ │ -optimistic unchoke of peers. i.e. have the on_optimistic_unchoke() │ │ │ │ -callback be called.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
tick_feature
│ │ │ │ -
include this bit if your plugin needs to have on_tick() called
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
dht_request_feature
│ │ │ │ -
include this bit if your plugin needs to have on_dht_request() │ │ │ │ -called
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
alert_feature
│ │ │ │ -
include this bit if your plugin needs to have on_alert() │ │ │ │ -called
│ │ │ │ +

store a mutable item. The key is the public key the blob is │ │ │ │ +to be stored under. The optional salt argument is a string that │ │ │ │ +is to be mixed in with the key when determining where in the DHT │ │ │ │ +the value is to be stored. The callback function is called from within │ │ │ │ +the libtorrent network thread once we've found where to store the blob, │ │ │ │ +possibly with the current value stored under the key. │ │ │ │ +The values passed to the callback functions are:

│ │ │ │ +
│ │ │ │ +
entry& value
│ │ │ │ +
the current value stored under the key (may be empty). Also expected │ │ │ │ +to be set to the value to be stored by the function.
│ │ │ │ +
std::array<char,64>& signature
│ │ │ │ +
the signature authenticating the current value. This may be zeros │ │ │ │ +if there is currently no value stored. The function is expected to │ │ │ │ +fill in this buffer with the signature of the new value to store. │ │ │ │ +To generate the signature, you may want to use the │ │ │ │ +sign_mutable_item function.
│ │ │ │ +
std::int64_t& seq
│ │ │ │ +
current sequence number. May be zero if there is no current value. │ │ │ │ +The function is expected to set this to the new sequence number of │ │ │ │ +the value that is to be stored. Sequence numbers must be monotonically │ │ │ │ +increasing. Attempting to overwrite a value with a lower or equal │ │ │ │ +sequence number will fail, even if the signature is correct.
│ │ │ │ +
std::string const& salt
│ │ │ │ +
this is the salt that was used for this put call.
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -

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;
│ │ │ │ -};
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -

new_connection()

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

This function is called each time a new peer is connected to the torrent. You │ │ │ │ -may choose to ignore this by just returning a default constructed │ │ │ │ -shared_ptr (in which case you don't need to override this member │ │ │ │ -function).

│ │ │ │ -

If you need an extension to the peer connection (which most plugins do) you │ │ │ │ -are supposed to return an instance of your peer_plugin class. Which in │ │ │ │ -turn will have its hook functions called on event specific to that peer.

│ │ │ │ -

The peer_connection_handle will be valid as long as the shared_ptr │ │ │ │ -is being held by the torrent object. So, it is generally a good idea to not │ │ │ │ -keep a shared_ptr to your own peer_plugin. If you want to keep references │ │ │ │ -to it, use weak_ptr.

│ │ │ │ -

If this function throws an exception, the connection will be closed.

│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

on_piece_pass() on_piece_failed()

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

These hooks are called when a piece passes the hash check or fails the hash │ │ │ │ -check, respectively. The index is the piece index that was downloaded. │ │ │ │ -It is possible to access the list of peers that participated in sending the │ │ │ │ -piece through the torrent and the piece_picker.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

tick()

│ │ │ │ +

Since the callback function cb is called from within libtorrent, │ │ │ │ +it is critical to not perform any blocking operations. Ideally not │ │ │ │ +even locking a mutex. Pass any data required for this function along │ │ │ │ +with the function object's context and make the function entirely │ │ │ │ +self-contained. The only reason data blob's value is computed │ │ │ │ +via a function instead of just passing in the new value is to avoid │ │ │ │ +race conditions. If you want to update the value in the DHT, you │ │ │ │ +must first retrieve it, then modify it, then write it back. The way │ │ │ │ +the DHT works, it is natural to always do a lookup before storing and │ │ │ │ +calling the callback in between is convenient.

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

dht_announce() dht_get_peers()

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

This hook is called approximately once per second. It is a way of making it │ │ │ │ -easy for plugins to do timed events, for sending messages or whatever.

│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

on_resume() on_pause()

│ │ │ │ +

dht_get_peers() will issue a DHT get_peer request to the DHT for the │ │ │ │ +specified info-hash. The response (the peers) will be posted back in a │ │ │ │ +dht_get_peers_reply_alert.

│ │ │ │ +

dht_announce() will issue a DHT announce request to the DHT to the │ │ │ │ +specified info-hash, advertising the specified port. If the port is │ │ │ │ +left at its default, 0, the port will be implied by the DHT message's │ │ │ │ +source port (which may improve connectivity through a NAT).

│ │ │ │ +

Both these functions are exposed for advanced custom use of the DHT. │ │ │ │ +All torrents eligible to be announce to the DHT will be automatically, │ │ │ │ +by libtorrent.

│ │ │ │ +

For possible flags, see announce_flags_t.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

dht_live_nodes()

│ │ │ │ 
│ │ │ │ -virtual bool on_resume ();
│ │ │ │ -virtual bool on_pause ();
│ │ │ │ +void dht_live_nodes (sha1_hash const& nid);
│ │ │ │
│ │ │ │ -

These hooks are called when the torrent is paused and resumed respectively. │ │ │ │ -The return value indicates if the event was handled. A return value of │ │ │ │ -true indicates that it was handled, and no other plugin after this one │ │ │ │ -will have this hook function called, and the standard handler will also not be │ │ │ │ -invoked. So, returning true effectively overrides the standard behavior of │ │ │ │ -pause or resume.

│ │ │ │ -

Note that if you call pause() or resume() on the torrent from your │ │ │ │ -handler it will recurse back into your handler, so in order to invoke the │ │ │ │ -standard handler, you have to keep your own state on whether you want standard │ │ │ │ -behavior or overridden behavior.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

on_files_checked()

│ │ │ │ +

Retrieve all the live DHT (identified by nid) nodes. All the │ │ │ │ +nodes id and endpoint will be returned in the list of nodes in the │ │ │ │ +alert dht_live_nodes_alert. │ │ │ │ +Since this alert is a response to an explicit call, it will always be │ │ │ │ +posted, regardless of the alert mask.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

dht_sample_infohashes()

│ │ │ │ 
│ │ │ │ -virtual void on_files_checked ();
│ │ │ │ +void dht_sample_infohashes (udp::endpoint const& ep, sha1_hash const& target);
│ │ │ │
│ │ │ │ -

This function is called when the initial files of the torrent have been │ │ │ │ -checked. If there are no files to check, this function is called immediately.

│ │ │ │ -

i.e. This function is always called when the torrent is in a state where it │ │ │ │ -can start downloading.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

on_state()

│ │ │ │ +

Query the DHT node specified by ep to retrieve a sample of the │ │ │ │ +info-hashes that the node currently have in their storage. │ │ │ │ +The target is included for iterative lookups so that indexing nodes │ │ │ │ +can perform a key space traversal with a single RPC per node by adjusting │ │ │ │ +the target value for each RPC. It has no effect on the returned sample value. │ │ │ │ +The result is posted as a dht_sample_infohashes_alert.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

dht_direct_request()

│ │ │ │ 
│ │ │ │ -virtual void on_state (torrent_status::state_t);
│ │ │ │ +void dht_direct_request (udp::endpoint const& ep, entry const& e, client_data_t userdata = {});
│ │ │ │
│ │ │ │ -

called when the torrent changes state │ │ │ │ -the state is one of torrent_status::state_t │ │ │ │ -enum members

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

on_add_peer()

│ │ │ │ +

Send an arbitrary DHT request directly to the specified endpoint. This │ │ │ │ +function is intended for use by plugins. When a response is received │ │ │ │ +or the request times out, a dht_direct_response_alert will be posted │ │ │ │ +with the response (if any) and the userdata pointer passed in here. │ │ │ │ +Since this alert is a response to an explicit call, it will always be │ │ │ │ +posted, regardless of the alert mask.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

add_extension()

│ │ │ │ 
│ │ │ │ -virtual void on_add_peer (tcp::endpoint const&,
│ │ │ │ -      peer_source_flags_t, add_peer_flags_t);
│ │ │ │ +void add_extension (std::shared_ptr<plugin> ext);
│ │ │ │ +void add_extension (std::function<std::shared_ptr<torrent_plugin>(
│ │ │ │ +      torrent_handle const&, client_data_t)> ext);
│ │ │ │
│ │ │ │ -

called every time a new peer is added to the peer list. │ │ │ │ -This is before the peer is connected to. For flags, see │ │ │ │ -torrent_plugin::flags_t. The source argument refers to │ │ │ │ -the source where we learned about this peer from. It's a │ │ │ │ -bitmask, because many sources may have told us about the same │ │ │ │ -peer. For peer source flags, see peer_info::peer_source_flags.

│ │ │ │ -[report issue]
│ │ │ │ -
first_time
│ │ │ │ -
this is the first time we see this peer
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
filtered
│ │ │ │ -
this peer was not added because it was │ │ │ │ -filtered by the IP filter
│ │ │ │ +

This function adds an extension to this session. The argument is a │ │ │ │ +function object that is called with a torrent_handle and which should │ │ │ │ +return a std::shared_ptr<torrent_plugin>. To write custom │ │ │ │ +plugins, see libtorrent plugins. For the typical bittorrent client │ │ │ │ +all of these extensions should be added. The main plugins implemented │ │ │ │ +in libtorrent are:

│ │ │ │ +
│ │ │ │ +
uTorrent metadata
│ │ │ │ +
Allows peers to download the metadata (.torrent files) from the swarm │ │ │ │ +directly. Makes it possible to join a swarm with just a tracker and │ │ │ │ +info-hash.
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -

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_interested ();
│ │ │ │ -   virtual bool on_dont_have (piece_index_t);
│ │ │ │ -   virtual bool on_bitfield (bitfield const& /*bitfield*/);
│ │ │ │ -   virtual bool on_request (peer_request const&);
│ │ │ │ -   virtual bool on_have_none ();
│ │ │ │ -   virtual bool on_have_all ();
│ │ │ │ -   virtual bool on_unchoke ();
│ │ │ │ -   virtual bool on_choke ();
│ │ │ │ -   virtual bool on_not_interested ();
│ │ │ │ -   virtual bool on_have (piece_index_t);
│ │ │ │ -   virtual bool on_allowed_fast (piece_index_t);
│ │ │ │ -   virtual bool on_piece (peer_request const& /*piece*/
│ │ │ │ -      , span<char const> /*buf*/);
│ │ │ │ -   virtual bool on_cancel (peer_request const&);
│ │ │ │ -   virtual bool on_suggest (piece_index_t);
│ │ │ │ -   virtual bool on_reject (peer_request const&);
│ │ │ │ -   virtual void sent_reject_request (peer_request const&);
│ │ │ │ -   virtual void sent_allow_fast (piece_index_t);
│ │ │ │ -   virtual void sent_suggest (piece_index_t);
│ │ │ │ -   virtual void sent_choke ();
│ │ │ │ -   virtual void sent_have_none ();
│ │ │ │ -   virtual void sent_request (peer_request const&);
│ │ │ │ -   virtual void sent_have_all ();
│ │ │ │ -   virtual void sent_cancel (peer_request const&);
│ │ │ │ -   virtual void sent_interested ();
│ │ │ │ -   virtual void sent_have (piece_index_t);
│ │ │ │ -   virtual void sent_not_interested ();
│ │ │ │ -   virtual void sent_unchoke ();
│ │ │ │ -   virtual void sent_piece (peer_request const&);
│ │ │ │ -   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&);
│ │ │ │ -};
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -

type()

│ │ │ │ -
│ │ │ │ -virtual string_view type () const;
│ │ │ │ -
│ │ │ │ -

This function is expected to return the name of │ │ │ │ -the plugin.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

add_handshake()

│ │ │ │ -
│ │ │ │ -virtual void add_handshake (entry&);
│ │ │ │ -
│ │ │ │ -

can add entries to the extension handshake │ │ │ │ -this is not called for web seeds

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

on_disconnect()

│ │ │ │ -
│ │ │ │ -virtual void on_disconnect (error_code const&);
│ │ │ │ -
│ │ │ │ -

called when the peer is being disconnected.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

on_connected()

│ │ │ │ -
│ │ │ │ -virtual void on_connected ();
│ │ │ │ -
│ │ │ │ -

called when the peer is successfully connected. Note that │ │ │ │ -incoming connections will have been connected by the time │ │ │ │ -the peer plugin is attached to it, and won't have this hook │ │ │ │ -called.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

on_handshake()

│ │ │ │ -
│ │ │ │ -virtual bool on_handshake (span<char const>);
│ │ │ │ -
│ │ │ │ -

this is called when the initial bittorrent handshake is received. │ │ │ │ -Returning false means that the other end doesn't support this extension │ │ │ │ -and will remove it from the list of plugins. this is not called for web │ │ │ │ -seeds

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

on_extension_handshake()

│ │ │ │ -
│ │ │ │ -virtual bool on_extension_handshake (bdecode_node const&);
│ │ │ │ -
│ │ │ │ -

called when the extension handshake from the other end is received │ │ │ │ -if this returns false, it means that this extension isn't │ │ │ │ -supported by this peer. It will result in this peer_plugin │ │ │ │ -being removed from the peer_connection and destructed. │ │ │ │ -this is not called for web seeds

│ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

on_dont_have() on_allowed_fast() on_not_interested() on_bitfield() on_have_none() on_have() on_choke() on_interested() on_request() on_unchoke() on_have_all()

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

returning true from any of the message handlers │ │ │ │ -indicates that the plugin has handled the message. │ │ │ │ -it will break the plugin chain traversing and not let │ │ │ │ -anyone else handle the message, including the default │ │ │ │ -handler.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

on_piece()

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

This function is called when the peer connection is receiving │ │ │ │ -a piece. buf points (non-owning pointer) to the data in an │ │ │ │ -internal immutable disk buffer. The length of the data is specified │ │ │ │ -in the length member of the piece parameter. │ │ │ │ -returns true to indicate that the piece is handled and the │ │ │ │ -rest of the logic should be ignored.

│ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

sent_have() sent_unchoke() sent_piece() sent_interested() sent_not_interested()

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

called after a choke message has been sent to the peer

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

sent_payload()

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

called after piece data has been sent to the peer │ │ │ │ -this can be used for stats book keeping

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

can_disconnect()

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

called when libtorrent think this peer should be disconnected. │ │ │ │ -if the plugin returns false, the peer will not be disconnected.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

on_extended()

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

called when an extended message is received. If returning true, │ │ │ │ -the message is not processed by any other plugin and if false │ │ │ │ -is returned the next plugin in the chain will receive it to │ │ │ │ -be able to handle it. This is not called for web seeds. │ │ │ │ -thus function may be called more than once per incoming message, but │ │ │ │ -only the last of the calls will the body size equal the length. │ │ │ │ -i.e. Every time another fragment of the message is received, this │ │ │ │ -function will be called, until finally the whole message has been │ │ │ │ -received. The purpose of this is to allow early disconnects for invalid │ │ │ │ -messages and for reporting progress of receiving large messages.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

on_unknown_message()

│ │ │ │ -
│ │ │ │ -virtual bool on_unknown_message (int /*length*/, int /*msg*/,
│ │ │ │ -      span<char const> /*body*/);
│ │ │ │ +
│ │ │ │ +#include <libtorrent/extensions/ut_metadata.hpp>
│ │ │ │ +ses.add_extension(&lt::create_ut_metadata_plugin);
│ │ │ │  

│ │ │ │ -
this is not called for web seeds

│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

on_piece_pass() on_piece_failed()

│ │ │ │ -
│ │ │ │ -virtual void on_piece_failed (piece_index_t);
│ │ │ │ -virtual void on_piece_pass (piece_index_t);
│ │ │ │ +

│ │ │ │ +
uTorrent peer exchange

│ │ │ │ +
Exchanges peers between clients.

│ │ │ │ +

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

│ │ │ │ -
called when a piece that this peer participated in either
│ │ │ │ -fails or passes the hash_check

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

tick()

│ │ │ │ -
│ │ │ │ -virtual void tick ();
│ │ │ │ +

│ │ │ │ +
smart ban plugin

│ │ │ │ +
A plugin that, with a small overhead, can ban peers
│ │ │ │ +that sends bad data with very high accuracy. Should
│ │ │ │ +eliminate most problems on poisoned torrents.

│ │ │ │ +

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

│ │ │ │ -
called approximately once every second

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

write_request()

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

get_ip_filter() set_ip_filter()

│ │ │ │ 
│ │ │ │ -virtual bool write_request (peer_request const&);
│ │ │ │ +ip_filter get_ip_filter () const;
│ │ │ │ +void set_ip_filter (ip_filter f);
│ │ │ │
│ │ │ │ -

called each time a request message is to be sent. If true │ │ │ │ -is returned, the original request message won't be sent and │ │ │ │ -no other plugin will have this function called.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -

crypto_plugin

│ │ │ │ -

Declared in "libtorrent/extensions.hpp"

│ │ │ │ +

Sets a filter that will be used to reject and accept incoming as well │ │ │ │ +as outgoing connections based on their originating ip address. The │ │ │ │ +default filter will allow connections to any ip address. To build a │ │ │ │ +set of rules for which addresses are accepted and not, see ip_filter.

│ │ │ │ +

Each time a peer is blocked because of the IP filter, a │ │ │ │ +peer_blocked_alert is generated. get_ip_filter() Returns the │ │ │ │ +ip_filter currently in the session. See ip_filter.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

set_port_filter()

│ │ │ │ 
│ │ │ │ -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;
│ │ │ │ -};
│ │ │ │ +void set_port_filter (port_filter const& f);
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -

decrypt()

│ │ │ │ +

apply port_filter f to incoming and outgoing peers. a port filter │ │ │ │ +will reject making outgoing peer connections to certain remote ports. │ │ │ │ +The main intention is to be able to avoid triggering certain │ │ │ │ +anti-virus software by connecting to SMTP, FTP ports.

│ │ │ │ + │ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

ssl_listen_port() is_listening() listen_port()

│ │ │ │ 
│ │ │ │ -virtual std::tuple<int, int, int> decrypt (span<span<char>> /*receive_vec*/) = 0;
│ │ │ │ +unsigned short ssl_listen_port () const;
│ │ │ │ +unsigned short listen_port () const;
│ │ │ │ +bool is_listening () const;
│ │ │ │
│ │ │ │ -

decrypt the provided buffers. │ │ │ │ -returns is a tuple representing the values │ │ │ │ -(consume, produce, packet_size)

│ │ │ │ -

consume is set to the number of bytes which should be trimmed from the │ │ │ │ -head of the buffers, default is 0

│ │ │ │ -

produce is set to the number of bytes of payload which are now ready to │ │ │ │ -be sent to the upper layer. default is the number of bytes passed in receive_vec

│ │ │ │ -

packet_size is set to the minimum number of bytes which must be read to │ │ │ │ -advance the next step of decryption. default is 0

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -

create_ut_pex_plugin()

│ │ │ │ -

Declared in "libtorrent/extensions/ut_pex.hpp"

│ │ │ │ +

is_listening() will tell you whether or not the session has │ │ │ │ +successfully opened a listening port. If it hasn't, this function will │ │ │ │ +return false, and then you can set a new │ │ │ │ +settings_pack::listen_interfaces to try another interface and port to │ │ │ │ +bind to.

│ │ │ │ +

listen_port() returns the port we ended up listening on.

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

get_peer_class_filter() set_peer_class_filter()

│ │ │ │ 
│ │ │ │ -std::shared_ptr<torrent_plugin> create_ut_pex_plugin (torrent_handle const&, client_data_t);
│ │ │ │ +ip_filter get_peer_class_filter () const;
│ │ │ │ +void set_peer_class_filter (ip_filter const& f);
│ │ │ │
│ │ │ │ -

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

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

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);
│ │ │ │ +
Sets the peer class filter for this session. All new peer connections
│ │ │ │ +will take this into account and be added to the peer classes specified
│ │ │ │ +by this filter, based on the peer's IP address.

│ │ │ │ +
The ip-filter essentially maps an IP -> uint32. Each bit in that 32
│ │ │ │ +bit integer represents a peer class. The least significant bit
│ │ │ │ +represents class 0, the next bit class 1 and so on.

│ │ │ │ +
For more info, see ip_filter.

│ │ │ │ +
For example, to make all peers in the range 200.1.1.0 - 200.1.255.255
│ │ │ │ +belong to their own peer class, apply the following filter:

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

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

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

create_smart_ban_plugin()

│ │ │ │ -

Declared in "libtorrent/extensions/smart_ban.hpp"

│ │ │ │ +

This setting only applies to new connections, it won't affect existing │ │ │ │ +peer connections.

│ │ │ │ +

This function is limited to only peer class 0-31, since there are only │ │ │ │ +32 bits in the IP range mapping. Only the set bits matter; no peer │ │ │ │ +class will be removed from a peer as a result of this call, peer │ │ │ │ +classes are only added.

│ │ │ │ +

The peer_class argument cannot be greater than 31. The bitmasks │ │ │ │ +representing peer classes in the peer_class_filter are 32 bits.

│ │ │ │ +

The get_peer_class_filter() function returns the current filter.

│ │ │ │ +

For more information, see peer classes.

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

set_peer_class_type_filter() get_peer_class_type_filter()

│ │ │ │ 
│ │ │ │ -std::shared_ptr<torrent_plugin> create_smart_ban_plugin (torrent_handle const&, client_data_t);
│ │ │ │ +void set_peer_class_type_filter (peer_class_type_filter const& f);
│ │ │ │ +peer_class_type_filter get_peer_class_type_filter () const;
│ │ │ │
│ │ │ │ -

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

│ │ │ │ -

This section describes the functions and classes that are used │ │ │ │ -to create torrent files. It is a layered API with low level classes │ │ │ │ -and higher level convenience functions. A torrent is created in 4 │ │ │ │ -steps:

│ │ │ │ +

Sets and gets the peer class type filter. This is controls automatic │ │ │ │ +peer class assignments to peers based on what kind of socket it is.

│ │ │ │ +

It does not only support assigning peer classes, it also supports │ │ │ │ +removing peer classes based on socket type.

│ │ │ │ +

The order of these rules being applied are:

│ │ │ │
    │ │ │ │ -
  1. first the files that will be part of the torrent are determined.
    2. │ │ │ │ -
  2. the torrent properties are set, such as tracker url, web seeds, │ │ │ │ -DHT nodes etc.
    3. │ │ │ │ -
  3. Read through all the files in the torrent, SHA-1 all the data │ │ │ │ -and set the piece hashes.
    4. │ │ │ │ -
  4. The torrent is bencoded into a file or buffer.
    5. │ │ │ │ +
  5. peer-class IP filter
    6. │ │ │ │ +
  6. peer-class type filter, removing classes
    7. │ │ │ │ +
  7. peer-class type filter, adding classes
    8. │ │ │ │
│ │ │ │ -

If there are a lot of files and or deep directory hierarchies to │ │ │ │ -traverse, step one can be time consuming.

│ │ │ │ -

Typically step 3 is by far the most time consuming step, since it │ │ │ │ -requires to read all the bytes from all the files in the torrent.

│ │ │ │ -

All of these classes and functions are declared by including │ │ │ │ -libtorrent/create_torrent.hpp.

│ │ │ │ -

example:

│ │ │ │ -
│ │ │ │ -file_storage fs;
│ │ │ │ -
│ │ │ │ -// recursively adds files in directories
│ │ │ │ -add_files(fs, "./my_torrent");
│ │ │ │ -
│ │ │ │ -create_torrent t(fs);
│ │ │ │ -t.add_tracker("http://my.tracker.com/announce");
│ │ │ │ -t.set_creator("libtorrent example");
│ │ │ │ -
│ │ │ │ -// reads the files and calculates the hashes
│ │ │ │ -set_piece_hashes(t, ".");
│ │ │ │ -
│ │ │ │ -ofstream out("my_torrent.torrent", std::ios_base::binary);
│ │ │ │ -std::vector<char> buf = t.generate_buf();
│ │ │ │ -out.write(buf.data(), buf.size());
│ │ │ │ -
│ │ │ │ -// alternatively, generate an entry and encode it directly to an ostream
│ │ │ │ -// iterator
│ │ │ │ -bencode(std::ostream_iterator<char>(out), t.generate());
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

create_torrent

│ │ │ │ -

Declared in "libtorrent/create_torrent.hpp"

│ │ │ │ -

This class holds state for creating a torrent. After having added │ │ │ │ -all information to it, call create_torrent::generate() to generate │ │ │ │ -the torrent. The entry that's returned can then be bencoded into a │ │ │ │ -.torrent file using bencode().

│ │ │ │ -
│ │ │ │ -struct create_torrent
│ │ │ │ -{
│ │ │ │ -   explicit create_torrent (file_storage& fs, int piece_size = 0
│ │ │ │ -      , create_flags_t flags = {});
│ │ │ │ -   explicit create_torrent (torrent_info const& ti);
│ │ │ │ -   entry generate () const;
│ │ │ │ -   std::vector<char> generate_buf () const;
│ │ │ │ -   file_storage const& files () const;
│ │ │ │ -   void set_comment (char const* str);
│ │ │ │ -   void set_creator (char const* str);
│ │ │ │ -   void set_creation_date (std::time_t timestamp);
│ │ │ │ -   void set_hash (piece_index_t index, sha1_hash const& h);
│ │ │ │ -   void set_hash2 (file_index_t file, piece_index_t::diff_type piece, sha256_hash const& h);
│ │ │ │ -   void add_url_seed (string_view url);
│ │ │ │ -   void add_http_seed (string_view url);
│ │ │ │ -   void add_node (std::pair<std::string, int> node);
│ │ │ │ -   void add_tracker (string_view url, int tier = 0);
│ │ │ │ -   void set_root_cert (string_view cert);
│ │ │ │ -   void set_priv (bool p);
│ │ │ │ -   bool priv () const;
│ │ │ │ -   bool is_v1_only () const;
│ │ │ │ -   bool is_v2_only () const;
│ │ │ │ -   int num_pieces () const;
│ │ │ │ -   piece_index_t end_piece () const;
│ │ │ │ -   index_range<piece_index_t> piece_range () const noexcept;
│ │ │ │ -   file_index_t end_file () const;
│ │ │ │ -   index_range<file_index_t> file_range () const noexcept;
│ │ │ │ -   index_range<piece_index_t::diff_type> file_piece_range (file_index_t f);
│ │ │ │ -   std::int64_t total_size () const;
│ │ │ │ -   int piece_length () const;
│ │ │ │ -   int piece_size (piece_index_t i) const;
│ │ │ │ -   void add_collection (string_view c);
│ │ │ │ -   void add_similar_torrent (sha1_hash ih);
│ │ │ │ -
│ │ │ │ -   static constexpr create_flags_t modification_time  = 2_bit;
│ │ │ │ -   static constexpr create_flags_t symlinks  = 3_bit;
│ │ │ │ -   static constexpr create_flags_t v2_only  = 5_bit;
│ │ │ │ -   static constexpr create_flags_t v1_only  = 6_bit;
│ │ │ │ -   static constexpr create_flags_t canonical_files  = 7_bit;
│ │ │ │ -   static constexpr create_flags_t no_attributes  = 8_bit;
│ │ │ │ -   static constexpr create_flags_t canonical_files_no_tail_padding  = 9_bit;
│ │ │ │ -};
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -

create_torrent()

│ │ │ │ -
│ │ │ │ -explicit create_torrent (file_storage& fs, int piece_size = 0
│ │ │ │ -      , create_flags_t flags = {});
│ │ │ │ -explicit create_torrent (torrent_info const& ti);
│ │ │ │ -
│ │ │ │ -

The piece_size is the size of each piece in bytes. It must be a │ │ │ │ -power of 2 and a minimum of 16 kiB. If a piece size of 0 is │ │ │ │ -specified, a piece_size will be set automatically.

│ │ │ │ -

The flags arguments specifies options for the torrent creation. It can │ │ │ │ -be any combination of the flags defined by create_flags_t.

│ │ │ │ -

The file_storage (fs) parameter defines the files, sizes and │ │ │ │ -their properties for the torrent to be created. Set this up first, │ │ │ │ -before passing it to the create_torrent constructor.

│ │ │ │ -

The overload that takes a torrent_info object will make a verbatim │ │ │ │ -copy of its info dictionary (to preserve the info-hash). The copy of │ │ │ │ -the info dictionary will be used by create_torrent::generate(). This means │ │ │ │ -that none of the member functions of create_torrent that affects │ │ │ │ -the content of the info dictionary (such as set_hash()), will │ │ │ │ -have any affect. Instead of using this overload, consider using │ │ │ │ -write_torrent_file() instead.

│ │ │ │ -
│ │ │ │ -

Warning

│ │ │ │ -

The file_storage and torrent_info objects must stay alive for the │ │ │ │ -entire duration of the create_torrent object.

│ │ │ │ -
│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

generate_buf() generate()

│ │ │ │ -
│ │ │ │ -entry generate () const;
│ │ │ │ -std::vector<char> generate_buf () const;
│ │ │ │ -
│ │ │ │ -

This function will generate the .torrent file as a bencode tree, or a │ │ │ │ -bencoded into a buffer. │ │ │ │ -In order to encode the entry into a flat file, use the bencode() function.

│ │ │ │ -

The function returning an entry may be useful to add custom entries │ │ │ │ -to the torrent file before bencoding it and saving it to disk.

│ │ │ │ -

Whether the resulting torrent object is v1, v2 or hybrid depends on │ │ │ │ -whether any of the v1_only or v2_only flags were set on the │ │ │ │ -constructor. If neither were set, the resulting torrent depends on │ │ │ │ -which hashes were set. If both v1 and v2 hashes were set, a hybrid │ │ │ │ -torrent is created.

│ │ │ │ -

Any failure will cause this function to throw system_error, with an │ │ │ │ -appropriate error message. These are the reasons this call may throw:

│ │ │ │ -
    │ │ │ │ -
  • the file storage has 0 files
    • │ │ │ │ -
  • the total size of the file storage is 0 bytes (i.e. it only has │ │ │ │ -empty files)
    • │ │ │ │ -
  • not all v1 hashes (set_hash()) and not all v2 hashes (set_hash2()) │ │ │ │ -were set
    • │ │ │ │ -
  • for v2 torrents, you may not have a directory with the same name as │ │ │ │ -a file. If that's encountered in the file storage, generate() │ │ │ │ -fails.
    • │ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

files()

│ │ │ │ -
│ │ │ │ -file_storage const& files () const;
│ │ │ │ -
│ │ │ │ -

returns an immutable reference to the file_storage used to create │ │ │ │ -the torrent from.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

set_comment()

│ │ │ │ -
│ │ │ │ -void set_comment (char const* str);
│ │ │ │ -
│ │ │ │ -

Sets the comment for the torrent. The string str should be utf-8 encoded. │ │ │ │ -The comment in a torrent file is optional.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

set_creator()

│ │ │ │ -
│ │ │ │ -void set_creator (char const* str);
│ │ │ │ -
│ │ │ │ -

Sets the creator of the torrent. The string str should be utf-8 encoded. │ │ │ │ -This is optional.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

set_creation_date()

│ │ │ │ -
│ │ │ │ -void set_creation_date (std::time_t timestamp);
│ │ │ │ -
│ │ │ │ -

sets the "creation time" field. Defaults to the system clock at the │ │ │ │ -time of construction of the create_torrent object. The timestamp is │ │ │ │ -specified in seconds, posix time. If the creation date is set to 0, │ │ │ │ -the "creation date" field will be omitted from the generated torrent.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

set_hash()

│ │ │ │ -
│ │ │ │ -void set_hash (piece_index_t index, sha1_hash const& h);
│ │ │ │ -
│ │ │ │ -

This sets the SHA-1 hash for the specified piece (index). You are required │ │ │ │ -to set the hash for every piece in the torrent before generating it. If you have │ │ │ │ -the files on disk, you can use the high level convenience function to do this. │ │ │ │ -See set_piece_hashes(). │ │ │ │ -A SHA-1 hash of all zeros is internally used to indicate a hash that │ │ │ │ -has not been set. Setting such hash will not be considered set when │ │ │ │ -calling generate(). │ │ │ │ -This function will throw std::system_error if it is called on an │ │ │ │ -object constructed with the v2_only flag.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

set_hash2()

│ │ │ │ -
│ │ │ │ -void set_hash2 (file_index_t file, piece_index_t::diff_type piece, sha256_hash const& h);
│ │ │ │ -
│ │ │ │ -

sets the bittorrent v2 hash for file file of the piece piece. │ │ │ │ -piece is relative to the first piece of the file, starting at 0. The │ │ │ │ -first piece in the file can be computed with │ │ │ │ -file_storage::file_index_at_piece(). │ │ │ │ -The hash, h, is the root of the merkle tree formed by the piece's │ │ │ │ -16 kiB blocks. Note that piece sizes must be powers-of-2, so all │ │ │ │ -per-piece merkle trees are complete. │ │ │ │ -A SHA-256 hash of all zeros is internally used to indicate a hash │ │ │ │ -that has not been set. Setting such hash will not be considered set │ │ │ │ -when calling generate(). │ │ │ │ -This function will throw std::system_error if it is called on an │ │ │ │ -object constructed with the v1_only flag.

│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

add_url_seed() add_http_seed()

│ │ │ │ -
│ │ │ │ -void add_url_seed (string_view url);
│ │ │ │ -void add_http_seed (string_view url);
│ │ │ │ -
│ │ │ │ -

This adds a url seed to the torrent. You can have any number of url seeds. For a │ │ │ │ -single file torrent, this should be an HTTP url, pointing to a file with identical │ │ │ │ -content as the file of the torrent. For a multi-file torrent, it should point to │ │ │ │ -a directory containing a directory with the same name as this torrent, and all the │ │ │ │ -files of the torrent in it.

│ │ │ │ -

The second function, add_http_seed() adds an HTTP seed instead.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

add_node()

│ │ │ │ -
│ │ │ │ -void add_node (std::pair<std::string, int> node);
│ │ │ │ -
│ │ │ │ -

This adds a DHT node to the torrent. This especially useful if you're creating a │ │ │ │ -tracker less torrent. It can be used by clients to bootstrap their DHT node from. │ │ │ │ -The node is a hostname and a port number where there is a DHT node running. │ │ │ │ -You can have any number of DHT nodes in a torrent.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

add_tracker()

│ │ │ │ -
│ │ │ │ -void add_tracker (string_view url, int tier = 0);
│ │ │ │ -
│ │ │ │ -

Adds a tracker to the torrent. This is not strictly required, but most torrents │ │ │ │ -use a tracker as their main source of peers. The url should be an http:// or udp:// │ │ │ │ -url to a machine running a bittorrent tracker that accepts announces for this torrent's │ │ │ │ -info-hash. The tier is the fallback priority of the tracker. All trackers with tier 0 are │ │ │ │ -tried first (in any order). If all fail, trackers with tier 1 are tried. If all of those │ │ │ │ -fail, trackers with tier 2 are tried, and so on.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

set_root_cert()

│ │ │ │ +

For more information, see peer classes.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

create_peer_class()

│ │ │ │ 
│ │ │ │ -void set_root_cert (string_view cert);
│ │ │ │ +peer_class_t create_peer_class (char const* name);
│ │ │ │
│ │ │ │ -

This function sets an X.509 certificate in PEM format to the torrent. This makes the │ │ │ │ -torrent an SSL torrent. An SSL torrent requires that each peer has a valid certificate │ │ │ │ -signed by this root certificate. For SSL torrents, all peers are connecting over SSL │ │ │ │ -connections. For more information, see the section on ssl torrents.

│ │ │ │ -

The string is not the path to the cert, it's the actual content of the │ │ │ │ -certificate.

│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

priv() set_priv()

│ │ │ │ +

Creates a new peer class (see peer classes) with the given name. The │ │ │ │ +returned integer is the new peer class identifier. Peer classes may │ │ │ │ +have the same name, so each invocation of this function creates a new │ │ │ │ +class and returns a unique identifier.

│ │ │ │ +

Identifiers are assigned from low numbers to higher. So if you plan on │ │ │ │ +using certain peer classes in a call to set_peer_class_filter(), │ │ │ │ +make sure to create those early on, to get low identifiers.

│ │ │ │ +

For more information on peer classes, see peer classes.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

delete_peer_class()

│ │ │ │ 
│ │ │ │ -void set_priv (bool p);
│ │ │ │ -bool priv () const;
│ │ │ │ +void delete_peer_class (peer_class_t cid);
│ │ │ │
│ │ │ │ -

Sets and queries the private flag of the torrent. │ │ │ │ -Torrents with the private flag set ask the client to not use any other │ │ │ │ -sources than the tracker for peers, and to not use DHT to advertise itself publicly, │ │ │ │ -only the tracker.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

num_pieces()

│ │ │ │ +

This call dereferences the reference count of the specified peer │ │ │ │ +class. When creating a peer class it's automatically referenced by 1. │ │ │ │ +If you want to recycle a peer class, you may call this function. You │ │ │ │ +may only call this function once per peer class you create. │ │ │ │ +Calling it more than once for the same class will lead to memory │ │ │ │ +corruption.

│ │ │ │ +

Since peer classes are reference counted, this function will not │ │ │ │ +remove the peer class if it's still assigned to torrents or peers. It │ │ │ │ +will however remove it once the last peer and torrent drops their │ │ │ │ +references to it.

│ │ │ │ +

There is no need to call this function for custom peer classes. All │ │ │ │ +peer classes will be properly destructed when the session object │ │ │ │ +destructs.

│ │ │ │ +

For more information on peer classes, see peer classes.

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

set_peer_class() get_peer_class()

│ │ │ │ 
│ │ │ │ -int num_pieces () const;
│ │ │ │ +void set_peer_class (peer_class_t cid, peer_class_info const& pci);
│ │ │ │ +peer_class_info get_peer_class (peer_class_t cid) const;
│ │ │ │
│ │ │ │ -

returns the number of pieces in the associated file_storage object.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

piece_range()

│ │ │ │ +

These functions queries information from a peer class and updates the │ │ │ │ +configuration of a peer class, respectively.

│ │ │ │ +

cid must refer to an existing peer class. If it does not, the │ │ │ │ +return value of get_peer_class() is undefined.

│ │ │ │ +

set_peer_class() sets all the information in the │ │ │ │ +peer_class_info object in the specified peer class. There is no │ │ │ │ +option to only update a single property.

│ │ │ │ +

A peer or torrent belonging to more than one class, the highest │ │ │ │ +priority among any of its classes is the one that is taken into │ │ │ │ +account.

│ │ │ │ +

For more information, see peer classes.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

remove_torrent()

│ │ │ │ 
│ │ │ │ -index_range<piece_index_t> piece_range () const noexcept;
│ │ │ │ +void remove_torrent (const torrent_handle&, remove_flags_t = {});
│ │ │ │
│ │ │ │ -

all piece indices in the torrent to be created

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

file_range()

│ │ │ │ +

remove_torrent() will close all peer connections associated with │ │ │ │ +the torrent and tell the tracker that we've stopped participating in │ │ │ │ +the swarm. This operation cannot fail. When it completes, you will │ │ │ │ +receive a torrent_removed_alert.

│ │ │ │ +

remove_torrent() is non-blocking, but will remove the torrent from the │ │ │ │ +session synchronously. Calling session_handle::add_torrent() immediately │ │ │ │ +afterward with the same torrent will succeed. Note that this creates a │ │ │ │ +new handle which is not equal to the removed one.

│ │ │ │ +

The optional second argument options can be used to delete all the │ │ │ │ +files downloaded by this torrent. To do so, pass in the value │ │ │ │ +session_handle::delete_files. Once the torrent is deleted, a │ │ │ │ +torrent_deleted_alert is posted.

│ │ │ │ +

The torrent_handle remains valid for some time after remove_torrent() is │ │ │ │ +called. It will become invalid only after all libtorrent tasks (such as │ │ │ │ +I/O tasks) release their references to the torrent. Until this happens, │ │ │ │ +torrent_handle::is_valid() will return true, and other calls such │ │ │ │ +as torrent_handle::status() will succeed. Because of this, and because │ │ │ │ +remove_torrent() is non-blocking, the following sequence usually │ │ │ │ +succeeds (does not throw system_error): │ │ │ │ +.. code:: c++

│ │ │ │ +
│ │ │ │ +session.remove_handle(handle); │ │ │ │ +handle.save_resume_data();
│ │ │ │ +

Note that when a queued or downloading torrent is removed, its position │ │ │ │ +in the download queue is vacated and every subsequent torrent in the │ │ │ │ +queue has their queue positions updated. This can potentially cause a │ │ │ │ +large state_update to be posted. When removing all torrents, it is │ │ │ │ +advised to remove them from the back of the queue, to minimize the │ │ │ │ +shifting.

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

get_settings() apply_settings()

│ │ │ │ 
│ │ │ │ -index_range<file_index_t> file_range () const noexcept;
│ │ │ │ +void apply_settings (settings_pack&&);
│ │ │ │ +settings_pack get_settings () const;
│ │ │ │ +void apply_settings (settings_pack const&);
│ │ │ │
│ │ │ │ -

all file indices in the torrent to be created

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

file_piece_range()

│ │ │ │ +

Applies the settings specified by the settings_pack s. This is an │ │ │ │ +asynchronous operation that will return immediately and actually apply │ │ │ │ +the settings to the main thread of libtorrent some time later.

│ │ │ │ + │ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

wait_for_alert() set_alert_notify() pop_alerts()

│ │ │ │ 
│ │ │ │ -index_range<piece_index_t::diff_type> file_piece_range (file_index_t f);
│ │ │ │ +alert* wait_for_alert (time_duration max_wait);
│ │ │ │ +void set_alert_notify (std::function<void()> const& fun);
│ │ │ │ +void pop_alerts (std::vector<alert*>* alerts);
│ │ │ │
│ │ │ │ -

for v2 and hybrid torrents only, the pieces in the │ │ │ │ -specified file, specified as delta from the first piece in the file. │ │ │ │ -i.e. the first index is 0.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

total_size()

│ │ │ │ +

Alerts is the main mechanism for libtorrent to report errors and │ │ │ │ +events. pop_alerts fills in the vector passed to it with pointers │ │ │ │ +to new alerts. The session still owns these alerts and they will stay │ │ │ │ +valid until the next time pop_alerts is called. You may not delete │ │ │ │ +the alert objects.

│ │ │ │ +

It is safe to call pop_alerts from multiple different threads, as │ │ │ │ +long as the alerts themselves are not accessed once another thread │ │ │ │ +calls pop_alerts. Doing this requires manual synchronization │ │ │ │ +between the popping threads.

│ │ │ │ +

wait_for_alert will block the current thread for max_wait time │ │ │ │ +duration, or until another alert is posted. If an alert is available │ │ │ │ +at the time of the call, it returns immediately. The returned alert │ │ │ │ +pointer is the head of the alert queue. wait_for_alert does not │ │ │ │ +pop alerts from the queue, it merely peeks at it. The returned alert │ │ │ │ +will stay valid until pop_alerts is called twice. The first time │ │ │ │ +will pop it and the second will free it.

│ │ │ │ +

If there is no alert in the queue and no alert arrives within the │ │ │ │ +specified timeout, wait_for_alert returns nullptr.

│ │ │ │ +

In the python binding, wait_for_alert takes the number of │ │ │ │ +milliseconds to wait as an integer.

│ │ │ │ +

The alert queue in the session will not grow indefinitely. Make sure │ │ │ │ +to pop periodically to not miss notifications. To control the max │ │ │ │ +number of alerts that's queued by the session, see │ │ │ │ +settings_pack::alert_queue_size.

│ │ │ │ +

Some alerts are considered so important that they are posted even when │ │ │ │ +the alert queue is full. Some alerts are considered mandatory and cannot │ │ │ │ +be disabled by the alert_mask. For instance, │ │ │ │ +save_resume_data_alert and save_resume_data_failed_alert are always │ │ │ │ +posted, regardless of the alert mask.

│ │ │ │ +

To control which alerts are posted, set the alert_mask │ │ │ │ +(settings_pack::alert_mask).

│ │ │ │ +

If the alert queue fills up to the point where alerts are dropped, this │ │ │ │ +will be indicated by a alerts_dropped_alert, which contains a bitmask │ │ │ │ +of which types of alerts were dropped. Generally it is a good idea to │ │ │ │ +make sure the alert queue is large enough, the alert_mask doesn't have │ │ │ │ +unnecessary categories enabled and to call pop_alert() frequently, to │ │ │ │ +avoid alerts being dropped.

│ │ │ │ +

the set_alert_notify function lets the client set a function object │ │ │ │ +to be invoked every time the alert queue goes from having 0 alerts to │ │ │ │ +1 alert. This function is called from within libtorrent, it may be the │ │ │ │ +main thread, or it may be from within a user call. The intention of │ │ │ │ +of the function is that the client wakes up its main thread, to poll │ │ │ │ +for more alerts using pop_alerts(). If the notify function fails │ │ │ │ +to do so, it won't be called again, until pop_alerts is called for │ │ │ │ +some other reason. For instance, it could signal an eventfd, post a │ │ │ │ +message to an HWND or some other main message pump. The actual │ │ │ │ +retrieval of alerts should not be done in the callback. In fact, the │ │ │ │ +callback should not block. It should not perform any expensive work. │ │ │ │ +It really should just notify the main application thread.

│ │ │ │ +

The type of an alert is returned by the polymorphic function │ │ │ │ +alert::type() but can also be queries from a concrete type via │ │ │ │ +T::alert_type, as a static constant.

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

add_port_mapping() delete_port_mapping()

│ │ │ │ 
│ │ │ │ -std::int64_t total_size () const;
│ │ │ │ +void delete_port_mapping (port_mapping_t handle);
│ │ │ │ +std::vector<port_mapping_t> add_port_mapping (portmap_protocol t, int external_port, int local_port);
│ │ │ │
│ │ │ │ -

the total number of bytes of all files and pad files

│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

piece_size() piece_length()

│ │ │ │ +

add_port_mapping adds one or more port forwards on UPnP and/or NAT-PMP, │ │ │ │ +whichever is enabled. A mapping is created for each listen socket │ │ │ │ +in the session. The return values are all handles referring to the │ │ │ │ +port mappings that were just created. Pass them to delete_port_mapping() │ │ │ │ +to remove them.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

reopen_network_sockets()

│ │ │ │ 
│ │ │ │ -int piece_length () const;
│ │ │ │ -int piece_size (piece_index_t i) const;
│ │ │ │ +void reopen_network_sockets (reopen_network_flags_t options = reopen_map_ports);
│ │ │ │
│ │ │ │ -

piece_length() returns the piece size of all pieces but the │ │ │ │ -last one. piece_size() returns the size of the specified piece. │ │ │ │ -these functions are just forwarding to the associated file_storage.

│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

add_similar_torrent() add_collection()

│ │ │ │ +

Instructs the session to reopen all listen and outgoing sockets.

│ │ │ │ +

It's useful in the case your platform doesn't support the built in │ │ │ │ +IP notifier mechanism, or if you have a better more reliable way to │ │ │ │ +detect changes in the IP routing table.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

native_handle()

│ │ │ │ 
│ │ │ │ -void add_collection (string_view c);
│ │ │ │ -void add_similar_torrent (sha1_hash ih);
│ │ │ │ +std::shared_ptr<aux::session_impl> native_handle () const;
│ │ │ │
│ │ │ │ -

Add similar torrents (by info-hash) or collections of similar torrents. │ │ │ │ -Similar torrents are expected to share some files with this torrent. │ │ │ │ -Torrents sharing a collection name with this torrent are also expected │ │ │ │ -to share files with this torrent. A torrent may have more than one │ │ │ │ -collection and more than one similar torrents. For more information, │ │ │ │ -see BEP 38.

│ │ │ │ -[report issue]
│ │ │ │ -
modification_time
│ │ │ │ -
This will include the file modification time as part of the torrent. │ │ │ │ -This is not enabled by default, as it might cause problems when you │ │ │ │ -create a torrent from separate files with the same content, hoping to │ │ │ │ -yield the same info-hash. If the files have different modification times, │ │ │ │ -with this option enabled, you would get different info-hashes for the │ │ │ │ -files.
│ │ │ │ +

This function is intended only for use by plugins. This type does │ │ │ │ +not have a stable API and should be relied on as little as possible.

│ │ │ │ +[report issue]
│ │ │ │ +
save_settings
│ │ │ │ +
saves settings (i.e. the settings_pack)
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
symlinks
│ │ │ │ -
If this flag is set, files that are symlinks get a symlink attribute │ │ │ │ -set on them and their data will not be included in the torrent. This │ │ │ │ -is useful if you need to reconstruct a file hierarchy which contains │ │ │ │ -symlinks.
│ │ │ │ +[report issue]
│ │ │ │ +
save_dht_state
│ │ │ │ +
saves dht state such as nodes and node-id, possibly accelerating │ │ │ │ +joining the DHT if provided at next session startup.
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
v2_only
│ │ │ │ -
Do not generate v1 metadata. The resulting torrent will only be usable by │ │ │ │ -clients which support v2. This requires setting all v2 hashes, with │ │ │ │ -set_hash2() before calling generate(). Setting v1 hashes (with │ │ │ │ -set_hash()) is an error with this flag set.
│ │ │ │ +[report issue]
│ │ │ │ +
save_extension_state
│ │ │ │ +
load or save state from plugins
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
v1_only
│ │ │ │ -
do not generate v2 metadata or enforce v2 alignment and padding rules │ │ │ │ -this is mainly for tests, not recommended for production use. This │ │ │ │ -requires setting all v1 hashes, with set_hash(), before calling │ │ │ │ -generate(). Setting v2 hashes (with set_hash2()) is an error with │ │ │ │ -this flag set.
│ │ │ │ +[report issue]
│ │ │ │ +
save_ip_filter
│ │ │ │ +
load or save the IP filter set on the session
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
canonical_files
│ │ │ │ -
This flag only affects v1-only torrents, and is only relevant │ │ │ │ -together with the v1_only_flag. This flag will force the │ │ │ │ -same file order and padding as a v2 (or hybrid) torrent would have. │ │ │ │ -It has the effect of ordering files and inserting pad files to align │ │ │ │ -them with piece boundaries.
│ │ │ │ + │ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
global_peer_class_id tcp_peer_class_id local_peer_class_id
│ │ │ │ +
built-in peer classes
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
no_attributes
│ │ │ │ -
passing this flag to add_files() will ignore file attributes (such as │ │ │ │ -executable or hidden) when adding the files to the file storage. │ │ │ │ -Since not all filesystems and operating systems support all file │ │ │ │ -attributes the resulting torrent may differ depending on where it's │ │ │ │ -created. If it's important for torrents to be created consistently │ │ │ │ -across systems, this flag should be set.
│ │ │ │ +[report issue]
│ │ │ │ +
delete_files
│ │ │ │ +
delete the files belonging to the torrent from disk. │ │ │ │ +including the part-file, if there is one
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
canonical_files_no_tail_padding
│ │ │ │ -
this flag enforces the file layout to be canonical according to the │ │ │ │ -bittorrent v2 specification (just like the canonical_files flag) │ │ │ │ -with the one exception that tail padding is not added to the last │ │ │ │ -file. │ │ │ │ -This behavior deviates from the specification but was the way │ │ │ │ -libtorrent created torrents in version up to and including 2.0.7. │ │ │ │ -This flag is here for backwards compatibility.
│ │ │ │ +[report issue]
│ │ │ │ +
delete_partfile
│ │ │ │ +
delete just the part-file associated with this torrent
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ +[report issue]
│ │ │ │ +
paused
│ │ │ │ +
when set, the session will start paused. Call │ │ │ │ +session_handle::resume() to start
│ │ │ │ +
│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
udp tcp
│ │ │ │ +
protocols used by add_port_mapping()
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
reopen_map_ports
│ │ │ │ +
This option indicates if the ports are mapped using natpmp │ │ │ │ +and upnp. If mapping was already made, they are deleted and added │ │ │ │ +again. This only works if natpmp and/or upnp are configured to be │ │ │ │ +enable.
│ │ │ │ +
│ │ │ │ + │ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │
│ │ │ │ -
│ │ │ │ -

add_files()

│ │ │ │ -

Declared in "libtorrent/create_torrent.hpp"

│ │ │ │ -
│ │ │ │ -void add_files (file_storage& fs, std::string const& file
│ │ │ │ -   , create_flags_t flags = {});
│ │ │ │ -void add_files (file_storage& fs, std::string const& file
│ │ │ │ -   , std::function<bool(std::string)> p, create_flags_t flags = {});
│ │ │ │ -
│ │ │ │ -

Adds the file specified by path to the file_storage object. In case path │ │ │ │ -refers to a directory, files will be added recursively from the directory.

│ │ │ │ -

If specified, the predicate p is called once for every file and directory that │ │ │ │ -is encountered. Files for which p returns true are added, and directories for │ │ │ │ -which p returns true are traversed. p must have the following signature:

│ │ │ │ -
│ │ │ │ -bool Pred(std::string const& p);
│ │ │ │ -
│ │ │ │ -

The path that is passed in to the predicate is the full path of the file or │ │ │ │ -directory. If no predicate is specified, all files are added, and all directories │ │ │ │ -are traversed.

│ │ │ │ -

The ".." directory is never traversed.

│ │ │ │ -

The flags argument should be the same as the flags passed to the create_torrent │ │ │ │ -constructor.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

set_piece_hashes()

│ │ │ │ -

Declared in "libtorrent/create_torrent.hpp"

│ │ │ │ -
│ │ │ │ -inline void set_piece_hashes (create_torrent& t, std::string const& p);
│ │ │ │ -void set_piece_hashes (create_torrent& t, std::string const& p
│ │ │ │ -   , settings_interface const& settings
│ │ │ │ -   , std::function<void(piece_index_t)> const& f, error_code& ec);
│ │ │ │ -inline void set_piece_hashes (create_torrent& t, std::string const& p
│ │ │ │ -   , settings_interface const& settings
│ │ │ │ -   , std::function<void(piece_index_t)> const& f);
│ │ │ │ -void set_piece_hashes (create_torrent& t, std::string const& p
│ │ │ │ -   , settings_interface const& settings, disk_io_constructor_type disk_io
│ │ │ │ -   , std::function<void(piece_index_t)> const& f, error_code& ec);
│ │ │ │ -void set_piece_hashes (create_torrent& t, std::string const& p
│ │ │ │ -   , std::function<void(piece_index_t)> const& f, error_code& ec);
│ │ │ │ -inline void set_piece_hashes (create_torrent& t, std::string const& p, error_code& ec);
│ │ │ │ -inline void set_piece_hashes (create_torrent& t, std::string const& p
│ │ │ │ -   , std::function<void(piece_index_t)> const& f);
│ │ │ │ -
│ │ │ │ -

This function will assume that the files added to the torrent file exists at path │ │ │ │ -p, read those files and hash the content and set the hashes in the create_torrent │ │ │ │ -object. The optional function f is called in between every hash that is set. f │ │ │ │ -must have the following signature:

│ │ │ │ -
│ │ │ │ -void Fun(piece_index_t);
│ │ │ │ -
│ │ │ │ -

The overloads taking a settings_pack may be used to configure the │ │ │ │ -underlying disk access. Such as settings_pack::aio_threads.

│ │ │ │ -

The overloads that don't take an error_code& may throw an exception in case of a │ │ │ │ -file error, the other overloads sets the error code to reflect the error, if any.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

piece_block

│ │ │ │ -

Declared in "libtorrent/piece_block.hpp"

│ │ │ │ +
│ │ │ │ +

write_session_params() write_session_params_buf() read_session_params()

│ │ │ │ +

Declared in "libtorrent/session_params.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;
│ │ │ │ -};
│ │ │ │ +std::vector<char> write_session_params_buf (session_params const& sp
│ │ │ │ +   , save_state_flags_t flags = save_state_flags_t::all());
│ │ │ │ +entry write_session_params (session_params const& sp
│ │ │ │ +   , save_state_flags_t flags = save_state_flags_t::all());
│ │ │ │ +session_params read_session_params (span<char const> buf
│ │ │ │ +   , save_state_flags_t flags = save_state_flags_t::all());
│ │ │ │ +session_params read_session_params (bdecode_node const& e
│ │ │ │ +   , save_state_flags_t flags = save_state_flags_t::all());
│ │ │ │
│ │ │ │ +

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

│ │ │ │ [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;
│ │ │ │ +   info_hash_t (sha1_hash h1, sha256_hash h2) noexcept;
│ │ │ │     explicit info_hash_t (sha1_hash h1) noexcept;
│ │ │ │ +   explicit info_hash_t (sha256_hash h2) noexcept;
│ │ │ │     info_hash_t () noexcept = default;
│ │ │ │ -   info_hash_t (sha1_hash h1, sha256_hash h2) noexcept;
│ │ │ │ -   bool has_v2 () const;
│ │ │ │ -   bool has_v1 () const;
│ │ │ │     bool has (protocol_version v) const;
│ │ │ │ +   bool has_v1 () 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);
│ │ │ │ @@ -4208,33 +1858,33 @@
│ │ │ │     sha1_hash v1;
│ │ │ │     sha256_hash v2;
│ │ │ │  };
│ │ │ │
│ │ │ │ [report issue]
│ │ │ │

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;
│ │ │ │ +explicit info_hash_t (sha256_hash h2) 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() has_v2() has_v1()

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

has() has_v1() has_v2()

│ │ │ │ 
│ │ │ │ -bool has_v2 () const;
│ │ │ │ -bool has_v1 () const;
│ │ │ │  bool has (protocol_version v) const;
│ │ │ │ +bool has_v1 () const;
│ │ │ │ +bool has_v2 () const;
│ │ │ │
│ │ │ │

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

│ │ │ │ [report issue]
│ │ │ │
│ │ │ │

get()

│ │ │ │ 
│ │ │ │ @@ -4732,14 +2382,32 @@
│ │ │ │  [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 (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;
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ [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.

│ │ │ │ 
│ │ │ │ @@ -4748,15 +2416,15 @@
│ │ │ │     bool operator== (peer_request const& r) const;
│ │ │ │  
│ │ │ │     piece_index_t piece;
│ │ │ │     int start;
│ │ │ │     int length;
│ │ │ │  };
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ +[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]
│ │ │ │ @@ -4767,23 +2435,65 @@ │ │ │ │
start
│ │ │ │
The byte offset within that piece where the range starts.
│ │ │ │
│ │ │ │ [report issue]
│ │ │ │
length
│ │ │ │
The size of the range, in bytes.
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ + │ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │
│ │ │ │ +
│ │ │ │ +

load_torrent_file() load_torrent_parsed() load_torrent_buffer()

│ │ │ │ +

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

│ │ │ │ +
│ │ │ │ + │ │ │ │ +
│ │ │ │ +[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]
│ │ │ │
│ │ │ │

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);
│ │ │ │ +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, │ │ │ │ @@ -4803,100 +2513,58 @@ │ │ │ │ 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, 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);
│ │ │ │ +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]
│ │ │ │ -
│ │ │ │ -

load_torrent_buffer() load_torrent_parsed() load_torrent_file()

│ │ │ │ -

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_file (
│ │ │ │ -   std::string const& filename, 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_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:

│ │ │ │ -
│ │ │ │ - │ │ │ │ -
│ │ │ │ [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]
│ │ │ │ -
│ │ │ │ -

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 connection_type

│ │ │ │ -

Declared in "libtorrent/peer_connection.hpp"

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

enum protocol_version

│ │ │ │ +

Declared in "libtorrent/info_hash.hpp"

│ │ │ │ │ │ │ │ │ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │
namevaluedescription
bittorrent
V10 The original BitTorrent version, using SHA-1 hashes
url_seed
V21 Version 2 of the BitTorrent protocol, using SHA-256 hashes
http_seed
NUM2 
│ │ │ │ [report issue]
│ │ │ │
│ │ │ │ @@ -4933,14 +2601,45 @@ │ │ │ │ │ │ │ │ paused │ │ │ │ 4 │ │ │ │   │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

enum connection_type

│ │ │ │ +

Declared in "libtorrent/peer_connection.hpp"

│ │ │ │ + │ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ +
namevaluedescription
bittorrent0 
url_seed1 
http_seed2 
│ │ │ │ [report issue]
│ │ │ │
│ │ │ │

enum socket_type_t

│ │ │ │

Declared in "libtorrent/socket_type.hpp"

│ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ @@ -5046,45 +2745,14 @@ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │
udp2 
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

enum protocol_version

│ │ │ │ -

Declared in "libtorrent/info_hash.hpp"

│ │ │ │ - │ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ -
namevaluedescription
V10The original BitTorrent version, using SHA-1 hashes
V21Version 2 of the BitTorrent protocol, using SHA-256 hashes
NUM2 
│ │ │ │ [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 │ │ │ │ @@ -5098,14 +2766,57 @@ │ │ │ │
low_priority
│ │ │ │
The lowest priority for files and pieces.
│ │ │ │
│ │ │ │
│ │ │ │
top_priority
│ │ │ │
The highest priority for files and pieces.
│ │ │ │
│ │ │ │ +[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]
│ │ │ │ +
│ │ │ │ +

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]
│ │ │ │
│ │ │ │

torrent_flags_t

│ │ │ │

Declared in "libtorrent/torrent_flags.hpp"

│ │ │ │
│ │ │ │
seed_mode
│ │ │ │

If seed_mode is set, libtorrent will assume that all files │ │ │ │ @@ -5234,15 +2945,15 @@ │ │ │ │ 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 │ │ │ │ +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

│ │ │ │
│ │ │ │ @@ -5317,30 +3028,14 @@ │ │ │ │ (dont_download). │ │ │ │
│ │ │ │
│ │ │ │
all
│ │ │ │
all torrent flags combined. Can conveniently be used when creating masks │ │ │ │ for flags
│ │ │ │
│ │ │ │ -[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
│ │ │ │ @@ -5349,919 +3044,1606 @@ │ │ │ │
│ │ │ │

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
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

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;
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
version
│ │ │ │ +
filled in by the constructor and should be left untouched. It is used │ │ │ │ +for forward binary compatibility.
│ │ │ │
│ │ │ │ -
│ │ │ │ -
pex_seed
│ │ │ │ -
the peer is a seed
│ │ │ │ +[report issue]
│ │ │ │ +
ti
│ │ │ │ +
torrent_info object with the torrent to add. Unless the │ │ │ │ +info_hash is set, this is required to be initialized.
│ │ │ │
│ │ │ │ -
│ │ │ │ -
pex_utp
│ │ │ │ -
the peer supports the uTP, transport protocol over UDP.
│ │ │ │ +[report issue]
│ │ │ │ +
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.
│ │ │ │
│ │ │ │ -
│ │ │ │ -
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
│ │ │ │ +[report issue]
│ │ │ │ +
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.
│ │ │ │
│ │ │ │ -
│ │ │ │ -
pex_lt_v2
│ │ │ │ -
protocol v2 │ │ │ │ -this is not a standard flag, it is only used internally
│ │ │ │ +[report issue]
│ │ │ │ +
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.
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

ip_filter

│ │ │ │ -

Declared in "libtorrent/ip_filter.hpp"

│ │ │ │ -

The ip_filter class is a set of rules that uniquely categorizes all │ │ │ │ -ip addresses as allowed or disallowed. The default constructor creates │ │ │ │ -a single rule that allows all addresses (0.0.0.0 - 255.255.255.255 for │ │ │ │ -the IPv4 range, and the equivalent range covering all addresses for the │ │ │ │ -IPv6 range).

│ │ │ │ -

A default constructed ip_filter does not filter any address.

│ │ │ │ +[report issue]
│ │ │ │ +
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.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
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.

│ │ │ │ +
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
storage_mode
│ │ │ │ +
One of the values from storage_mode_t. For more information, see │ │ │ │ +storage allocation.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
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().
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
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.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
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.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
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.

│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
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.
│ │ │ │ +
│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
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.

│ │ │ │ +
│ │ │ │ +
│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
upload_limit download_limit
│ │ │ │ +
the upload and download rate limits for this torrent, specified in │ │ │ │ +bytes per second. -1 means unlimited.
│ │ │ │ +
│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
total_uploaded total_downloaded
│ │ │ │ +
the total number of bytes uploaded and downloaded by this torrent so │ │ │ │ +far.
│ │ │ │ +
│ │ │ │ + │ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
active_time finished_time seeding_time
│ │ │ │ +
the number of seconds this torrent has spent in started, finished and │ │ │ │ +seeding state so far, respectively.
│ │ │ │ +
│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
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.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
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.
│ │ │ │ +
│ │ │ │ + │ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
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.

│ │ │ │ +
│ │ │ │ +
│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
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.

│ │ │ │ +
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
peers
│ │ │ │ +
peers to add to the torrent, to be tried to be connected to as │ │ │ │ +bittorrent peers.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
banned_peers
│ │ │ │ +
peers banned from this torrent. The will not be connected to
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
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.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
have_pieces
│ │ │ │ +
this is a bitfield indicating which pieces we already have of this │ │ │ │ +torrent.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
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.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
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.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
merkle_trees
│ │ │ │ +
v2 hashes, if known
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
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.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
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.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
renamed_files
│ │ │ │ +
this is a map of file indices in the torrent and new filenames to be │ │ │ │ +applied before the torrent is added.
│ │ │ │ +
│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
last_download last_upload
│ │ │ │ +
the posix time of the last time payload was received or sent for this │ │ │ │ +torrent, respectively.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

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 ip_filter
│ │ │ │ +struct client_data_t
│ │ │ │  {
│ │ │ │ -   ip_filter ();
│ │ │ │ -   ip_filter (ip_filter&&);
│ │ │ │ -   ip_filter& operator= (ip_filter const&);
│ │ │ │ -   ip_filter& operator= (ip_filter&&);
│ │ │ │ -   ip_filter (ip_filter const&);
│ │ │ │ -   ~ip_filter ();
│ │ │ │ -   bool empty () const;
│ │ │ │ -   void add_rule (address const& first, address const& last, std::uint32_t flags);
│ │ │ │ -   std::uint32_t access (address const& addr) const;
│ │ │ │ -   filter_tuple_t export_filter () const;
│ │ │ │ +   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*) = delete;
│ │ │ │ +   operator void const* () const = delete;
│ │ │ │ +   client_data_t& operator= (void const*) = delete;
│ │ │ │ +   operator void* () const = delete;
│ │ │ │  
│ │ │ │ -   enum access_flags
│ │ │ │ -   {
│ │ │ │ -      blocked,
│ │ │ │ -   };
│ │ │ │ +   template <typename T, typename U  = typename std::enable_if<std::is_pointer<T>::value>::type>
│ │ │ │  };
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -

empty()

│ │ │ │ +[report issue]
│ │ │ │ +

client_data_t()

│ │ │ │ 
│ │ │ │ -bool empty () const;
│ │ │ │ +client_data_t () = default;
│ │ │ │
│ │ │ │ -

returns true if the filter does not contain any rules

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

add_rule()

│ │ │ │ +

construct a nullptr client data

│ │ │ │ + │ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

const*() void*() operator=()

│ │ │ │ 
│ │ │ │ -void add_rule (address const& first, address const& last, std::uint32_t flags);
│ │ │ │ +client_data_t& operator= (void*) = delete;
│ │ │ │ +operator void const* () const = delete;
│ │ │ │ +client_data_t& operator= (void const*) = delete;
│ │ │ │ +operator void* () const = delete;
│ │ │ │
│ │ │ │ -

Adds a rule to the filter. first and last defines a range of │ │ │ │ -ip addresses that will be marked with the given flags. The flags │ │ │ │ -can currently be 0, which means allowed, or ip_filter::blocked, which │ │ │ │ -means disallowed.

│ │ │ │ -

precondition: │ │ │ │ -first.is_v4() == last.is_v4() && first.is_v6() == last.is_v6()

│ │ │ │ -

postcondition: │ │ │ │ -access(x) == flags for every x in the range [first, last]

│ │ │ │ -

This means that in a case of overlapping ranges, the last one applied takes │ │ │ │ -precedence.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

access()

│ │ │ │ +

we don't allow type-unsafe operations

│ │ │ │ +

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:

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +

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.

│ │ │ │ 
│ │ │ │ -std::uint32_t access (address const& addr) const;
│ │ │ │ +struct open_file_state
│ │ │ │ +{
│ │ │ │ +   file_index_t file_index;
│ │ │ │ +   file_open_mode_t open_mode;
│ │ │ │ +   time_point last_use;
│ │ │ │ +};
│ │ │ │
│ │ │ │ -

Returns the access permissions for the given address (addr). The permission │ │ │ │ -can currently be 0 or ip_filter::blocked. The complexity of this operation │ │ │ │ -is O(log n), where n is the minimum number of non-overlapping ranges to describe │ │ │ │ -the current filter.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

export_filter()

│ │ │ │ +[report issue]
│ │ │ │ +
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.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
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.

│ │ │ │ +
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
last_use
│ │ │ │ +
a (high precision) timestamp of when the file was last used.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

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.

│ │ │ │ 
│ │ │ │ -filter_tuple_t export_filter () const;
│ │ │ │ +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 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_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 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;
│ │ │ │ +};
│ │ │ │
│ │ │ │ -

This function will return the current state of the filter in the minimum number of │ │ │ │ -ranges possible. They are sorted from ranges in low addresses to high addresses. Each │ │ │ │ -entry in the returned vector is a range with the access control specified in its │ │ │ │ -flags field.

│ │ │ │ -

The return value is a tuple containing two range-lists. One for IPv4 addresses │ │ │ │ -and one for IPv6 addresses.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

enum access_flags

│ │ │ │ -

Declared in "libtorrent/ip_filter.hpp"

│ │ │ │ - │ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ -
namevaluedescription
blocked1indicates that IPs in this range should not be connected │ │ │ │ -to nor accepted as incoming connections
│ │ │ │ -[report issue]
│ │ │ │ +[report issue]
│ │ │ │ +

new_torrent()

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

this is called when a new torrent is added. The shared_ptr can be │ │ │ │ +used to hold the internal torrent object alive as long as there are │ │ │ │ +outstanding disk operations on the storage. │ │ │ │ +The returned storage_holder is an owning reference to the underlying │ │ │ │ +storage that was just created. It is fundamentally a storage_index_t

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

remove_torrent()

│ │ │ │ +
│ │ │ │ +virtual void remove_torrent (storage_index_t) = 0;
│ │ │ │ +
│ │ │ │ +

remove the storage with the specified index. This is not expected to │ │ │ │ +delete any files from disk, just to clean up any resources associated │ │ │ │ +with the specified storage.

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

async_write() async_read()

│ │ │ │ +
│ │ │ │ +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_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;
│ │ │ │ +
│ │ │ │ +

perform a read or write operation from/to the specified storage │ │ │ │ +index and the specified request. When the operation completes, call │ │ │ │ +handler possibly with a disk_buffer_holder, holding the buffer with │ │ │ │ +the result. Flags may be set to affect the read operation. See │ │ │ │ +disk_job_flags_t.

│ │ │ │ +

The disk_observer is a callback to indicate that │ │ │ │ +the store buffer/disk write queue is below the watermark to let peers │ │ │ │ +start writing buffers to disk again. When async_write() returns │ │ │ │ +true, indicating the write queue is full, the peer will stop │ │ │ │ +further writes and wait for the passed-in disk_observer to be │ │ │ │ +notified before resuming.

│ │ │ │ +

Note that for async_read, the peer_request (r) is not │ │ │ │ +necessarily aligned to blocks (but it is most of the time). However, │ │ │ │ +all writes (passed to async_write) are guaranteed to be block │ │ │ │ +aligned.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

async_hash()

│ │ │ │ +
│ │ │ │ +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;
│ │ │ │ +
│ │ │ │ +

Compute hash(es) for the specified piece. Unless the v1_hash flag is │ │ │ │ +set (in flags), the SHA-1 hash of the whole piece does not need │ │ │ │ +to be computed.

│ │ │ │ +

The v2 span is optional and can be empty, which means v2 hashes │ │ │ │ +should not be computed. If v2 is non-empty it must be at least large │ │ │ │ +enough to hold all v2 blocks in the piece, and this function will │ │ │ │ +fill in the span with the SHA-256 block hashes of the piece.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

async_hash2()

│ │ │ │ +
│ │ │ │ +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;
│ │ │ │ +
│ │ │ │ +

computes the v2 hash (SHA-256) of a single block. The block at │ │ │ │ +offset in piece piece.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

async_move_storage()

│ │ │ │ +
│ │ │ │ +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;
│ │ │ │ +
│ │ │ │ +

called to request the files for the specified storage/torrent be │ │ │ │ +moved to a new location. It is the disk I/O object's responsibility │ │ │ │ +to synchronize this with any currently outstanding disk operations to │ │ │ │ +the storage. Whether files are replaced at the destination path or │ │ │ │ +not is controlled by flags (see move_flags_t).

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

async_release_files()

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

This is called on disk I/O objects to request they close all open │ │ │ │ +files for the specified storage/torrent. If file handles are not │ │ │ │ +pooled/cached, it can be a no-op. For truly asynchronous disk I/O, │ │ │ │ +this should provide at least one point in time when all files are │ │ │ │ +closed. It is possible that later asynchronous operations will │ │ │ │ +re-open some of the files, by the time this completion handler is │ │ │ │ +called, that's fine.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

async_check_files()

│ │ │ │ +
│ │ │ │ +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;
│ │ │ │ +
│ │ │ │ +

this is called when torrents are added to validate their resume data │ │ │ │ +against the files on disk. This function is expected to do a few things:

│ │ │ │ +

if links is non-empty, it contains a string for each file in the │ │ │ │ +torrent. The string being a path to an existing identical file. The │ │ │ │ +default behavior is to create hard links of those files into the │ │ │ │ +storage of the new torrent (specified by storage). An empty │ │ │ │ +string indicates that there is no known identical file. This is part │ │ │ │ +of the "mutable torrent" feature, where files can be reused from │ │ │ │ +other torrents.

│ │ │ │ +

The resume_data points the resume data passed in by the client.

│ │ │ │ +

If the resume_data->flags field has the seed_mode flag set, all │ │ │ │ +files/pieces are expected to be on disk already. This should be │ │ │ │ +verified. Not just the existence of the file, but also that it has │ │ │ │ +the correct size.

│ │ │ │ +

Any file with a piece set in the resume_data->have_pieces bitmask │ │ │ │ +should exist on disk, this should be verified. Pad files and files │ │ │ │ +with zero priority may be skipped.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

async_stop_torrent()

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

This is called when a torrent is stopped. It gives the disk I/O │ │ │ │ +object an opportunity to flush any data to disk that's currently kept │ │ │ │ +cached. This function should at least do the same thing as │ │ │ │ +async_release_files().

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

async_rename_file()

│ │ │ │ +
│ │ │ │ +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;
│ │ │ │ +
│ │ │ │ +

This function is called when the name of a file in the specified │ │ │ │ +storage has been requested to be renamed. The disk I/O object is │ │ │ │ +responsible for renaming the file without racing with other │ │ │ │ +potentially outstanding operations against the file (such as read, │ │ │ │ +write, move, etc.).

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

async_delete_files()

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

This function is called when some file(s) on disk have been requested │ │ │ │ +to be removed by the client. storage indicates which torrent is │ │ │ │ +referred to. See session_handle for remove_flags_t flags │ │ │ │ +indicating which files are to be removed. │ │ │ │ +e.g. session_handle::delete_files - delete all files │ │ │ │ +session_handle::delete_partfile - only delete part file.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

async_set_file_priority()

│ │ │ │ +
│ │ │ │ +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;
│ │ │ │ +
│ │ │ │ +

This is called to set the priority of some or all files. Changing the │ │ │ │ +priority from or to 0 may involve moving data to and from the │ │ │ │ +partfile. The disk I/O object is responsible for correctly │ │ │ │ +synchronizing this work to not race with any potentially outstanding │ │ │ │ +asynchronous operations affecting these files.

│ │ │ │ +

prio is a vector of the file priority for all files. If it's │ │ │ │ +shorter than the total number of files in the torrent, they are │ │ │ │ +assumed to be set to the default priority.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

async_clear_piece()

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

This is called when a piece fails the hash check, to ensure there are │ │ │ │ +no outstanding disk operations to the piece before blocks are │ │ │ │ +re-requested from peers to overwrite the existing blocks. The disk I/O │ │ │ │ +object does not need to perform any action other than synchronize │ │ │ │ +with all outstanding disk operations to the specified piece before │ │ │ │ +posting the result back.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

update_stats_counters()

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

update_stats_counters() is called to give the disk storage an │ │ │ │ +opportunity to update gauges in the c stats counters, that aren't │ │ │ │ +updated continuously as operations are performed. This is called │ │ │ │ +before a snapshot of the counters are passed to the client.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

get_status()

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

Return a list of all the files that are currently open for the │ │ │ │ +specified storage/torrent. This is is just used for the client to │ │ │ │ +query the currently open files, and which modes those files are open │ │ │ │ +in.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

abort()

│ │ │ │ +
│ │ │ │ +virtual void abort (bool wait) = 0;
│ │ │ │ +
│ │ │ │ +

this is called when the session is starting to shut down. The disk │ │ │ │ +I/O object is expected to flush any outstanding write jobs, cancel │ │ │ │ +hash jobs and initiate tearing down of any internal threads. If │ │ │ │ +wait is true, this should be asynchronous. i.e. this call should │ │ │ │ +not return until all threads have stopped and all jobs have either │ │ │ │ +been aborted or completed and the disk I/O object is ready to be │ │ │ │ +destructed.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

submit_jobs()

│ │ │ │ +
│ │ │ │ +virtual void submit_jobs () = 0;
│ │ │ │ +
│ │ │ │ +

This will be called after a batch of disk jobs has been issues (via │ │ │ │ +the async_* ). It gives the disk I/O object an opportunity to │ │ │ │ +notify any potential condition variables to wake up the disk │ │ │ │ +thread(s). The async_* calls can of course also notify condition │ │ │ │ +variables, but doing it in this call allows for batching jobs, by │ │ │ │ +issuing the notification once for a collection of jobs.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

settings_updated()

│ │ │ │ +
│ │ │ │ +virtual void settings_updated () = 0;
│ │ │ │ +
│ │ │ │ +

This is called to notify the disk I/O object that the settings have │ │ │ │ +been updated. In the disk io constructor, a settings_interface │ │ │ │ +reference is passed in. Whenever these settings are updated, this │ │ │ │ +function is called to allow the disk I/O object to react to any │ │ │ │ +changed settings relevant to its operations.

│ │ │ │ +[report issue]
│ │ │ │ +
force_copy
│ │ │ │ +
force making a copy of the cached block, rather than getting a │ │ │ │ +reference to a block already in the cache. This is used the block is │ │ │ │ +expected to be overwritten very soon, by async_write()`, and we need │ │ │ │ +access to the previous content.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
sequential_access
│ │ │ │ +
hint that there may be more disk operations with sequential access to │ │ │ │ +the file
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
volatile_read
│ │ │ │ +
don't keep the read block in cache. This is a hint that this block is │ │ │ │ +unlikely to be read again anytime soon, and caching it would be │ │ │ │ +wasteful.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
v1_hash
│ │ │ │ +
compute a v1 piece hash. This is only used by the async_hash() call. │ │ │ │ +If this flag is not set in the async_hash() call, the SHA-1 piece │ │ │ │ +hash does not need to be computed.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
flush_piece
│ │ │ │ +
this flag instructs a hash job that we just completed this piece, and │ │ │ │ +it should be flushed to disk
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │
│ │ │ │ -
│ │ │ │ -

port_filter

│ │ │ │ -

Declared in "libtorrent/ip_filter.hpp"

│ │ │ │ -

the port filter maps non-overlapping port ranges to flags. This │ │ │ │ -is primarily used to indicate whether a range of ports should │ │ │ │ -be connected to or not. The default is to have the full port │ │ │ │ -range (0-65535) set to flag 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.

│ │ │ │ 
│ │ │ │ -class port_filter
│ │ │ │ +struct storage_holder
│ │ │ │  {
│ │ │ │ -   port_filter ();
│ │ │ │ -   port_filter (port_filter const&);
│ │ │ │ -   port_filter& operator= (port_filter&&);
│ │ │ │ -   port_filter (port_filter&&);
│ │ │ │ -   ~port_filter ();
│ │ │ │ -   port_filter& operator= (port_filter const&);
│ │ │ │ -   void add_rule (std::uint16_t first, std::uint16_t last, std::uint32_t flags);
│ │ │ │ -   std::uint32_t access (std::uint16_t port) const;
│ │ │ │ +   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;
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

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_str (int name, std::string val) = 0;
│ │ │ │ +   virtual void set_bool (int name, bool val) = 0;
│ │ │ │ +   virtual void set_int (int name, int 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;
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

disk_observer

│ │ │ │ +

Declared in "libtorrent/disk_observer.hpp"

│ │ │ │ +
│ │ │ │ +struct disk_observer
│ │ │ │ +{
│ │ │ │ +   virtual void on_disk () = 0;
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +

on_disk()

│ │ │ │ +
│ │ │ │ +virtual void on_disk () = 0;
│ │ │ │ +
│ │ │ │ +

called when the disk cache size has dropped │ │ │ │ +below the low watermark again and we can │ │ │ │ +resume downloading from peers

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +

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;
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

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& operator= (disk_buffer_holder&&) & noexcept;
│ │ │ │ +   disk_buffer_holder (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;
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +

disk_buffer_holder()

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

construct a buffer holder that will free the held buffer │ │ │ │ +using a disk buffer pool directly (there's only one │ │ │ │ +disk_buffer_pool per session)

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

disk_buffer_holder()

│ │ │ │ +
│ │ │ │ +disk_buffer_holder () noexcept = default;
│ │ │ │ +
│ │ │ │ +

default construct a holder that does not own any buffer

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

~disk_buffer_holder()

│ │ │ │ +
│ │ │ │ +~disk_buffer_holder ();
│ │ │ │ +
│ │ │ │ +

frees disk buffer held by this object

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

data()

│ │ │ │ +
│ │ │ │ +char* data () const noexcept;
│ │ │ │ +
│ │ │ │ +

return a pointer to the held buffer, if any. Otherwise returns nullptr.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

reset()

│ │ │ │ +
│ │ │ │ +void reset ();
│ │ │ │ +
│ │ │ │ +

free the held disk buffer, if any, and clear the holder. This sets the │ │ │ │ +holder object to a default-constructed state

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

swap()

│ │ │ │ +
│ │ │ │ +void swap (disk_buffer_holder& h) noexcept;
│ │ │ │ +
│ │ │ │ +

swap pointers of two disk buffer holders.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

is_mutable()

│ │ │ │ +
│ │ │ │ +bool is_mutable () const noexcept;
│ │ │ │ +
│ │ │ │ +

if this returns true, the buffer may not be modified in place

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

bool()

│ │ │ │ +
│ │ │ │ +explicit operator bool () const noexcept;
│ │ │ │ +
│ │ │ │ +

implicitly convertible to true if the object is currently holding a │ │ │ │ +buffer

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +

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
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

web_seed_entry

│ │ │ │ +

Declared in "libtorrent/torrent_info.hpp"

│ │ │ │ +

the web_seed_entry holds information about a web seed (also known │ │ │ │ +as URL seed or HTTP seed). It is essentially a URL with some state │ │ │ │ +associated with it. For more information, see BEP 17 and BEP 19.

│ │ │ │ +
│ │ │ │ +struct web_seed_entry
│ │ │ │ +{
│ │ │ │ +   bool operator== (web_seed_entry const& e) const;
│ │ │ │ +   bool operator< (web_seed_entry const& e) const;
│ │ │ │  
│ │ │ │ -   enum access_flags
│ │ │ │ +   enum type_t
│ │ │ │     {
│ │ │ │ -      blocked,
│ │ │ │ +      url_seed,
│ │ │ │ +      http_seed,
│ │ │ │     };
│ │ │ │ +
│ │ │ │ +   std::string url;
│ │ │ │ +   std::string auth;
│ │ │ │ +   headers_t extra_headers;
│ │ │ │ +   std::uint8_t type;
│ │ │ │  };
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -

add_rule()

│ │ │ │ +[report issue]
│ │ │ │ +

operator==()

│ │ │ │ 
│ │ │ │ -void add_rule (std::uint16_t first, std::uint16_t last, std::uint32_t flags);
│ │ │ │ +bool operator== (web_seed_entry const& e) const;
│ │ │ │
│ │ │ │ -

set the flags for the specified port range (first, last) to │ │ │ │ -flags overwriting any existing rule for those ports. The range │ │ │ │ -is inclusive, i.e. the port last also has the flag set on it.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

access()

│ │ │ │ +

URL and type comparison

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

operator<()

│ │ │ │ 
│ │ │ │ -std::uint32_t access (std::uint16_t port) const;
│ │ │ │ +bool operator< (web_seed_entry const& e) const;
│ │ │ │
│ │ │ │ -

test the specified port (port) for whether it is blocked │ │ │ │ -or not. The returned value is the flags set for this port. │ │ │ │ -see access_flags.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

enum access_flags

│ │ │ │ -

Declared in "libtorrent/ip_filter.hpp"

│ │ │ │ +

URL and type less-than comparison

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

enum type_t

│ │ │ │ +

Declared in "libtorrent/torrent_info.hpp"

│ │ │ │ │ │ │ │ │ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ │ │ │ │
namevaluedescription
blocked
url_seed0 
http_seed1this flag indicates that destination ports in the │ │ │ │ -range should not be connected to 
│ │ │ │ -[report issue]
│ │ │ │ +[report issue]
│ │ │ │ +
url
│ │ │ │ +
The URL of the web seed
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
auth
│ │ │ │ +
Optional authentication. If this is set, it's passed │ │ │ │ +in as HTTP basic auth to the web seed. The format is: │ │ │ │ +username:password.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
extra_headers
│ │ │ │ +
Any extra HTTP headers that need to be passed to the web seed
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
type
│ │ │ │ +
The type of web seed (see type_t)
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │
│ │ │ │ -
│ │ │ │ -

storage_params

│ │ │ │ -

Declared in "libtorrent/storage_defs.hpp"

│ │ │ │ -

a parameter pack used to construct the storage for a torrent, used in │ │ │ │ -disk_interface

│ │ │ │ -
│ │ │ │ -struct storage_params
│ │ │ │ -{
│ │ │ │ -   storage_params (file_storage const& f, file_storage const* mf
│ │ │ │ -      , std::string const& sp, storage_mode_t const sm
│ │ │ │ -      , aux::vector<download_priority_t, file_index_t> const& prio
│ │ │ │ -      , sha1_hash const& ih);
│ │ │ │ -
│ │ │ │ -   file_storage const& files;
│ │ │ │ -   file_storage const* mapped_files  = nullptr;
│ │ │ │ -   std::string const& path;
│ │ │ │ -   storage_mode_t mode {storage_mode_sparse};
│ │ │ │ -   aux::vector<download_priority_t, file_index_t> const& priorities;
│ │ │ │ -   sha1_hash info_hash;
│ │ │ │ -};
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

file_slice

│ │ │ │ -

Declared in "libtorrent/file_storage.hpp"

│ │ │ │ -

represents a window of a file in a torrent.

│ │ │ │ -

The file_index refers to the index of the file (in the torrent_info). │ │ │ │ -To get the path and filename, use file_path() and give the file_index │ │ │ │ -as argument. The offset is the byte offset in the file where the range │ │ │ │ -starts, and size is the number of bytes this range is. The size + offset │ │ │ │ -will never be greater than the file size.

│ │ │ │ +
│ │ │ │ +

load_torrent_limits

│ │ │ │ +

Declared in "libtorrent/torrent_info.hpp"

│ │ │ │ +

this object holds configuration options for limits to use when loading │ │ │ │ +torrents. They are meant to prevent loading potentially malicious torrents │ │ │ │ +that cause excessive memory allocations.

│ │ │ │ 
│ │ │ │ -struct file_slice
│ │ │ │ +struct load_torrent_limits
│ │ │ │  {
│ │ │ │ -   file_index_t file_index;
│ │ │ │ -   std::int64_t offset;
│ │ │ │ -   std::int64_t size;
│ │ │ │ +   int max_buffer_size  = 10000000;
│ │ │ │ +   int max_pieces  = 0x200000;
│ │ │ │ +   int max_decode_depth  = 100;
│ │ │ │ +   int max_decode_tokens  = 3000000;
│ │ │ │  };
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
file_index
│ │ │ │ -
the index of the file
│ │ │ │ +[report issue]
│ │ │ │ +
max_buffer_size
│ │ │ │ +
the max size of a .torrent file to load into RAM
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
offset
│ │ │ │ -
the offset from the start of the file, in bytes
│ │ │ │ +[report issue]
│ │ │ │ +
max_pieces
│ │ │ │ +
the max number of pieces allowed in the torrent
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
size
│ │ │ │ -
the size of the window, in bytes
│ │ │ │ +[report issue]
│ │ │ │ +
max_decode_depth
│ │ │ │ +
the max recursion depth in the bdecoded structure
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

file_storage

│ │ │ │ -

Declared in "libtorrent/file_storage.hpp"

│ │ │ │ -

The file_storage class represents a file list and the piece │ │ │ │ -size. Everything necessary to interpret a regular bittorrent storage │ │ │ │ -file structure.

│ │ │ │ +[report issue]
│ │ │ │ +
max_decode_tokens
│ │ │ │ +
the max number of bdecode tokens
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

torrent_info

│ │ │ │ +

Declared in "libtorrent/torrent_info.hpp"

│ │ │ │ +

the torrent_info class holds the information found in a .torrent file.

│ │ │ │ 
│ │ │ │ -class file_storage
│ │ │ │ +class torrent_info
│ │ │ │  {
│ │ │ │ -   bool is_valid () const;
│ │ │ │ -   void reserve (int num_files);
│ │ │ │ -   void add_file_borrow (error_code& ec, string_view filename
│ │ │ │ -      , std::string const& path, std::int64_t file_size
│ │ │ │ -      , file_flags_t file_flags = {}, char const* filehash = nullptr
│ │ │ │ -      , std::int64_t mtime = 0, string_view symlink_path = string_view()
│ │ │ │ -      , char const* root_hash = nullptr);
│ │ │ │ -   void add_file (std::string const& path, std::int64_t file_size
│ │ │ │ -      , file_flags_t file_flags = {}
│ │ │ │ -      , std::time_t mtime = 0, string_view symlink_path = string_view()
│ │ │ │ -      , char const* root_hash = nullptr);
│ │ │ │ -   void add_file (error_code& ec, std::string const& path, std::int64_t file_size
│ │ │ │ -      , file_flags_t file_flags = {}
│ │ │ │ -      , std::time_t mtime = 0, string_view symlink_path = string_view()
│ │ │ │ -      , char const* root_hash = nullptr);
│ │ │ │ -   void add_file_borrow (string_view filename
│ │ │ │ -      , std::string const& path, std::int64_t file_size
│ │ │ │ -      , file_flags_t file_flags = {}, char const* filehash = nullptr
│ │ │ │ -      , std::int64_t mtime = 0, string_view symlink_path = string_view()
│ │ │ │ -      , char const* root_hash = nullptr);
│ │ │ │ +   torrent_info (char const* buffer, int size, error_code& ec);
│ │ │ │ +   explicit torrent_info (std::string const& filename);
│ │ │ │ +   torrent_info (bdecode_node const& torrent_file, error_code& ec);
│ │ │ │ +   explicit torrent_info (span<char const> buffer, from_span_t);
│ │ │ │ +   torrent_info (std::string const& filename, load_torrent_limits const& cfg);
│ │ │ │ +   torrent_info (span<char const> buffer, load_torrent_limits const& cfg, from_span_t);
│ │ │ │ +   torrent_info (span<char const> buffer, error_code& ec, from_span_t);
│ │ │ │ +   torrent_info (bdecode_node const& torrent_file, load_torrent_limits const& cfg);
│ │ │ │ +   torrent_info (char const* buffer, int size);
│ │ │ │ +   torrent_info (std::string const& filename, error_code& ec);
│ │ │ │ +   explicit torrent_info (bdecode_node const& torrent_file);
│ │ │ │ +   explicit torrent_info (info_hash_t const& info_hash);
│ │ │ │ +   torrent_info (torrent_info const& t);
│ │ │ │ +   ~torrent_info ();
│ │ │ │ +   file_storage const& files () const;
│ │ │ │ +   file_storage const& orig_files () const;
│ │ │ │     void rename_file (file_index_t index, std::string const& new_filename);
│ │ │ │ -   std::vector<file_slice> map_block (piece_index_t piece, std::int64_t offset
│ │ │ │ -      , std::int64_t size) const;
│ │ │ │ -   peer_request map_file (file_index_t file, std::int64_t offset, int size) const;
│ │ │ │ -   int num_files () const noexcept;
│ │ │ │ -   file_index_t end_file () const noexcept;
│ │ │ │ -   index_range<file_index_t> file_range () const noexcept;
│ │ │ │ +   void remap_files (file_storage const& f);
│ │ │ │ +   void add_tracker (std::string const& url, int tier = 0);
│ │ │ │ +   void clear_trackers ();
│ │ │ │ +   std::vector<announce_entry> const& trackers () const;
│ │ │ │ +   void add_tracker (std::string const& url, int tier
│ │ │ │ +      , announce_entry::tracker_source source);
│ │ │ │ +   std::vector<std::string> collections () const;
│ │ │ │ +   std::vector<sha1_hash> similar_torrents () const;
│ │ │ │ +   std::vector<web_seed_entry> const& web_seeds () const;
│ │ │ │ +   void set_web_seeds (std::vector<web_seed_entry> seeds);
│ │ │ │ +   void add_url_seed (std::string const& url
│ │ │ │ +      , std::string const& ext_auth = std::string()
│ │ │ │ +      , web_seed_entry::headers_t const& ext_headers = web_seed_entry::headers_t());
│ │ │ │ +   void add_http_seed (std::string const& url
│ │ │ │ +      , std::string const& extern_auth = std::string()
│ │ │ │ +      , web_seed_entry::headers_t const& extra_headers = web_seed_entry::headers_t());
│ │ │ │     std::int64_t total_size () const;
│ │ │ │ -   void set_num_pieces (int n);
│ │ │ │ +   int piece_length () const;
│ │ │ │     int num_pieces () const;
│ │ │ │ +   index_range<piece_index_t> piece_range () const;
│ │ │ │     piece_index_t end_piece () const;
│ │ │ │     piece_index_t last_piece () const;
│ │ │ │ -   index_range<piece_index_t> piece_range () const noexcept;
│ │ │ │ -   int piece_length () const;
│ │ │ │ -   void set_piece_length (int l);
│ │ │ │ -   int piece_size (piece_index_t index) const;
│ │ │ │ -   int piece_size2 (piece_index_t index) const;
│ │ │ │ -   int blocks_in_piece2 (piece_index_t index) const;
│ │ │ │ -   void set_name (std::string const& n);
│ │ │ │ -   std::string const& name () const;
│ │ │ │ -   void swap (file_storage& ti) noexcept;
│ │ │ │ -   void canonicalize ();
│ │ │ │ -   std::int64_t file_size (file_index_t index) const;
│ │ │ │ -   sha1_hash hash (file_index_t index) const;
│ │ │ │ -   std::string symlink (file_index_t index) const;
│ │ │ │ -   bool pad_file_at (file_index_t index) const;
│ │ │ │ -   std::time_t mtime (file_index_t index) const;
│ │ │ │ -   std::int64_t file_offset (file_index_t index) const;
│ │ │ │ -   sha256_hash root (file_index_t index) const;
│ │ │ │ -   string_view file_name (file_index_t index) const;
│ │ │ │ -   std::string file_path (file_index_t index, std::string const& save_path = "") const;
│ │ │ │ -   char const* root_ptr (file_index_t const index) const;
│ │ │ │ -   int file_num_blocks (file_index_t index) const;
│ │ │ │ -   int file_num_pieces (file_index_t index) const;
│ │ │ │ -   index_range<piece_index_t::diff_type> file_piece_range (file_index_t) const;
│ │ │ │ -   int file_first_piece_node (file_index_t index) const;
│ │ │ │ -   int file_first_block_node (file_index_t index) const;
│ │ │ │ -   std::uint32_t file_path_hash (file_index_t index, std::string const& save_path) const;
│ │ │ │ -   void all_path_hashes (std::unordered_set<std::uint32_t>& table) const;
│ │ │ │ -   file_flags_t file_flags (file_index_t index) const;
│ │ │ │ -   bool file_absolute_path (file_index_t index) const;
│ │ │ │ -   file_index_t file_index_at_offset (std::int64_t offset) const;
│ │ │ │ -   file_index_t file_index_at_piece (piece_index_t piece) const;
│ │ │ │ -   file_index_t file_index_for_root (sha256_hash const& root_hash) const;
│ │ │ │ -   piece_index_t piece_index_at_file (file_index_t f) const;
│ │ │ │ -   void sanitize_symlinks ();
│ │ │ │ +   info_hash_t const& info_hashes () const;
│ │ │ │ +   sha1_hash info_hash () const noexcept;
│ │ │ │ +   bool v1 () const;
│ │ │ │     bool v2 () const;
│ │ │ │ -
│ │ │ │ -   static constexpr file_flags_t flag_pad_file  = 0_bit;
│ │ │ │ -   static constexpr file_flags_t flag_hidden  = 1_bit;
│ │ │ │ -   static constexpr file_flags_t flag_executable  = 2_bit;
│ │ │ │ -   static constexpr file_flags_t flag_symlink  = 3_bit;
│ │ │ │ +   int num_files () const;
│ │ │ │ +   std::vector<file_slice> map_block (piece_index_t const piece
│ │ │ │ +      , std::int64_t offset, int size) const;
│ │ │ │ +   peer_request map_file (file_index_t const file, std::int64_t offset, int size) const;
│ │ │ │ +   string_view ssl_cert () const;
│ │ │ │ +   bool is_valid () const;
│ │ │ │ +   bool priv () const;
│ │ │ │ +   bool is_i2p () const;
│ │ │ │ +   int piece_size (piece_index_t index) const;
│ │ │ │ +   char const* hash_for_piece_ptr (piece_index_t const index) const;
│ │ │ │ +   sha1_hash hash_for_piece (piece_index_t index) const;
│ │ │ │ +   bool is_loaded () const;
│ │ │ │ +   const std::string& name () const;
│ │ │ │ +   std::time_t creation_date () const;
│ │ │ │ +   const std::string& creator () const;
│ │ │ │ +   const std::string& comment () const;
│ │ │ │ +   std::vector<std::pair<std::string, int>> const& nodes () const;
│ │ │ │ +   void add_node (std::pair<std::string, int> const& node);
│ │ │ │ +   bool parse_info_section (bdecode_node const& info, error_code& ec, int max_pieces);
│ │ │ │ +   bdecode_node info (char const* key) const;
│ │ │ │ +   span<char const> info_section () const;
│ │ │ │ +   span<char const> piece_layer (file_index_t) const;
│ │ │ │ +   void free_piece_layers ();
│ │ │ │  };
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -

is_valid()

│ │ │ │ +[report issue]
│ │ │ │ +

torrent_info()

│ │ │ │ 
│ │ │ │ -bool is_valid () const;
│ │ │ │ +torrent_info (char const* buffer, int size, error_code& ec);
│ │ │ │ +explicit torrent_info (std::string const& filename);
│ │ │ │ +torrent_info (bdecode_node const& torrent_file, error_code& ec);
│ │ │ │ +explicit torrent_info (span<char const> buffer, from_span_t);
│ │ │ │ +torrent_info (std::string const& filename, load_torrent_limits const& cfg);
│ │ │ │ +torrent_info (span<char const> buffer, load_torrent_limits const& cfg, from_span_t);
│ │ │ │ +torrent_info (span<char const> buffer, error_code& ec, from_span_t);
│ │ │ │ +torrent_info (bdecode_node const& torrent_file, load_torrent_limits const& cfg);
│ │ │ │ +torrent_info (char const* buffer, int size);
│ │ │ │ +torrent_info (std::string const& filename, error_code& ec);
│ │ │ │ +explicit torrent_info (bdecode_node const& torrent_file);
│ │ │ │ +explicit torrent_info (info_hash_t const& info_hash);
│ │ │ │ +torrent_info (torrent_info const& t);
│ │ │ │
│ │ │ │ -

returns true if the piece length has been initialized │ │ │ │ -on the file_storage. This is typically taken as a proxy │ │ │ │ -of whether the file_storage as a whole is initialized or │ │ │ │ -not.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

reserve()

│ │ │ │ +

The constructor that takes an info-hash will initialize the info-hash │ │ │ │ +to the given value, but leave all other fields empty. This is used │ │ │ │ +internally when downloading torrents without the metadata. The │ │ │ │ +metadata will be created by libtorrent as soon as it has been │ │ │ │ +downloaded from the swarm.

│ │ │ │ +

The constructor that takes a bdecode_node will create a torrent_info │ │ │ │ +object from the information found in the given torrent_file. The │ │ │ │ +bdecode_node represents a tree node in an bencoded file. To load an │ │ │ │ +ordinary .torrent file into a bdecode_node, use bdecode().

│ │ │ │ +

The version that takes a buffer pointer and a size will decode it as a │ │ │ │ +.torrent file and initialize the torrent_info object for you.

│ │ │ │ +

The version that takes a filename will simply load the torrent file │ │ │ │ +and decode it inside the constructor, for convenience. This might not │ │ │ │ +be the most suitable for applications that want to be able to report │ │ │ │ +detailed errors on what might go wrong.

│ │ │ │ +

There is an upper limit on the size of the torrent file that will be │ │ │ │ +loaded by the overload taking a filename. If it's important that even │ │ │ │ +very large torrent files are loaded, use one of the other overloads.

│ │ │ │ +

The overloads that takes an error_code const& never throws if an │ │ │ │ +error occur, they will simply set the error code to describe what went │ │ │ │ +wrong and not fully initialize the torrent_info object. The overloads │ │ │ │ +that do not take the extra error_code parameter will always throw if │ │ │ │ +an error occurs. These overloads are not available when building │ │ │ │ +without exception support.

│ │ │ │ +

The overload that takes a span also needs an extra parameter of │ │ │ │ +type from_span_t to disambiguate the std::string overload for │ │ │ │ +string literals. There is an object in the libtorrent namespace of this │ │ │ │ +type called from_span.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

~torrent_info()

│ │ │ │ 
│ │ │ │ -void reserve (int num_files);
│ │ │ │ +~torrent_info ();
│ │ │ │
│ │ │ │ -

allocates space for num_files in the internal file list. This can │ │ │ │ -be used to avoid reallocating the internal file list when the number │ │ │ │ -of files to be added is known up-front.

│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

add_file() add_file_borrow()

│ │ │ │ +

frees all storage associated with this torrent_info object

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

files() orig_files()

│ │ │ │ 
│ │ │ │ -void add_file_borrow (error_code& ec, string_view filename
│ │ │ │ -      , std::string const& path, std::int64_t file_size
│ │ │ │ -      , file_flags_t file_flags = {}, char const* filehash = nullptr
│ │ │ │ -      , std::int64_t mtime = 0, string_view symlink_path = string_view()
│ │ │ │ -      , char const* root_hash = nullptr);
│ │ │ │ -void add_file (std::string const& path, std::int64_t file_size
│ │ │ │ -      , file_flags_t file_flags = {}
│ │ │ │ -      , std::time_t mtime = 0, string_view symlink_path = string_view()
│ │ │ │ -      , char const* root_hash = nullptr);
│ │ │ │ -void add_file (error_code& ec, std::string const& path, std::int64_t file_size
│ │ │ │ -      , file_flags_t file_flags = {}
│ │ │ │ -      , std::time_t mtime = 0, string_view symlink_path = string_view()
│ │ │ │ -      , char const* root_hash = nullptr);
│ │ │ │ -void add_file_borrow (string_view filename
│ │ │ │ -      , std::string const& path, std::int64_t file_size
│ │ │ │ -      , file_flags_t file_flags = {}, char const* filehash = nullptr
│ │ │ │ -      , std::int64_t mtime = 0, string_view symlink_path = string_view()
│ │ │ │ -      , char const* root_hash = nullptr);
│ │ │ │ +file_storage const& files () const;
│ │ │ │ +file_storage const& orig_files () const;
│ │ │ │
│ │ │ │ -

Adds a file to the file storage. The add_file_borrow version │ │ │ │ -expects that filename is the file name (without a path) of │ │ │ │ -the file that's being added. │ │ │ │ -This memory is borrowed, i.e. it is the caller's │ │ │ │ -responsibility to make sure it stays valid throughout the lifetime │ │ │ │ -of this file_storage object or any copy of it. The same thing applies │ │ │ │ -to filehash, which is an optional pointer to a 20 byte binary │ │ │ │ -SHA-1 hash of the file.

│ │ │ │ -

if filename is empty, the filename from path is used and not │ │ │ │ -borrowed.

│ │ │ │ -

The path argument is the full path (in the torrent file) to │ │ │ │ -the file to add. Note that this is not supposed to be an absolute │ │ │ │ -path, but it is expected to include the name of the torrent as the │ │ │ │ -first path element.

│ │ │ │ -

file_size is the size of the file in bytes.

│ │ │ │ -

The file_flags argument sets attributes on the file. The file │ │ │ │ -attributes is an extension and may not work in all bittorrent clients.

│ │ │ │ -

For possible file attributes, see file_storage::flags_t.

│ │ │ │ -

The mtime argument is optional and can be set to 0. If non-zero, │ │ │ │ -it is the posix time of the last modification time of this file.

│ │ │ │ -

symlink_path is the path the file is a symlink to. To make this a │ │ │ │ -symlink you also need to set the file_storage::flag_symlink file flag.

│ │ │ │ -

root_hash is an optional pointer to a 32 byte SHA-256 hash, being │ │ │ │ -the merkle tree root hash for this file. This is only used for v2 │ │ │ │ -torrents. If the root hash is specified for one file, it has to │ │ │ │ -be specified for all, otherwise this function will fail. │ │ │ │ -Note that the buffer root_hash points to must out-live the │ │ │ │ -file_storage object, it will not be copied. This parameter is only │ │ │ │ -used when loading torrents, that already have their file hashes │ │ │ │ -computed. When creating torrents, the file hashes will be computed by │ │ │ │ -the piece hashes.

│ │ │ │ -

If more files than one are added, certain restrictions to their paths │ │ │ │ -apply. In a multi-file file storage (torrent), all files must share │ │ │ │ -the same root directory.

│ │ │ │ -

That is, the first path element of all files must be the same. │ │ │ │ -This shared path element is also set to the name of the torrent. It │ │ │ │ -can be changed by calling set_name.

│ │ │ │ -

The overloads that take an error_code reference will report failures │ │ │ │ -via that variable, otherwise system_error is thrown.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ +

The file_storage object contains the information on how to map the │ │ │ │ +pieces to files. It is separated from the torrent_info object because │ │ │ │ +when creating torrents a storage object needs to be created without │ │ │ │ +having a torrent file. When renaming files in a storage, the storage │ │ │ │ +needs to make its own copy of the file_storage in order to make its │ │ │ │ +mapping differ from the one in the torrent file.

│ │ │ │ +

orig_files() returns the original (unmodified) file storage for │ │ │ │ +this torrent. This is used by the web server connection, which needs │ │ │ │ +to request files with the original names. Filename may be changed using │ │ │ │ +torrent_info::rename_file().

│ │ │ │ +

For more information on the file_storage object, see the separate │ │ │ │ +document on how to create torrents.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │

rename_file()

│ │ │ │ 
│ │ │ │  void rename_file (file_index_t index, std::string const& new_filename);
│ │ │ │
│ │ │ │ -

renames the file at index to new_filename. Keep in mind │ │ │ │ -that filenames are expected to be UTF-8 encoded.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

map_block()

│ │ │ │ -
│ │ │ │ -std::vector<file_slice> map_block (piece_index_t piece, std::int64_t offset
│ │ │ │ -      , std::int64_t size) const;
│ │ │ │ -
│ │ │ │ -

returns a list of file_slice objects representing the portions of │ │ │ │ -files the specified piece index, byte offset and size range overlaps. │ │ │ │ -this is the inverse mapping of map_file().

│ │ │ │ -

Preconditions of this function is that the input range is within the │ │ │ │ -torrents address space. piece may not be negative and

│ │ │ │ -
│ │ │ │ -piece * piece_size + offset + size
│ │ │ │ -

may not exceed the total size of the torrent.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

map_file()

│ │ │ │ +

Renames the file with the specified index to the new name. The new │ │ │ │ +filename is reflected by the file_storage returned by files() │ │ │ │ +but not by the one returned by orig_files().

│ │ │ │ +

If you want to rename the base name of the torrent (for a multi file │ │ │ │ +torrent), you can copy the file_storage (see files() and │ │ │ │ +orig_files() ), change the name, and then use remap_files().

│ │ │ │ +

The new_filename can both be a relative path, in which case the │ │ │ │ +file name is relative to the save_path of the torrent. If the │ │ │ │ +new_filename is an absolute path (i.e. is_complete(new_filename) │ │ │ │ +== true), then the file is detached from the save_path of the │ │ │ │ +torrent. In this case the file is not moved when move_storage() is │ │ │ │ +invoked.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

remap_files()

│ │ │ │ 
│ │ │ │ -peer_request map_file (file_index_t file, std::int64_t offset, int size) const;
│ │ │ │ +void remap_files (file_storage const& f);
│ │ │ │
│ │ │ │ -

returns a peer_request representing the piece index, byte offset │ │ │ │ -and size the specified file range overlaps. This is the inverse │ │ │ │ -mapping over map_block(). Note that the peer_request return type │ │ │ │ -is meant to hold bittorrent block requests, which may not be larger │ │ │ │ -than 16 kiB. Mapping a range larger than that may return an overflown │ │ │ │ -integer.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

num_files()

│ │ │ │ +
│ │ │ │ +

Warning

│ │ │ │ +

Using remap_files() is discouraged as it's incompatible with v2 │ │ │ │ +torrents. This is because the piece boundaries and piece hashes in │ │ │ │ +v2 torrents are intimately tied to the file boundaries. Instead, │ │ │ │ +just rename individual files, or implement a custom disk_interface │ │ │ │ +to customize how to store files.

│ │ │ │ +
│ │ │ │ +

Remaps the file storage to a new file layout. This can be used to, for │ │ │ │ +instance, download all data in a torrent to a single file, or to a │ │ │ │ +number of fixed size sector aligned files, regardless of the number │ │ │ │ +and sizes of the files in the torrent.

│ │ │ │ +

The new specified file_storage must have the exact same size as │ │ │ │ +the current one.

│ │ │ │ + │ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

clear_trackers() trackers() add_tracker()

│ │ │ │ 
│ │ │ │ -int num_files () const noexcept;
│ │ │ │ +void add_tracker (std::string const& url, int tier = 0);
│ │ │ │ +void clear_trackers ();
│ │ │ │ +std::vector<announce_entry> const& trackers () const;
│ │ │ │ +void add_tracker (std::string const& url, int tier
│ │ │ │ +      , announce_entry::tracker_source source);
│ │ │ │
│ │ │ │ -

returns the number of files in the file_storage

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

end_file()

│ │ │ │ +

add_tracker() adds a tracker to the announce-list. The tier │ │ │ │ +determines the order in which the trackers are to be tried. │ │ │ │ +The trackers() function will return a sorted vector of │ │ │ │ +announce_entry. Each announce entry contains a string, which is │ │ │ │ +the tracker url, and a tier index. The tier index is the high-level │ │ │ │ +priority. No matter which trackers that works or not, the ones with │ │ │ │ +lower tier will always be tried before the one with higher tier │ │ │ │ +number. For more information, see announce_entry.

│ │ │ │ +

trackers() returns all entries from announce-list.

│ │ │ │ +

clear_trackers() removes all trackers from announce-list.

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

collections() similar_torrents()

│ │ │ │ 
│ │ │ │ -file_index_t end_file () const noexcept;
│ │ │ │ +std::vector<std::string> collections () const;
│ │ │ │ +std::vector<sha1_hash> similar_torrents () const;
│ │ │ │
│ │ │ │ -

returns the index of the one-past-end file in the file storage

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

file_range()

│ │ │ │ +

These two functions are related to BEP 38 (mutable torrents). The │ │ │ │ +vectors returned from these correspond to the "similar" and │ │ │ │ +"collections" keys in the .torrent file. Both info-hashes and │ │ │ │ +collections from within the info-dict and from outside of it are │ │ │ │ +included.

│ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

set_web_seeds() web_seeds() add_http_seed() add_url_seed()

│ │ │ │ 
│ │ │ │ -index_range<file_index_t> file_range () const noexcept;
│ │ │ │ +std::vector<web_seed_entry> const& web_seeds () const;
│ │ │ │ +void set_web_seeds (std::vector<web_seed_entry> seeds);
│ │ │ │ +void add_url_seed (std::string const& url
│ │ │ │ +      , std::string const& ext_auth = std::string()
│ │ │ │ +      , web_seed_entry::headers_t const& ext_headers = web_seed_entry::headers_t());
│ │ │ │ +void add_http_seed (std::string const& url
│ │ │ │ +      , std::string const& extern_auth = std::string()
│ │ │ │ +      , web_seed_entry::headers_t const& extra_headers = web_seed_entry::headers_t());
│ │ │ │
│ │ │ │ -

returns an implementation-defined type that can be used as the │ │ │ │ -container in a range-for loop. Where the values are the indices of all │ │ │ │ -files in the file_storage.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ +

web_seeds() returns all url seeds and http seeds in the torrent. │ │ │ │ +Each entry is a web_seed_entry and may refer to either a url seed │ │ │ │ +or http seed.

│ │ │ │ +

add_url_seed() and add_http_seed() adds one url to the list of │ │ │ │ +url/http seeds.

│ │ │ │ +

set_web_seeds() replaces all web seeds with the ones specified in │ │ │ │ +the seeds vector.

│ │ │ │ +

The extern_auth argument can be used for other authorization │ │ │ │ +schemes than basic HTTP authorization. If set, it will override any │ │ │ │ +username and password found in the URL itself. The string will be sent │ │ │ │ +as the HTTP authorization header's value (without specifying "Basic").

│ │ │ │ +

The extra_headers argument defaults to an empty list, but can be │ │ │ │ +used to insert custom HTTP headers in the requests to a specific web │ │ │ │ +seed.

│ │ │ │ +

See http seeding for more information.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │

total_size()

│ │ │ │ 
│ │ │ │  std::int64_t total_size () const;
│ │ │ │
│ │ │ │ -

returns the total number of bytes all the files in this torrent spans

│ │ │ │ +

total_size() returns the total number of bytes the torrent-file │ │ │ │ +represents. Note that this is the number of pieces times the piece │ │ │ │ +size (modulo the last piece possibly being smaller). With pad files, │ │ │ │ +the total size will be larger than the sum of all (regular) file │ │ │ │ +sizes.

│ │ │ │ │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

num_pieces() set_num_pieces()

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

num_pieces() piece_length()

│ │ │ │ 
│ │ │ │ -void set_num_pieces (int n);
│ │ │ │ +int piece_length () const;
│ │ │ │  int num_pieces () const;
│ │ │ │
│ │ │ │ -

set and get the number of pieces in the torrent

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

end_piece()

│ │ │ │ +

piece_length() and num_pieces() returns the number of byte │ │ │ │ +for each piece and the total number of pieces, respectively. The │ │ │ │ +difference between piece_size() and piece_length() is that │ │ │ │ +piece_size() takes the piece index as argument and gives you the │ │ │ │ +exact size of that piece. It will always be the same as │ │ │ │ +piece_length() except in the case of the last piece, which may be │ │ │ │ +smaller.

│ │ │ │ + │ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

last_piece() end_piece() piece_range()

│ │ │ │ 
│ │ │ │ +index_range<piece_index_t> piece_range () const;
│ │ │ │  piece_index_t end_piece () const;
│ │ │ │ -
│ │ │ │ -

returns the index of the one-past-end piece in the file storage

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

last_piece()

│ │ │ │ -
│ │ │ │  piece_index_t last_piece () const;
│ │ │ │
│ │ │ │ -

returns the index of the last piece in the torrent. The last piece is │ │ │ │ -special in that it may be smaller than the other pieces (and the other │ │ │ │ -pieces are all the same size).

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

piece_range()

│ │ │ │ -
│ │ │ │ -index_range<piece_index_t> piece_range () const noexcept;
│ │ │ │ -
│ │ │ │ -

returns an implementation-defined type that can be used as the │ │ │ │ -container in a range-for loop. Where the values are the indices of all │ │ │ │ -pieces in the file_storage.

│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

set_piece_length() piece_length()

│ │ │ │ -
│ │ │ │ -int piece_length () const;
│ │ │ │ -void set_piece_length (int l);
│ │ │ │ -
│ │ │ │ -

set and get the size of each piece in this torrent. It must be a power of two │ │ │ │ -and at least 16 kiB.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

piece_size()

│ │ │ │ +

last_piece() returns the index to the last piece in the torrent and │ │ │ │ +end_piece() returns the index to the one-past-end piece in the │ │ │ │ +torrent │ │ │ │ +piece_range() returns an implementation-defined type that can be │ │ │ │ +used as the container in a range-for loop. Where the values are the │ │ │ │ +indices of all pieces in the file_storage.

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

info_hashes() info_hash()

│ │ │ │ 
│ │ │ │ -int piece_size (piece_index_t index) const;
│ │ │ │ +info_hash_t const& info_hashes () const;
│ │ │ │ +sha1_hash info_hash () const noexcept;
│ │ │ │
│ │ │ │ -

returns the piece size of index. This will be the same as piece_length(), except │ │ │ │ -for the last piece, which may be shorter.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

piece_size2()

│ │ │ │ +

returns the info-hash of the torrent. For BitTorrent v2 support, use │ │ │ │ +info_hashes() to get an object that may hold both a v1 and v2 │ │ │ │ +info-hash

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

v2() v1()

│ │ │ │ 
│ │ │ │ -int piece_size2 (piece_index_t index) const;
│ │ │ │ +bool v1 () const;
│ │ │ │ +bool v2 () const;
│ │ │ │
│ │ │ │ -

Returns the size of the given piece. If the piece spans multiple files, │ │ │ │ -only the first file is considered part of the piece. This is used for │ │ │ │ -v2 torrents, where all files are piece aligned and padded. i.e. The pad │ │ │ │ -files are not considered part of the piece for this purpose.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

blocks_in_piece2()

│ │ │ │ +

returns whether this torrent has v1 and/or v2 metadata, respectively. │ │ │ │ +Hybrid torrents have both. These are shortcuts for │ │ │ │ +info_hashes().has_v1() and info_hashes().has_v2() calls.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

num_files()

│ │ │ │ 
│ │ │ │ -int blocks_in_piece2 (piece_index_t index) const;
│ │ │ │ +int num_files () const;
│ │ │ │
│ │ │ │ -

returns the number of blocks in the specified piece, for v2 torrents.

│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

set_name() name()

│ │ │ │ +

If you need index-access to files you can use the num_files() along │ │ │ │ +with the file_path(), file_size()-family of functions to access │ │ │ │ +files using indices.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

map_block()

│ │ │ │ 
│ │ │ │ -void set_name (std::string const& n);
│ │ │ │ -std::string const& name () const;
│ │ │ │ +std::vector<file_slice> map_block (piece_index_t const piece
│ │ │ │ +      , std::int64_t offset, int size) const;
│ │ │ │
│ │ │ │ -

set and get the name of this torrent. For multi-file torrents, this is also │ │ │ │ -the name of the root directory all the files are stored in.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

swap()

│ │ │ │ +

This function will map a piece index, a byte offset within that piece │ │ │ │ +and a size (in bytes) into the corresponding files with offsets where │ │ │ │ +that data for that piece is supposed to be stored. See file_slice.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

map_file()

│ │ │ │ 
│ │ │ │ -void swap (file_storage& ti) noexcept;
│ │ │ │ +peer_request map_file (file_index_t const file, std::int64_t offset, int size) const;
│ │ │ │
│ │ │ │ -

swap all content of this with ti.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

canonicalize()

│ │ │ │ +

This function will map a range in a specific file into a range in the │ │ │ │ +torrent. The file_offset parameter is the offset in the file, │ │ │ │ +given in bytes, where 0 is the start of the file. See peer_request.

│ │ │ │ +

The input range is assumed to be valid within the torrent. │ │ │ │ +file_offset + size is not allowed to be greater than the file │ │ │ │ +size. file_index must refer to a valid file, i.e. it cannot be >= │ │ │ │ +num_files().

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

ssl_cert()

│ │ │ │ 
│ │ │ │ -void canonicalize ();
│ │ │ │ +string_view ssl_cert () const;
│ │ │ │
│ │ │ │ -

arrange files and padding to match the canonical form required │ │ │ │ -by BEP 52

│ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ - │ │ │ │ +
│ │ │ │ +

is_valid()

│ │ │ │ 
│ │ │ │ -std::int64_t file_size (file_index_t index) const;
│ │ │ │ -sha1_hash hash (file_index_t index) const;
│ │ │ │ -std::string symlink (file_index_t index) const;
│ │ │ │ -bool pad_file_at (file_index_t index) const;
│ │ │ │ -std::time_t mtime (file_index_t index) const;
│ │ │ │ -std::int64_t file_offset (file_index_t index) const;
│ │ │ │ -sha256_hash root (file_index_t index) const;
│ │ │ │ -string_view file_name (file_index_t index) const;
│ │ │ │ -std::string file_path (file_index_t index, std::string const& save_path = "") const;
│ │ │ │ -char const* root_ptr (file_index_t const index) const;
│ │ │ │ +bool is_valid () const;
│ │ │ │
│ │ │ │ -

These functions are used to query attributes of files at │ │ │ │ -a given index.

│ │ │ │ -

The hash() is a SHA-1 hash of the file, or 0 if none was │ │ │ │ -provided in the torrent file. This can potentially be used to │ │ │ │ -join a bittorrent network with other file sharing networks.

│ │ │ │ -

root() returns the SHA-256 merkle tree root of the specified file, │ │ │ │ -in case this is a v2 torrent. Otherwise returns zeros. │ │ │ │ -root_ptr() returns a pointer to the SHA-256 merkle tree root hash │ │ │ │ -for the specified file. The pointer points into storage referred to │ │ │ │ -when the file was added, it is not owned by this object. Torrents │ │ │ │ -that are not v2 torrents return nullptr.

│ │ │ │ -

The mtime() is the modification time is the posix │ │ │ │ -time when a file was last modified when the torrent │ │ │ │ -was created, or 0 if it was not included in the torrent file.

│ │ │ │ -

file_path() returns the full path to a file.

│ │ │ │ -

file_size() returns the size of a file.

│ │ │ │ -

pad_file_at() returns true if the file at the given │ │ │ │ -index is a pad-file.

│ │ │ │ -

file_name() returns just the name of the file, whereas │ │ │ │ -file_path() returns the path (inside the torrent file) with │ │ │ │ -the filename appended.

│ │ │ │ -

file_offset() returns the byte offset within the torrent file │ │ │ │ -where this file starts. It can be used to map the file to a piece │ │ │ │ -index (given the piece size).

│ │ │ │ - │ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

file_num_pieces() file_num_blocks() file_piece_range()

│ │ │ │ +

returns true if this torrent_info object has a torrent loaded. │ │ │ │ +This is primarily used to determine if a magnet link has had its │ │ │ │ +metadata resolved yet or not.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

priv()

│ │ │ │ 
│ │ │ │ -int file_num_blocks (file_index_t index) const;
│ │ │ │ -int file_num_pieces (file_index_t index) const;
│ │ │ │ -index_range<piece_index_t::diff_type> file_piece_range (file_index_t) const;
│ │ │ │ +bool priv () const;
│ │ │ │
│ │ │ │ -

Returns the number of pieces or blocks the file at index spans, │ │ │ │ -under the assumption that the file is aligned to the start of a piece. │ │ │ │ -This is only meaningful for v2 torrents, where files are guaranteed │ │ │ │ -such alignment. │ │ │ │ -These numbers are used to size and navigate the merkle hash tree for │ │ │ │ -each file.

│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

file_first_block_node() file_first_piece_node()

│ │ │ │ +

returns true if this torrent is private. i.e., the client should not │ │ │ │ +advertise itself on the trackerless network (the Kademlia DHT) for this torrent.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

is_i2p()

│ │ │ │ 
│ │ │ │ -int file_first_piece_node (file_index_t index) const;
│ │ │ │ -int file_first_block_node (file_index_t index) const;
│ │ │ │ +bool is_i2p () const;
│ │ │ │
│ │ │ │ -

index of first piece node in the merkle tree

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

file_path_hash()

│ │ │ │ +

returns true if this is an i2p torrent. This is determined by whether │ │ │ │ +or not it has a tracker whose URL domain name ends with ".i2p". i2p │ │ │ │ +torrents disable the DHT and local peer discovery as well as talking │ │ │ │ +to peers over anything other than the i2p network.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

piece_size()

│ │ │ │ 
│ │ │ │ -std::uint32_t file_path_hash (file_index_t index, std::string const& save_path) const;
│ │ │ │ +int piece_size (piece_index_t index) const;
│ │ │ │
│ │ │ │ -

returns the crc32 hash of file_path(index)

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

all_path_hashes()

│ │ │ │ +

returns the piece size of file with index. This will be the same as piece_length(), │ │ │ │ +except for the last piece, which may be shorter.

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

hash_for_piece_ptr() hash_for_piece()

│ │ │ │ 
│ │ │ │ -void all_path_hashes (std::unordered_set<std::uint32_t>& table) const;
│ │ │ │ +char const* hash_for_piece_ptr (piece_index_t const index) const;
│ │ │ │ +sha1_hash hash_for_piece (piece_index_t index) const;
│ │ │ │
│ │ │ │ -

this will add the CRC32 hash of all directory entries to the table. No │ │ │ │ -filename will be included, just directories. Every depth of directories │ │ │ │ -are added separately to allow test for collisions with files at all │ │ │ │ -levels. i.e. if one path in the torrent is foo/bar/baz, the CRC32 │ │ │ │ -hashes for foo, foo/bar and foo/bar/baz will be added to │ │ │ │ -the set.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

file_flags()

│ │ │ │ +

hash_for_piece() takes a piece-index and returns the 20-bytes │ │ │ │ +sha1-hash for that piece and info_hash() returns the 20-bytes │ │ │ │ +sha1-hash for the info-section of the torrent file. │ │ │ │ +hash_for_piece_ptr() returns a pointer to the 20 byte sha1 digest │ │ │ │ +for the piece. Note that the string is not 0-terminated.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

name()

│ │ │ │ 
│ │ │ │ -file_flags_t file_flags (file_index_t index) const;
│ │ │ │ +const std::string& name () const;
│ │ │ │
│ │ │ │ -

returns a bitmask of flags from file_flags_t that apply │ │ │ │ -to file at index.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

file_absolute_path()

│ │ │ │ +

name() returns the name of the torrent. │ │ │ │ +name contains UTF-8 encoded string.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

creation_date()

│ │ │ │ 
│ │ │ │ -bool file_absolute_path (file_index_t index) const;
│ │ │ │ +std::time_t creation_date () const;
│ │ │ │
│ │ │ │ -

returns true if the file at the specified index has been renamed to │ │ │ │ -have an absolute path, i.e. is not anchored in the save path of the │ │ │ │ -torrent.

│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

file_index_at_offset() file_index_at_piece()

│ │ │ │ +

creation_date() returns the creation date of the torrent as time_t │ │ │ │ +(posix time). If there's no time stamp in the torrent file, 0 is │ │ │ │ +returned. │ │ │ │ +.. posix time: http://www.opengroup.org/onlinepubs/009695399/functions/time.html

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

creator()

│ │ │ │ 
│ │ │ │ -file_index_t file_index_at_offset (std::int64_t offset) const;
│ │ │ │ -file_index_t file_index_at_piece (piece_index_t piece) const;
│ │ │ │ +const std::string& creator () const;
│ │ │ │
│ │ │ │ -

returns the index of the file at the given offset in the torrent

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

file_index_for_root()

│ │ │ │ +

creator() returns the creator string in the torrent. If there is │ │ │ │ +no creator string it will return an empty string.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

comment()

│ │ │ │ 
│ │ │ │ -file_index_t file_index_for_root (sha256_hash const& root_hash) const;
│ │ │ │ +const std::string& comment () const;
│ │ │ │
│ │ │ │ -

finds the file with the given root hash and returns its index │ │ │ │ -if there is no file with the root hash, file_index_t{-1} is returned

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

piece_index_at_file()

│ │ │ │ +

comment() returns the comment associated with the torrent. If │ │ │ │ +there's no comment, it will return an empty string. │ │ │ │ +comment contains UTF-8 encoded string.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

nodes()

│ │ │ │ 
│ │ │ │ -piece_index_t piece_index_at_file (file_index_t f) const;
│ │ │ │ +std::vector<std::pair<std::string, int>> const& nodes () const;
│ │ │ │
│ │ │ │ -

returns the piece index the given file starts at

│ │ │ │ -[report issue]
│ │ │ │ - │ │ │ │ +
│ │ │ │ +

add_node()

│ │ │ │ 
│ │ │ │ -void sanitize_symlinks ();
│ │ │ │ +void add_node (std::pair<std::string, int> const& node);
│ │ │ │
│ │ │ │ -

validate any symlinks, to ensure they all point to │ │ │ │ -other files or directories inside this storage. Any invalid symlinks │ │ │ │ -are updated to point to themselves.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

v2()

│ │ │ │ +

This is used when creating torrent. Use this to add a known DHT node. │ │ │ │ +It may be used, by the client, to bootstrap into the DHT network.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

parse_info_section()

│ │ │ │ 
│ │ │ │ -bool v2 () const;
│ │ │ │ +bool parse_info_section (bdecode_node const& info, error_code& ec, int max_pieces);
│ │ │ │
│ │ │ │ -

returns true if this torrent contains v2 metadata.

│ │ │ │ -[report issue]
│ │ │ │ -
flag_pad_file
│ │ │ │ -
the file is a pad file. It's required to contain zeros │ │ │ │ -at it will not be saved to disk. Its purpose is to make │ │ │ │ -the following file start on a piece boundary.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
flag_hidden
│ │ │ │ -
this file has the hidden attribute set. This is primarily │ │ │ │ -a windows attribute
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
flag_executable
│ │ │ │ -
this file has the executable attribute set.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
flag_symlink
│ │ │ │ -
this file is a symbolic link. It should have a link │ │ │ │ -target string associated with it.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -

posix_disk_io_constructor()

│ │ │ │ -

Declared in "libtorrent/posix_disk_io.hpp"

│ │ │ │ +

populates the torrent_info by providing just the info-dict buffer. │ │ │ │ +This is used when loading a torrent from a magnet link for instance, │ │ │ │ +where we only have the info-dict. The bdecode_node e points to a │ │ │ │ +parsed info-dictionary. ec returns an error code if something │ │ │ │ +fails (typically if the info dictionary is malformed). │ │ │ │ +The max_pieces parameter allows limiting the amount of memory │ │ │ │ +dedicated to loading the torrent, and fails for torrents that exceed │ │ │ │ +the limit. To load large torrents, this limit may also need to be │ │ │ │ +raised in settings_pack::max_piece_count and in calls to │ │ │ │ +read_resume_data().

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

info()

│ │ │ │ 
│ │ │ │ -std::unique_ptr<disk_interface> posix_disk_io_constructor (
│ │ │ │ -   io_context& ios, settings_interface const&, counters& cnt);
│ │ │ │ +bdecode_node info (char const* key) const;
│ │ │ │
│ │ │ │ -

this is a simple posix disk I/O back-end, used for systems that don't │ │ │ │ -have a 64 bit virtual address space or don't support memory mapped files. │ │ │ │ -It's implemented using portable C file functions and is single-threaded.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

mmap_disk_io_constructor()

│ │ │ │ -

Declared in "libtorrent/mmap_disk_io.hpp"

│ │ │ │ +

This function looks up keys from the info-dictionary of the loaded │ │ │ │ +torrent file. It can be used to access extension values put in the │ │ │ │ +.torrent file. If the specified key cannot be found, it returns nullptr.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

info_section()

│ │ │ │ 
│ │ │ │ -std::unique_ptr<disk_interface> mmap_disk_io_constructor (
│ │ │ │ -   io_context& ios, settings_interface const&, counters& cnt);
│ │ │ │ +span<char const> info_section () const;
│ │ │ │
│ │ │ │ -

constructs a memory mapped file disk I/O object.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

disabled_disk_io_constructor()

│ │ │ │ -

Declared in "libtorrent/disabled_disk_io.hpp"

│ │ │ │ +

returns a the raw info section of the torrent file. │ │ │ │ +The underlying buffer is still owned by the torrent_info object

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

piece_layer()

│ │ │ │ 
│ │ │ │ -std::unique_ptr<disk_interface> disabled_disk_io_constructor (
│ │ │ │ -   io_context& ios, settings_interface const&, counters& cnt);
│ │ │ │ +span<char const> piece_layer (file_index_t) const;
│ │ │ │
│ │ │ │ -

creates a disk io object that discards all data written to it, and only │ │ │ │ -returns zero-buffers when read from. May be useful for testing and │ │ │ │ -benchmarking.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

default_disk_io_constructor()

│ │ │ │ -

Declared in "libtorrent/session.hpp"

│ │ │ │ +

return the bytes of the piece layer hashes for the specified file. If │ │ │ │ +the file doesn't have a piece layer, an empty span is returned. │ │ │ │ +The span size is divisible by 32, the size of a SHA-256 hash. │ │ │ │ +If the size of the file is smaller than or equal to the piece size, │ │ │ │ +the files "root hash" is the hash of the file and is not saved │ │ │ │ +separately in the "piece layers" field, but this function still │ │ │ │ +returns the root hash of the file in that case.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

free_piece_layers()

│ │ │ │ 
│ │ │ │ -std::unique_ptr<disk_interface> default_disk_io_constructor (
│ │ │ │ -   io_context& ios, settings_interface const&, counters& cnt);
│ │ │ │ +void free_piece_layers ();
│ │ │ │
│ │ │ │ -

the constructor function for the default storage. On systems that support │ │ │ │ -memory mapped files (and a 64 bit address space) the memory mapped storage │ │ │ │ -will be constructed, otherwise the portable posix storage.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

enum storage_mode_t

│ │ │ │ -

Declared in "libtorrent/storage_defs.hpp"

│ │ │ │ - │ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ -
namevaluedescription
storage_mode_allocate0All pieces will be written to their final position, all files will be │ │ │ │ -allocated in full when the torrent is first started. This mode minimizes │ │ │ │ -fragmentation but could be a costly operation.
storage_mode_sparse1All pieces will be written to the place where they belong and sparse files │ │ │ │ -will be used. This is the recommended, and default mode.
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

enum status_t

│ │ │ │ -

Declared in "libtorrent/storage_defs.hpp"

│ │ │ │ - │ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ -
namevaluedescription
no_error0 
fatal_disk_error1 
need_full_check2 
file_exist3 
oversized_file16this is not an enum value, but a flag that can be set in the return │ │ │ │ -from async_check_files, in case an existing file was found larger than │ │ │ │ -specified in the torrent. i.e. it has garbage at the end │ │ │ │ -the status_t field is used for this to preserve ABI.
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

enum move_flags_t

│ │ │ │ -

Declared in "libtorrent/storage_defs.hpp"

│ │ │ │ - │ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ -
namevaluedescription
always_replace_files0replace any files in the destination when copying │ │ │ │ -or moving the storage
fail_if_exist1if any files that we want to copy exist in the destination │ │ │ │ -exist, fail the whole operation and don't perform │ │ │ │ -any copy or move. There is an inherent race condition │ │ │ │ -in this mode. The files are checked for existence before │ │ │ │ -the operation starts. In between the check and performing │ │ │ │ -the copy, the destination files may be created, in which │ │ │ │ -case they are replaced.
dont_replace2if any file exist in the target, take those files instead │ │ │ │ -of the ones we may have in the source.
│ │ │ │ +

clears the piece layers from the torrent_info. This is done by the │ │ │ │ +session when a torrent is added, to avoid storing it twice. The piece │ │ │ │ +layer (or other hashes part of the merkle tree) are stored in the │ │ │ │ +internal torrent object.

│ │ │ │

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:

│ │ │ │ [report issue]
│ │ │ │ +
│ │ │ │
│ │ │ │

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.

│ │ │ │ @@ -10706,17 +9088,17 @@ │ │ │ │ 
│ │ │ │  struct settings_pack final : settings_interface
│ │ │ │  {
│ │ │ │     friend  void apply_pack_impl (settings_pack const*
│ │ │ │        , aux::session_settings_single_thread&
│ │ │ │        , std::vector<void(aux::session_impl::*)()>*);
│ │ │ │     void set_str (int name, std::string val) override;
│ │ │ │ -   void set_int (int name, int val) override;
│ │ │ │     void set_int (int name, flags::bitfield_flag<Type, Tag> const val);
│ │ │ │     void set_bool (int name, bool val) override;
│ │ │ │ +   void set_int (int name, int val) override;
│ │ │ │     bool has_val (int name) const override;
│ │ │ │     void clear ();
│ │ │ │     void clear (int name);
│ │ │ │     int get_int (int name) const override;
│ │ │ │     bool get_bool (int name) const override;
│ │ │ │     std::string const& get_str (int name) const override;
│ │ │ │     void for_each (Fun&& f) const;
│ │ │ │ @@ -10793,55 +9175,55 @@
│ │ │ │        socks5_pw,
│ │ │ │        http,
│ │ │ │        http_pw,
│ │ │ │        i2p_proxy,
│ │ │ │     };
│ │ │ │  };
│ │ │ │
│ │ │ │ - │ │ │ │ │ │ │ │ -[report issue]
│ │ │ │ -

set_str() set_bool() set_int()

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +

set_bool() set_int() set_str()

│ │ │ │ 
│ │ │ │  void set_str (int name, std::string val) override;
│ │ │ │ -void set_int (int name, int val) override;
│ │ │ │  void set_int (int name, flags::bitfield_flag<Type, Tag> const val);
│ │ │ │  void set_bool (int name, bool val) override;
│ │ │ │ +void set_int (int name, int val) override;
│ │ │ │
│ │ │ │

set a configuration option in the settings_pack. name is one of │ │ │ │ the enum values from string_types, int_types or bool_types. They must │ │ │ │ match the respective type of the set_* function.

│ │ │ │ [report issue]
│ │ │ │
│ │ │ │

has_val()

│ │ │ │ 
│ │ │ │  bool has_val (int name) const override;
│ │ │ │
│ │ │ │

queries whether the specified configuration option has a value set in │ │ │ │ this pack. name can be any enumeration value from string_types, │ │ │ │ int_types or bool_types.

│ │ │ │ [report issue]
│ │ │ │ -
│ │ │ │ +
│ │ │ │

clear()

│ │ │ │ 
│ │ │ │  void clear ();
│ │ │ │
│ │ │ │

clear the settings pack from all settings

│ │ │ │ [report issue]
│ │ │ │ -
│ │ │ │ +
│ │ │ │

clear()

│ │ │ │ 
│ │ │ │  void clear (int name);
│ │ │ │
│ │ │ │

clear a specific setting from the pack

│ │ │ │ - │ │ │ │ │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

get_bool() get_int() get_str()

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

get_int() get_str() get_bool()

│ │ │ │ 
│ │ │ │  int get_int (int name) const override;
│ │ │ │  bool get_bool (int name) const override;
│ │ │ │  std::string const& get_str (int name) const override;
│ │ │ │
│ │ │ │

queries the current configuration option from the settings_pack. │ │ │ │ name is one of the enumeration values from string_types, int_types │ │ │ │ @@ -10850,1537 +9232,2356 @@ │ │ │ │ value is returned.

│ │ │ │ [report issue]
│ │ │ │
│ │ │ │

enum type_bases

│ │ │ │

Declared in "libtorrent/settings_pack.hpp"

│ │ │ │ │ │ │ │ │ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ +
namevaluedescription
string_type_base0 
int_type_base16384 
bool_type_base32768 
type_mask49152 
index_mask16383 
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

enum mmap_write_mode_t

│ │ │ │ +

Declared in "libtorrent/settings_pack.hpp"

│ │ │ │ + │ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ +
namevaluedescription
always_pwrite0disable writing to disk via mmap, always use normal write calls
always_mmap_write1prefer using memory mapped files for disk writes (at least for │ │ │ │ +large files where it might make sense)
auto_mmap_write2determine whether to use pwrite or memory mapped files for disk │ │ │ │ +writes depending on the kind of storage behind the save path
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

enum suggest_mode_t

│ │ │ │ +

Declared in "libtorrent/settings_pack.hpp"

│ │ │ │ + │ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ +
namevaluedescription
no_piece_suggestions0 
suggest_read_cache1 
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

enum choking_algorithm_t

│ │ │ │ +

Declared in "libtorrent/settings_pack.hpp"

│ │ │ │ + │ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ +
namevaluedescription
fixed_slots_choker0This is the traditional choker with a fixed number of unchoke │ │ │ │ +slots (as specified by settings_pack::unchoke_slots_limit).
rate_based_choker2

This opens up unchoke slots based on the upload rate achieved to │ │ │ │ +peers. The more slots that are opened, the marginal upload rate │ │ │ │ +required to open up another slot increases. Configure the initial │ │ │ │ +threshold with settings_pack::rate_choker_initial_threshold.

│ │ │ │ +

For more information, see rate based choking.

│ │ │ │ +
deprecated_bittyrant_choker3 
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

enum seed_choking_algorithm_t

│ │ │ │ +

Declared in "libtorrent/settings_pack.hpp"

│ │ │ │ + │ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ +
namevaluedescription
round_robin0which round-robins the peers that are unchoked │ │ │ │ +when seeding. This distributes the upload bandwidth uniformly and │ │ │ │ +fairly. It minimizes the ability for a peer to download everything │ │ │ │ +without redistributing it.
fastest_upload1unchokes the peers we can send to the fastest. This might be a │ │ │ │ +bit more reliable in utilizing all available capacity.
anti_leech2prioritizes peers who have just started or are │ │ │ │ +just about to finish the download. The intention is to force │ │ │ │ +peers in the middle of the download to trade with each other. │ │ │ │ +This does not just take into account the pieces a peer is │ │ │ │ +reporting having downloaded, but also the pieces we have sent │ │ │ │ +to it.
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

enum io_buffer_mode_t

│ │ │ │ +

Declared in "libtorrent/settings_pack.hpp"

│ │ │ │ + │ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ +
namevaluedescription
enable_os_cache0 
deprecated_disable_os_cache_for_aligned_files1 
disable_os_cache2 
write_through3 
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

enum bandwidth_mixed_algo_t

│ │ │ │ +

Declared in "libtorrent/settings_pack.hpp"

│ │ │ │ + │ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ +
namevaluedescription
prefer_tcp0disables the mixed mode bandwidth balancing
peer_proportional1does not throttle uTP, throttles TCP to the same proportion │ │ │ │ +of throughput as there are TCP connections
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

enum enc_policy

│ │ │ │ +

Declared in "libtorrent/settings_pack.hpp"

│ │ │ │ + │ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ +
namevaluedescription
pe_forced0Only encrypted connections are allowed. Incoming connections that │ │ │ │ +are not encrypted are closed and if the encrypted outgoing │ │ │ │ +connection fails, a non-encrypted retry will not be made.
pe_enabled1encrypted connections are enabled, but non-encrypted connections │ │ │ │ +are allowed. An incoming non-encrypted connection will be accepted, │ │ │ │ +and if an outgoing encrypted connection fails, a non- encrypted │ │ │ │ +connection will be tried.
pe_disabled2only non-encrypted connections are allowed.
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

enum enc_level

│ │ │ │ +

Declared in "libtorrent/settings_pack.hpp"

│ │ │ │ + │ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ +
namevaluedescription
pe_plaintext1use only plain text encryption
pe_rc42use only RC4 encryption
pe_both3allow both
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

enum proxy_type_t

│ │ │ │ +

Declared in "libtorrent/settings_pack.hpp"

│ │ │ │ + │ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ +
namevaluedescription
none0No proxy server is used and all other fields are ignored.
socks41The server is assumed to be a SOCKS4 server that requires a │ │ │ │ +username.
socks52The server is assumed to be a SOCKS5 server (RFC 1928) that does │ │ │ │ +not require any authentication. The username and password are │ │ │ │ +ignored.
socks5_pw3The server is assumed to be a SOCKS5 server that supports plain │ │ │ │ +text username and password authentication (RFC 1929). The │ │ │ │ +username and password specified may be sent to the proxy if it │ │ │ │ +requires.
http4The server is assumed to be an HTTP proxy. If the transport used │ │ │ │ +for the connection is non-HTTP, the server is assumed to support │ │ │ │ +the CONNECT method. i.e. for web seeds and HTTP trackers, a plain │ │ │ │ +proxy will suffice. The proxy is assumed to not require │ │ │ │ +authorization. The username and password will not be used.
http_pw5The server is assumed to be an HTTP proxy that requires user │ │ │ │ +authorization. The username and password will be sent to the proxy.
i2p_proxy6route through a i2p SAM proxy
│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +

min_memory_usage() high_performance_seed()

│ │ │ │ +

Declared in "libtorrent/session.hpp"

│ │ │ │ +
│ │ │ │ +settings_pack min_memory_usage ();
│ │ │ │ +settings_pack high_performance_seed ();
│ │ │ │ +
│ │ │ │ +

The default values of the session settings are set for a regular │ │ │ │ +bittorrent client running on a desktop system. There are functions that │ │ │ │ +can set the session settings to pre set settings for other environments. │ │ │ │ +These can be used for the basis, and should be tweaked to fit your needs │ │ │ │ +better.

│ │ │ │ +

min_memory_usage returns settings that will use the minimal amount of │ │ │ │ +RAM, at the potential expense of upload and download performance. It │ │ │ │ +adjusts the socket buffer sizes, disables the disk cache, lowers the send │ │ │ │ +buffer watermarks so that each connection only has at most one block in │ │ │ │ +use at any one time. It lowers the outstanding blocks send to the disk │ │ │ │ +I/O thread so that connections only have one block waiting to be flushed │ │ │ │ +to disk at any given time. It lowers the max number of peers in the peer │ │ │ │ +list for torrents. It performs multiple smaller reads when it hashes │ │ │ │ +pieces, instead of reading it all into memory before hashing.

│ │ │ │ +

This configuration is intended to be the starting point for embedded │ │ │ │ +devices. It will significantly reduce memory usage.

│ │ │ │ +

high_performance_seed returns settings optimized for a seed box, │ │ │ │ +serving many peers and that doesn't do any downloading. It has a 128 MB │ │ │ │ +disk cache and has a limit of 400 files in its file pool. It support fast │ │ │ │ +upload rates by allowing large send buffers.

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

name_for_setting() setting_by_name()

│ │ │ │ +

Declared in "libtorrent/settings_pack.hpp"

│ │ │ │ +
│ │ │ │ +char const* name_for_setting (int s);
│ │ │ │ +int setting_by_name (string_view name);
│ │ │ │ +
│ │ │ │ +

converts a setting integer (from the enums string_types, int_types or │ │ │ │ +bool_types) to a string, and vice versa.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

default_settings()

│ │ │ │ +

Declared in "libtorrent/settings_pack.hpp"

│ │ │ │ +
│ │ │ │ +settings_pack default_settings ();
│ │ │ │ +
│ │ │ │ +

returns a settings_pack with every setting set to its default value

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

generate_fingerprint()

│ │ │ │ +

Declared in "libtorrent/fingerprint.hpp"

│ │ │ │ +
│ │ │ │ +std::string generate_fingerprint (std::string name
│ │ │ │ +   , int major, int minor = 0, int revision = 0, int tag = 0);
│ │ │ │ +
│ │ │ │ +

This is a utility function to produce a client ID fingerprint formatted to │ │ │ │ +the most common convention. The fingerprint can be set via the │ │ │ │ +peer_fingerprint setting, in settings_pack.

│ │ │ │ +

The name string should contain exactly two characters. These are the │ │ │ │ +characters unique to your client, used to identify it. Make sure not to │ │ │ │ +clash with anybody else. Here are some taken id's:

│ │ │ │ + │ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ +
id charsclient
LTlibtorrent (default)
UTuTorrent
UMuTorrent Mac
qBqBittorrent
BPBitTorrent Pro
BTBitTorrent
DEDeluge
AZAzureus
TLTribler
│ │ │ │ +

There's an informal directory of client id's here.

│ │ │ │ +

The major, minor, revision and tag parameters are used to │ │ │ │ +identify the version of your client.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

bitfield

│ │ │ │ +

Declared in "libtorrent/bitfield.hpp"

│ │ │ │ +

The bitfield type stores any number of bits as a bitfield │ │ │ │ +in a heap allocated array.

│ │ │ │ +
│ │ │ │ +struct bitfield
│ │ │ │ +{
│ │ │ │ +   explicit bitfield (int bits);
│ │ │ │ +   bitfield (char const* b, int bits);
│ │ │ │ +   bitfield (bitfield const& rhs);
│ │ │ │ +   bitfield (bitfield&& rhs) noexcept = default;
│ │ │ │ +   bitfield (int bits, bool val);
│ │ │ │ +   bitfield () noexcept = default;
│ │ │ │ +   void assign (char const* b, int const bits);
│ │ │ │ +   bool operator[] (int index) const noexcept;
│ │ │ │ +   bool get_bit (int index) const noexcept;
│ │ │ │ +   void clear_bit (int index) noexcept;
│ │ │ │ +   void set_bit (int index) noexcept;
│ │ │ │ +   bool all_set () const noexcept;
│ │ │ │ +   bool none_set () const noexcept;
│ │ │ │ +   int size () const noexcept;
│ │ │ │ +   int num_words () const noexcept;
│ │ │ │ +   bool empty () const noexcept;
│ │ │ │ +   char const* data () const noexcept;
│ │ │ │ +   char* data () noexcept;
│ │ │ │ +   void swap (bitfield& rhs) noexcept;
│ │ │ │ +   int count () const noexcept;
│ │ │ │ +   int find_first_set () const noexcept;
│ │ │ │ +   int find_last_clear () const noexcept;
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +

bitfield()

│ │ │ │ +
│ │ │ │ +explicit bitfield (int bits);
│ │ │ │ +bitfield (char const* b, int bits);
│ │ │ │ +bitfield (bitfield const& rhs);
│ │ │ │ +bitfield (bitfield&& rhs) noexcept = default;
│ │ │ │ +bitfield (int bits, bool val);
│ │ │ │ +bitfield () noexcept = default;
│ │ │ │ +
│ │ │ │ +

constructs a new bitfield. The default constructor creates an empty │ │ │ │ +bitfield. bits is the size of the bitfield (specified in bits). │ │ │ │ +val is the value to initialize the bits to. If not specified │ │ │ │ +all bits are initialized to 0.

│ │ │ │ +

The constructor taking a pointer b and bits copies a bitfield │ │ │ │ +from the specified buffer, and bits number of bits (rounded up to │ │ │ │ +the nearest byte boundary).

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

assign()

│ │ │ │ +
│ │ │ │ +void assign (char const* b, int const bits);
│ │ │ │ +
│ │ │ │ +

copy bitfield from buffer b of bits number of bits, rounded up to │ │ │ │ +the nearest byte boundary.

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

operator[]() get_bit()

│ │ │ │ +
│ │ │ │ +bool operator[] (int index) const noexcept;
│ │ │ │ +bool get_bit (int index) const noexcept;
│ │ │ │ +
│ │ │ │ +

query bit at index. Returns true if bit is 1, otherwise false.

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

clear_bit() set_bit()

│ │ │ │ +
│ │ │ │ +void clear_bit (int index) noexcept;
│ │ │ │ +void set_bit (int index) noexcept;
│ │ │ │ +
│ │ │ │ +

set bit at index to 0 (clear_bit) or 1 (set_bit).

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

all_set()

│ │ │ │ +
│ │ │ │ +bool all_set () const noexcept;
│ │ │ │ +
│ │ │ │ +

returns true if all bits in the bitfield are set

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

none_set()

│ │ │ │ +
│ │ │ │ +bool none_set () const noexcept;
│ │ │ │ +
│ │ │ │ +

returns true if no bit in the bitfield is set

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

size()

│ │ │ │ +
│ │ │ │ +int size () const noexcept;
│ │ │ │ +
│ │ │ │ +

returns the size of the bitfield in bits.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

num_words()

│ │ │ │ +
│ │ │ │ +int num_words () const noexcept;
│ │ │ │ +
│ │ │ │ +

returns the number of 32 bit words are needed to represent all bits in │ │ │ │ +this bitfield.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

empty()

│ │ │ │ +
│ │ │ │ +bool empty () const noexcept;
│ │ │ │ +
│ │ │ │ +

returns true if the bitfield has zero size.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

data()

│ │ │ │ +
│ │ │ │ +char const* data () const noexcept;
│ │ │ │ +char* data () noexcept;
│ │ │ │ +
│ │ │ │ +

returns a pointer to the internal buffer of the bitfield, or │ │ │ │ +nullptr if it's empty.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

swap()

│ │ │ │ +
│ │ │ │ +void swap (bitfield& rhs) noexcept;
│ │ │ │ +
│ │ │ │ +

swaps the bit-fields two variables refer to

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

count()

│ │ │ │ +
│ │ │ │ +int count () const noexcept;
│ │ │ │ +
│ │ │ │ +

count the number of bits in the bitfield that are set to 1.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

find_first_set()

│ │ │ │ +
│ │ │ │ +int find_first_set () const noexcept;
│ │ │ │ +
│ │ │ │ +

returns the index of the first set bit in the bitfield, i.e. 1 bit.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

find_last_clear()

│ │ │ │ +
│ │ │ │ +int find_last_clear () const noexcept;
│ │ │ │ +
│ │ │ │ +

returns the index to the last cleared bit in the bitfield, i.e. 0 bit.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +

hasher

│ │ │ │ +

Declared in "libtorrent/hasher.hpp"

│ │ │ │ +

this is a SHA-1 hash class.

│ │ │ │ +

You use it by first instantiating it, then call update() to feed it │ │ │ │ +with data. i.e. you don't have to keep the entire buffer of which you want to │ │ │ │ +create the hash in memory. You can feed the hasher parts of it at a time. When │ │ │ │ +You have fed the hasher with all the data, you call final() and it │ │ │ │ +will return the sha1-hash of the data.

│ │ │ │ +

The constructor that takes a char const* and an integer will construct the │ │ │ │ +sha1 context and feed it the data passed in.

│ │ │ │ +

If you want to reuse the hasher object once you have created a hash, you have to │ │ │ │ +call reset() to reinitialize it.

│ │ │ │ +

The built-in software version of sha1-algorithm was implemented │ │ │ │ +by Steve Reid and released as public domain. │ │ │ │ +For more info, see src/sha1.cpp.

│ │ │ │ +
│ │ │ │ +class hasher
│ │ │ │ +{
│ │ │ │ +   hasher ();
│ │ │ │ +   hasher& operator= (hasher const&) &;
│ │ │ │ +   explicit hasher (span<char const> data);
│ │ │ │ +   hasher (char const* data, int len);
│ │ │ │ +   hasher (hasher const&);
│ │ │ │ +   hasher& update (char const* data, int len);
│ │ │ │ +   hasher& update (span<char const> data);
│ │ │ │ +   sha1_hash final ();
│ │ │ │ +   void reset ();
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +

operator=() hasher()

│ │ │ │ +
│ │ │ │ +hasher& operator= (hasher const&) &;
│ │ │ │ +explicit hasher (span<char const> data);
│ │ │ │ +hasher (char const* data, int len);
│ │ │ │ +hasher (hasher const&);
│ │ │ │ +
│ │ │ │ +

this is the same as default constructing followed by a call to │ │ │ │ +update(data, len).

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

update()

│ │ │ │ +
│ │ │ │ +hasher& update (char const* data, int len);
│ │ │ │ +hasher& update (span<char const> data);
│ │ │ │ +
│ │ │ │ +

append the following bytes to what is being hashed

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

final()

│ │ │ │ +
│ │ │ │ +sha1_hash final ();
│ │ │ │ +
│ │ │ │ +

returns the SHA-1 digest of the buffers previously passed to │ │ │ │ +update() and the hasher constructor.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

reset()

│ │ │ │ +
│ │ │ │ +void reset ();
│ │ │ │ +
│ │ │ │ +

restore the hasher state to be as if the hasher has just been │ │ │ │ +default constructed.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +

hasher256

│ │ │ │ +

Declared in "libtorrent/hasher.hpp"

│ │ │ │ +
│ │ │ │ +class hasher256
│ │ │ │ +{
│ │ │ │ +   hasher256 ();
│ │ │ │ +   hasher256 (char const* data, int len);
│ │ │ │ +   explicit hasher256 (span<char const> data);
│ │ │ │ +   hasher256 (hasher256 const&);
│ │ │ │ +   hasher256& operator= (hasher256 const&) &;
│ │ │ │ +   hasher256& update (char const* data, int len);
│ │ │ │ +   hasher256& update (span<char const> data);
│ │ │ │ +   sha256_hash final ();
│ │ │ │ +   void reset ();
│ │ │ │ +   ~hasher256 ();
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +

hasher256() operator=()

│ │ │ │ +
│ │ │ │ +hasher256 (char const* data, int len);
│ │ │ │ +explicit hasher256 (span<char const> data);
│ │ │ │ +hasher256 (hasher256 const&);
│ │ │ │ +hasher256& operator= (hasher256 const&) &;
│ │ │ │ +
│ │ │ │ +

this is the same as default constructing followed by a call to │ │ │ │ +update(data, len).

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

update()

│ │ │ │ +
│ │ │ │ +hasher256& update (char const* data, int len);
│ │ │ │ +hasher256& update (span<char const> data);
│ │ │ │ +
│ │ │ │ +

append the following bytes to what is being hashed

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

final()

│ │ │ │ +
│ │ │ │ +sha256_hash final ();
│ │ │ │ +
│ │ │ │ +

returns the SHA-1 digest of the buffers previously passed to │ │ │ │ +update() and the hasher constructor.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

reset()

│ │ │ │ +
│ │ │ │ +void reset ();
│ │ │ │ +
│ │ │ │ +

restore the hasher state to be as if the hasher has just been │ │ │ │ +default constructed.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +

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,
│ │ │ │ +   };
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +

add() remove()

│ │ │ │ +
│ │ │ │ +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);
│ │ │ │ +
│ │ │ │ +

add() and remove() adds and removes a peer class to be added │ │ │ │ +to new peers based on socket type.

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

disallow() allow()

│ │ │ │ +
│ │ │ │ +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);
│ │ │ │ +
│ │ │ │ +

disallow() and allow() adds and removes a peer class to be │ │ │ │ +removed from new peers based on socket type.

│ │ │ │ +

The peer_class argument cannot be greater than 31. The bitmasks representing │ │ │ │ +peer classes in the peer_class_type_filter are 32 bits.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

apply()

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

takes a bitmask of peer classes and returns a new bitmask of │ │ │ │ +peer classes after the rules have been applied, based on the socket type argument │ │ │ │ +(st).

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

enum socket_type_t

│ │ │ │ +

Declared in "libtorrent/peer_class_type_filter.hpp"

│ │ │ │ + │ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ +
namevaluedescription
tcp_socket0these match the socket types from socket_type.hpp │ │ │ │ +shifted one down
utp_socket1 
ssl_tcp_socket2 
ssl_utp_socket3 
i2p_socket4 
num_socket_types5 
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +

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;
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
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.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
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.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
label
│ │ │ │ +
not used by libtorrent. It's intended as a potentially user-facing │ │ │ │ +identifier of this peer class.
│ │ │ │ +
│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
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.
│ │ │ │ +
│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
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.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

storage_error

│ │ │ │ +

Declared in "libtorrent/error_code.hpp"

│ │ │ │ +

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

│ │ │ │ +
│ │ │ │ +struct storage_error
│ │ │ │ +{
│ │ │ │ +   explicit operator bool () const;
│ │ │ │ +   file_index_t file () const;
│ │ │ │ +   void file (file_index_t f);
│ │ │ │ +
│ │ │ │ +   error_code ec;
│ │ │ │ +   operation_t operation;
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +

bool()

│ │ │ │ +
│ │ │ │ +explicit operator bool () const;
│ │ │ │ +
│ │ │ │ +

explicitly converts to true if this object represents an error, and │ │ │ │ +false if it does not.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

file()

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

set and query the index (in the torrent) of the file this error │ │ │ │ +occurred on. This may also have special values defined in │ │ │ │ +torrent_status.

│ │ │ │ +[report issue]
│ │ │ │ +
ec
│ │ │ │ +
the error that occurred
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
operation
│ │ │ │ +
A code from operation_t enum, indicating what │ │ │ │ +kind of operation failed.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +

libtorrent_category()

│ │ │ │ +

Declared in "libtorrent/error_code.hpp"

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

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

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

http_category()

│ │ │ │ +

Declared in "libtorrent/error_code.hpp"

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

returns the error_category for HTTP errors

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

pcp_category()

│ │ │ │ +

Declared in "libtorrent/natpmp.hpp"

│ │ │ │ +
│ │ │ │ +boost::system::error_category& pcp_category ();
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

upnp_category()

│ │ │ │ +

Declared in "libtorrent/upnp.hpp"

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

the boost.system error category for UPnP errors

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

gzip_category()

│ │ │ │ +

Declared in "libtorrent/gzip.hpp"

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

get the error_category for zip errors

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

socks_category()

│ │ │ │ +

Declared in "libtorrent/socks5_stream.hpp"

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

returns the error_category for SOCKS5 errors

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

i2p_category()

│ │ │ │ +

Declared in "libtorrent/i2p_stream.hpp"

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

returns the error category for I2P errors

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

bdecode_category()

│ │ │ │ +

Declared in "libtorrent/bdecode.hpp"

│ │ │ │ +
│ │ │ │ +boost::system::error_category& bdecode_category ();
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

enum error_code_enum

│ │ │ │ +

Declared in "libtorrent/error_code.hpp"

│ │ │ │ + │ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ +
namevaluedescription
no_error0Not an error
file_collision1Two torrents has files which end up overwriting each other
failed_hash_check2A piece did not match its piece hash
torrent_is_no_dict3The .torrent file does not contain a bencoded dictionary at │ │ │ │ +its top level
torrent_missing_info4The .torrent file does not have an info dictionary
torrent_info_no_dict5The .torrent file's info entry is not a dictionary
torrent_missing_piece_length6The .torrent file does not have a piece length entry
torrent_missing_name7The .torrent file does not have a name entry
torrent_invalid_name8The .torrent file's name entry is invalid
torrent_invalid_length9The length of a file, or of the whole .torrent file is invalid. │ │ │ │ +Either negative or not an integer
torrent_file_parse_failed10Failed to parse a file entry in the .torrent
torrent_missing_pieces11The pieces field is missing or invalid in the .torrent file
torrent_invalid_hashes12The pieces string has incorrect length
too_many_pieces_in_torrent13The .torrent file has more pieces than is supported by libtorrent
invalid_swarm_metadata14The metadata (.torrent file) that was received from the swarm │ │ │ │ +matched the info-hash, but failed to be parsed
invalid_bencoding15The file or buffer is not correctly bencoded
no_files_in_torrent16The .torrent file does not contain any files
invalid_escaped_string17The string was not properly url-encoded as expected
session_is_closing18Operation is not permitted since the session is shutting down
duplicate_torrent19There's already a torrent with that info-hash added to the │ │ │ │ +session
invalid_torrent_handle20The supplied torrent_handle is not referring to a valid torrent
invalid_entry_type21The type requested from the entry did not match its type
missing_info_hash_in_uri22The specified URI does not contain a valid info-hash
file_too_short23One of the files in the torrent was unexpectedly small. This │ │ │ │ +might be caused by files being changed by an external process
unsupported_url_protocol24The URL used an unknown protocol. Currently http and │ │ │ │ +https (if built with openssl support) are recognized. For │ │ │ │ +trackers udp is recognized as well.
url_parse_error25The URL did not conform to URL syntax and failed to be parsed
peer_sent_empty_piece26The peer sent a piece message of length 0
parse_failed27A bencoded structure was corrupt and failed to be parsed
invalid_file_tag28The fast resume file was missing or had an invalid file version │ │ │ │ +tag
missing_info_hash29The fast resume file was missing or had an invalid info-hash
mismatching_info_hash30The info-hash did not match the torrent
invalid_hostname31The URL contained an invalid hostname
invalid_port32The URL had an invalid port
port_blocked33The port is blocked by the port-filter, and prevented the │ │ │ │ +connection
expected_close_bracket_in_address34The IPv6 address was expected to end with "]"
destructing_torrent35The torrent is being destructed, preventing the operation to │ │ │ │ +succeed
timed_out36The connection timed out
upload_upload_connection37The peer is upload only, and we are upload only. There's no point │ │ │ │ +in keeping the connection
uninteresting_upload_peer38The peer is upload only, and we're not interested in it. There's │ │ │ │ +no point in keeping the connection
invalid_info_hash39The peer sent an unknown info-hash
torrent_paused40The torrent is paused, preventing the operation from succeeding
invalid_have41The peer sent an invalid have message, either wrong size or │ │ │ │ +referring to a piece that doesn't exist in the torrent
invalid_bitfield_size42The bitfield message had the incorrect size
too_many_requests_when_choked43The peer kept requesting pieces after it was choked, possible │ │ │ │ +abuse attempt.
invalid_piece44The peer sent a piece message that does not correspond to a │ │ │ │ +piece request sent by the client
no_memory45memory allocation failed
torrent_aborted46The torrent is aborted, preventing the operation to succeed
self_connection47The peer is a connection to ourself, no point in keeping it
invalid_piece_size48The peer sent a piece message with invalid size, either negative │ │ │ │ +or greater than one block
timed_out_no_interest49The peer has not been interesting or interested in us for too │ │ │ │ +long, no point in keeping it around
timed_out_inactivity50The peer has not said anything in a long time, possibly dead
timed_out_no_handshake51The peer did not send a handshake within a reasonable amount of │ │ │ │ +time, it might not be a bittorrent peer
timed_out_no_request52The peer has been unchoked for too long without requesting any │ │ │ │ +data. It might be lying about its interest in us
invalid_choke53The peer sent an invalid choke message
invalid_unchoke54The peer send an invalid unchoke message
invalid_interested55The peer sent an invalid interested message
invalid_not_interested56The peer sent an invalid not-interested message
invalid_request57The peer sent an invalid piece request message
invalid_hash_list58The peer sent an invalid hash-list message (this is part of the │ │ │ │ +merkle-torrent extension)
invalid_hash_piece59The peer sent an invalid hash-piece message (this is part of the │ │ │ │ +merkle-torrent extension)
invalid_cancel60The peer sent an invalid cancel message
invalid_dht_port61The peer sent an invalid DHT port-message
invalid_suggest62The peer sent an invalid suggest piece-message
invalid_have_all63The peer sent an invalid have all-message
invalid_have_none64The peer sent an invalid have none-message
invalid_reject65The peer sent an invalid reject message
invalid_allow_fast66The peer sent an invalid allow fast-message
invalid_extended67The peer sent an invalid extension message ID
invalid_message68The peer sent an invalid message ID
sync_hash_not_found69The synchronization hash was not found in the encrypted handshake
invalid_encryption_constant70The encryption constant in the handshake is invalid
no_plaintext_mode71The peer does not support plain text, which is the selected mode
no_rc4_mode72The peer does not support RC4, which is the selected mode
unsupported_encryption_mode73The peer does not support any of the encryption modes that the │ │ │ │ +client supports
unsupported_encryption_mode_selected74The peer selected an encryption mode that the client did not │ │ │ │ +advertise and does not support
invalid_pad_size75The pad size used in the encryption handshake is of invalid size
invalid_encrypt_handshake76The encryption handshake is invalid
no_incoming_encrypted77The client is set to not support incoming encrypted connections │ │ │ │ +and this is an encrypted connection
no_incoming_regular78The client is set to not support incoming regular bittorrent │ │ │ │ +connections, and this is a regular connection
duplicate_peer_id79The client is already connected to this peer-ID
torrent_removed80Torrent was removed
packet_too_large81The packet size exceeded the upper sanity check-limit
reserved82 
http_error83The web server responded with an error
missing_location84The web server response is missing a location header
invalid_redirection85The web seed redirected to a path that no longer matches the │ │ │ │ +.torrent directory structure
redirecting86The connection was closed because it redirected to a different │ │ │ │ +URL
invalid_range87The HTTP range header is invalid
no_content_length88The HTTP response did not have a content length
banned_by_ip_filter89The IP is blocked by the IP filter
too_many_connections90At the connection limit
peer_banned91The peer is marked as banned
stopping_torrent92The torrent is stopping, causing the operation to fail
too_many_corrupt_pieces93The peer has sent too many corrupt pieces and is banned
torrent_not_ready94The torrent is not ready to receive peers
peer_not_constructed95The peer is not completely constructed yet
session_closing96The session is closing, causing the operation to fail
optimistic_disconnect97The peer was disconnected in order to leave room for a │ │ │ │ +potentially better peer
torrent_finished98The torrent is finished
no_router99No UPnP router found
metadata_too_large100The metadata message says the metadata exceeds the limit
invalid_metadata_request101The peer sent an invalid metadata request message
invalid_metadata_size102The peer advertised an invalid metadata size
invalid_metadata_offset103The peer sent a message with an invalid metadata offset
invalid_metadata_message104The peer sent an invalid metadata message
pex_message_too_large105The peer sent a peer exchange message that was too large
invalid_pex_message106The peer sent an invalid peer exchange message
invalid_lt_tracker_message107The peer sent an invalid tracker exchange message
too_frequent_pex108The peer sent an pex messages too often. This is a possible │ │ │ │ +attempt of and attack
no_metadata109The operation failed because it requires the torrent to have │ │ │ │ +the metadata (.torrent file) and it doesn't have it yet. │ │ │ │ +This happens for magnet links before they have downloaded the │ │ │ │ +metadata, and also torrents added by URL.
invalid_dont_have110The peer sent an invalid dont_have message. The don't have │ │ │ │ +message is an extension to allow peers to advertise that the │ │ │ │ +no longer has a piece they previously had.
requires_ssl_connection111The peer tried to connect to an SSL torrent without connecting │ │ │ │ +over SSL.
invalid_ssl_cert112The peer tried to connect to a torrent with a certificate │ │ │ │ +for a different torrent.
not_an_ssl_torrent113the torrent is not an SSL torrent, and the operation requires │ │ │ │ +an SSL torrent
banned_by_port_filter114peer was banned because its listen port is within a banned port │ │ │ │ +range, as specified by the port_filter.
invalid_session_handle115The session_handle is not referring to a valid session_impl
invalid_listen_socket116the listen socket associated with this request was closed
invalid_hash_request117 
invalid_hashes118 
invalid_hash_reject119 
deprecated_120120 
deprecated_121121 
deprecated_122122 
deprecated_123123 
deprecated_124124 
missing_file_sizes130The resume data file is missing the file sizes entry
no_files_in_resume_data131The resume data file file sizes entry is empty
missing_pieces132The resume data file is missing the pieces and slots entry
mismatching_number_of_files133The number of files in the resume data does not match the number │ │ │ │ +of files in the torrent
mismatching_file_size134One of the files on disk has a different size than in the fast │ │ │ │ +resume file
mismatching_file_timestamp135One of the files on disk has a different timestamp than in the │ │ │ │ +fast resume file
not_a_dictionary136The resume data file is not a dictionary
invalid_blocks_per_piece137The blocks per piece entry is invalid in the resume data file
missing_slots138The resume file is missing the slots entry, which is required │ │ │ │ +for torrents with compact allocation. DEPRECATED
too_many_slots139The resume file contains more slots than the torrent
invalid_slot_list140The slot entry is invalid in the resume data
invalid_piece_index141One index in the slot list is invalid
pieces_need_reorder142The pieces on disk needs to be re-ordered for the specified │ │ │ │ +allocation mode. This happens if you specify sparse allocation │ │ │ │ +and the files on disk are using compact storage. The pieces needs │ │ │ │ +to be moved to their right position. DEPRECATED
resume_data_not_modified143this error is returned when asking to save resume data and │ │ │ │ +specifying the flag to only save when there's anything new to save │ │ │ │ +(torrent_handle::only_if_modified) and there wasn't anything changed.
http_parse_error150The HTTP header was not correctly formatted
http_missing_location151The HTTP response was in the 300-399 range but lacked a location │ │ │ │ +header
http_failed_decompress152The HTTP response was encoded with gzip or deflate but │ │ │ │ +decompressing it failed
no_i2p_router160The URL specified an i2p address, but no i2p router is configured
no_i2p_endpoint161i2p acceptor is not available yet, can't announce without endpoint
scrape_not_available170The tracker URL doesn't support transforming it into a scrape │ │ │ │ +URL. i.e. it doesn't contain "announce.
invalid_tracker_response171invalid tracker response
invalid_peer_dict172invalid peer dictionary entry. Not a dictionary
tracker_failure173tracker sent a failure message
invalid_files_entry174missing or invalid files entry
invalid_hash_entry175missing or invalid hash entry
invalid_peers_entry176missing or invalid peers and peers6 entry
invalid_tracker_response_length177UDP tracker response packet has invalid size
invalid_tracker_transaction_id178invalid transaction id in UDP tracker response
invalid_tracker_action179invalid action field in UDP tracker response
announce_skipped180skipped announce (because it's assumed to be unreachable over the │ │ │ │ +given source network interface)
no_entropy200random number generation failed
ssrf_mitigation201blocked by SSRF mitigation
blocked_by_idna202blocked because IDNA host names are banned
torrent_unknown_version210the torrent file has an unknown meta version
torrent_missing_file_tree211the v2 torrent file has no file tree
torrent_missing_meta_version212the torrent contains v2 keys but does not specify meta version 2
torrent_inconsistent_files213the v1 and v2 file metadata does not match
torrent_missing_piece_layer214one or more files are missing piece layer hashes
torrent_invalid_piece_layer215a piece layer has the wrong size or failed hash check
torrent_missing_pieces_root216a v2 file entry has no root hash
torrent_inconsistent_hashes217the v1 and v2 hashes do not describe the same data
torrent_invalid_pad_file218a file in the v2 metadata has the pad attribute set
error_code_max219the number of error codes
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

enum http_errors

│ │ │ │ +

Declared in "libtorrent/error_code.hpp"

│ │ │ │ + │ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ │ │ │ │ - │ │ │ │ -
namevaluedescription
string_type_base0
cont100 
int_type_base16384
ok200 
bool_type_base32768
created201 
type_mask49152
accepted202 
index_mask16383
no_content204 
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

enum mmap_write_mode_t

│ │ │ │ -

Declared in "libtorrent/settings_pack.hpp"

│ │ │ │ - │ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ -
namevaluedescription
multiple_choices300 
always_pwrite0disable writing to disk via mmap, always use normal write calls
moved_permanently301 
always_mmap_write1prefer using memory mapped files for disk writes (at least for │ │ │ │ -large files where it might make sense)
moved_temporarily302 
auto_mmap_write2determine whether to use pwrite or memory mapped files for disk │ │ │ │ -writes depending on the kind of storage behind the save path
not_modified304 
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

enum suggest_mode_t

│ │ │ │ -

Declared in "libtorrent/settings_pack.hpp"

│ │ │ │ - │ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ │ │ │ │ - │ │ │ │ -
namevaluedescription
bad_request400 
no_piece_suggestions0
unauthorized401 
suggest_read_cache1
forbidden403 
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

enum choking_algorithm_t

│ │ │ │ -

Declared in "libtorrent/settings_pack.hpp"

│ │ │ │ - │ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │
namevaluedescription
not_found404 
fixed_slots_choker0This is the traditional choker with a fixed number of unchoke │ │ │ │ -slots (as specified by settings_pack::unchoke_slots_limit).
internal_server_error500 
rate_based_choker2

This opens up unchoke slots based on the upload rate achieved to │ │ │ │ -peers. The more slots that are opened, the marginal upload rate │ │ │ │ -required to open up another slot increases. Configure the initial │ │ │ │ -threshold with settings_pack::rate_choker_initial_threshold.

│ │ │ │ -

For more information, see rate based choking.

│ │ │ │ -
not_implemented501 
deprecated_bittyrant_choker3
bad_gateway502 
service_unavailable503 
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

enum seed_choking_algorithm_t

│ │ │ │ -

Declared in "libtorrent/settings_pack.hpp"

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

enum pcp_errors

│ │ │ │ +

Declared in "libtorrent/natpmp.hpp"

│ │ │ │ │ │ │ │ │ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ -
namevaluedescription
round_robin
pcp_success0which round-robins the peers that are unchoked │ │ │ │ -when seeding. This distributes the upload bandwidth uniformly and │ │ │ │ -fairly. It minimizes the ability for a peer to download everything │ │ │ │ -without redistributing it. 
fastest_upload
pcp_unsupp_version1unchokes the peers we can send to the fastest. This might be a │ │ │ │ -bit more reliable in utilizing all available capacity. 
anti_leech
pcp_not_authorized2prioritizes peers who have just started or are │ │ │ │ -just about to finish the download. The intention is to force │ │ │ │ -peers in the middle of the download to trade with each other. │ │ │ │ -This does not just take into account the pieces a peer is │ │ │ │ -reporting having downloaded, but also the pieces we have sent │ │ │ │ -to it. 
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

enum io_buffer_mode_t

│ │ │ │ -

Declared in "libtorrent/settings_pack.hpp"

│ │ │ │ - │ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │
namevaluedescription
pcp_malformed_request3 
enable_os_cache0
pcp_unsupp_opcode4 
deprecated_disable_os_cache_for_aligned_files1
pcp_unsupp_option5 
disable_os_cache2
pcp_malformed_option6 
write_through3
pcp_network_failure7 
pcp_no_resources8 
pcp_unsupp_protocol9 
pcp_user_ex_quota10 
pcp_cannot_provide_external11 
pcp_address_mismatch12 
pcp_excessive_remote_peers13 
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

enum bandwidth_mixed_algo_t

│ │ │ │ -

Declared in "libtorrent/settings_pack.hpp"

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

enum error_code_enum

│ │ │ │ +

Declared in "libtorrent/upnp.hpp"

│ │ │ │ │ │ │ │ │ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ │ │ │ │
namevaluedescription
prefer_tcp
no_error0disables the mixed mode bandwidth balancingNo error
peer_proportional1does not throttle uTP, throttles TCP to the same proportion │ │ │ │ -of throughput as there are TCP connections
invalid_argument402One of the arguments in the request is invalid
action_failed501The request failed
value_not_in_array714The specified value does not exist in the array
source_ip_cannot_be_wildcarded715The source IP address cannot be wild-carded, but │ │ │ │ +must be fully specified
external_port_cannot_be_wildcarded716The external port cannot be a wildcard, but must │ │ │ │ +be specified
port_mapping_conflict718The port mapping entry specified conflicts with a │ │ │ │ +mapping assigned previously to another client
internal_port_must_match_external724Internal and external port value must be the same
only_permanent_leases_supported725The NAT implementation only supports permanent │ │ │ │ +lease times on port mappings
remote_host_must_be_wildcard726RemoteHost must be a wildcard and cannot be a │ │ │ │ +specific IP address or DNS name
external_port_must_be_wildcard727ExternalPort must be a wildcard and cannot be a │ │ │ │ +specific port
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

enum enc_policy

│ │ │ │ -

Declared in "libtorrent/settings_pack.hpp"

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

enum error_code_enum

│ │ │ │ +

Declared in "libtorrent/gzip.hpp"

│ │ │ │ │ │ │ │ │ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ │ │ │ │
namevaluedescription
pe_forced
no_error0Only encrypted connections are allowed. Incoming connections that │ │ │ │ -are not encrypted are closed and if the encrypted outgoing │ │ │ │ -connection fails, a non-encrypted retry will not be made.Not an error
pe_enabled
invalid_gzip_header1encrypted connections are enabled, but non-encrypted connections │ │ │ │ -are allowed. An incoming non-encrypted connection will be accepted, │ │ │ │ -and if an outgoing encrypted connection fails, a non- encrypted │ │ │ │ -connection will be tried.the supplied gzip buffer has invalid header
pe_disabled
inflated_data_too_large2only non-encrypted connections are allowed.the gzip buffer would inflate to more bytes than the specified │ │ │ │ +maximum size, and was rejected.
data_did_not_terminate3available inflate data did not terminate
space_exhausted4output space exhausted before completing inflate
invalid_block_type5invalid block type (type == 3)
invalid_stored_block_length6stored block length did not match one's complement
too_many_length_or_distance_codes7dynamic block code description: too many length or distance codes
code_lengths_codes_incomplete8dynamic block code description: code lengths codes incomplete
repeat_lengths_with_no_first_length9dynamic block code description: repeat lengths with no first length
repeat_more_than_specified_lengths10dynamic block code description: repeat more than specified lengths
invalid_literal_length_code_lengths11dynamic block code description: invalid literal/length code lengths
invalid_distance_code_lengths12dynamic block code description: invalid distance code lengths
invalid_literal_code_in_block13invalid literal/length or distance code in fixed or dynamic block
distance_too_far_back_in_block14distance is too far back in fixed or dynamic block
unknown_gzip_error15an unknown error occurred during gzip inflation
error_code_max16the number of error codes
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

enum enc_level

│ │ │ │ -

Declared in "libtorrent/settings_pack.hpp"

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

enum socks_error_code

│ │ │ │ +

Declared in "libtorrent/socks5_stream.hpp"

│ │ │ │ │ │ │ │ │ │ │ │ -│ │ │ │ +│ │ │ │ │ │ │ │ -│ │ │ │ +│ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ │ │ │ │
namevaluedescription
pe_plaintext
no_error0 
unsupported_version1use only plain text encryption 
pe_rc4
unsupported_authentication_method2use only RC4 encryption 
pe_both
unsupported_authentication_version3allow both 
authentication_error4 
username_required5 
general_failure6 
command_not_supported7 
no_identd8 
identd_error9 
num_errors10 
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

enum proxy_type_t

│ │ │ │ -

Declared in "libtorrent/settings_pack.hpp"

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

enum i2p_error_code

│ │ │ │ +

Declared in "libtorrent/i2p_stream.hpp"

│ │ │ │ │ │ │ │ │ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ │ │ │ │
namevaluedescription
none
no_error0No proxy server is used and all other fields are ignored. 
socks4
parse_failed1The server is assumed to be a SOCKS4 server that requires a │ │ │ │ -username. 
socks5
cant_reach_peer2The server is assumed to be a SOCKS5 server (RFC 1928) that does │ │ │ │ -not require any authentication. The username and password are │ │ │ │ -ignored. 
socks5_pw
i2p_error3The server is assumed to be a SOCKS5 server that supports plain │ │ │ │ -text username and password authentication (RFC 1929). The │ │ │ │ -username and password specified may be sent to the proxy if it │ │ │ │ -requires. 
http
invalid_key4The server is assumed to be an HTTP proxy. If the transport used │ │ │ │ -for the connection is non-HTTP, the server is assumed to support │ │ │ │ -the CONNECT method. i.e. for web seeds and HTTP trackers, a plain │ │ │ │ -proxy will suffice. The proxy is assumed to not require │ │ │ │ -authorization. The username and password will not be used. 
http_pw
invalid_id5The server is assumed to be an HTTP proxy that requires user │ │ │ │ -authorization. The username and password will be sent to the proxy. 
i2p_proxy
timeout6route through a i2p SAM proxy 
key_not_found7 
duplicated_id8 
num_errors9 
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -

generate_fingerprint()

│ │ │ │ -

Declared in "libtorrent/fingerprint.hpp"

│ │ │ │ -
│ │ │ │ -std::string generate_fingerprint (std::string name
│ │ │ │ -   , int major, int minor = 0, int revision = 0, int tag = 0);
│ │ │ │ -
│ │ │ │ -

This is a utility function to produce a client ID fingerprint formatted to │ │ │ │ -the most common convention. The fingerprint can be set via the │ │ │ │ -peer_fingerprint setting, in settings_pack.

│ │ │ │ -

The name string should contain exactly two characters. These are the │ │ │ │ -characters unique to your client, used to identify it. Make sure not to │ │ │ │ -clash with anybody else. Here are some taken id's:

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

enum error_code_enum

│ │ │ │ +

Declared in "libtorrent/bdecode.hpp"

│ │ │ │ │ │ │ │ │ │ │ │ -│ │ │ │ -│ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ │ │ │ │ │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ │ │ │ │
id charsclient
namevaluedescription
LTlibtorrent (default)
no_error0Not an error
UTuTorrent
expected_digit1expected digit in bencoded string
UMuTorrent Mac
expected_colon2expected colon in bencoded string
qBqBittorrent
unexpected_eof3unexpected end of file in bencoded string
BPBitTorrent Pro
expected_value4expected value (list, dict, int or string) in bencoded string
BTBitTorrent
depth_exceeded5bencoded recursion depth limit exceeded
DEDeluge
limit_exceeded6bencoded item count limit exceeded
AZAzureus
overflow7integer overflow
TLTribler
error_code_max8the number of error codes
│ │ │ │ -

There's an informal directory of client id's here.

│ │ │ │ -

The major, minor, revision and tag parameters are used to │ │ │ │ -identify the version of your client.

│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

name_for_setting() setting_by_name()

│ │ │ │ -

Declared in "libtorrent/settings_pack.hpp"

│ │ │ │ -
│ │ │ │ -int setting_by_name (string_view name);
│ │ │ │ -char const* name_for_setting (int s);
│ │ │ │ -
│ │ │ │ -

converts a setting integer (from the enums string_types, int_types or │ │ │ │ -bool_types) to a string, and vice versa.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

default_settings()

│ │ │ │ -

Declared in "libtorrent/settings_pack.hpp"

│ │ │ │ -
│ │ │ │ -settings_pack default_settings ();
│ │ │ │ -
│ │ │ │ -

returns a settings_pack with every setting set to its default value

│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

high_performance_seed() min_memory_usage()

│ │ │ │ -

Declared in "libtorrent/session.hpp"

│ │ │ │ -
│ │ │ │ -settings_pack min_memory_usage ();
│ │ │ │ -settings_pack high_performance_seed ();
│ │ │ │ -
│ │ │ │ -

The default values of the session settings are set for a regular │ │ │ │ -bittorrent client running on a desktop system. There are functions that │ │ │ │ -can set the session settings to pre set settings for other environments. │ │ │ │ -These can be used for the basis, and should be tweaked to fit your needs │ │ │ │ -better.

│ │ │ │ -

min_memory_usage returns settings that will use the minimal amount of │ │ │ │ -RAM, at the potential expense of upload and download performance. It │ │ │ │ -adjusts the socket buffer sizes, disables the disk cache, lowers the send │ │ │ │ -buffer watermarks so that each connection only has at most one block in │ │ │ │ -use at any one time. It lowers the outstanding blocks send to the disk │ │ │ │ -I/O thread so that connections only have one block waiting to be flushed │ │ │ │ -to disk at any given time. It lowers the max number of peers in the peer │ │ │ │ -list for torrents. It performs multiple smaller reads when it hashes │ │ │ │ -pieces, instead of reading it all into memory before hashing.

│ │ │ │ -

This configuration is intended to be the starting point for embedded │ │ │ │ -devices. It will significantly reduce memory usage.

│ │ │ │ -

high_performance_seed returns settings optimized for a seed box, │ │ │ │ -serving many peers and that doesn't do any downloading. It has a 128 MB │ │ │ │ -disk cache and has a limit of 400 files in its file pool. It support fast │ │ │ │ -upload rates by allowing large send buffers.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

session_params

│ │ │ │ -

Declared in "libtorrent/session_params.hpp"

│ │ │ │ -

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

│ │ │ │ -
│ │ │ │ -struct session_params
│ │ │ │ -{
│ │ │ │ -   session_params (settings_pack const& sp);
│ │ │ │ -   session_params ();
│ │ │ │ -   session_params (settings_pack&& sp);
│ │ │ │ -   session_params (settings_pack const& sp
│ │ │ │ -      , std::vector<std::shared_ptr<plugin>> exts);
│ │ │ │ -   session_params (settings_pack&& sp
│ │ │ │ -      , std::vector<std::shared_ptr<plugin>> exts);
│ │ │ │ -
│ │ │ │ -   settings_pack settings;
│ │ │ │ -   std::vector<std::shared_ptr<plugin>> extensions;
│ │ │ │ -   dht::dht_state dht_state;
│ │ │ │ -   dht::dht_storage_constructor_type dht_storage_constructor;
│ │ │ │ -   disk_io_constructor_type disk_io_constructor;
│ │ │ │ -   std::map<std::string, std::string> ext_state;
│ │ │ │ -   libtorrent::ip_filter ip_filter;
│ │ │ │ -};
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -

session_params()

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

This constructor can be used to start with the default plugins │ │ │ │ -(ut_metadata, ut_pex and smart_ban). Pass a settings_pack to set the │ │ │ │ -initial settings when the session starts.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

session_params()

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

This constructor helps to configure the set of initial plugins │ │ │ │ -to be added to the session before it's started.

│ │ │ │ -[report issue]
│ │ │ │ -
settings
│ │ │ │ -
The settings to configure the session with
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
extensions
│ │ │ │ -
the plugins to add to the session as it is constructed
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
dht_state
│ │ │ │ -
DHT node ID and node addresses to bootstrap the DHT with.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
dht_storage_constructor
│ │ │ │ -
function object to construct the storage object for DHT items.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
disk_io_constructor
│ │ │ │ -
function object to create the disk I/O subsystem. Defaults to │ │ │ │ -default_disk_io_constructor.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
ext_state
│ │ │ │ -
this container can be used by extensions/plugins to store settings. It's │ │ │ │ -primarily here to make it convenient to save and restore state across │ │ │ │ -sessions, using read_session_params() and write_session_params().
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
ip_filter
│ │ │ │ -
the IP filter to use for the session. This restricts which peers are allowed │ │ │ │ -to connect. As if passed to set_ip_filter().
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -

session_proxy

│ │ │ │ -

Declared in "libtorrent/session.hpp"

│ │ │ │ -

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

│ │ │ │ -
│ │ │ │ -struct session_proxy
│ │ │ │ -{
│ │ │ │ -   session_proxy ();
│ │ │ │ -   session_proxy (session_proxy&&) noexcept;
│ │ │ │ -   session_proxy (session_proxy const&);
│ │ │ │ -   session_proxy& operator= (session_proxy const&) &;
│ │ │ │ -   ~session_proxy ();
│ │ │ │ -   session_proxy& operator= (session_proxy&&) & noexcept;
│ │ │ │ -};
│ │ │ │ -
│ │ │ │ - │ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -

~session_proxy() operator=() session_proxy()

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

default constructor, does not refer to any session │ │ │ │ -implementation object.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -

session

│ │ │ │ -

Declared in "libtorrent/session.hpp"

│ │ │ │ -

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

│ │ │ │ -

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

│ │ │ │ -

see apply_settings().

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

counters

│ │ │ │ +

Declared in "libtorrent/performance_counters.hpp"

│ │ │ │ 
│ │ │ │ -struct session : session_handle
│ │ │ │ +struct counters
│ │ │ │  {
│ │ │ │ -   explicit session (session_params&& params);
│ │ │ │ -   explicit session (session_params const& params);
│ │ │ │ -   session (session_params const& params, session_flags_t flags);
│ │ │ │ -   session (session_params&& params, session_flags_t flags);
│ │ │ │ -   session ();
│ │ │ │ -   session (session_params&& params, io_context& ios, session_flags_t);
│ │ │ │ -   session (session_params&& params, io_context& ios);
│ │ │ │ -   session (session_params const& params, io_context& ios, session_flags_t);
│ │ │ │ -   session (session_params const& params, io_context& ios);
│ │ │ │ -   ~session ();
│ │ │ │ -   session_proxy abort ();
│ │ │ │ +   counters () ;
│ │ │ │ +   counters (counters const&) ;
│ │ │ │ +   counters& operator= (counters const&) & ;
│ │ │ │ +   std::int64_t inc_stats_counter (int c, std::int64_t value = 1) ;
│ │ │ │ +   std::int64_t operator[] (int i) const ;
│ │ │ │ +   void set_value (int c, std::int64_t value) ;
│ │ │ │ +   void blend_stats_counter (int c, std::int64_t value, int ratio) ;
│ │ │ │  };
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -

session()

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

Constructs the session objects which acts as the container of torrents. │ │ │ │ -In order to avoid a race condition between starting the session and │ │ │ │ -configuring it, you can pass in a session_params object. Its settings │ │ │ │ -will take effect before the session starts up.

│ │ │ │ -

The overloads taking flags can be used to start a session in │ │ │ │ -paused mode (by passing in session::paused). Note that │ │ │ │ -add_default_plugins do not have an affect on constructors that │ │ │ │ -take a session_params object. It already contains the plugins to use.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

session()

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

Overload of the constructor that takes an external io_context to run │ │ │ │ -the session object on. This is primarily useful for tests that may want │ │ │ │ -to run multiple sessions on a single io_context, or low resource │ │ │ │ -systems where additional threads are expensive and sharing an │ │ │ │ -io_context with other events is fine.

│ │ │ │ -
│ │ │ │ -

Warning

│ │ │ │ -

The session object does not cleanly terminate with an external │ │ │ │ -io_context. The io_context::run() call must have returned │ │ │ │ -before it's safe to destruct the session. Which means you MUST │ │ │ │ -call session::abort() and save the session_proxy first, then │ │ │ │ -destruct the session object, then sync with the io_context, then │ │ │ │ -destruct the session_proxy object.

│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

~session()

│ │ │ │ -
│ │ │ │ -~session ();
│ │ │ │ -
│ │ │ │ -

The destructor of session will notify all trackers that our torrents │ │ │ │ -have been shut down. If some trackers are down, they will time out. │ │ │ │ -All this before the destructor of session returns. So, it's advised │ │ │ │ -that any kind of interface (such as windows) are closed before │ │ │ │ -destructing the session object. Because it can take a few second for │ │ │ │ -it to finish. The timeout can be set with apply_settings().

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

abort()

│ │ │ │ -
│ │ │ │ -session_proxy abort ();
│ │ │ │ -
│ │ │ │ -

In case you want to destruct the session asynchronously, you can │ │ │ │ -request a session destruction proxy. If you don't do this, the │ │ │ │ -destructor of the session object will block while the trackers are │ │ │ │ -contacted. If you keep one session_proxy to the session when │ │ │ │ -destructing it, the destructor will not block, but start to close down │ │ │ │ -the session, the destructor of the proxy will then synchronize the │ │ │ │ -threads. So, the destruction of the session is performed from the │ │ │ │ -session destructor call until the session_proxy destructor │ │ │ │ -call. The session_proxy does not have any operations on it (since │ │ │ │ -the session is being closed down, no operations are allowed on it). │ │ │ │ -The only valid operation is calling the destructor:

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +

operator[]() inc_stats_counter()

│ │ │ │ 
│ │ │ │ -struct session_proxy {};
│ │ │ │ +std::int64_t inc_stats_counter (int c, std::int64_t value = 1) ;
│ │ │ │ +std::int64_t operator[] (int i) const ;
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ +

returns the new value

│ │ │ │ +[report issue]
│ │ │ │
│ │ │ │ -
│ │ │ │ -

session_handle

│ │ │ │ -

Declared in "libtorrent/session_handle.hpp"

│ │ │ │ -

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

│ │ │ │ +
│ │ │ │ +

stats_metric

│ │ │ │ +

Declared in "libtorrent/session_stats.hpp"

│ │ │ │ +

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

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

is_valid()

│ │ │ │ -
│ │ │ │ -bool is_valid () const;
│ │ │ │ -
│ │ │ │ -

returns true if this handle refers to a valid session object. If the │ │ │ │ -session has been destroyed, all session_handle objects will expire and │ │ │ │ -not be valid.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

session_state()

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

returns the current session state. This can be passed to │ │ │ │ -write_session_params() to save the state to disk and restored using │ │ │ │ -read_session_params() when constructing a new session. The kind of │ │ │ │ -state that's included is all settings, the DHT routing table, possibly │ │ │ │ -plugin-specific state. │ │ │ │ -the flags parameter can be used to only save certain parts of the │ │ │ │ -session state

│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

get_torrent_status() refresh_torrent_status()

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

Note

│ │ │ │ -

these calls are potentially expensive and won't scale well with │ │ │ │ -lots of torrents. If you're concerned about performance, consider │ │ │ │ -using post_torrent_updates() instead.

│ │ │ │ -
│ │ │ │ -

get_torrent_status returns a vector of the torrent_status for │ │ │ │ -every torrent which satisfies pred, which is a predicate function │ │ │ │ -which determines if a torrent should be included in the returned set │ │ │ │ -or not. Returning true means it should be included and false means │ │ │ │ -excluded. The flags argument is the same as to │ │ │ │ -torrent_handle::status(). Since pred is guaranteed to be │ │ │ │ -called for every torrent, it may be used to count the number of │ │ │ │ -torrents of different categories as well.

│ │ │ │ -

refresh_torrent_status takes a vector of torrent_status structs │ │ │ │ -(for instance the same vector that was returned by │ │ │ │ -get_torrent_status() ) and refreshes the status based on the │ │ │ │ -handle member. It is possible to use this function by first │ │ │ │ -setting up a vector of default constructed torrent_status objects, │ │ │ │ -only initializing the handle member, in order to request the │ │ │ │ -torrent status for multiple torrents in a single call. This can save a │ │ │ │ -significant amount of time if you have a lot of torrents.

│ │ │ │ -

Any torrent_status object whose handle member is not referring to │ │ │ │ -a valid torrent are ignored.

│ │ │ │ -

The intended use of these functions is to start off by calling │ │ │ │ -get_torrent_status() to get a list of all torrents that match your │ │ │ │ -criteria. Then call refresh_torrent_status() on that list. This │ │ │ │ -will only refresh the status for the torrents in your list, and thus │ │ │ │ -ignore all other torrents you might be running. This may save a │ │ │ │ -significant amount of time, especially if the number of torrents you're │ │ │ │ -interested in is small. In order to keep your list of interested │ │ │ │ -torrents up to date, you can either call get_torrent_status() from │ │ │ │ -time to time, to include torrents you might have become interested in │ │ │ │ -since the last time. In order to stop refreshing a certain torrent, │ │ │ │ -simply remove it from the list.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

post_torrent_updates()

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

This functions instructs the session to post the state_update_alert, │ │ │ │ -containing the status of all torrents whose state changed since the │ │ │ │ -last time this function was called.

│ │ │ │ -

Only torrents who has the state subscription flag set will be │ │ │ │ -included. This flag is on by default. See add_torrent_params. │ │ │ │ -the flags argument is the same as for torrent_handle::status(). │ │ │ │ -see status_flags_t in torrent_handle.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

post_session_stats()

│ │ │ │ -
│ │ │ │ -void post_session_stats ();
│ │ │ │ -
│ │ │ │ -

This function will post a session_stats_alert object, containing a │ │ │ │ -snapshot of the performance counters from the internals of libtorrent. │ │ │ │ -To interpret these counters, query the session via │ │ │ │ -session_stats_metrics().

│ │ │ │ -

For more information, see the session statistics section.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

post_dht_stats()

│ │ │ │ -
│ │ │ │ -void post_dht_stats ();
│ │ │ │ -
│ │ │ │ -

This will cause a dht_stats_alert to be posted.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

set_dht_state()

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

set the DHT state for the session. This will be taken into account the │ │ │ │ -next time the DHT is started, as if it had been passed in via the │ │ │ │ -session_params on startup.

│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

find_torrent() get_torrents()

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

find_torrent() looks for a torrent with the given info-hash. In │ │ │ │ -case there is such a torrent in the session, a torrent_handle to that │ │ │ │ -torrent is returned. In case the torrent cannot be found, an invalid │ │ │ │ -torrent_handle is returned.

│ │ │ │ -

See torrent_handle::is_valid() to know if the torrent was found or │ │ │ │ -not.

│ │ │ │ -

get_torrents() returns a vector of torrent_handles to all the │ │ │ │ -torrents currently in the session.

│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

add_torrent() async_add_torrent()

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

You add torrents through the add_torrent() function where you give an │ │ │ │ -object with all the parameters. The add_torrent() overloads will block │ │ │ │ -until the torrent has been added (or failed to be added) and returns │ │ │ │ -an error code and a torrent_handle. In order to add torrents more │ │ │ │ -efficiently, consider using async_add_torrent() which returns │ │ │ │ -immediately, without waiting for the torrent to add. Notification of │ │ │ │ -the torrent being added is sent as add_torrent_alert.

│ │ │ │ -

The overload that does not take an error_code throws an exception on │ │ │ │ -error and is not available when building without exception support. │ │ │ │ -The torrent_handle returned by add_torrent() can be used to retrieve │ │ │ │ -information about the torrent's progress, its peers etc. It is also │ │ │ │ -used to abort a torrent.

│ │ │ │ -

If the torrent you are trying to add already exists in the session (is │ │ │ │ -either queued for checking, being checked or downloading) │ │ │ │ -add_torrent() will throw system_error which derives from │ │ │ │ -std::exception unless duplicate_is_error is set to false. In that │ │ │ │ -case, add_torrent() will return the handle to the existing torrent.

│ │ │ │ -

The add_torrent_params class has a flags field. It can be used to │ │ │ │ -control what state the new torrent will be added in. Common flags to │ │ │ │ -want to control are torrent_flags::paused and │ │ │ │ -torrent_flags::auto_managed. In order to add a magnet link that will │ │ │ │ -just download the metadata, but no payload, set the │ │ │ │ -torrent_flags::upload_mode flag.

│ │ │ │ -

Special consideration has to be taken when adding hybrid torrents │ │ │ │ -(i.e. torrents that are BitTorrent v2 torrents that are backwards │ │ │ │ -compatible with v1). For more details, see BitTorrent v2 torrents.

│ │ │ │ - │ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

resume() pause() is_paused()

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

Pausing the session has the same effect as pausing every torrent in │ │ │ │ -it, except that torrents will not be resumed by the auto-manage │ │ │ │ -mechanism. Resuming will restore the torrents to their previous paused │ │ │ │ -state. i.e. the session pause state is separate from the torrent pause │ │ │ │ -state. A torrent is inactive if it is paused or if the session is │ │ │ │ -paused.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

is_dht_running()

│ │ │ │ -
│ │ │ │ -bool is_dht_running () const;
│ │ │ │ -
│ │ │ │ -

is_dht_running() returns true if the DHT support has been started │ │ │ │ -and false otherwise.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

set_dht_storage()

│ │ │ │ -
│ │ │ │ -void set_dht_storage (dht::dht_storage_constructor_type sc);
│ │ │ │ -
│ │ │ │ -

set_dht_storage set a dht custom storage constructor function │ │ │ │ -to be used internally when the dht is created.

│ │ │ │ -

Since the dht storage is a critical component for the dht behavior, │ │ │ │ -this function will only be effective the next time the dht is started. │ │ │ │ -If you never touch this feature, a default map-memory based storage │ │ │ │ -is used.

│ │ │ │ -

If you want to make sure the dht is initially created with your │ │ │ │ -custom storage, create a session with the setting │ │ │ │ -settings_pack::enable_dht to false, set your constructor function │ │ │ │ -and call apply_settings with settings_pack::enable_dht to true.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

add_dht_node()

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

add_dht_node takes a host name and port pair. That endpoint will be │ │ │ │ -pinged, and if a valid DHT reply is received, the node will be added to │ │ │ │ -the routing table.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

dht_get_item()

│ │ │ │ -
│ │ │ │ -void dht_get_item (sha1_hash const& target);
│ │ │ │ -
│ │ │ │ -

query the DHT for an immutable item at the target hash. │ │ │ │ -the result is posted as a dht_immutable_item_alert.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

dht_get_item()

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

query the DHT for a mutable item under the public key key. │ │ │ │ -this is an ed25519 key. salt is optional and may be left │ │ │ │ -as an empty string if no salt is to be used. │ │ │ │ -if the item is found in the DHT, a dht_mutable_item_alert is │ │ │ │ -posted.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

dht_put_item()

│ │ │ │ -
│ │ │ │ -sha1_hash dht_put_item (entry data);
│ │ │ │ -
│ │ │ │ -

store the given bencoded data as an immutable item in the DHT. │ │ │ │ -the returned hash is the key that is to be used to look the item │ │ │ │ -up again. It's just the SHA-1 hash of the bencoded form of the │ │ │ │ -structure.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

dht_put_item()

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

store a mutable item. The key is the public key the blob is │ │ │ │ -to be stored under. The optional salt argument is a string that │ │ │ │ -is to be mixed in with the key when determining where in the DHT │ │ │ │ -the value is to be stored. The callback function is called from within │ │ │ │ -the libtorrent network thread once we've found where to store the blob, │ │ │ │ -possibly with the current value stored under the key. │ │ │ │ -The values passed to the callback functions are:

│ │ │ │ -
│ │ │ │ -
entry& value
│ │ │ │ -
the current value stored under the key (may be empty). Also expected │ │ │ │ -to be set to the value to be stored by the function.
│ │ │ │ -
std::array<char,64>& signature
│ │ │ │ -
the signature authenticating the current value. This may be zeros │ │ │ │ -if there is currently no value stored. The function is expected to │ │ │ │ -fill in this buffer with the signature of the new value to store. │ │ │ │ -To generate the signature, you may want to use the │ │ │ │ -sign_mutable_item function.
│ │ │ │ -
std::int64_t& seq
│ │ │ │ -
current sequence number. May be zero if there is no current value. │ │ │ │ -The function is expected to set this to the new sequence number of │ │ │ │ -the value that is to be stored. Sequence numbers must be monotonically │ │ │ │ -increasing. Attempting to overwrite a value with a lower or equal │ │ │ │ -sequence number will fail, even if the signature is correct.
│ │ │ │ -
std::string const& salt
│ │ │ │ -
this is the salt that was used for this put call.
│ │ │ │ -
│ │ │ │ -

Since the callback function cb is called from within libtorrent, │ │ │ │ -it is critical to not perform any blocking operations. Ideally not │ │ │ │ -even locking a mutex. Pass any data required for this function along │ │ │ │ -with the function object's context and make the function entirely │ │ │ │ -self-contained. The only reason data blob's value is computed │ │ │ │ -via a function instead of just passing in the new value is to avoid │ │ │ │ -race conditions. If you want to update the value in the DHT, you │ │ │ │ -must first retrieve it, then modify it, then write it back. The way │ │ │ │ -the DHT works, it is natural to always do a lookup before storing and │ │ │ │ -calling the callback in between is convenient.

│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

dht_get_peers() dht_announce()

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

dht_get_peers() will issue a DHT get_peer request to the DHT for the │ │ │ │ -specified info-hash. The response (the peers) will be posted back in a │ │ │ │ -dht_get_peers_reply_alert.

│ │ │ │ -

dht_announce() will issue a DHT announce request to the DHT to the │ │ │ │ -specified info-hash, advertising the specified port. If the port is │ │ │ │ -left at its default, 0, the port will be implied by the DHT message's │ │ │ │ -source port (which may improve connectivity through a NAT).

│ │ │ │ -

Both these functions are exposed for advanced custom use of the DHT. │ │ │ │ -All torrents eligible to be announce to the DHT will be automatically, │ │ │ │ -by libtorrent.

│ │ │ │ -

For possible flags, see announce_flags_t.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

dht_live_nodes()

│ │ │ │ -
│ │ │ │ -void dht_live_nodes (sha1_hash const& nid);
│ │ │ │ -
│ │ │ │ -

Retrieve all the live DHT (identified by nid) nodes. All the │ │ │ │ -nodes id and endpoint will be returned in the list of nodes in the │ │ │ │ -alert dht_live_nodes_alert. │ │ │ │ -Since this alert is a response to an explicit call, it will always be │ │ │ │ -posted, regardless of the alert mask.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

dht_sample_infohashes()

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

Query the DHT node specified by ep to retrieve a sample of the │ │ │ │ -info-hashes that the node currently have in their storage. │ │ │ │ -The target is included for iterative lookups so that indexing nodes │ │ │ │ -can perform a key space traversal with a single RPC per node by adjusting │ │ │ │ -the target value for each RPC. It has no effect on the returned sample value. │ │ │ │ -The result is posted as a dht_sample_infohashes_alert.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

dht_direct_request()

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

Send an arbitrary DHT request directly to the specified endpoint. This │ │ │ │ -function is intended for use by plugins. When a response is received │ │ │ │ -or the request times out, a dht_direct_response_alert will be posted │ │ │ │ -with the response (if any) and the userdata pointer passed in here. │ │ │ │ -Since this alert is a response to an explicit call, it will always be │ │ │ │ -posted, regardless of the alert mask.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

add_extension()

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

This function adds an extension to this session. The argument is a │ │ │ │ -function object that is called with a torrent_handle and which should │ │ │ │ -return a std::shared_ptr<torrent_plugin>. To write custom │ │ │ │ -plugins, see libtorrent plugins. For the typical bittorrent client │ │ │ │ -all of these extensions should be added. The main plugins implemented │ │ │ │ -in libtorrent are:

│ │ │ │ -
│ │ │ │ -
uTorrent metadata
│ │ │ │ -
Allows peers to download the metadata (.torrent files) from the swarm │ │ │ │ -directly. Makes it possible to join a swarm with just a tracker and │ │ │ │ -info-hash.
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -#include <libtorrent/extensions/ut_metadata.hpp>
│ │ │ │ -ses.add_extension(&lt::create_ut_metadata_plugin);
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
uTorrent peer exchange
│ │ │ │ -
Exchanges peers between clients.
│ │ │ │ +[report issue]
│ │ │ │ +
name
│ │ │ │ +
the name of the counter or gauge
│ │ │ │
│ │ │ │ -
│ │ │ │ -#include <libtorrent/extensions/ut_pex.hpp>
│ │ │ │ -ses.add_extension(&lt::create_ut_pex_plugin);
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
smart ban plugin
│ │ │ │ -
A plugin that, with a small overhead, can ban peers │ │ │ │ -that sends bad data with very high accuracy. Should │ │ │ │ -eliminate most problems on poisoned torrents.
│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
value_index type
│ │ │ │ +
the index into the session stats array, where the underlying value of │ │ │ │ +this counter or gauge is found. The session stats array is part of the │ │ │ │ +session_stats_alert object.
│ │ │ │
│ │ │ │ -
│ │ │ │ -#include <libtorrent/extensions/smart_ban.hpp>
│ │ │ │ -ses.add_extension(&lt::create_smart_ban_plugin);
│ │ │ │ -
│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

get_ip_filter() set_ip_filter()

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

Sets a filter that will be used to reject and accept incoming as well │ │ │ │ -as outgoing connections based on their originating ip address. The │ │ │ │ -default filter will allow connections to any ip address. To build a │ │ │ │ -set of rules for which addresses are accepted and not, see ip_filter.

│ │ │ │ -

Each time a peer is blocked because of the IP filter, a │ │ │ │ -peer_blocked_alert is generated. get_ip_filter() Returns the │ │ │ │ -ip_filter currently in the session. See ip_filter.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

set_port_filter()

│ │ │ │ -
│ │ │ │ -void set_port_filter (port_filter const& f);
│ │ │ │ -
│ │ │ │ -

apply port_filter f to incoming and outgoing peers. a port filter │ │ │ │ -will reject making outgoing peer connections to certain remote ports. │ │ │ │ -The main intention is to be able to avoid triggering certain │ │ │ │ -anti-virus software by connecting to SMTP, FTP ports.

│ │ │ │ - │ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

ssl_listen_port() listen_port() is_listening()

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

is_listening() will tell you whether or not the session has │ │ │ │ -successfully opened a listening port. If it hasn't, this function will │ │ │ │ -return false, and then you can set a new │ │ │ │ -settings_pack::listen_interfaces to try another interface and port to │ │ │ │ -bind to.

│ │ │ │ -

listen_port() returns the port we ended up listening on.

│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

set_peer_class_filter() get_peer_class_filter()

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

Sets the peer class filter for this session. All new peer connections │ │ │ │ -will take this into account and be added to the peer classes specified │ │ │ │ -by this filter, based on the peer's IP address.

│ │ │ │ -

The ip-filter essentially maps an IP -> uint32. Each bit in that 32 │ │ │ │ -bit integer represents a peer class. The least significant bit │ │ │ │ -represents class 0, the next bit class 1 and so on.

│ │ │ │ -

For more info, see ip_filter.

│ │ │ │ -

For example, to make all peers in the range 200.1.1.0 - 200.1.255.255 │ │ │ │ -belong to their own peer class, apply the following filter:

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

This setting only applies to new connections, it won't affect existing │ │ │ │ -peer connections.

│ │ │ │ -

This function is limited to only peer class 0-31, since there are only │ │ │ │ -32 bits in the IP range mapping. Only the set bits matter; no peer │ │ │ │ -class will be removed from a peer as a result of this call, peer │ │ │ │ -classes are only added.

│ │ │ │ -

The peer_class argument cannot be greater than 31. The bitmasks │ │ │ │ -representing peer classes in the peer_class_filter are 32 bits.

│ │ │ │ -

The get_peer_class_filter() function returns the current filter.

│ │ │ │ -

For more information, see peer classes.

│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

get_peer_class_type_filter() set_peer_class_type_filter()

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

Sets and gets the peer class type filter. This is controls automatic │ │ │ │ -peer class assignments to peers based on what kind of socket it is.

│ │ │ │ -

It does not only support assigning peer classes, it also supports │ │ │ │ -removing peer classes based on socket type.

│ │ │ │ -

The order of these rules being applied are:

│ │ │ │ -
    │ │ │ │ -
  1. peer-class IP filter
    2. │ │ │ │ -
  2. peer-class type filter, removing classes
    3. │ │ │ │ -
  3. peer-class type filter, adding classes
    4. │ │ │ │ -
│ │ │ │ -

For more information, see peer classes.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

create_peer_class()

│ │ │ │ -
│ │ │ │ -peer_class_t create_peer_class (char const* name);
│ │ │ │ -
│ │ │ │ -

Creates a new peer class (see peer classes) with the given name. The │ │ │ │ -returned integer is the new peer class identifier. Peer classes may │ │ │ │ -have the same name, so each invocation of this function creates a new │ │ │ │ -class and returns a unique identifier.

│ │ │ │ -

Identifiers are assigned from low numbers to higher. So if you plan on │ │ │ │ -using certain peer classes in a call to set_peer_class_filter(), │ │ │ │ -make sure to create those early on, to get low identifiers.

│ │ │ │ -

For more information on peer classes, see peer classes.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

delete_peer_class()

│ │ │ │ -
│ │ │ │ -void delete_peer_class (peer_class_t cid);
│ │ │ │ -
│ │ │ │ -

This call dereferences the reference count of the specified peer │ │ │ │ -class. When creating a peer class it's automatically referenced by 1. │ │ │ │ -If you want to recycle a peer class, you may call this function. You │ │ │ │ -may only call this function once per peer class you create. │ │ │ │ -Calling it more than once for the same class will lead to memory │ │ │ │ -corruption.

│ │ │ │ -

Since peer classes are reference counted, this function will not │ │ │ │ -remove the peer class if it's still assigned to torrents or peers. It │ │ │ │ -will however remove it once the last peer and torrent drops their │ │ │ │ -references to it.

│ │ │ │ -

There is no need to call this function for custom peer classes. All │ │ │ │ -peer classes will be properly destructed when the session object │ │ │ │ -destructs.

│ │ │ │ -

For more information on peer classes, see peer classes.

│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

set_peer_class() get_peer_class()

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

These functions queries information from a peer class and updates the │ │ │ │ -configuration of a peer class, respectively.

│ │ │ │ -

cid must refer to an existing peer class. If it does not, the │ │ │ │ -return value of get_peer_class() is undefined.

│ │ │ │ -

set_peer_class() sets all the information in the │ │ │ │ -peer_class_info object in the specified peer class. There is no │ │ │ │ -option to only update a single property.

│ │ │ │ -

A peer or torrent belonging to more than one class, the highest │ │ │ │ -priority among any of its classes is the one that is taken into │ │ │ │ -account.

│ │ │ │ -

For more information, see peer classes.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

remove_torrent()

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

remove_torrent() will close all peer connections associated with │ │ │ │ -the torrent and tell the tracker that we've stopped participating in │ │ │ │ -the swarm. This operation cannot fail. When it completes, you will │ │ │ │ -receive a torrent_removed_alert.

│ │ │ │ -

remove_torrent() is non-blocking, but will remove the torrent from the │ │ │ │ -session synchronously. Calling session_handle::add_torrent() immediately │ │ │ │ -afterward with the same torrent will succeed. Note that this creates a │ │ │ │ -new handle which is not equal to the removed one.

│ │ │ │ -

The optional second argument options can be used to delete all the │ │ │ │ -files downloaded by this torrent. To do so, pass in the value │ │ │ │ -session_handle::delete_files. Once the torrent is deleted, a │ │ │ │ -torrent_deleted_alert is posted.

│ │ │ │ -

The torrent_handle remains valid for some time after remove_torrent() is │ │ │ │ -called. It will become invalid only after all libtorrent tasks (such as │ │ │ │ -I/O tasks) release their references to the torrent. Until this happens, │ │ │ │ -torrent_handle::is_valid() will return true, and other calls such │ │ │ │ -as torrent_handle::status() will succeed. Because of this, and because │ │ │ │ -remove_torrent() is non-blocking, the following sequence usually │ │ │ │ -succeeds (does not throw system_error): │ │ │ │ -.. code:: c++

│ │ │ │ -
│ │ │ │ -session.remove_handle(handle); │ │ │ │ -handle.save_resume_data();
│ │ │ │ -

Note that when a queued or downloading torrent is removed, its position │ │ │ │ -in the download queue is vacated and every subsequent torrent in the │ │ │ │ -queue has their queue positions updated. This can potentially cause a │ │ │ │ -large state_update to be posted. When removing all torrents, it is │ │ │ │ -advised to remove them from the back of the queue, to minimize the │ │ │ │ -shifting.

│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

apply_settings() get_settings()

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

Applies the settings specified by the settings_pack s. This is an │ │ │ │ -asynchronous operation that will return immediately and actually apply │ │ │ │ -the settings to the main thread of libtorrent some time later.

│ │ │ │ - │ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

set_alert_notify() pop_alerts() wait_for_alert()

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

Alerts is the main mechanism for libtorrent to report errors and │ │ │ │ -events. pop_alerts fills in the vector passed to it with pointers │ │ │ │ -to new alerts. The session still owns these alerts and they will stay │ │ │ │ -valid until the next time pop_alerts is called. You may not delete │ │ │ │ -the alert objects.

│ │ │ │ -

It is safe to call pop_alerts from multiple different threads, as │ │ │ │ -long as the alerts themselves are not accessed once another thread │ │ │ │ -calls pop_alerts. Doing this requires manual synchronization │ │ │ │ -between the popping threads.

│ │ │ │ -

wait_for_alert will block the current thread for max_wait time │ │ │ │ -duration, or until another alert is posted. If an alert is available │ │ │ │ -at the time of the call, it returns immediately. The returned alert │ │ │ │ -pointer is the head of the alert queue. wait_for_alert does not │ │ │ │ -pop alerts from the queue, it merely peeks at it. The returned alert │ │ │ │ -will stay valid until pop_alerts is called twice. The first time │ │ │ │ -will pop it and the second will free it.

│ │ │ │ -

If there is no alert in the queue and no alert arrives within the │ │ │ │ -specified timeout, wait_for_alert returns nullptr.

│ │ │ │ -

In the python binding, wait_for_alert takes the number of │ │ │ │ -milliseconds to wait as an integer.

│ │ │ │ -

The alert queue in the session will not grow indefinitely. Make sure │ │ │ │ -to pop periodically to not miss notifications. To control the max │ │ │ │ -number of alerts that's queued by the session, see │ │ │ │ -settings_pack::alert_queue_size.

│ │ │ │ -

Some alerts are considered so important that they are posted even when │ │ │ │ -the alert queue is full. Some alerts are considered mandatory and cannot │ │ │ │ -be disabled by the alert_mask. For instance, │ │ │ │ -save_resume_data_alert and save_resume_data_failed_alert are always │ │ │ │ -posted, regardless of the alert mask.

│ │ │ │ -

To control which alerts are posted, set the alert_mask │ │ │ │ -(settings_pack::alert_mask).

│ │ │ │ -

If the alert queue fills up to the point where alerts are dropped, this │ │ │ │ -will be indicated by a alerts_dropped_alert, which contains a bitmask │ │ │ │ -of which types of alerts were dropped. Generally it is a good idea to │ │ │ │ -make sure the alert queue is large enough, the alert_mask doesn't have │ │ │ │ -unnecessary categories enabled and to call pop_alert() frequently, to │ │ │ │ -avoid alerts being dropped.

│ │ │ │ -

the set_alert_notify function lets the client set a function object │ │ │ │ -to be invoked every time the alert queue goes from having 0 alerts to │ │ │ │ -1 alert. This function is called from within libtorrent, it may be the │ │ │ │ -main thread, or it may be from within a user call. The intention of │ │ │ │ -of the function is that the client wakes up its main thread, to poll │ │ │ │ -for more alerts using pop_alerts(). If the notify function fails │ │ │ │ -to do so, it won't be called again, until pop_alerts is called for │ │ │ │ -some other reason. For instance, it could signal an eventfd, post a │ │ │ │ -message to an HWND or some other main message pump. The actual │ │ │ │ -retrieval of alerts should not be done in the callback. In fact, the │ │ │ │ -callback should not block. It should not perform any expensive work. │ │ │ │ -It really should just notify the main application thread.

│ │ │ │ -

The type of an alert is returned by the polymorphic function │ │ │ │ -alert::type() but can also be queries from a concrete type via │ │ │ │ -T::alert_type, as a static constant.

│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

delete_port_mapping() add_port_mapping()

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

add_port_mapping adds one or more port forwards on UPnP and/or NAT-PMP, │ │ │ │ -whichever is enabled. A mapping is created for each listen socket │ │ │ │ -in the session. The return values are all handles referring to the │ │ │ │ -port mappings that were just created. Pass them to delete_port_mapping() │ │ │ │ -to remove them.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

reopen_network_sockets()

│ │ │ │ -
│ │ │ │ -void reopen_network_sockets (reopen_network_flags_t options = reopen_map_ports);
│ │ │ │ -
│ │ │ │ -

Instructs the session to reopen all listen and outgoing sockets.

│ │ │ │ -

It's useful in the case your platform doesn't support the built in │ │ │ │ -IP notifier mechanism, or if you have a better more reliable way to │ │ │ │ -detect changes in the IP routing table.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

native_handle()

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

session_stats_metrics()

│ │ │ │ +

Declared in "libtorrent/session_stats.hpp"

│ │ │ │ 
│ │ │ │ -std::shared_ptr<aux::session_impl> native_handle () const;
│ │ │ │ +std::vector<stats_metric> session_stats_metrics ();
│ │ │ │
│ │ │ │ -

This function is intended only for use by plugins. This type does │ │ │ │ -not have a stable API and should be relied on as little as possible.

│ │ │ │ -[report issue]
│ │ │ │ -
save_settings
│ │ │ │ -
saves settings (i.e. the settings_pack)
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
save_dht_state
│ │ │ │ -
saves dht state such as nodes and node-id, possibly accelerating │ │ │ │ -joining the DHT if provided at next session startup.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
save_extension_state
│ │ │ │ -
load or save state from plugins
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
save_ip_filter
│ │ │ │ -
load or save the IP filter set on the session
│ │ │ │ -
│ │ │ │ - │ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
global_peer_class_id tcp_peer_class_id local_peer_class_id
│ │ │ │ -
built-in peer classes
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
delete_files
│ │ │ │ -
delete the files belonging to the torrent from disk. │ │ │ │ -including the part-file, if there is one
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
delete_partfile
│ │ │ │ -
delete just the part-file associated with this torrent
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
paused
│ │ │ │ -
when set, the session will start paused. Call │ │ │ │ -session_handle::resume() to start
│ │ │ │ -
│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
udp tcp
│ │ │ │ -
protocols used by add_port_mapping()
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
reopen_map_ports
│ │ │ │ -
This option indicates if the ports are mapped using natpmp │ │ │ │ -and upnp. If mapping was already made, they are deleted and added │ │ │ │ -again. This only works if natpmp and/or upnp are configured to be │ │ │ │ -enable.
│ │ │ │ -
│ │ │ │ - │ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -

write_session_params_buf() write_session_params() read_session_params()

│ │ │ │ -

Declared in "libtorrent/session_params.hpp"

│ │ │ │ +

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

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

find_metric_idx()

│ │ │ │ +

Declared in "libtorrent/session_stats.hpp"

│ │ │ │ 
│ │ │ │ -session_params read_session_params (bdecode_node const& e
│ │ │ │ -   , save_state_flags_t flags = save_state_flags_t::all());
│ │ │ │ -session_params read_session_params (span<char const> buf
│ │ │ │ -   , save_state_flags_t flags = save_state_flags_t::all());
│ │ │ │ -entry write_session_params (session_params const& sp
│ │ │ │ -   , save_state_flags_t flags = save_state_flags_t::all());
│ │ │ │ -std::vector<char> write_session_params_buf (session_params const& sp
│ │ │ │ -   , save_state_flags_t flags = save_state_flags_t::all());
│ │ │ │ +int find_metric_idx (string_view name);
│ │ │ │
│ │ │ │ -

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

│ │ │ │ +

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

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

enum metric_type_t

│ │ │ │ +

Declared in "libtorrent/session_stats.hpp"

│ │ │ │ + │ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ +
namevaluedescription
counter0 
gauge1 
│ │ │ │

The pop_alerts() function on session is the main interface for retrieving │ │ │ │ alerts (warnings, messages and errors from libtorrent). If no alerts have │ │ │ │ been posted by libtorrent pop_alerts() will return an empty list.

│ │ │ │

By default, only errors are reported. settings_pack::alert_mask can be │ │ │ │ used to specify which kinds of events should be reported. The alert mask is │ │ │ │ a combination of the alert_category_t flags in the alert class.

│ │ │ │

Every alert belongs to one or more category. There is a cost associated with │ │ │ │ @@ -12392,124 +11593,15 @@ │ │ │ │

There are other alert base classes that some alerts derive from, all the │ │ │ │ alerts that are generated for a specific torrent are derived from │ │ │ │ torrent_alert, and tracker events derive from tracker_alert.

│ │ │ │

Alerts returned by pop_alerts() are only valid until the next call to │ │ │ │ pop_alerts(). You may not copy an alert object to access it after the next │ │ │ │ call to pop_alerts(). Internal members of alerts also become invalid once │ │ │ │ pop_alerts() is called again.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

alert

│ │ │ │ -

Declared in "libtorrent/alert.hpp"

│ │ │ │ -

The alert class is the base class that specific messages are derived from. │ │ │ │ -alert types are not copyable, and cannot be constructed by the client. The │ │ │ │ -pointers returned by libtorrent are short lived (the details are described │ │ │ │ -under session_handle::pop_alerts())

│ │ │ │ -
│ │ │ │ -struct alert
│ │ │ │ -{
│ │ │ │ -   time_point timestamp () const;
│ │ │ │ -   virtual int type () const noexcept = 0;
│ │ │ │ -   virtual char const* what () const noexcept = 0;
│ │ │ │ -   virtual std::string message () const = 0;
│ │ │ │ -   virtual alert_category_t category () const noexcept = 0;
│ │ │ │ -
│ │ │ │ -   static constexpr alert_category_t error_notification  = 0_bit;
│ │ │ │ -   static constexpr alert_category_t peer_notification  = 1_bit;
│ │ │ │ -   static constexpr alert_category_t port_mapping_notification  = 2_bit;
│ │ │ │ -   static constexpr alert_category_t storage_notification  = 3_bit;
│ │ │ │ -   static constexpr alert_category_t tracker_notification  = 4_bit;
│ │ │ │ -   static constexpr alert_category_t connect_notification  = 5_bit;
│ │ │ │ -   static constexpr alert_category_t status_notification  = 6_bit;
│ │ │ │ -   static constexpr alert_category_t ip_block_notification  = 8_bit;
│ │ │ │ -   static constexpr alert_category_t performance_warning  = 9_bit;
│ │ │ │ -   static constexpr alert_category_t dht_notification  = 10_bit;
│ │ │ │ -   static constexpr alert_category_t session_log_notification  = 13_bit;
│ │ │ │ -   static constexpr alert_category_t torrent_log_notification  = 14_bit;
│ │ │ │ -   static constexpr alert_category_t peer_log_notification  = 15_bit;
│ │ │ │ -   static constexpr alert_category_t incoming_request_notification  = 16_bit;
│ │ │ │ -   static constexpr alert_category_t dht_log_notification  = 17_bit;
│ │ │ │ -   static constexpr alert_category_t dht_operation_notification  = 18_bit;
│ │ │ │ -   static constexpr alert_category_t port_mapping_log_notification  = 19_bit;
│ │ │ │ -   static constexpr alert_category_t picker_log_notification  = 20_bit;
│ │ │ │ -   static constexpr alert_category_t file_progress_notification  = 21_bit;
│ │ │ │ -   static constexpr alert_category_t piece_progress_notification  = 22_bit;
│ │ │ │ -   static constexpr alert_category_t upload_notification  = 23_bit;
│ │ │ │ -   static constexpr alert_category_t block_progress_notification  = 24_bit;
│ │ │ │ -   static constexpr alert_category_t all_categories  = alert_category_t::all();
│ │ │ │ -};
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -

timestamp()

│ │ │ │ -
│ │ │ │ -time_point timestamp () const;
│ │ │ │ -
│ │ │ │ -

a timestamp is automatically created in the constructor

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

type()

│ │ │ │ -
│ │ │ │ -virtual int type () const noexcept = 0;
│ │ │ │ -
│ │ │ │ -

returns an integer that is unique to this alert type. It can be │ │ │ │ -compared against a specific alert by querying a static constant called alert_type │ │ │ │ -in the alert. It can be used to determine the run-time type of an alert* in │ │ │ │ -order to cast to that alert type and access specific members.

│ │ │ │ -

e.g:

│ │ │ │ -
│ │ │ │ -std::vector<alert*> alerts;
│ │ │ │ -ses.pop_alerts(&alerts);
│ │ │ │ -for (alert* a : alerts) {
│ │ │ │ -        switch (a->type()) {
│ │ │ │ -
│ │ │ │ -                case read_piece_alert::alert_type:
│ │ │ │ -                {
│ │ │ │ -                        auto* p = static_cast<read_piece_alert*>(a);
│ │ │ │ -                        if (p->ec) {
│ │ │ │ -                                // read_piece failed
│ │ │ │ -                                break;
│ │ │ │ -                        }
│ │ │ │ -                        // use p
│ │ │ │ -                        break;
│ │ │ │ -                }
│ │ │ │ -                case file_renamed_alert::alert_type:
│ │ │ │ -                {
│ │ │ │ -                        // etc...
│ │ │ │ -                }
│ │ │ │ -        }
│ │ │ │ -}
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

what()

│ │ │ │ -
│ │ │ │ -virtual char const* what () const noexcept = 0;
│ │ │ │ -
│ │ │ │ -

returns a string literal describing the type of the alert. It does │ │ │ │ -not include any information that might be bundled with the alert.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

message()

│ │ │ │ -
│ │ │ │ -virtual std::string message () const = 0;
│ │ │ │ -
│ │ │ │ -

generate a string describing the alert and the information bundled │ │ │ │ -with it. This is mainly intended for debug and development use. It is not suitable │ │ │ │ -to use this for applications that may be localized. Instead, handle each alert │ │ │ │ -type individually and extract and render the information from the alert depending │ │ │ │ -on the locale.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

category()

│ │ │ │ -
│ │ │ │ -virtual alert_category_t category () const noexcept = 0;
│ │ │ │ -
│ │ │ │ -

returns a bitmask specifying which categories this alert belong to.

│ │ │ │ [report issue]
│ │ │ │ -
│ │ │ │
│ │ │ │

dht_routing_bucket

│ │ │ │

Declared in "libtorrent/alert_types.hpp"

│ │ │ │

struct to hold information about a single DHT routing table bucket

│ │ │ │ 
│ │ │ │  struct dht_routing_bucket
│ │ │ │  {
│ │ │ │ @@ -12541,15 +11633,15 @@
│ │ │ │  {
│ │ │ │     std::string message () const override;
│ │ │ │     char const* torrent_name () const;
│ │ │ │  
│ │ │ │     torrent_handle handle;
│ │ │ │  };
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ +[report issue]
│ │ │ │

message()

│ │ │ │ 
│ │ │ │  std::string message () const override;
│ │ │ │
│ │ │ │

returns the message associated with this alert

│ │ │ │ [report issue]
│ │ │ │
handle
│ │ │ │ @@ -12691,27 +11783,27 @@ │ │ │ │

Declared in "libtorrent/alert_types.hpp"

│ │ │ │

This is posted as a response to a torrent_handle::rename_file() call, if the rename │ │ │ │ operation succeeds.

│ │ │ │ 
│ │ │ │  struct file_renamed_alert final : torrent_alert
│ │ │ │  {
│ │ │ │     std::string message () const override;
│ │ │ │ -   char const* old_name () const;
│ │ │ │     char const* new_name () const;
│ │ │ │ +   char const* old_name () const;
│ │ │ │  
│ │ │ │     static constexpr alert_category_t static_category  = alert_category::storage;
│ │ │ │     file_index_t const index;
│ │ │ │  };
│ │ │ │
│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -

new_name() old_name()

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +

old_name() new_name()

│ │ │ │ 
│ │ │ │ -char const* old_name () const;
│ │ │ │  char const* new_name () const;
│ │ │ │ +char const* old_name () const;
│ │ │ │
│ │ │ │

returns the new and previous file name, respectively.

│ │ │ │ [report issue]
│ │ │ │
index
│ │ │ │
refers to the index of the file that was renamed,
│ │ │ │
│ │ │ │ [report issue]
│ │ │ │ @@ -15091,27 +14183,27 @@ │ │ │ │

posted in response to a call to session::dht_live_nodes(). It contains the │ │ │ │ live nodes from the DHT routing table of one of the DHT nodes running │ │ │ │ locally.

│ │ │ │ 
│ │ │ │  struct dht_live_nodes_alert final : alert
│ │ │ │  {
│ │ │ │     std::string message () const override;
│ │ │ │ -   std::vector<std::pair<sha1_hash, udp::endpoint>> nodes () const;
│ │ │ │     int num_nodes () const;
│ │ │ │ +   std::vector<std::pair<sha1_hash, udp::endpoint>> nodes () const;
│ │ │ │  
│ │ │ │     static constexpr alert_category_t static_category  = alert_category::dht;
│ │ │ │     sha1_hash node_id;
│ │ │ │  };
│ │ │ │
│ │ │ │ │ │ │ │ [report issue]
│ │ │ │

num_nodes() nodes()

│ │ │ │ 
│ │ │ │ -std::vector<std::pair<sha1_hash, udp::endpoint>> nodes () const;
│ │ │ │  int num_nodes () const;
│ │ │ │ +std::vector<std::pair<sha1_hash, udp::endpoint>> nodes () const;
│ │ │ │
│ │ │ │

the number of nodes in the routing table and the actual nodes.

│ │ │ │ [report issue]
│ │ │ │
node_id
│ │ │ │
the local DHT node's node-ID this routing table belongs to
│ │ │ │
│ │ │ │ [report issue]
│ │ │ │ @@ -15152,17 +14244,17 @@ │ │ │ │ static constexpr alert_category_t static_category = alert_category::dht_operation; │ │ │ │ sha1_hash node_id; │ │ │ │ aux::noexcept_movable<udp::endpoint> endpoint; │ │ │ │ time_duration const interval; │ │ │ │ int const num_infohashes; │ │ │ │ }; │ │ │ │ │ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -

num_samples() samples()

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +

samples() num_samples()

│ │ │ │ 
│ │ │ │  int num_samples () const;
│ │ │ │  std::vector<sha1_hash> samples () const;
│ │ │ │
│ │ │ │

returns the number of info-hashes returned by the node, as well as the │ │ │ │ actual info-hashes. num_samples() is more efficient than │ │ │ │ samples().size().

│ │ │ │ @@ -15226,16 +14318,16 @@ │ │ │ │

this alert is posted to indicate to the client that some alerts were │ │ │ │ dropped. Dropped meaning that the alert failed to be delivered to the │ │ │ │ client. The most common cause of such failure is that the internal alert │ │ │ │ queue grew too big (controlled by alert_queue_size).

│ │ │ │ 
│ │ │ │  struct alerts_dropped_alert final : alert
│ │ │ │  {
│ │ │ │ -   static_assert (num_alert_types <= abi_alert_count, "need to increase bitset. This is an ABI break");
│ │ │ │     std::string message () const override;
│ │ │ │ +   static_assert (num_alert_types <= abi_alert_count, "need to increase bitset. This is an ABI break");
│ │ │ │  
│ │ │ │     static constexpr alert_category_t static_category  = alert_category::error;
│ │ │ │     std::bitset<abi_alert_count> dropped_alerts;
│ │ │ │  };
│ │ │ │
│ │ │ │ [report issue]
│ │ │ │
dropped_alerts
│ │ │ │ @@ -15346,30 +14438,139 @@ │ │ │ │
│ │ │ │ [report issue]
│ │ │ │
metadata
│ │ │ │
the metadata that was received by one of the torrents in conflict. │ │ │ │ One way to resolve the conflict is to remove both failing torrents │ │ │ │ and re-add it using this metadata
│ │ │ │
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

alert

│ │ │ │ +

Declared in "libtorrent/alert.hpp"

│ │ │ │ +

The alert class is the base class that specific messages are derived from. │ │ │ │ +alert types are not copyable, and cannot be constructed by the client. The │ │ │ │ +pointers returned by libtorrent are short lived (the details are described │ │ │ │ +under session_handle::pop_alerts())

│ │ │ │ +
│ │ │ │ +struct alert
│ │ │ │ +{
│ │ │ │ +   time_point timestamp () const;
│ │ │ │ +   virtual int type () const noexcept = 0;
│ │ │ │ +   virtual char const* what () const noexcept = 0;
│ │ │ │ +   virtual std::string message () const = 0;
│ │ │ │ +   virtual alert_category_t category () const noexcept = 0;
│ │ │ │ +
│ │ │ │ +   static constexpr alert_category_t error_notification  = 0_bit;
│ │ │ │ +   static constexpr alert_category_t peer_notification  = 1_bit;
│ │ │ │ +   static constexpr alert_category_t port_mapping_notification  = 2_bit;
│ │ │ │ +   static constexpr alert_category_t storage_notification  = 3_bit;
│ │ │ │ +   static constexpr alert_category_t tracker_notification  = 4_bit;
│ │ │ │ +   static constexpr alert_category_t connect_notification  = 5_bit;
│ │ │ │ +   static constexpr alert_category_t status_notification  = 6_bit;
│ │ │ │ +   static constexpr alert_category_t ip_block_notification  = 8_bit;
│ │ │ │ +   static constexpr alert_category_t performance_warning  = 9_bit;
│ │ │ │ +   static constexpr alert_category_t dht_notification  = 10_bit;
│ │ │ │ +   static constexpr alert_category_t session_log_notification  = 13_bit;
│ │ │ │ +   static constexpr alert_category_t torrent_log_notification  = 14_bit;
│ │ │ │ +   static constexpr alert_category_t peer_log_notification  = 15_bit;
│ │ │ │ +   static constexpr alert_category_t incoming_request_notification  = 16_bit;
│ │ │ │ +   static constexpr alert_category_t dht_log_notification  = 17_bit;
│ │ │ │ +   static constexpr alert_category_t dht_operation_notification  = 18_bit;
│ │ │ │ +   static constexpr alert_category_t port_mapping_log_notification  = 19_bit;
│ │ │ │ +   static constexpr alert_category_t picker_log_notification  = 20_bit;
│ │ │ │ +   static constexpr alert_category_t file_progress_notification  = 21_bit;
│ │ │ │ +   static constexpr alert_category_t piece_progress_notification  = 22_bit;
│ │ │ │ +   static constexpr alert_category_t upload_notification  = 23_bit;
│ │ │ │ +   static constexpr alert_category_t block_progress_notification  = 24_bit;
│ │ │ │ +   static constexpr alert_category_t all_categories  = alert_category_t::all();
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +

timestamp()

│ │ │ │ +
│ │ │ │ +time_point timestamp () const;
│ │ │ │ +
│ │ │ │ +

a timestamp is automatically created in the constructor

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

type()

│ │ │ │ +
│ │ │ │ +virtual int type () const noexcept = 0;
│ │ │ │ +
│ │ │ │ +

returns an integer that is unique to this alert type. It can be │ │ │ │ +compared against a specific alert by querying a static constant called alert_type │ │ │ │ +in the alert. It can be used to determine the run-time type of an alert* in │ │ │ │ +order to cast to that alert type and access specific members.

│ │ │ │ +

e.g:

│ │ │ │ +
│ │ │ │ +std::vector<alert*> alerts;
│ │ │ │ +ses.pop_alerts(&alerts);
│ │ │ │ +for (alert* a : alerts) {
│ │ │ │ +        switch (a->type()) {
│ │ │ │ +
│ │ │ │ +                case read_piece_alert::alert_type:
│ │ │ │ +                {
│ │ │ │ +                        auto* p = static_cast<read_piece_alert*>(a);
│ │ │ │ +                        if (p->ec) {
│ │ │ │ +                                // read_piece failed
│ │ │ │ +                                break;
│ │ │ │ +                        }
│ │ │ │ +                        // use p
│ │ │ │ +                        break;
│ │ │ │ +                }
│ │ │ │ +                case file_renamed_alert::alert_type:
│ │ │ │ +                {
│ │ │ │ +                        // etc...
│ │ │ │ +                }
│ │ │ │ +        }
│ │ │ │ +}
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

what()

│ │ │ │ +
│ │ │ │ +virtual char const* what () const noexcept = 0;
│ │ │ │ +
│ │ │ │ +

returns a string literal describing the type of the alert. It does │ │ │ │ +not include any information that might be bundled with the alert.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

message()

│ │ │ │ +
│ │ │ │ +virtual std::string message () const = 0;
│ │ │ │ +
│ │ │ │ +

generate a string describing the alert and the information bundled │ │ │ │ +with it. This is mainly intended for debug and development use. It is not suitable │ │ │ │ +to use this for applications that may be localized. Instead, handle each alert │ │ │ │ +type individually and extract and render the information from the alert depending │ │ │ │ +on the locale.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

category()

│ │ │ │ +
│ │ │ │ +virtual alert_category_t category () const noexcept = 0;
│ │ │ │ +
│ │ │ │ +

returns a bitmask specifying which categories this alert belong to.

│ │ │ │ [report issue]
│ │ │ │ +
│ │ │ │
│ │ │ │

operation_name()

│ │ │ │

Declared in "libtorrent/operations.hpp"

│ │ │ │ 
│ │ │ │  char const* operation_name (operation_t op);
│ │ │ │
│ │ │ │

maps an operation id (from peer_error_alert and peer_disconnected_alert) │ │ │ │ to its name. See operation_t for the constants

│ │ │ │ [report issue]
│ │ │ │
│ │ │ │

alert_cast()

│ │ │ │

Declared in "libtorrent/alert.hpp"

│ │ │ │ 
│ │ │ │ -template <typename T> T const* alert_cast (alert const* a);
│ │ │ │  template <typename T> T* alert_cast (alert* a);
│ │ │ │ +template <typename T> T const* alert_cast (alert const* a);
│ │ │ │
│ │ │ │

When you get an alert, you can use alert_cast<> to attempt to cast the │ │ │ │ pointer to a specific alert type, in order to query it for more │ │ │ │ information.

│ │ │ │
│ │ │ │

Note

│ │ │ │

alert_cast<> can only cast to an exact alert type, not a base class

│ │ │ │ @@ -15582,14 +14783,26 @@ │ │ │ │ │ │ │ │ file_truncate │ │ │ │ 46 │ │ │ │ call to ftruncate() (or SetEndOfFile() on windows) │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

int

│ │ │ │ +

Declared in "libtorrent/alert_types.hpp"

│ │ │ │ +
│ │ │ │ +
user_alert_id
│ │ │ │ +
user defined alerts should use IDs greater than this
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
num_alert_types
│ │ │ │ +
this constant represents "max_alert_index" + 1
│ │ │ │ +
│ │ │ │ [report issue]
│ │ │ │
│ │ │ │

alert_category_t

│ │ │ │

Declared in "libtorrent/alert.hpp"

│ │ │ │
│ │ │ │
error
│ │ │ │

Enables alerts that report an error. This includes:

│ │ │ │ @@ -15717,1409 +14930,3483 @@ │ │ │ │

The full bitmask, representing all available categories.

│ │ │ │

since the enum is signed, make sure this isn't │ │ │ │ interpreted as -1. For instance, boost.python │ │ │ │ does that and fails when assigning it to an │ │ │ │ unsigned parameter.

│ │ │ │
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

int

│ │ │ │ -

Declared in "libtorrent/alert_types.hpp"

│ │ │ │ -
│ │ │ │ -
user_alert_id
│ │ │ │ -
user defined alerts should use IDs greater than this
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

torrent_status

│ │ │ │ +

Declared in "libtorrent/torrent_status.hpp"

│ │ │ │ +

holds a snapshot of the status of a torrent, as queried by │ │ │ │ +torrent_handle::status().

│ │ │ │ +
│ │ │ │ +struct torrent_status
│ │ │ │ +{
│ │ │ │ +   bool operator== (torrent_status const& st) const;
│ │ │ │ +
│ │ │ │ +   enum state_t
│ │ │ │ +   {
│ │ │ │ +      checking_files,
│ │ │ │ +      downloading_metadata,
│ │ │ │ +      downloading,
│ │ │ │ +      finished,
│ │ │ │ +      seeding,
│ │ │ │ +      unused_enum_for_backwards_compatibility_allocating,
│ │ │ │ +      checking_resume_data,
│ │ │ │ +   };
│ │ │ │ +
│ │ │ │ +   torrent_handle handle;
│ │ │ │ +   error_code errc;
│ │ │ │ +   file_index_t error_file  = torrent_status::error_file_none;
│ │ │ │ +   static constexpr file_index_t error_file_none {-1};
│ │ │ │ +   static constexpr file_index_t error_file_ssl_ctx {-3};
│ │ │ │ +   static constexpr file_index_t error_file_metadata {-4};
│ │ │ │ +   static constexpr file_index_t error_file_exception {-5};
│ │ │ │ +   static constexpr file_index_t error_file_partfile {-6};
│ │ │ │ +   std::string save_path;
│ │ │ │ +   std::string name;
│ │ │ │ +   std::weak_ptr<const torrent_info> torrent_file;
│ │ │ │ +   time_duration next_announce  = seconds{0};
│ │ │ │ +   std::string current_tracker;
│ │ │ │ +   std::int64_t total_download  = 0;
│ │ │ │ +   std::int64_t total_upload  = 0;
│ │ │ │ +   std::int64_t total_payload_download  = 0;
│ │ │ │ +   std::int64_t total_payload_upload  = 0;
│ │ │ │ +   std::int64_t total_failed_bytes  = 0;
│ │ │ │ +   std::int64_t total_redundant_bytes  = 0;
│ │ │ │ +   typed_bitfield<piece_index_t> pieces;
│ │ │ │ +   typed_bitfield<piece_index_t> verified_pieces;
│ │ │ │ +   std::int64_t total_done  = 0;
│ │ │ │ +   std::int64_t total  = 0;
│ │ │ │ +   std::int64_t total_wanted_done  = 0;
│ │ │ │ +   std::int64_t total_wanted  = 0;
│ │ │ │ +   std::int64_t all_time_upload  = 0;
│ │ │ │ +   std::int64_t all_time_download  = 0;
│ │ │ │ +   std::time_t added_time  = 0;
│ │ │ │ +   std::time_t completed_time  = 0;
│ │ │ │ +   std::time_t last_seen_complete  = 0;
│ │ │ │ +   storage_mode_t storage_mode  = storage_mode_sparse;
│ │ │ │ +   float progress  = 0.f;
│ │ │ │ +   int progress_ppm  = 0;
│ │ │ │ +   queue_position_t queue_position {};
│ │ │ │ +   int download_rate  = 0;
│ │ │ │ +   int upload_rate  = 0;
│ │ │ │ +   int download_payload_rate  = 0;
│ │ │ │ +   int upload_payload_rate  = 0;
│ │ │ │ +   int num_seeds  = 0;
│ │ │ │ +   int num_peers  = 0;
│ │ │ │ +   int num_complete  = -1;
│ │ │ │ +   int num_incomplete  = -1;
│ │ │ │ +   int list_seeds  = 0;
│ │ │ │ +   int list_peers  = 0;
│ │ │ │ +   int connect_candidates  = 0;
│ │ │ │ +   int num_pieces  = 0;
│ │ │ │ +   int distributed_full_copies  = 0;
│ │ │ │ +   int distributed_fraction  = 0;
│ │ │ │ +   float distributed_copies  = 0.f;
│ │ │ │ +   int block_size  = 0;
│ │ │ │ +   int num_uploads  = 0;
│ │ │ │ +   int num_connections  = 0;
│ │ │ │ +   int uploads_limit  = 0;
│ │ │ │ +   int connections_limit  = 0;
│ │ │ │ +   int up_bandwidth_queue  = 0;
│ │ │ │ +   int down_bandwidth_queue  = 0;
│ │ │ │ +   int seed_rank  = 0;
│ │ │ │ +   state_t state  = checking_resume_data;
│ │ │ │ +   bool need_save_resume  = false;
│ │ │ │ +   bool is_seeding  = false;
│ │ │ │ +   bool is_finished  = false;
│ │ │ │ +   bool has_metadata  = false;
│ │ │ │ +   bool has_incoming  = false;
│ │ │ │ +   bool moving_storage  = false;
│ │ │ │ +   bool announcing_to_trackers  = false;
│ │ │ │ +   bool announcing_to_lsd  = false;
│ │ │ │ +   bool announcing_to_dht  = false;
│ │ │ │ +   info_hash_t info_hashes;
│ │ │ │ +   time_point last_upload;
│ │ │ │ +   time_point last_download;
│ │ │ │ +   seconds active_duration;
│ │ │ │ +   seconds finished_duration;
│ │ │ │ +   seconds seeding_duration;
│ │ │ │ +   torrent_flags_t flags {};
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +

operator==()

│ │ │ │ +
│ │ │ │ +bool operator== (torrent_status const& st) const;
│ │ │ │ +
│ │ │ │ +

compares if the torrent status objects come from the same torrent. i.e. │ │ │ │ +only the torrent_handle field is compared.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

enum state_t

│ │ │ │ +

Declared in "libtorrent/torrent_status.hpp"

│ │ │ │ + │ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ +
namevaluedescription
checking_files1The torrent has not started its download yet, and is │ │ │ │ +currently checking existing files.
downloading_metadata2The torrent is trying to download metadata from peers. │ │ │ │ +This implies the ut_metadata extension is in use.
downloading3The torrent is being downloaded. This is the state │ │ │ │ +most torrents will be in most of the time. The progress │ │ │ │ +meter will tell how much of the files that has been │ │ │ │ +downloaded.
finished4In this state the torrent has finished downloading but │ │ │ │ +still doesn't have the entire torrent. i.e. some pieces │ │ │ │ +are filtered and won't get downloaded.
seeding5In this state the torrent has finished downloading and │ │ │ │ +is a pure seeder.
unused_enum_for_backwards_compatibility_allocating6If the torrent was started in full allocation mode, this │ │ │ │ +indicates that the (disk) storage for the torrent is │ │ │ │ +allocated.
checking_resume_data7The torrent is currently checking the fast resume data and │ │ │ │ +comparing it to the files on disk. This is typically │ │ │ │ +completed in a fraction of a second, but if you add a │ │ │ │ +large number of torrents at once, they will queue up.
│ │ │ │ +[report issue]
│ │ │ │ +
handle
│ │ │ │ +
a handle to the torrent whose status the object represents.
│ │ │ │
│ │ │ │ -
│ │ │ │ -
num_alert_types
│ │ │ │ -
this constant represents "max_alert_index" + 1
│ │ │ │ +[report issue]
│ │ │ │ +
errc
│ │ │ │ +
may be set to an error code describing why the torrent was paused, in │ │ │ │ +case it was paused by an error. If the torrent is not paused or if it's │ │ │ │ +paused but not because of an error, this error_code is not set. │ │ │ │ +if the error is attributed specifically to a file, error_file is set to │ │ │ │ +the index of that file in the .torrent file.
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

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.

│ │ │ │ +[report issue]
│ │ │ │ +
error_file
│ │ │ │ +
if the torrent is stopped because of an disk I/O error, this field │ │ │ │ +contains the index of the file in the torrent that encountered the │ │ │ │ +error. If the error did not originate in a file in the torrent, there │ │ │ │ +are a few special values this can be set to: error_file_none, │ │ │ │ +error_file_ssl_ctx, error_file_exception, error_file_partfile or │ │ │ │ +error_file_metadata;
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
error_file_none
│ │ │ │ +
special values for error_file to describe which file or component │ │ │ │ +encountered the error (errc). │ │ │ │ +the error did not occur on a file
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
error_file_ssl_ctx
│ │ │ │ +
the error occurred setting up the SSL context
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
error_file_metadata
│ │ │ │ +
the error occurred while loading the metadata for the torrent
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
error_file_exception
│ │ │ │ +
there was a serious error reported in this torrent. The error code │ │ │ │ +or a torrent log alert may provide more information.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
error_file_partfile
│ │ │ │ +
the error occurred with the partfile
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
save_path
│ │ │ │ +
the path to the directory where this torrent's files are stored. │ │ │ │ +It's typically the path as was given to async_add_torrent() or │ │ │ │ +add_torrent() when this torrent was started. This field is only │ │ │ │ +included if the torrent status is queried with │ │ │ │ +torrent_handle::query_save_path.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
name
│ │ │ │ +
the name of the torrent. Typically this is derived from the │ │ │ │ +.torrent file. In case the torrent was started without metadata, │ │ │ │ +and hasn't completely received it yet, it returns the name given │ │ │ │ +to it when added to the session. See session::add_torrent. │ │ │ │ +This field is only included if the torrent status is queried │ │ │ │ +with torrent_handle::query_name.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
torrent_file
│ │ │ │ +
set to point to the torrent_info object for this torrent. It's │ │ │ │ +only included if the torrent status is queried with │ │ │ │ +torrent_handle::query_torrent_file.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
next_announce
│ │ │ │ +
the time until the torrent will announce itself to the tracker.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
current_tracker
│ │ │ │ +
the URL of the last working tracker. If no tracker request has │ │ │ │ +been successful yet, it's set to an empty string.
│ │ │ │ +
│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
total_download total_upload
│ │ │ │ +
the number of bytes downloaded and uploaded to all peers, accumulated, │ │ │ │ +this session only. The session is considered to restart when a │ │ │ │ +torrent is paused and restarted again. When a torrent is paused, these │ │ │ │ +counters are reset to 0. If you want complete, persistent, stats, see │ │ │ │ +all_time_upload and all_time_download.
│ │ │ │ +
│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
total_payload_download total_payload_upload
│ │ │ │ +
counts the amount of bytes send and received this session, but only │ │ │ │ +the actual payload data (i.e the interesting data), these counters │ │ │ │ +ignore any protocol overhead. The session is considered to restart │ │ │ │ +when a torrent is paused and restarted again. When a torrent is │ │ │ │ +paused, these counters are reset to 0.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
total_failed_bytes
│ │ │ │ +
the number of bytes that has been downloaded and that has failed the │ │ │ │ +piece hash test. In other words, this is just how much crap that has │ │ │ │ +been downloaded since the torrent was last started. If a torrent is │ │ │ │ +paused and then restarted again, this counter will be reset.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
total_redundant_bytes
│ │ │ │ +
the number of bytes that has been downloaded even though that data │ │ │ │ +already was downloaded. The reason for this is that in some situations │ │ │ │ +the same data can be downloaded by mistake. When libtorrent sends │ │ │ │ +requests to a peer, and the peer doesn't send a response within a │ │ │ │ +certain timeout, libtorrent will re-request that block. Another │ │ │ │ +situation when libtorrent may re-request blocks is when the requests │ │ │ │ +it sends out are not replied in FIFO-order (it will re-request blocks │ │ │ │ +that are skipped by an out of order block). This is supposed to be as │ │ │ │ +low as possible. This only counts bytes since the torrent was last │ │ │ │ +started. If a torrent is paused and then restarted again, this counter │ │ │ │ +will be reset.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
pieces
│ │ │ │ +
a bitmask that represents which pieces we have (set to true) and the │ │ │ │ +pieces we don't have. It's a pointer and may be set to 0 if the │ │ │ │ +torrent isn't downloading or seeding.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
verified_pieces
│ │ │ │ +
a bitmask representing which pieces has had their hash checked. This │ │ │ │ +only applies to torrents in seed mode. If the torrent is not in seed │ │ │ │ +mode, this bitmask may be empty.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
total_done
│ │ │ │ +
the total number of bytes of the file(s) that we have. All this does │ │ │ │ +not necessarily has to be downloaded during this session (that's │ │ │ │ +total_payload_download).
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
total
│ │ │ │ +
the total number of bytes to download for this torrent. This │ │ │ │ +may be less than the size of the torrent in case there are │ │ │ │ +pad files. This number only counts bytes that will actually │ │ │ │ +be requested from peers.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
total_wanted_done
│ │ │ │ +
the number of bytes we have downloaded, only counting the pieces that │ │ │ │ +we actually want to download. i.e. excluding any pieces that we have │ │ │ │ +but have priority 0 (i.e. not wanted). │ │ │ │ +Once a torrent becomes seed, any piece- and file priorities are │ │ │ │ +forgotten and all bytes are considered "wanted".
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
total_wanted
│ │ │ │ +
The total number of bytes we want to download. This may be smaller │ │ │ │ +than the total torrent size in case any pieces are prioritized to 0, │ │ │ │ +i.e. not wanted. │ │ │ │ +Once a torrent becomes seed, any piece- and file priorities are │ │ │ │ +forgotten and all bytes are considered "wanted".
│ │ │ │ +
│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
all_time_upload all_time_download
│ │ │ │ +
are accumulated upload and download payload byte counters. They are │ │ │ │ +saved in and restored from resume data to keep totals across sessions.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
added_time
│ │ │ │ +
the posix-time when this torrent was added. i.e. what time(nullptr) │ │ │ │ +returned at the time.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
completed_time
│ │ │ │ +
the posix-time when this torrent was finished. If the torrent is not │ │ │ │ +yet finished, this is 0.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
last_seen_complete
│ │ │ │ +
the time when we, or one of our peers, last saw a complete copy of │ │ │ │ +this torrent.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
storage_mode
│ │ │ │ +
The allocation mode for the torrent. See storage_mode_t for the │ │ │ │ +options. For more information, see storage allocation.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
progress
│ │ │ │ +
a value in the range [0, 1], that represents the progress of the │ │ │ │ +torrent's current task. It may be checking files or downloading.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
progress_ppm
│ │ │ │ +

progress parts per million (progress * 1000000) when disabling │ │ │ │ +floating point operations, this is the only option to query progress

│ │ │ │ +

reflects the same value as progress, but instead in a range [0, │ │ │ │ +1000000] (ppm = parts per million). When floating point operations are │ │ │ │ +disabled, this is the only alternative to the floating point value in │ │ │ │ +progress.

│ │ │ │ +
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
queue_position
│ │ │ │ +
the position this torrent has in the download │ │ │ │ +queue. If the torrent is a seed or finished, this is -1.
│ │ │ │ +
│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
download_rate upload_rate
│ │ │ │ +
the total rates for all peers for this torrent. These will usually │ │ │ │ +have better precision than summing the rates from all peers. The rates │ │ │ │ +are given as the number of bytes per second.
│ │ │ │ +
│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
download_payload_rate upload_payload_rate
│ │ │ │ +
the total transfer rate of payload only, not counting protocol │ │ │ │ +chatter. This might be slightly smaller than the other rates, but if │ │ │ │ +projected over a long time (e.g. when calculating ETA:s) the │ │ │ │ +difference may be noticeable.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
num_seeds
│ │ │ │ +
the number of peers that are seeding that this client is │ │ │ │ +currently connected to.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
num_peers
│ │ │ │ +
the number of peers this torrent currently is connected to. Peer │ │ │ │ +connections that are in the half-open state (is attempting to connect) │ │ │ │ +or are queued for later connection attempt do not count. Although they │ │ │ │ +are visible in the peer list when you call get_peer_info().
│ │ │ │ +
│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
num_complete num_incomplete
│ │ │ │ +
if the tracker sends scrape info in its announce reply, these fields │ │ │ │ +will be set to the total number of peers that have the whole file and │ │ │ │ +the total number of peers that are still downloading. set to -1 if the │ │ │ │ +tracker did not send any scrape data in its announce reply.
│ │ │ │ +
│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
list_seeds list_peers
│ │ │ │ +
the number of seeds in our peer list and the total number of peers │ │ │ │ +(including seeds). We are not necessarily connected to all the peers │ │ │ │ +in our peer list. This is the number of peers we know of in total, │ │ │ │ +including banned peers and peers that we have failed to connect to.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
connect_candidates
│ │ │ │ +
the number of peers in this torrent's peer list that is a candidate to │ │ │ │ +be connected to. i.e. It has fewer connect attempts than the max fail │ │ │ │ +count, it is not a seed if we are a seed, it is not banned etc. If │ │ │ │ +this is 0, it means we don't know of any more peers that we can try.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
num_pieces
│ │ │ │ +
the number of pieces that has been downloaded. It is equivalent to: │ │ │ │ +std::accumulate(pieces->begin(), pieces->end()). So you don't have │ │ │ │ +to count yourself. This can be used to see if anything has updated │ │ │ │ +since last time if you want to keep a graph of the pieces up to date.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
distributed_full_copies
│ │ │ │ +
the number of distributed copies of the torrent. Note that one copy │ │ │ │ +may be spread out among many peers. It tells how many copies there are │ │ │ │ +currently of the rarest piece(s) among the peers this client is │ │ │ │ +connected to.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
distributed_fraction
│ │ │ │ +

tells the share of pieces that have more copies than the rarest │ │ │ │ +piece(s). Divide this number by 1000 to get the fraction.

│ │ │ │ +

For example, if distributed_full_copies is 2 and │ │ │ │ +distributed_fraction is 500, it means that the rarest pieces have │ │ │ │ +only 2 copies among the peers this torrent is connected to, and that │ │ │ │ +50% of all the pieces have more than two copies.

│ │ │ │ +

If we are a seed, the piece picker is deallocated as an optimization, │ │ │ │ +and piece availability is no longer tracked. In this case the │ │ │ │ +distributed copies members are set to -1.

│ │ │ │ +
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
distributed_copies
│ │ │ │ +

the number of distributed copies of the file. note that one copy may │ │ │ │ +be spread out among many peers. This is a floating point │ │ │ │ +representation of the distributed copies.

│ │ │ │ +
│ │ │ │ +
the integer part tells how many copies
│ │ │ │ +
there are of the rarest piece(s)
│ │ │ │ +
the fractional part tells the fraction of pieces that
│ │ │ │ +
have more copies than the rarest piece(s).
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
block_size
│ │ │ │ +
the size of a block, in bytes. A block is a sub piece, it is the │ │ │ │ +number of bytes that each piece request asks for and the number of │ │ │ │ +bytes that each bit in the partial_piece_info's bitset represents, │ │ │ │ +see get_download_queue(). This is typically 16 kB, but it may be │ │ │ │ +smaller, if the pieces are smaller.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
num_uploads
│ │ │ │ +
the number of unchoked peers in this torrent.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
num_connections
│ │ │ │ +
the number of peer connections this torrent has, including half-open │ │ │ │ +connections that hasn't completed the bittorrent handshake yet. This │ │ │ │ +is always >= num_peers.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
uploads_limit
│ │ │ │ +
the set limit of upload slots (unchoked peers) for this torrent.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
connections_limit
│ │ │ │ +
the set limit of number of connections for this torrent.
│ │ │ │ +
│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
up_bandwidth_queue down_bandwidth_queue
│ │ │ │ +
the number of peers in this torrent that are waiting for more │ │ │ │ +bandwidth quota from the torrent rate limiter. This can determine if │ │ │ │ +the rate you get from this torrent is bound by the torrents limit or │ │ │ │ +not. If there is no limit set on this torrent, the peers might still │ │ │ │ +be waiting for bandwidth quota from the global limiter, but then they │ │ │ │ +are counted in the session_status object.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
seed_rank
│ │ │ │ +
A rank of how important it is to seed the torrent, it is used to │ │ │ │ +determine which torrents to seed and which to queue. It is based on │ │ │ │ +the peer to seed ratio from the tracker scrape. For more information, │ │ │ │ +see queuing. Higher value means more important to seed
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
state
│ │ │ │ +
the main state the torrent is in. See torrent_status::state_t.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
need_save_resume
│ │ │ │ +
true if this torrent has unsaved changes │ │ │ │ +to its download state and statistics since the last resume data │ │ │ │ +was saved.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
is_seeding
│ │ │ │ +
true if all pieces have been downloaded.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
is_finished
│ │ │ │ +
true if all pieces that have a priority > 0 are downloaded. There is │ │ │ │ +only a distinction between finished and seeding if some pieces or │ │ │ │ +files have been set to priority 0, i.e. are not downloaded.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
has_metadata
│ │ │ │ +
true if this torrent has metadata (either it was started from a │ │ │ │ +.torrent file or the metadata has been downloaded). The only scenario │ │ │ │ +where this can be false is when the torrent was started torrent-less │ │ │ │ +(i.e. with just an info-hash and tracker ip, a magnet link for │ │ │ │ +instance).
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
has_incoming
│ │ │ │ +
true if there has ever been an incoming connection attempt to this │ │ │ │ +torrent.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
moving_storage
│ │ │ │ +
this is true if this torrent's storage is currently being moved from │ │ │ │ +one location to another. This may potentially be a long operation │ │ │ │ +if a large file ends up being copied from one drive to another.
│ │ │ │ +
│ │ │ │ + │ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
announcing_to_trackers announcing_to_lsd announcing_to_dht
│ │ │ │ +
these are set to true if this torrent is allowed to announce to the │ │ │ │ +respective peer source. Whether they are true or false is determined by │ │ │ │ +the queue logic/auto manager. Torrents that are not auto managed will │ │ │ │ +always be allowed to announce to all peer sources.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
info_hashes
│ │ │ │ +
the info-hash for this torrent
│ │ │ │ +
│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
last_upload last_download
│ │ │ │ +
the timestamps of the last time this torrent uploaded or downloaded │ │ │ │ +payload to any peer.
│ │ │ │ +
│ │ │ │ + │ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
active_duration finished_duration seeding_duration
│ │ │ │ +
these are cumulative counters of for how long the torrent has been in │ │ │ │ +different states. active means not paused and added to session. Whether │ │ │ │ +it has found any peers or not is not relevant. │ │ │ │ +finished means all selected files/pieces were downloaded and available │ │ │ │ +to other peers (this is always a subset of active time). │ │ │ │ +seeding means all files/pieces were downloaded and available to │ │ │ │ +peers. Being available to peers does not imply there are other peers │ │ │ │ +asking for the payload.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
flags
│ │ │ │ +
reflects several of the torrent's flags. For more │ │ │ │ +information, see torrent_handle::flags().
│ │ │ │ +
│ │ │ │ +

Bencoding is a common representation in bittorrent used for dictionary, │ │ │ │ +list, int and string hierarchies. It's used to encode .torrent files and │ │ │ │ +some messages in the network protocol. libtorrent also uses it to store │ │ │ │ +settings, resume data and other session state.

│ │ │ │ +

Strings in bencoded structures do not necessarily represent text. │ │ │ │ +Strings are raw byte buffers of a certain length. If a string is meant to be │ │ │ │ +interpreted as text, it is required to be UTF-8 encoded. See BEP 3.

│ │ │ │ +

The function for decoding bencoded data bdecode(), returning a bdecode_node. │ │ │ │ +This function builds a tree that points back into the original buffer. The │ │ │ │ +returned bdecode_node will not be valid once the buffer it was parsed out of │ │ │ │ +is discarded.

│ │ │ │ +

It's possible to construct an entry from a bdecode_node, if a structure needs │ │ │ │ +to be altered and re-encoded.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +

entry

│ │ │ │ +

Declared in "libtorrent/entry.hpp"

│ │ │ │ +

The entry class represents one node in a bencoded hierarchy. It works as a │ │ │ │ +variant type, it can be either a list, a dictionary (std::map), an integer │ │ │ │ +or a string.

│ │ │ │ 
│ │ │ │ -struct client_data_t
│ │ │ │ +class entry
│ │ │ │  {
│ │ │ │ -   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*) = delete;
│ │ │ │ -   operator void* () const = delete;
│ │ │ │ -   operator void const* () const = delete;
│ │ │ │ -   client_data_t& operator= (void const*) = delete;
│ │ │ │ +   data_type type () const;
│ │ │ │ +   entry (span<char const>);
│ │ │ │ +   entry (preformatted_type);
│ │ │ │ +   entry (list_type);
│ │ │ │ +   entry (dictionary_type);
│ │ │ │ +   entry (integer_type);
│ │ │ │ +   entry (U v);
│ │ │ │ +   entry (data_type t);
│ │ │ │ +   entry (bdecode_node const& n);
│ │ │ │ +   entry& operator= (span<char const>) &;
│ │ │ │ +   entry& operator= (entry&&) & noexcept;
│ │ │ │ +   entry& operator= (preformatted_type) &;
│ │ │ │ +   entry& operator= (entry const&) &;
│ │ │ │ +   entry& operator= (list_type) &;
│ │ │ │ +   entry& operator= (integer_type) &;
│ │ │ │ +   entry& operator= (dictionary_type) &;
│ │ │ │ +   entry& operator= (bdecode_node const&) &;
│ │ │ │ +   entry& operator= (U v) &;
│ │ │ │ +   preformatted_type& preformatted ();
│ │ │ │ +   dictionary_type& dict ();
│ │ │ │ +   string_type const& string () const;
│ │ │ │ +   list_type& list ();
│ │ │ │ +   integer_type const& integer () const;
│ │ │ │ +   list_type const& list () const;
│ │ │ │ +   string_type& string ();
│ │ │ │ +   preformatted_type const& preformatted () const;
│ │ │ │ +   integer_type& integer ();
│ │ │ │ +   dictionary_type const& dict () const;
│ │ │ │ +   void swap (entry& e);
│ │ │ │ +   entry const& operator[] (string_view key) const;
│ │ │ │ +   entry& operator[] (string_view key);
│ │ │ │ +   entry* find_key (string_view key);
│ │ │ │ +   entry const* find_key (string_view key) const;
│ │ │ │ +   std::string to_string (bool single_line = false) const;
│ │ │ │  
│ │ │ │ -   template <typename T, typename U  = typename std::enable_if<std::is_pointer<T>::value>::type>
│ │ │ │ +   enum data_type
│ │ │ │ +   {
│ │ │ │ +      int_t,
│ │ │ │ +      string_t,
│ │ │ │ +      list_t,
│ │ │ │ +      dictionary_t,
│ │ │ │ +      undefined_t,
│ │ │ │ +      preformatted_t,
│ │ │ │ +   };
│ │ │ │  };
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -

client_data_t()

│ │ │ │ +[report issue]
│ │ │ │ +

type()

│ │ │ │ 
│ │ │ │ -client_data_t () = default;
│ │ │ │ +data_type type () const;
│ │ │ │
│ │ │ │ -

construct a nullptr client data

│ │ │ │ - │ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

const*() operator=() void*()

│ │ │ │ +

returns the concrete type of the entry

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

entry()

│ │ │ │ 
│ │ │ │ -client_data_t& operator= (void*) = delete;
│ │ │ │ -operator void* () const = delete;
│ │ │ │ -operator void const* () const = delete;
│ │ │ │ -client_data_t& operator= (void const*) = delete;
│ │ │ │ +entry (span<char const>);
│ │ │ │ +entry (preformatted_type);
│ │ │ │ +entry (list_type);
│ │ │ │ +entry (dictionary_type);
│ │ │ │ +entry (integer_type);
│ │ │ │
│ │ │ │ -

we don't allow type-unsafe operations

│ │ │ │ -[report issue]
│ │ │ │ +

constructors directly from a specific type. │ │ │ │ +The content of the argument is copied into the │ │ │ │ +newly constructed entry

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

entry()

│ │ │ │ +
│ │ │ │ +entry (data_type t);
│ │ │ │ +
│ │ │ │ +

construct an empty entry of the specified type. │ │ │ │ +see data_type enum.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

entry()

│ │ │ │ +
│ │ │ │ +entry (bdecode_node const& n);
│ │ │ │ +
│ │ │ │ +

construct from bdecode_node parsed form (see bdecode())

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

operator=()

│ │ │ │ +
│ │ │ │ +entry& operator= (span<char const>) &;
│ │ │ │ +entry& operator= (entry&&) & noexcept;
│ │ │ │ +entry& operator= (preformatted_type) &;
│ │ │ │ +entry& operator= (entry const&) &;
│ │ │ │ +entry& operator= (list_type) &;
│ │ │ │ +entry& operator= (integer_type) &;
│ │ │ │ +entry& operator= (dictionary_type) &;
│ │ │ │ +entry& operator= (bdecode_node const&) &;
│ │ │ │ +
│ │ │ │ +

copies the structure of the right hand side into this │ │ │ │ +entry.

│ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

preformatted() integer() list() dict() string()

│ │ │ │ +
│ │ │ │ +preformatted_type& preformatted ();
│ │ │ │ +dictionary_type& dict ();
│ │ │ │ +string_type const& string () const;
│ │ │ │ +list_type& list ();
│ │ │ │ +integer_type const& integer () const;
│ │ │ │ +list_type const& list () const;
│ │ │ │ +string_type& string ();
│ │ │ │ +preformatted_type const& preformatted () const;
│ │ │ │ +integer_type& integer ();
│ │ │ │ +dictionary_type const& dict () const;
│ │ │ │ +
│ │ │ │ +

The integer(), string(), list() and dict() functions │ │ │ │ +are accessors that return the respective type. If the entry object │ │ │ │ +isn't of the type you request, the accessor will throw │ │ │ │ +system_error. You can ask an entry for its type through the │ │ │ │ +type() function.

│ │ │ │ +

If you want to create an entry you give it the type you want it to │ │ │ │ +have in its constructor, and then use one of the non-const accessors │ │ │ │ +to get a reference which you then can assign the value you want it to │ │ │ │ +have.

│ │ │ │ +

The typical code to get info from a torrent file will then look like │ │ │ │ +this:

│ │ │ │ +
│ │ │ │ +entry torrent_file;
│ │ │ │ +// ...
│ │ │ │ +
│ │ │ │ +// throws if this is not a dictionary
│ │ │ │ +entry::dictionary_type const& dict = torrent_file.dict();
│ │ │ │ +entry::dictionary_type::const_iterator i;
│ │ │ │ +i = dict.find("announce");
│ │ │ │ +if (i != dict.end())
│ │ │ │ +{
│ │ │ │ +        std::string tracker_url = i->second.string();
│ │ │ │ +        std::cout << tracker_url << "\n";
│ │ │ │ +}
│ │ │ │ +
│ │ │ │ +

The following code is equivalent, but a little bit shorter:

│ │ │ │ +
│ │ │ │ +entry torrent_file;
│ │ │ │ +// ...
│ │ │ │ +
│ │ │ │ +// throws if this is not a dictionary
│ │ │ │ +if (entry* i = torrent_file.find_key("announce"))
│ │ │ │ +{
│ │ │ │ +        std::string tracker_url = i->string();
│ │ │ │ +        std::cout << tracker_url << "\n";
│ │ │ │ +}
│ │ │ │ +
│ │ │ │ +

To make it easier to extract information from a torrent file, the │ │ │ │ +class torrent_info exists.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

swap()

│ │ │ │ +
│ │ │ │ +void swap (entry& e);
│ │ │ │ +
│ │ │ │ +

swaps the content of this with e.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

operator[]()

│ │ │ │ +
│ │ │ │ +entry const& operator[] (string_view key) const;
│ │ │ │ +entry& operator[] (string_view key);
│ │ │ │ +
│ │ │ │ +

All of these functions requires the entry to be a dictionary, if it │ │ │ │ +isn't they will throw system_error.

│ │ │ │ +

The non-const versions of the operator[] will return a reference │ │ │ │ +to either the existing element at the given key or, if there is no │ │ │ │ +element with the given key, a reference to a newly inserted element at │ │ │ │ +that key.

│ │ │ │ +

The const version of operator[] will only return a reference to an │ │ │ │ +existing element at the given key. If the key is not found, it will │ │ │ │ +throw system_error.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

find_key()

│ │ │ │ +
│ │ │ │ +entry* find_key (string_view key);
│ │ │ │ +entry const* find_key (string_view key) const;
│ │ │ │ +
│ │ │ │ +

These functions requires the entry to be a dictionary, if it isn't │ │ │ │ +they will throw system_error.

│ │ │ │ +

They will look for an element at the given key in the dictionary, if │ │ │ │ +the element cannot be found, they will return nullptr. If an element │ │ │ │ +with the given key is found, the return a pointer to it.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

to_string()

│ │ │ │ +
│ │ │ │ +std::string to_string (bool single_line = false) const;
│ │ │ │ +
│ │ │ │ +

returns a pretty-printed string representation │ │ │ │ +of the bencoded structure, with JSON-style syntax

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

enum data_type

│ │ │ │ +

Declared in "libtorrent/entry.hpp"

│ │ │ │ + │ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ +
namevaluedescription
int_t0 
string_t1 
list_t2 
dictionary_t3 
undefined_t4 
preformatted_t5 
│ │ │ │ +[report issue]
│ │ │ │
│ │ │ │ -
│ │ │ │ -

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:

│ │ │ │ +
│ │ │ │ +

operator<<()

│ │ │ │ +

Declared in "libtorrent/entry.hpp"

│ │ │ │ +
│ │ │ │ +inline std::ostream& operator<< (std::ostream& os, const entry& e);
│ │ │ │ +
│ │ │ │ +

prints the bencoded structure to the ostream as a JSON-style structure.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

bencode()

│ │ │ │ +

Declared in "libtorrent/bencode.hpp"

│ │ │ │ +
│ │ │ │ +template<class OutIt> int bencode (OutIt out, const entry& e);
│ │ │ │ +
│ │ │ │ +

This function will encode data to bencoded form.

│ │ │ │ +

The entry class is the internal representation of the bencoded data │ │ │ │ +and it can be used to retrieve information, an entry can also be build by │ │ │ │ +the program and given to bencode() to encode it into the OutIt │ │ │ │ +iterator.

│ │ │ │ +

OutIt is an OutputIterator. It's a template and usually │ │ │ │ +instantiated as ostream_iterator or back_insert_iterator. This │ │ │ │ +function assumes the value_type of the iterator is a char. │ │ │ │ +In order to encode entry e into a buffer, do:

│ │ │ │ +
│ │ │ │ +std::vector<char> buffer;
│ │ │ │ +bencode(std::back_inserter(buf), e);
│ │ │ │ +
│ │ │ │ +

libtorrent has a plugin interface for implementing extensions to the protocol. │ │ │ │ +These can be general extensions for transferring metadata or peer exchange │ │ │ │ +extensions, or it could be used to provide a way to customize the protocol │ │ │ │ +to fit a particular (closed) network.

│ │ │ │ +

In short, the plugin interface makes it possible to:

│ │ │ │
    │ │ │ │ -
  • 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.
    • │ │ │ │ +
  • register extension messages (sent in the extension handshake), see │ │ │ │ +extensions.
    • │ │ │ │ +
  • add data and parse data from the extension handshake.
    • │ │ │ │ +
  • send extension messages and standard bittorrent messages.
    • │ │ │ │ +
  • override or block the handling of standard bittorrent messages.
    • │ │ │ │ +
  • save and restore state via the session state
    • │ │ │ │ +
  • see all alerts that are posted
    • │ │ │ │
│ │ │ │ -

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

│ │ │ │ +
│ │ │ │ +
│ │ │ │ +

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.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

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;
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +

implemented_features()

│ │ │ │ +
│ │ │ │ +virtual feature_flags_t implemented_features ();
│ │ │ │ +
│ │ │ │ +

This function is expected to return a bitmask indicating which features │ │ │ │ +this plugin implements. Some callbacks on this object may not be called │ │ │ │ +unless the corresponding feature flag is returned here. Note that │ │ │ │ +callbacks may still be called even if the corresponding feature is not │ │ │ │ +specified in the return value here. See feature_flags_t for possible │ │ │ │ +flags to return.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

new_torrent()

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

this is called by the session every time a new torrent is added. │ │ │ │ +The torrent* points to the internal torrent object created │ │ │ │ +for the new torrent. The client_data_t is the userdata pointer as │ │ │ │ +passed in via add_torrent_params.

│ │ │ │ +

If the plugin returns a torrent_plugin instance, it will be added │ │ │ │ +to the new torrent. Otherwise, return an empty shared_ptr to a │ │ │ │ +torrent_plugin (the default).

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

added()

│ │ │ │ +
│ │ │ │ +virtual void added (session_handle const&);
│ │ │ │ +
│ │ │ │ +

called when plugin is added to a session

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

abort()

│ │ │ │ +
│ │ │ │ +virtual void abort ();
│ │ │ │ +
│ │ │ │ +

called when the session is aborted │ │ │ │ +the plugin should perform any cleanup necessary to allow the session's │ │ │ │ +destruction (e.g. cancel outstanding async operations)

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

on_dht_request()

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

called when a dht request is received. │ │ │ │ +If your plugin expects this to be called, make sure to include the flag │ │ │ │ +dht_request_feature in the return value from implemented_features().

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

on_alert()

│ │ │ │ +
│ │ │ │ +virtual void on_alert (alert const*);
│ │ │ │ +
│ │ │ │ +

called when an alert is posted alerts that are filtered are not posted. │ │ │ │ +If your plugin expects this to be called, make sure to include the flag │ │ │ │ +alert_feature in the return value from implemented_features().

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

on_unknown_torrent()

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

return true if the add_torrent_params should be added

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

on_tick()

│ │ │ │ +
│ │ │ │ +virtual void on_tick ();
│ │ │ │ +
│ │ │ │ +

called once per second. │ │ │ │ +If your plugin expects this to be called, make sure to include the flag │ │ │ │ +tick_feature in the return value from implemented_features().

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

get_unchoke_priority()

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

called when choosing peers to optimistically unchoke. The return value │ │ │ │ +indicates the peer's priority for unchoking. Lower return values │ │ │ │ +correspond to higher priority. Priorities above 2^63-1 are reserved. │ │ │ │ +If your plugin has no priority to assign a peer it should return 2^64-1. │ │ │ │ +If your plugin expects this to be called, make sure to include the flag │ │ │ │ +optimistic_unchoke_feature in the return value from implemented_features(). │ │ │ │ +If multiple plugins implement this function the lowest return value │ │ │ │ +(i.e. the highest priority) is used.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

load_state()

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

called on startup while loading settings state from the session_params

│ │ │ │ +[report issue]
│ │ │ │ +
optimistic_unchoke_feature
│ │ │ │ +
include this bit if your plugin needs to alter the order of the │ │ │ │ +optimistic unchoke of peers. i.e. have the on_optimistic_unchoke() │ │ │ │ +callback be called.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
tick_feature
│ │ │ │ +
include this bit if your plugin needs to have on_tick() called
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
dht_request_feature
│ │ │ │ +
include this bit if your plugin needs to have on_dht_request() │ │ │ │ +called
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
alert_feature
│ │ │ │ +
include this bit if your plugin needs to have on_alert() │ │ │ │ +called
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +

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_pause ();
│ │ │ │ +   virtual bool on_resume ();
│ │ │ │ +   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;
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +

new_connection()

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

This function is called each time a new peer is connected to the torrent. You │ │ │ │ +may choose to ignore this by just returning a default constructed │ │ │ │ +shared_ptr (in which case you don't need to override this member │ │ │ │ +function).

│ │ │ │ +

If you need an extension to the peer connection (which most plugins do) you │ │ │ │ +are supposed to return an instance of your peer_plugin class. Which in │ │ │ │ +turn will have its hook functions called on event specific to that peer.

│ │ │ │ +

The peer_connection_handle will be valid as long as the shared_ptr │ │ │ │ +is being held by the torrent object. So, it is generally a good idea to not │ │ │ │ +keep a shared_ptr to your own peer_plugin. If you want to keep references │ │ │ │ +to it, use weak_ptr.

│ │ │ │ +

If this function throws an exception, the connection will be closed.

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

on_piece_failed() on_piece_pass()

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

These hooks are called when a piece passes the hash check or fails the hash │ │ │ │ +check, respectively. The index is the piece index that was downloaded. │ │ │ │ +It is possible to access the list of peers that participated in sending the │ │ │ │ +piece through the torrent and the piece_picker.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

tick()

│ │ │ │ +
│ │ │ │ +virtual void tick ();
│ │ │ │ +
│ │ │ │ +

This hook is called approximately once per second. It is a way of making it │ │ │ │ +easy for plugins to do timed events, for sending messages or whatever.

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

on_pause() on_resume()

│ │ │ │ +
│ │ │ │ +virtual bool on_pause ();
│ │ │ │ +virtual bool on_resume ();
│ │ │ │ +
│ │ │ │ +

These hooks are called when the torrent is paused and resumed respectively. │ │ │ │ +The return value indicates if the event was handled. A return value of │ │ │ │ +true indicates that it was handled, and no other plugin after this one │ │ │ │ +will have this hook function called, and the standard handler will also not be │ │ │ │ +invoked. So, returning true effectively overrides the standard behavior of │ │ │ │ +pause or resume.

│ │ │ │ +

Note that if you call pause() or resume() on the torrent from your │ │ │ │ +handler it will recurse back into your handler, so in order to invoke the │ │ │ │ +standard handler, you have to keep your own state on whether you want standard │ │ │ │ +behavior or overridden behavior.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

on_files_checked()

│ │ │ │ +
│ │ │ │ +virtual void on_files_checked ();
│ │ │ │ +
│ │ │ │ +

This function is called when the initial files of the torrent have been │ │ │ │ +checked. If there are no files to check, this function is called immediately.

│ │ │ │ +

i.e. This function is always called when the torrent is in a state where it │ │ │ │ +can start downloading.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

on_state()

│ │ │ │ +
│ │ │ │ +virtual void on_state (torrent_status::state_t);
│ │ │ │ +
│ │ │ │ +

called when the torrent changes state │ │ │ │ +the state is one of torrent_status::state_t │ │ │ │ +enum members

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

on_add_peer()

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

called every time a new peer is added to the peer list. │ │ │ │ +This is before the peer is connected to. For flags, see │ │ │ │ +torrent_plugin::flags_t. The source argument refers to │ │ │ │ +the source where we learned about this peer from. It's a │ │ │ │ +bitmask, because many sources may have told us about the same │ │ │ │ +peer. For peer source flags, see peer_info::peer_source_flags.

│ │ │ │ +[report issue]
│ │ │ │ +
first_time
│ │ │ │ +
this is the first time we see this peer
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
filtered
│ │ │ │ +
this peer was not added because it was │ │ │ │ +filtered by the IP filter
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +

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_bitfield (bitfield const& /*bitfield*/);
│ │ │ │ +   virtual bool on_request (peer_request const&);
│ │ │ │ +   virtual bool on_not_interested ();
│ │ │ │ +   virtual bool on_interested ();
│ │ │ │ +   virtual bool on_have_all ();
│ │ │ │ +   virtual bool on_unchoke ();
│ │ │ │ +   virtual bool on_dont_have (piece_index_t);
│ │ │ │ +   virtual bool on_have (piece_index_t);
│ │ │ │ +   virtual bool on_have_none ();
│ │ │ │ +   virtual bool on_choke ();
│ │ │ │ +   virtual bool on_allowed_fast (piece_index_t);
│ │ │ │ +   virtual bool on_piece (peer_request const& /*piece*/
│ │ │ │ +      , span<char const> /*buf*/);
│ │ │ │ +   virtual bool on_cancel (peer_request const&);
│ │ │ │ +   virtual bool on_reject (peer_request const&);
│ │ │ │ +   virtual bool on_suggest (piece_index_t);
│ │ │ │ +   virtual void sent_have_none ();
│ │ │ │ +   virtual void sent_have_all ();
│ │ │ │ +   virtual void sent_suggest (piece_index_t);
│ │ │ │ +   virtual void sent_reject_request (peer_request const&);
│ │ │ │ +   virtual void sent_request (peer_request const&);
│ │ │ │ +   virtual void sent_cancel (peer_request const&);
│ │ │ │ +   virtual void sent_allow_fast (piece_index_t);
│ │ │ │ +   virtual void sent_choke ();
│ │ │ │ +   virtual void sent_piece (peer_request const&);
│ │ │ │ +   virtual void sent_not_interested ();
│ │ │ │ +   virtual void sent_unchoke ();
│ │ │ │ +   virtual void sent_interested ();
│ │ │ │ +   virtual void sent_have (piece_index_t);
│ │ │ │ +   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&);
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +

type()

│ │ │ │ +
│ │ │ │ +virtual string_view type () const;
│ │ │ │ +
│ │ │ │ +

This function is expected to return the name of │ │ │ │ +the plugin.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

add_handshake()

│ │ │ │ +
│ │ │ │ +virtual void add_handshake (entry&);
│ │ │ │ +
│ │ │ │ +

can add entries to the extension handshake │ │ │ │ +this is not called for web seeds

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

on_disconnect()

│ │ │ │ +
│ │ │ │ +virtual void on_disconnect (error_code const&);
│ │ │ │ +
│ │ │ │ +

called when the peer is being disconnected.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

on_connected()

│ │ │ │ +
│ │ │ │ +virtual void on_connected ();
│ │ │ │ +
│ │ │ │ +

called when the peer is successfully connected. Note that │ │ │ │ +incoming connections will have been connected by the time │ │ │ │ +the peer plugin is attached to it, and won't have this hook │ │ │ │ +called.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

on_handshake()

│ │ │ │ +
│ │ │ │ +virtual bool on_handshake (span<char const>);
│ │ │ │ +
│ │ │ │ +

this is called when the initial bittorrent handshake is received. │ │ │ │ +Returning false means that the other end doesn't support this extension │ │ │ │ +and will remove it from the list of plugins. this is not called for web │ │ │ │ +seeds

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

on_extension_handshake()

│ │ │ │ +
│ │ │ │ +virtual bool on_extension_handshake (bdecode_node const&);
│ │ │ │ +
│ │ │ │ +

called when the extension handshake from the other end is received │ │ │ │ +if this returns false, it means that this extension isn't │ │ │ │ +supported by this peer. It will result in this peer_plugin │ │ │ │ +being removed from the peer_connection and destructed. │ │ │ │ +this is not called for web seeds

│ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

on_have() on_have_all() on_interested() on_request() on_bitfield() on_dont_have() on_allowed_fast() on_unchoke() on_have_none() on_not_interested() on_choke()

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

returning true from any of the message handlers │ │ │ │ +indicates that the plugin has handled the message. │ │ │ │ +it will break the plugin chain traversing and not let │ │ │ │ +anyone else handle the message, including the default │ │ │ │ +handler.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

on_piece()

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

This function is called when the peer connection is receiving │ │ │ │ +a piece. buf points (non-owning pointer) to the data in an │ │ │ │ +internal immutable disk buffer. The length of the data is specified │ │ │ │ +in the length member of the piece parameter. │ │ │ │ +returns true to indicate that the piece is handled and the │ │ │ │ +rest of the logic should be ignored.

│ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

sent_piece() sent_unchoke() sent_interested() sent_not_interested() sent_have()

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

called after a choke message has been sent to the peer

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

sent_payload()

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

called after piece data has been sent to the peer │ │ │ │ +this can be used for stats book keeping

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

can_disconnect()

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

called when libtorrent think this peer should be disconnected. │ │ │ │ +if the plugin returns false, the peer will not be disconnected.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

on_extended()

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

called when an extended message is received. If returning true, │ │ │ │ +the message is not processed by any other plugin and if false │ │ │ │ +is returned the next plugin in the chain will receive it to │ │ │ │ +be able to handle it. This is not called for web seeds. │ │ │ │ +thus function may be called more than once per incoming message, but │ │ │ │ +only the last of the calls will the body size equal the length. │ │ │ │ +i.e. Every time another fragment of the message is received, this │ │ │ │ +function will be called, until finally the whole message has been │ │ │ │ +received. The purpose of this is to allow early disconnects for invalid │ │ │ │ +messages and for reporting progress of receiving large messages.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

on_unknown_message()

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

this is not called for web seeds

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

on_piece_failed() on_piece_pass()

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

called when a piece that this peer participated in either │ │ │ │ +fails or passes the hash_check

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

tick()

│ │ │ │ +
│ │ │ │ +virtual void tick ();
│ │ │ │ +
│ │ │ │ +

called approximately once every second

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

write_request()

│ │ │ │ +
│ │ │ │ +virtual bool write_request (peer_request const&);
│ │ │ │ +
│ │ │ │ +

called each time a request message is to be sent. If true │ │ │ │ +is returned, the original request message won't be sent and │ │ │ │ +no other plugin will have this function called.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +

crypto_plugin

│ │ │ │ +

Declared in "libtorrent/extensions.hpp"

│ │ │ │ +
│ │ │ │ +struct crypto_plugin
│ │ │ │ +{
│ │ │ │ +   virtual void set_outgoing_key (span<char const> key) = 0;
│ │ │ │ +   virtual void set_incoming_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;
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +

decrypt()

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

decrypt the provided buffers. │ │ │ │ +returns is a tuple representing the values │ │ │ │ +(consume, produce, packet_size)

│ │ │ │ +

consume is set to the number of bytes which should be trimmed from the │ │ │ │ +head of the buffers, default is 0

│ │ │ │ +

produce is set to the number of bytes of payload which are now ready to │ │ │ │ +be sent to the upper layer. default is the number of bytes passed in receive_vec

│ │ │ │ +

packet_size is set to the minimum number of bytes which must be read to │ │ │ │ +advance the next step of decryption. default is 0

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +

peer_connection_handle

│ │ │ │ +

Declared in "libtorrent/peer_connection_handle.hpp"

│ │ │ │ +

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

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

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;
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

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

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

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

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

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

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

ip_filter

│ │ │ │ +

Declared in "libtorrent/ip_filter.hpp"

│ │ │ │ +

The ip_filter class is a set of rules that uniquely categorizes all │ │ │ │ +ip addresses as allowed or disallowed. The default constructor creates │ │ │ │ +a single rule that allows all addresses (0.0.0.0 - 255.255.255.255 for │ │ │ │ +the IPv4 range, and the equivalent range covering all addresses for the │ │ │ │ +IPv6 range).

│ │ │ │ +

A default constructed ip_filter does not filter any address.

│ │ │ │ +
│ │ │ │ +struct ip_filter
│ │ │ │ +{
│ │ │ │ +   ip_filter ();
│ │ │ │ +   ip_filter& operator= (ip_filter&&);
│ │ │ │ +   ~ip_filter ();
│ │ │ │ +   ip_filter (ip_filter&&);
│ │ │ │ +   ip_filter& operator= (ip_filter const&);
│ │ │ │ +   ip_filter (ip_filter const&);
│ │ │ │ +   bool empty () const;
│ │ │ │ +   void add_rule (address const& first, address const& last, std::uint32_t flags);
│ │ │ │ +   std::uint32_t access (address const& addr) const;
│ │ │ │ +   filter_tuple_t export_filter () const;
│ │ │ │ +
│ │ │ │ +   enum access_flags
│ │ │ │ +   {
│ │ │ │ +      blocked,
│ │ │ │ +   };
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +

empty()

│ │ │ │ +
│ │ │ │ +bool empty () const;
│ │ │ │ +
│ │ │ │ +

returns true if the filter does not contain any rules

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

add_rule()

│ │ │ │ +
│ │ │ │ +void add_rule (address const& first, address const& last, std::uint32_t flags);
│ │ │ │ +
│ │ │ │ +

Adds a rule to the filter. first and last defines a range of │ │ │ │ +ip addresses that will be marked with the given flags. The flags │ │ │ │ +can currently be 0, which means allowed, or ip_filter::blocked, which │ │ │ │ +means disallowed.

│ │ │ │ +

precondition: │ │ │ │ +first.is_v4() == last.is_v4() && first.is_v6() == last.is_v6()

│ │ │ │ +

postcondition: │ │ │ │ +access(x) == flags for every x in the range [first, last]

│ │ │ │ +

This means that in a case of overlapping ranges, the last one applied takes │ │ │ │ +precedence.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

access()

│ │ │ │ +
│ │ │ │ +std::uint32_t access (address const& addr) const;
│ │ │ │ +
│ │ │ │ +

Returns the access permissions for the given address (addr). The permission │ │ │ │ +can currently be 0 or ip_filter::blocked. The complexity of this operation │ │ │ │ +is O(log n), where n is the minimum number of non-overlapping ranges to describe │ │ │ │ +the current filter.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

export_filter()

│ │ │ │ +
│ │ │ │ +filter_tuple_t export_filter () const;
│ │ │ │ +
│ │ │ │ +

This function will return the current state of the filter in the minimum number of │ │ │ │ +ranges possible. They are sorted from ranges in low addresses to high addresses. Each │ │ │ │ +entry in the returned vector is a range with the access control specified in its │ │ │ │ +flags field.

│ │ │ │ +

The return value is a tuple containing two range-lists. One for IPv4 addresses │ │ │ │ +and one for IPv6 addresses.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

enum access_flags

│ │ │ │ +

Declared in "libtorrent/ip_filter.hpp"

│ │ │ │ + │ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ +
namevaluedescription
blocked1indicates that IPs in this range should not be connected │ │ │ │ +to nor accepted as incoming connections
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +

port_filter

│ │ │ │ +

Declared in "libtorrent/ip_filter.hpp"

│ │ │ │ +

the port filter maps non-overlapping port ranges to flags. This │ │ │ │ +is primarily used to indicate whether a range of ports should │ │ │ │ +be connected to or not. The default is to have the full port │ │ │ │ +range (0-65535) set to flag 0.

│ │ │ │ +
│ │ │ │ +class port_filter
│ │ │ │ +{
│ │ │ │ +   ~port_filter ();
│ │ │ │ +   port_filter (port_filter const&);
│ │ │ │ +   port_filter& operator= (port_filter const&);
│ │ │ │ +   port_filter& operator= (port_filter&&);
│ │ │ │ +   port_filter ();
│ │ │ │ +   port_filter (port_filter&&);
│ │ │ │ +   void add_rule (std::uint16_t first, std::uint16_t last, std::uint32_t flags);
│ │ │ │ +   std::uint32_t access (std::uint16_t port) const;
│ │ │ │ +
│ │ │ │ +   enum access_flags
│ │ │ │ +   {
│ │ │ │ +      blocked,
│ │ │ │ +   };
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +

add_rule()

│ │ │ │ +
│ │ │ │ +void add_rule (std::uint16_t first, std::uint16_t last, std::uint32_t flags);
│ │ │ │ +
│ │ │ │ +

set the flags for the specified port range (first, last) to │ │ │ │ +flags overwriting any existing rule for those ports. The range │ │ │ │ +is inclusive, i.e. the port last also has the flag set on it.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

access()

│ │ │ │ +
│ │ │ │ +std::uint32_t access (std::uint16_t port) const;
│ │ │ │ +
│ │ │ │ +

test the specified port (port) for whether it is blocked │ │ │ │ +or not. The returned value is the flags set for this port. │ │ │ │ +see access_flags.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

enum access_flags

│ │ │ │ +

Declared in "libtorrent/ip_filter.hpp"

│ │ │ │ + │ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ +
namevaluedescription
blocked1this flag indicates that destination ports in the │ │ │ │ +range should not be connected to
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +

bdecode_node

│ │ │ │ +

Declared in "libtorrent/bdecode.hpp"

│ │ │ │ +

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

│ │ │ │ +

There are 5 different types of nodes, see type_t.

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

bdecode_node()

│ │ │ │ +
│ │ │ │ +bdecode_node () = default;
│ │ │ │ +
│ │ │ │ +

creates a default constructed node, it will have the type none_t.

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

bdecode_node() operator=()

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

For owning nodes, the copy will create a copy of the tree, but the │ │ │ │ +underlying buffer remains the same.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

type()

│ │ │ │ +
│ │ │ │ +type_t type () const noexcept;
│ │ │ │ +
│ │ │ │ +

the type of this node. See type_t.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

bool()

│ │ │ │ +
│ │ │ │ +explicit operator bool () const noexcept;
│ │ │ │ +
│ │ │ │ +

returns true if type() != none_t.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

non_owning()

│ │ │ │ +
│ │ │ │ +bdecode_node non_owning () const;
│ │ │ │ +
│ │ │ │ +

return a non-owning reference to this node. This is useful to refer to │ │ │ │ +the root node without copying it in assignments.

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

data_offset() data_section()

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

returns the buffer and length of the section in the original bencoded │ │ │ │ +buffer where this node is defined. For a dictionary for instance, this │ │ │ │ +starts with d and ends with e, and has all the content of the │ │ │ │ +dictionary in between. │ │ │ │ +the data_offset() function returns the byte-offset to this node in, │ │ │ │ +starting from the beginning of the buffer that was parsed.

│ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

list_string_value_at() list_at() list_int_value_at() list_size()

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

functions with the list_ prefix operate on lists. These functions are │ │ │ │ +only valid if type() == list_t. list_at() returns the item │ │ │ │ +in the list at index i. i may not be greater than or equal to the │ │ │ │ +size of the list. size() returns the size of the list.

│ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

dict_find_string_value() dict_find_int_value() dict_find() dict_at() dict_find_dict() dict_find_string() dict_find_int() dict_at_node() dict_size() dict_find_list()

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

Functions with the dict_ prefix operates on dictionaries. They are │ │ │ │ +only valid if type() == dict_t. In case a key you're looking up │ │ │ │ +contains a 0 byte, you cannot use the 0-terminated string overloads, │ │ │ │ +but have to use string_view instead. dict_find_list will return a │ │ │ │ +valid bdecode_node if the key is found _and_ it is a list. Otherwise │ │ │ │ +it will return a default-constructed bdecode_node.

│ │ │ │ +

Functions with the _value suffix return the value of the node │ │ │ │ +directly, rather than the nodes. In case the node is not found, or it has │ │ │ │ +a different type, a default value is returned (which can be specified).

│ │ │ │ +

dict_at() returns the (key, value)-pair at the specified index in a │ │ │ │ +dictionary. Keys are only allowed to be strings. dict_at_node() also │ │ │ │ +returns the (key, value)-pair, but the key is returned as a │ │ │ │ +bdecode_node (and it will always be a string).

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

int_value()

│ │ │ │ +
│ │ │ │ +std::int64_t int_value () const;
│ │ │ │ +
│ │ │ │ +

this function is only valid if type() == int_t. It returns the │ │ │ │ +value of the integer.

│ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

string_ptr() string_offset() string_value() string_length()

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

these functions are only valid if type() == string_t. They return │ │ │ │ +the string values. Note that string_ptr() is not 0-terminated. │ │ │ │ +string_length() returns the number of bytes in the string. │ │ │ │ +string_offset() returns the byte offset from the start of the parsed │ │ │ │ +bencoded buffer this string can be found.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

clear()

│ │ │ │ +
│ │ │ │ +void clear ();
│ │ │ │ +
│ │ │ │ +

resets the bdecoded_node to a default constructed state. If this is │ │ │ │ +an owning node, the tree is freed and all child nodes are invalidated.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

swap()

│ │ │ │ +
│ │ │ │ +void swap (bdecode_node& n);
│ │ │ │ +
│ │ │ │ +

Swap contents.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

reserve()

│ │ │ │ +
│ │ │ │ +void reserve (int tokens);
│ │ │ │ +
│ │ │ │ +

preallocate memory for the specified numbers of tokens. This is │ │ │ │ +useful if you know approximately how many tokens are in the file │ │ │ │ +you are about to parse. Doing so will save realloc operations │ │ │ │ +while parsing. You should only call this on the root node, before │ │ │ │ +passing it in to bdecode().

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

switch_underlying_buffer()

│ │ │ │ +
│ │ │ │ +void switch_underlying_buffer (char const* buf) noexcept;
│ │ │ │ +
│ │ │ │ +

this buffer MUST be identical to the one originally parsed. This │ │ │ │ +operation is only defined on owning root nodes, i.e. the one passed in to │ │ │ │ +decode().

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

has_soft_error()

│ │ │ │ +
│ │ │ │ +bool has_soft_error (span<char> error) const;
│ │ │ │ +
│ │ │ │ +

returns true if there is a non-fatal error in the bencoding of this node │ │ │ │ +or its children

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

enum type_t

│ │ │ │ +

Declared in "libtorrent/bdecode.hpp"

│ │ │ │ + │ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ +
namevaluedescription
none_t0uninitialized or default constructed. This is also used │ │ │ │ +to indicate that a node was not found in some cases.
dict_t1a dictionary node. The dict_find_ functions are valid.
list_t2a list node. The list_ functions are valid.
string_t3a string node, the string_ functions are valid.
int_t4an integer node. The int_ functions are valid.
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +

print_entry()

│ │ │ │ +

Declared in "libtorrent/bdecode.hpp"

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

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

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

bdecode()

│ │ │ │ +

Declared in "libtorrent/bdecode.hpp"

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

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

│ │ │ │ +

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

│ │ │ │ +

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

│ │ │ │ +

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

│ │ │ │ +

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

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

storage_params

│ │ │ │ +

Declared in "libtorrent/storage_defs.hpp"

│ │ │ │ +

a parameter pack used to construct the storage for a torrent, used in │ │ │ │ +disk_interface

│ │ │ │ +
│ │ │ │ +struct storage_params
│ │ │ │ +{
│ │ │ │ +   storage_params (file_storage const& f, file_storage const* mf
│ │ │ │ +      , std::string const& sp, storage_mode_t const sm
│ │ │ │ +      , aux::vector<download_priority_t, file_index_t> const& prio
│ │ │ │ +      , sha1_hash const& ih);
│ │ │ │ +
│ │ │ │ +   file_storage const& files;
│ │ │ │ +   file_storage const* mapped_files  = nullptr;
│ │ │ │ +   std::string const& path;
│ │ │ │ +   storage_mode_t mode {storage_mode_sparse};
│ │ │ │ +   aux::vector<download_priority_t, file_index_t> const& priorities;
│ │ │ │ +   sha1_hash info_hash;
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

file_slice

│ │ │ │ +

Declared in "libtorrent/file_storage.hpp"

│ │ │ │ +

represents a window of a file in a torrent.

│ │ │ │ +

The file_index refers to the index of the file (in the torrent_info). │ │ │ │ +To get the path and filename, use file_path() and give the file_index │ │ │ │ +as argument. The offset is the byte offset in the file where the range │ │ │ │ +starts, and size is the number of bytes this range is. The size + offset │ │ │ │ +will never be greater than the file size.

│ │ │ │ 
│ │ │ │ -struct add_torrent_params
│ │ │ │ +struct file_slice
│ │ │ │  {
│ │ │ │ -   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;
│ │ │ │ +   file_index_t file_index;
│ │ │ │ +   std::int64_t offset;
│ │ │ │ +   std::int64_t size;
│ │ │ │  };
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
version
│ │ │ │ -
filled in by the constructor and should be left untouched. It is used │ │ │ │ -for forward binary compatibility.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
ti
│ │ │ │ -
torrent_info object with the torrent to add. Unless the │ │ │ │ -info_hash is set, this is required to be initialized.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
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.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
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.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
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.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
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.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
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.

│ │ │ │ -
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
storage_mode
│ │ │ │ -
One of the values from storage_mode_t. For more information, see │ │ │ │ -storage allocation.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
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().
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
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.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
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.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
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.

│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
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.
│ │ │ │ -
│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
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.

│ │ │ │ -
│ │ │ │ -
│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
upload_limit download_limit
│ │ │ │ -
the upload and download rate limits for this torrent, specified in │ │ │ │ -bytes per second. -1 means unlimited.
│ │ │ │ -
│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
total_uploaded total_downloaded
│ │ │ │ -
the total number of bytes uploaded and downloaded by this torrent so │ │ │ │ -far.
│ │ │ │ -
│ │ │ │ - │ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
active_time finished_time seeding_time
│ │ │ │ -
the number of seconds this torrent has spent in started, finished and │ │ │ │ -seeding state so far, respectively.
│ │ │ │ -
│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
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.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
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.
│ │ │ │ -
│ │ │ │ - │ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
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.

│ │ │ │ -
│ │ │ │ -
│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
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.

│ │ │ │ -
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
peers
│ │ │ │ -
peers to add to the torrent, to be tried to be connected to as │ │ │ │ -bittorrent peers.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
banned_peers
│ │ │ │ -
peers banned from this torrent. The will not be connected to
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
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.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
have_pieces
│ │ │ │ -
this is a bitfield indicating which pieces we already have of this │ │ │ │ -torrent.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
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.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
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.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
merkle_trees
│ │ │ │ -
v2 hashes, if known
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
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.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
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.
│ │ │ │ +[report issue]
│ │ │ │ +
file_index
│ │ │ │ +
the index of the file
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
renamed_files
│ │ │ │ -
this is a map of file indices in the torrent and new filenames to be │ │ │ │ -applied before the torrent is added.
│ │ │ │ +[report issue]
│ │ │ │ +
offset
│ │ │ │ +
the offset from the start of the file, in bytes
│ │ │ │
│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
last_download last_upload
│ │ │ │ -
the posix time of the last time payload was received or sent for this │ │ │ │ -torrent, respectively.
│ │ │ │ +[report issue]
│ │ │ │ +
size
│ │ │ │ +
the size of the window, in bytes
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

hasher

│ │ │ │ -

Declared in "libtorrent/hasher.hpp"

│ │ │ │ -

this is a SHA-1 hash class.

│ │ │ │ -

You use it by first instantiating it, then call update() to feed it │ │ │ │ -with data. i.e. you don't have to keep the entire buffer of which you want to │ │ │ │ -create the hash in memory. You can feed the hasher parts of it at a time. When │ │ │ │ -You have fed the hasher with all the data, you call final() and it │ │ │ │ -will return the sha1-hash of the data.

│ │ │ │ -

The constructor that takes a char const* and an integer will construct the │ │ │ │ -sha1 context and feed it the data passed in.

│ │ │ │ -

If you want to reuse the hasher object once you have created a hash, you have to │ │ │ │ -call reset() to reinitialize it.

│ │ │ │ -

The built-in software version of sha1-algorithm was implemented │ │ │ │ -by Steve Reid and released as public domain. │ │ │ │ -For more info, see src/sha1.cpp.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

file_storage

│ │ │ │ +

Declared in "libtorrent/file_storage.hpp"

│ │ │ │ +

The file_storage class represents a file list and the piece │ │ │ │ +size. Everything necessary to interpret a regular bittorrent storage │ │ │ │ +file structure.

│ │ │ │ 
│ │ │ │ -class hasher
│ │ │ │ +class file_storage
│ │ │ │  {
│ │ │ │ -   hasher ();
│ │ │ │ -   hasher& operator= (hasher const&) &;
│ │ │ │ -   hasher (hasher const&);
│ │ │ │ -   explicit hasher (span<char const> data);
│ │ │ │ -   hasher (char const* data, int len);
│ │ │ │ -   hasher& update (span<char const> data);
│ │ │ │ -   hasher& update (char const* data, int len);
│ │ │ │ -   sha1_hash final ();
│ │ │ │ -   void reset ();
│ │ │ │ +   bool is_valid () const;
│ │ │ │ +   void reserve (int num_files);
│ │ │ │ +   void add_file_borrow (string_view filename
│ │ │ │ +      , std::string const& path, std::int64_t file_size
│ │ │ │ +      , file_flags_t file_flags = {}, char const* filehash = nullptr
│ │ │ │ +      , std::int64_t mtime = 0, string_view symlink_path = string_view()
│ │ │ │ +      , char const* root_hash = nullptr);
│ │ │ │ +   void add_file (std::string const& path, std::int64_t file_size
│ │ │ │ +      , file_flags_t file_flags = {}
│ │ │ │ +      , std::time_t mtime = 0, string_view symlink_path = string_view()
│ │ │ │ +      , char const* root_hash = nullptr);
│ │ │ │ +   void add_file (error_code& ec, std::string const& path, std::int64_t file_size
│ │ │ │ +      , file_flags_t file_flags = {}
│ │ │ │ +      , std::time_t mtime = 0, string_view symlink_path = string_view()
│ │ │ │ +      , char const* root_hash = nullptr);
│ │ │ │ +   void add_file_borrow (error_code& ec, string_view filename
│ │ │ │ +      , std::string const& path, std::int64_t file_size
│ │ │ │ +      , file_flags_t file_flags = {}, char const* filehash = nullptr
│ │ │ │ +      , std::int64_t mtime = 0, string_view symlink_path = string_view()
│ │ │ │ +      , char const* root_hash = nullptr);
│ │ │ │ +   void rename_file (file_index_t index, std::string const& new_filename);
│ │ │ │ +   std::vector<file_slice> map_block (piece_index_t piece, std::int64_t offset
│ │ │ │ +      , std::int64_t size) const;
│ │ │ │ +   peer_request map_file (file_index_t file, std::int64_t offset, int size) const;
│ │ │ │ +   int num_files () const noexcept;
│ │ │ │ +   file_index_t end_file () const noexcept;
│ │ │ │ +   index_range<file_index_t> file_range () const noexcept;
│ │ │ │ +   std::int64_t total_size () const;
│ │ │ │ +   int num_pieces () const;
│ │ │ │ +   void set_num_pieces (int n);
│ │ │ │ +   piece_index_t end_piece () const;
│ │ │ │ +   piece_index_t last_piece () const;
│ │ │ │ +   index_range<piece_index_t> piece_range () const noexcept;
│ │ │ │ +   int piece_length () const;
│ │ │ │ +   void set_piece_length (int l);
│ │ │ │ +   int piece_size (piece_index_t index) const;
│ │ │ │ +   int piece_size2 (piece_index_t index) const;
│ │ │ │ +   int blocks_in_piece2 (piece_index_t index) const;
│ │ │ │ +   void set_name (std::string const& n);
│ │ │ │ +   std::string const& name () const;
│ │ │ │ +   void swap (file_storage& ti) noexcept;
│ │ │ │ +   void canonicalize ();
│ │ │ │ +   std::string symlink (file_index_t index) const;
│ │ │ │ +   std::int64_t file_size (file_index_t index) const;
│ │ │ │ +   sha256_hash root (file_index_t index) const;
│ │ │ │ +   std::int64_t file_offset (file_index_t index) const;
│ │ │ │ +   sha1_hash hash (file_index_t index) const;
│ │ │ │ +   char const* root_ptr (file_index_t const index) const;
│ │ │ │ +   std::time_t mtime (file_index_t index) const;
│ │ │ │ +   std::string file_path (file_index_t index, std::string const& save_path = "") const;
│ │ │ │ +   bool pad_file_at (file_index_t index) const;
│ │ │ │ +   string_view file_name (file_index_t index) const;
│ │ │ │ +   index_range<piece_index_t::diff_type> file_piece_range (file_index_t) const;
│ │ │ │ +   int file_num_pieces (file_index_t index) const;
│ │ │ │ +   int file_num_blocks (file_index_t index) const;
│ │ │ │ +   int file_first_block_node (file_index_t index) const;
│ │ │ │ +   int file_first_piece_node (file_index_t index) const;
│ │ │ │ +   std::uint32_t file_path_hash (file_index_t index, std::string const& save_path) const;
│ │ │ │ +   void all_path_hashes (std::unordered_set<std::uint32_t>& table) const;
│ │ │ │ +   file_flags_t file_flags (file_index_t index) const;
│ │ │ │ +   bool file_absolute_path (file_index_t index) const;
│ │ │ │ +   file_index_t file_index_at_offset (std::int64_t offset) const;
│ │ │ │ +   file_index_t file_index_at_piece (piece_index_t piece) const;
│ │ │ │ +   file_index_t file_index_for_root (sha256_hash const& root_hash) const;
│ │ │ │ +   piece_index_t piece_index_at_file (file_index_t f) const;
│ │ │ │ +   void sanitize_symlinks ();
│ │ │ │ +   bool v2 () const;
│ │ │ │ +
│ │ │ │ +   static constexpr file_flags_t flag_pad_file  = 0_bit;
│ │ │ │ +   static constexpr file_flags_t flag_hidden  = 1_bit;
│ │ │ │ +   static constexpr file_flags_t flag_executable  = 2_bit;
│ │ │ │ +   static constexpr file_flags_t flag_symlink  = 3_bit;
│ │ │ │  };
│ │ │ │
│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -

hasher() operator=()

│ │ │ │ -
│ │ │ │ -hasher& operator= (hasher const&) &;
│ │ │ │ -hasher (hasher const&);
│ │ │ │ -explicit hasher (span<char const> data);
│ │ │ │ -hasher (char const* data, int len);
│ │ │ │ -
│ │ │ │ -

this is the same as default constructing followed by a call to │ │ │ │ -update(data, len).

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

update()

│ │ │ │ +[report issue]
│ │ │ │ +

is_valid()

│ │ │ │ 
│ │ │ │ -hasher& update (span<char const> data);
│ │ │ │ -hasher& update (char const* data, int len);
│ │ │ │ +bool is_valid () const;
│ │ │ │
│ │ │ │ -

append the following bytes to what is being hashed

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

final()

│ │ │ │ +

returns true if the piece length has been initialized │ │ │ │ +on the file_storage. This is typically taken as a proxy │ │ │ │ +of whether the file_storage as a whole is initialized or │ │ │ │ +not.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

reserve()

│ │ │ │ 
│ │ │ │ -sha1_hash final ();
│ │ │ │ +void reserve (int num_files);
│ │ │ │
│ │ │ │ -

returns the SHA-1 digest of the buffers previously passed to │ │ │ │ -update() and the hasher constructor.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

reset()

│ │ │ │ +

allocates space for num_files in the internal file list. This can │ │ │ │ +be used to avoid reallocating the internal file list when the number │ │ │ │ +of files to be added is known up-front.

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

add_file() add_file_borrow()

│ │ │ │ 
│ │ │ │ -void reset ();
│ │ │ │ +void add_file_borrow (string_view filename
│ │ │ │ +      , std::string const& path, std::int64_t file_size
│ │ │ │ +      , file_flags_t file_flags = {}, char const* filehash = nullptr
│ │ │ │ +      , std::int64_t mtime = 0, string_view symlink_path = string_view()
│ │ │ │ +      , char const* root_hash = nullptr);
│ │ │ │ +void add_file (std::string const& path, std::int64_t file_size
│ │ │ │ +      , file_flags_t file_flags = {}
│ │ │ │ +      , std::time_t mtime = 0, string_view symlink_path = string_view()
│ │ │ │ +      , char const* root_hash = nullptr);
│ │ │ │ +void add_file (error_code& ec, std::string const& path, std::int64_t file_size
│ │ │ │ +      , file_flags_t file_flags = {}
│ │ │ │ +      , std::time_t mtime = 0, string_view symlink_path = string_view()
│ │ │ │ +      , char const* root_hash = nullptr);
│ │ │ │ +void add_file_borrow (error_code& ec, string_view filename
│ │ │ │ +      , std::string const& path, std::int64_t file_size
│ │ │ │ +      , file_flags_t file_flags = {}, char const* filehash = nullptr
│ │ │ │ +      , std::int64_t mtime = 0, string_view symlink_path = string_view()
│ │ │ │ +      , char const* root_hash = nullptr);
│ │ │ │
│ │ │ │ -

restore the hasher state to be as if the hasher has just been │ │ │ │ -default constructed.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -

hasher256

│ │ │ │ -

Declared in "libtorrent/hasher.hpp"

│ │ │ │ +

Adds a file to the file storage. The add_file_borrow version │ │ │ │ +expects that filename is the file name (without a path) of │ │ │ │ +the file that's being added. │ │ │ │ +This memory is borrowed, i.e. it is the caller's │ │ │ │ +responsibility to make sure it stays valid throughout the lifetime │ │ │ │ +of this file_storage object or any copy of it. The same thing applies │ │ │ │ +to filehash, which is an optional pointer to a 20 byte binary │ │ │ │ +SHA-1 hash of the file.

│ │ │ │ +

if filename is empty, the filename from path is used and not │ │ │ │ +borrowed.

│ │ │ │ +

The path argument is the full path (in the torrent file) to │ │ │ │ +the file to add. Note that this is not supposed to be an absolute │ │ │ │ +path, but it is expected to include the name of the torrent as the │ │ │ │ +first path element.

│ │ │ │ +

file_size is the size of the file in bytes.

│ │ │ │ +

The file_flags argument sets attributes on the file. The file │ │ │ │ +attributes is an extension and may not work in all bittorrent clients.

│ │ │ │ +

For possible file attributes, see file_storage::flags_t.

│ │ │ │ +

The mtime argument is optional and can be set to 0. If non-zero, │ │ │ │ +it is the posix time of the last modification time of this file.

│ │ │ │ +

symlink_path is the path the file is a symlink to. To make this a │ │ │ │ +symlink you also need to set the file_storage::flag_symlink file flag.

│ │ │ │ +

root_hash is an optional pointer to a 32 byte SHA-256 hash, being │ │ │ │ +the merkle tree root hash for this file. This is only used for v2 │ │ │ │ +torrents. If the root hash is specified for one file, it has to │ │ │ │ +be specified for all, otherwise this function will fail. │ │ │ │ +Note that the buffer root_hash points to must out-live the │ │ │ │ +file_storage object, it will not be copied. This parameter is only │ │ │ │ +used when loading torrents, that already have their file hashes │ │ │ │ +computed. When creating torrents, the file hashes will be computed by │ │ │ │ +the piece hashes.

│ │ │ │ +

If more files than one are added, certain restrictions to their paths │ │ │ │ +apply. In a multi-file file storage (torrent), all files must share │ │ │ │ +the same root directory.

│ │ │ │ +

That is, the first path element of all files must be the same. │ │ │ │ +This shared path element is also set to the name of the torrent. It │ │ │ │ +can be changed by calling set_name.

│ │ │ │ +

The overloads that take an error_code reference will report failures │ │ │ │ +via that variable, otherwise system_error is thrown.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

rename_file()

│ │ │ │ 
│ │ │ │ -class hasher256
│ │ │ │ -{
│ │ │ │ -   hasher256 ();
│ │ │ │ -   hasher256 (hasher256 const&);
│ │ │ │ -   hasher256& operator= (hasher256 const&) &;
│ │ │ │ -   explicit hasher256 (span<char const> data);
│ │ │ │ -   hasher256 (char const* data, int len);
│ │ │ │ -   hasher256& update (span<char const> data);
│ │ │ │ -   hasher256& update (char const* data, int len);
│ │ │ │ -   sha256_hash final ();
│ │ │ │ -   void reset ();
│ │ │ │ -   ~hasher256 ();
│ │ │ │ -};
│ │ │ │ +void rename_file (file_index_t index, std::string const& new_filename);
│ │ │ │
│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -

hasher256() operator=()

│ │ │ │ +

renames the file at index to new_filename. Keep in mind │ │ │ │ +that filenames are expected to be UTF-8 encoded.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

map_block()

│ │ │ │ 
│ │ │ │ -hasher256 (hasher256 const&);
│ │ │ │ -hasher256& operator= (hasher256 const&) &;
│ │ │ │ -explicit hasher256 (span<char const> data);
│ │ │ │ -hasher256 (char const* data, int len);
│ │ │ │ +std::vector<file_slice> map_block (piece_index_t piece, std::int64_t offset
│ │ │ │ +      , std::int64_t size) const;
│ │ │ │
│ │ │ │ -

this is the same as default constructing followed by a call to │ │ │ │ -update(data, len).

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

update()

│ │ │ │ +

returns a list of file_slice objects representing the portions of │ │ │ │ +files the specified piece index, byte offset and size range overlaps. │ │ │ │ +this is the inverse mapping of map_file().

│ │ │ │ +

Preconditions of this function is that the input range is within the │ │ │ │ +torrents address space. piece may not be negative and

│ │ │ │ +
│ │ │ │ +piece * piece_size + offset + size
│ │ │ │ +

may not exceed the total size of the torrent.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

map_file()

│ │ │ │ 
│ │ │ │ -hasher256& update (span<char const> data);
│ │ │ │ -hasher256& update (char const* data, int len);
│ │ │ │ +peer_request map_file (file_index_t file, std::int64_t offset, int size) const;
│ │ │ │
│ │ │ │ -

append the following bytes to what is being hashed

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

final()

│ │ │ │ +

returns a peer_request representing the piece index, byte offset │ │ │ │ +and size the specified file range overlaps. This is the inverse │ │ │ │ +mapping over map_block(). Note that the peer_request return type │ │ │ │ +is meant to hold bittorrent block requests, which may not be larger │ │ │ │ +than 16 kiB. Mapping a range larger than that may return an overflown │ │ │ │ +integer.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

num_files()

│ │ │ │ 
│ │ │ │ -sha256_hash final ();
│ │ │ │ +int num_files () const noexcept;
│ │ │ │
│ │ │ │ -

returns the SHA-1 digest of the buffers previously passed to │ │ │ │ -update() and the hasher constructor.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

reset()

│ │ │ │ +

returns the number of files in the file_storage

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

end_file()

│ │ │ │ 
│ │ │ │ -void reset ();
│ │ │ │ +file_index_t end_file () const noexcept;
│ │ │ │
│ │ │ │ -

restore the hasher state to be as if the hasher has just been │ │ │ │ -default constructed.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -

bitfield

│ │ │ │ -

Declared in "libtorrent/bitfield.hpp"

│ │ │ │ -

The bitfield type stores any number of bits as a bitfield │ │ │ │ -in a heap allocated array.

│ │ │ │ +

returns the index of the one-past-end file in the file storage

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

file_range()

│ │ │ │ 
│ │ │ │ -struct bitfield
│ │ │ │ -{
│ │ │ │ -   bitfield (int bits, bool val);
│ │ │ │ -   bitfield (bitfield const& rhs);
│ │ │ │ -   bitfield (bitfield&& rhs) noexcept = default;
│ │ │ │ -   bitfield (char const* b, int bits);
│ │ │ │ -   bitfield () noexcept = default;
│ │ │ │ -   explicit bitfield (int bits);
│ │ │ │ -   void assign (char const* b, int const bits);
│ │ │ │ -   bool operator[] (int index) const noexcept;
│ │ │ │ -   bool get_bit (int index) const noexcept;
│ │ │ │ -   void clear_bit (int index) noexcept;
│ │ │ │ -   void set_bit (int index) noexcept;
│ │ │ │ -   bool all_set () const noexcept;
│ │ │ │ -   bool none_set () const noexcept;
│ │ │ │ -   int size () const noexcept;
│ │ │ │ -   int num_words () const noexcept;
│ │ │ │ -   bool empty () const noexcept;
│ │ │ │ -   char* data () noexcept;
│ │ │ │ -   char const* data () const noexcept;
│ │ │ │ -   void swap (bitfield& rhs) noexcept;
│ │ │ │ -   int count () const noexcept;
│ │ │ │ -   int find_first_set () const noexcept;
│ │ │ │ -   int find_last_clear () const noexcept;
│ │ │ │ -};
│ │ │ │ +index_range<file_index_t> file_range () const noexcept;
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -

bitfield()

│ │ │ │ +

returns an implementation-defined type that can be used as the │ │ │ │ +container in a range-for loop. Where the values are the indices of all │ │ │ │ +files in the file_storage.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

total_size()

│ │ │ │ 
│ │ │ │ -bitfield (int bits, bool val);
│ │ │ │ -bitfield (bitfield const& rhs);
│ │ │ │ -bitfield (bitfield&& rhs) noexcept = default;
│ │ │ │ -bitfield (char const* b, int bits);
│ │ │ │ -bitfield () noexcept = default;
│ │ │ │ -explicit bitfield (int bits);
│ │ │ │ +std::int64_t total_size () const;
│ │ │ │
│ │ │ │ -

constructs a new bitfield. The default constructor creates an empty │ │ │ │ -bitfield. bits is the size of the bitfield (specified in bits). │ │ │ │ -val is the value to initialize the bits to. If not specified │ │ │ │ -all bits are initialized to 0.

│ │ │ │ -

The constructor taking a pointer b and bits copies a bitfield │ │ │ │ -from the specified buffer, and bits number of bits (rounded up to │ │ │ │ -the nearest byte boundary).

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

assign()

│ │ │ │ +

returns the total number of bytes all the files in this torrent spans

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

num_pieces() set_num_pieces()

│ │ │ │ 
│ │ │ │ -void assign (char const* b, int const bits);
│ │ │ │ +int num_pieces () const;
│ │ │ │ +void set_num_pieces (int n);
│ │ │ │
│ │ │ │ -

copy bitfield from buffer b of bits number of bits, rounded up to │ │ │ │ -the nearest byte boundary.

│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

operator[]() get_bit()

│ │ │ │ +

set and get the number of pieces in the torrent

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

end_piece()

│ │ │ │ 
│ │ │ │ -bool operator[] (int index) const noexcept;
│ │ │ │ -bool get_bit (int index) const noexcept;
│ │ │ │ +piece_index_t end_piece () const;
│ │ │ │
│ │ │ │ -

query bit at index. Returns true if bit is 1, otherwise false.

│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

clear_bit() set_bit()

│ │ │ │ +

returns the index of the one-past-end piece in the file storage

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

last_piece()

│ │ │ │ 
│ │ │ │ -void clear_bit (int index) noexcept;
│ │ │ │ -void set_bit (int index) noexcept;
│ │ │ │ +piece_index_t last_piece () const;
│ │ │ │
│ │ │ │ -

set bit at index to 0 (clear_bit) or 1 (set_bit).

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

all_set()

│ │ │ │ +

returns the index of the last piece in the torrent. The last piece is │ │ │ │ +special in that it may be smaller than the other pieces (and the other │ │ │ │ +pieces are all the same size).

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

piece_range()

│ │ │ │ 
│ │ │ │ -bool all_set () const noexcept;
│ │ │ │ +index_range<piece_index_t> piece_range () const noexcept;
│ │ │ │
│ │ │ │ -

returns true if all bits in the bitfield are set

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

none_set()

│ │ │ │ +

returns an implementation-defined type that can be used as the │ │ │ │ +container in a range-for loop. Where the values are the indices of all │ │ │ │ +pieces in the file_storage.

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

set_piece_length() piece_length()

│ │ │ │ 
│ │ │ │ -bool none_set () const noexcept;
│ │ │ │ +int piece_length () const;
│ │ │ │ +void set_piece_length (int l);
│ │ │ │
│ │ │ │ -

returns true if no bit in the bitfield is set

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

size()

│ │ │ │ +

set and get the size of each piece in this torrent. It must be a power of two │ │ │ │ +and at least 16 kiB.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

piece_size()

│ │ │ │ 
│ │ │ │ -int size () const noexcept;
│ │ │ │ +int piece_size (piece_index_t index) const;
│ │ │ │
│ │ │ │ -

returns the size of the bitfield in bits.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

num_words()

│ │ │ │ +

returns the piece size of index. This will be the same as piece_length(), except │ │ │ │ +for the last piece, which may be shorter.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

piece_size2()

│ │ │ │ 
│ │ │ │ -int num_words () const noexcept;
│ │ │ │ +int piece_size2 (piece_index_t index) const;
│ │ │ │
│ │ │ │ -

returns the number of 32 bit words are needed to represent all bits in │ │ │ │ -this bitfield.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

empty()

│ │ │ │ +

Returns the size of the given piece. If the piece spans multiple files, │ │ │ │ +only the first file is considered part of the piece. This is used for │ │ │ │ +v2 torrents, where all files are piece aligned and padded. i.e. The pad │ │ │ │ +files are not considered part of the piece for this purpose.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

blocks_in_piece2()

│ │ │ │ 
│ │ │ │ -bool empty () const noexcept;
│ │ │ │ +int blocks_in_piece2 (piece_index_t index) const;
│ │ │ │
│ │ │ │ -

returns true if the bitfield has zero size.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

data()

│ │ │ │ +

returns the number of blocks in the specified piece, for v2 torrents.

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

set_name() name()

│ │ │ │ 
│ │ │ │ -char* data () noexcept;
│ │ │ │ -char const* data () const noexcept;
│ │ │ │ +void set_name (std::string const& n);
│ │ │ │ +std::string const& name () const;
│ │ │ │
│ │ │ │ -

returns a pointer to the internal buffer of the bitfield, or │ │ │ │ -nullptr if it's empty.

│ │ │ │ -[report issue]
│ │ │ │ +

set and get the name of this torrent. For multi-file torrents, this is also │ │ │ │ +the name of the root directory all the files are stored in.

│ │ │ │ +[report issue]
│ │ │ │
│ │ │ │

swap()

│ │ │ │ 
│ │ │ │ -void swap (bitfield& rhs) noexcept;
│ │ │ │ +void swap (file_storage& ti) noexcept;
│ │ │ │
│ │ │ │ -

swaps the bit-fields two variables refer to

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

count()

│ │ │ │ +

swap all content of this with ti.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

canonicalize()

│ │ │ │ 
│ │ │ │ -int count () const noexcept;
│ │ │ │ +void canonicalize ();
│ │ │ │
│ │ │ │ -

count the number of bits in the bitfield that are set to 1.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

find_first_set()

│ │ │ │ +

arrange files and padding to match the canonical form required │ │ │ │ +by BEP 52

│ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ + │ │ │ │ -
│ │ │ │ -

find_last_clear()

│ │ │ │ +

These functions are used to query attributes of files at │ │ │ │ +a given index.

│ │ │ │ +

The hash() is a SHA-1 hash of the file, or 0 if none was │ │ │ │ +provided in the torrent file. This can potentially be used to │ │ │ │ +join a bittorrent network with other file sharing networks.

│ │ │ │ +

root() returns the SHA-256 merkle tree root of the specified file, │ │ │ │ +in case this is a v2 torrent. Otherwise returns zeros. │ │ │ │ +root_ptr() returns a pointer to the SHA-256 merkle tree root hash │ │ │ │ +for the specified file. The pointer points into storage referred to │ │ │ │ +when the file was added, it is not owned by this object. Torrents │ │ │ │ +that are not v2 torrents return nullptr.

│ │ │ │ +

The mtime() is the modification time is the posix │ │ │ │ +time when a file was last modified when the torrent │ │ │ │ +was created, or 0 if it was not included in the torrent file.

│ │ │ │ +

file_path() returns the full path to a file.

│ │ │ │ +

file_size() returns the size of a file.

│ │ │ │ +

pad_file_at() returns true if the file at the given │ │ │ │ +index is a pad-file.

│ │ │ │ +

file_name() returns just the name of the file, whereas │ │ │ │ +file_path() returns the path (inside the torrent file) with │ │ │ │ +the filename appended.

│ │ │ │ +

file_offset() returns the byte offset within the torrent file │ │ │ │ +where this file starts. It can be used to map the file to a piece │ │ │ │ +index (given the piece size).

│ │ │ │ + │ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

file_num_pieces() file_piece_range() file_num_blocks()

│ │ │ │ 
│ │ │ │ -int find_last_clear () const noexcept;
│ │ │ │ +index_range<piece_index_t::diff_type> file_piece_range (file_index_t) const;
│ │ │ │ +int file_num_pieces (file_index_t index) const;
│ │ │ │ +int file_num_blocks (file_index_t index) const;
│ │ │ │
│ │ │ │ -

returns the index to the last cleared bit in the bitfield, i.e. 0 bit.

│ │ │ │ -[report issue]
│ │ │ │ +

Returns the number of pieces or blocks the file at index spans, │ │ │ │ +under the assumption that the file is aligned to the start of a piece. │ │ │ │ +This is only meaningful for v2 torrents, where files are guaranteed │ │ │ │ +such alignment. │ │ │ │ +These numbers are used to size and navigate the merkle hash tree for │ │ │ │ +each file.

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

file_first_piece_node() file_first_block_node()

│ │ │ │ +
│ │ │ │ +int file_first_block_node (file_index_t index) const;
│ │ │ │ +int file_first_piece_node (file_index_t index) const;
│ │ │ │ +
│ │ │ │ +

index of first piece node in the merkle tree

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

file_path_hash()

│ │ │ │ +
│ │ │ │ +std::uint32_t file_path_hash (file_index_t index, std::string const& save_path) const;
│ │ │ │ +
│ │ │ │ +

returns the crc32 hash of file_path(index)

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

all_path_hashes()

│ │ │ │ +
│ │ │ │ +void all_path_hashes (std::unordered_set<std::uint32_t>& table) const;
│ │ │ │ +
│ │ │ │ +

this will add the CRC32 hash of all directory entries to the table. No │ │ │ │ +filename will be included, just directories. Every depth of directories │ │ │ │ +are added separately to allow test for collisions with files at all │ │ │ │ +levels. i.e. if one path in the torrent is foo/bar/baz, the CRC32 │ │ │ │ +hashes for foo, foo/bar and foo/bar/baz will be added to │ │ │ │ +the set.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

file_flags()

│ │ │ │ +
│ │ │ │ +file_flags_t file_flags (file_index_t index) const;
│ │ │ │ +
│ │ │ │ +

returns a bitmask of flags from file_flags_t that apply │ │ │ │ +to file at index.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

file_absolute_path()

│ │ │ │ +
│ │ │ │ +bool file_absolute_path (file_index_t index) const;
│ │ │ │ +
│ │ │ │ +

returns true if the file at the specified index has been renamed to │ │ │ │ +have an absolute path, i.e. is not anchored in the save path of the │ │ │ │ +torrent.

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

file_index_at_offset() file_index_at_piece()

│ │ │ │ +
│ │ │ │ +file_index_t file_index_at_offset (std::int64_t offset) const;
│ │ │ │ +file_index_t file_index_at_piece (piece_index_t piece) const;
│ │ │ │ +
│ │ │ │ +

returns the index of the file at the given offset in the torrent

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

file_index_for_root()

│ │ │ │ +
│ │ │ │ +file_index_t file_index_for_root (sha256_hash const& root_hash) const;
│ │ │ │ +
│ │ │ │ +

finds the file with the given root hash and returns its index │ │ │ │ +if there is no file with the root hash, file_index_t{-1} is returned

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

piece_index_at_file()

│ │ │ │ +
│ │ │ │ +piece_index_t piece_index_at_file (file_index_t f) const;
│ │ │ │ +
│ │ │ │ +

returns the piece index the given file starts at

│ │ │ │ +[report issue]
│ │ │ │ + │ │ │ │ +
│ │ │ │ +

v2()

│ │ │ │ +
│ │ │ │ +bool v2 () const;
│ │ │ │ +
│ │ │ │ +

returns true if this torrent contains v2 metadata.

│ │ │ │ +[report issue]
│ │ │ │ +
flag_pad_file
│ │ │ │ +
the file is a pad file. It's required to contain zeros │ │ │ │ +at it will not be saved to disk. Its purpose is to make │ │ │ │ +the following file start on a piece boundary.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
flag_hidden
│ │ │ │ +
this file has the hidden attribute set. This is primarily │ │ │ │ +a windows attribute
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
flag_executable
│ │ │ │ +
this file has the executable attribute set.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
flag_symlink
│ │ │ │ +
this file is a symbolic link. It should have a link │ │ │ │ +target string associated with it.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │
│ │ │ │ -
│ │ │ │ -

torrent_status

│ │ │ │ -

Declared in "libtorrent/torrent_status.hpp"

│ │ │ │ -

holds a snapshot of the status of a torrent, as queried by │ │ │ │ -torrent_handle::status().

│ │ │ │ +
│ │ │ │ +

default_disk_io_constructor()

│ │ │ │ +

Declared in "libtorrent/session.hpp"

│ │ │ │ 
│ │ │ │ -struct torrent_status
│ │ │ │ -{
│ │ │ │ -   bool operator== (torrent_status const& st) const;
│ │ │ │ -
│ │ │ │ -   enum state_t
│ │ │ │ -   {
│ │ │ │ -      checking_files,
│ │ │ │ -      downloading_metadata,
│ │ │ │ -      downloading,
│ │ │ │ -      finished,
│ │ │ │ -      seeding,
│ │ │ │ -      unused_enum_for_backwards_compatibility_allocating,
│ │ │ │ -      checking_resume_data,
│ │ │ │ -   };
│ │ │ │ -
│ │ │ │ -   torrent_handle handle;
│ │ │ │ -   error_code errc;
│ │ │ │ -   file_index_t error_file  = torrent_status::error_file_none;
│ │ │ │ -   static constexpr file_index_t error_file_none {-1};
│ │ │ │ -   static constexpr file_index_t error_file_ssl_ctx {-3};
│ │ │ │ -   static constexpr file_index_t error_file_metadata {-4};
│ │ │ │ -   static constexpr file_index_t error_file_exception {-5};
│ │ │ │ -   static constexpr file_index_t error_file_partfile {-6};
│ │ │ │ -   std::string save_path;
│ │ │ │ -   std::string name;
│ │ │ │ -   std::weak_ptr<const torrent_info> torrent_file;
│ │ │ │ -   time_duration next_announce  = seconds{0};
│ │ │ │ -   std::string current_tracker;
│ │ │ │ -   std::int64_t total_download  = 0;
│ │ │ │ -   std::int64_t total_upload  = 0;
│ │ │ │ -   std::int64_t total_payload_download  = 0;
│ │ │ │ -   std::int64_t total_payload_upload  = 0;
│ │ │ │ -   std::int64_t total_failed_bytes  = 0;
│ │ │ │ -   std::int64_t total_redundant_bytes  = 0;
│ │ │ │ -   typed_bitfield<piece_index_t> pieces;
│ │ │ │ -   typed_bitfield<piece_index_t> verified_pieces;
│ │ │ │ -   std::int64_t total_done  = 0;
│ │ │ │ -   std::int64_t total  = 0;
│ │ │ │ -   std::int64_t total_wanted_done  = 0;
│ │ │ │ -   std::int64_t total_wanted  = 0;
│ │ │ │ -   std::int64_t all_time_upload  = 0;
│ │ │ │ -   std::int64_t all_time_download  = 0;
│ │ │ │ -   std::time_t added_time  = 0;
│ │ │ │ -   std::time_t completed_time  = 0;
│ │ │ │ -   std::time_t last_seen_complete  = 0;
│ │ │ │ -   storage_mode_t storage_mode  = storage_mode_sparse;
│ │ │ │ -   float progress  = 0.f;
│ │ │ │ -   int progress_ppm  = 0;
│ │ │ │ -   queue_position_t queue_position {};
│ │ │ │ -   int download_rate  = 0;
│ │ │ │ -   int upload_rate  = 0;
│ │ │ │ -   int download_payload_rate  = 0;
│ │ │ │ -   int upload_payload_rate  = 0;
│ │ │ │ -   int num_seeds  = 0;
│ │ │ │ -   int num_peers  = 0;
│ │ │ │ -   int num_complete  = -1;
│ │ │ │ -   int num_incomplete  = -1;
│ │ │ │ -   int list_seeds  = 0;
│ │ │ │ -   int list_peers  = 0;
│ │ │ │ -   int connect_candidates  = 0;
│ │ │ │ -   int num_pieces  = 0;
│ │ │ │ -   int distributed_full_copies  = 0;
│ │ │ │ -   int distributed_fraction  = 0;
│ │ │ │ -   float distributed_copies  = 0.f;
│ │ │ │ -   int block_size  = 0;
│ │ │ │ -   int num_uploads  = 0;
│ │ │ │ -   int num_connections  = 0;
│ │ │ │ -   int uploads_limit  = 0;
│ │ │ │ -   int connections_limit  = 0;
│ │ │ │ -   int up_bandwidth_queue  = 0;
│ │ │ │ -   int down_bandwidth_queue  = 0;
│ │ │ │ -   int seed_rank  = 0;
│ │ │ │ -   state_t state  = checking_resume_data;
│ │ │ │ -   bool need_save_resume  = false;
│ │ │ │ -   bool is_seeding  = false;
│ │ │ │ -   bool is_finished  = false;
│ │ │ │ -   bool has_metadata  = false;
│ │ │ │ -   bool has_incoming  = false;
│ │ │ │ -   bool moving_storage  = false;
│ │ │ │ -   bool announcing_to_trackers  = false;
│ │ │ │ -   bool announcing_to_lsd  = false;
│ │ │ │ -   bool announcing_to_dht  = false;
│ │ │ │ -   info_hash_t info_hashes;
│ │ │ │ -   time_point last_upload;
│ │ │ │ -   time_point last_download;
│ │ │ │ -   seconds active_duration;
│ │ │ │ -   seconds finished_duration;
│ │ │ │ -   seconds seeding_duration;
│ │ │ │ -   torrent_flags_t flags {};
│ │ │ │ -};
│ │ │ │ +std::unique_ptr<disk_interface> default_disk_io_constructor (
│ │ │ │ +   io_context& ios, settings_interface const&, counters& cnt);
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -

operator==()

│ │ │ │ +

the constructor function for the default storage. On systems that support │ │ │ │ +memory mapped files (and a 64 bit address space) the memory mapped storage │ │ │ │ +will be constructed, otherwise the portable posix storage.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

posix_disk_io_constructor()

│ │ │ │ +

Declared in "libtorrent/posix_disk_io.hpp"

│ │ │ │ 
│ │ │ │ -bool operator== (torrent_status const& st) const;
│ │ │ │ +std::unique_ptr<disk_interface> posix_disk_io_constructor (
│ │ │ │ +   io_context& ios, settings_interface const&, counters& cnt);
│ │ │ │
│ │ │ │ -

compares if the torrent status objects come from the same torrent. i.e. │ │ │ │ -only the torrent_handle field is compared.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

enum state_t

│ │ │ │ -

Declared in "libtorrent/torrent_status.hpp"

│ │ │ │ +

this is a simple posix disk I/O back-end, used for systems that don't │ │ │ │ +have a 64 bit virtual address space or don't support memory mapped files. │ │ │ │ +It's implemented using portable C file functions and is single-threaded.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

mmap_disk_io_constructor()

│ │ │ │ +

Declared in "libtorrent/mmap_disk_io.hpp"

│ │ │ │ +
│ │ │ │ +std::unique_ptr<disk_interface> mmap_disk_io_constructor (
│ │ │ │ +   io_context& ios, settings_interface const&, counters& cnt);
│ │ │ │ +
│ │ │ │ +

constructs a memory mapped file disk I/O object.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

disabled_disk_io_constructor()

│ │ │ │ +

Declared in "libtorrent/disabled_disk_io.hpp"

│ │ │ │ +
│ │ │ │ +std::unique_ptr<disk_interface> disabled_disk_io_constructor (
│ │ │ │ +   io_context& ios, settings_interface const&, counters& cnt);
│ │ │ │ +
│ │ │ │ +

creates a disk io object that discards all data written to it, and only │ │ │ │ +returns zero-buffers when read from. May be useful for testing and │ │ │ │ +benchmarking.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

enum storage_mode_t

│ │ │ │ +

Declared in "libtorrent/storage_defs.hpp"

│ │ │ │ │ │ │ │ │ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ +
namevaluedescription
checking_files
storage_mode_allocate0All pieces will be written to their final position, all files will be │ │ │ │ +allocated in full when the torrent is first started. This mode minimizes │ │ │ │ +fragmentation but could be a costly operation.
storage_mode_sparse1The torrent has not started its download yet, and is │ │ │ │ -currently checking existing files.All pieces will be written to the place where they belong and sparse files │ │ │ │ +will be used. This is the recommended, and default mode.
downloading_metadata
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

enum status_t

│ │ │ │ +

Declared in "libtorrent/storage_defs.hpp"

│ │ │ │ + │ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ +
namevaluedescription
no_error0 
fatal_disk_error1 
need_full_check2The torrent is trying to download metadata from peers. │ │ │ │ -This implies the ut_metadata extension is in use. 
downloading
file_exist3The torrent is being downloaded. This is the state │ │ │ │ -most torrents will be in most of the time. The progress │ │ │ │ -meter will tell how much of the files that has been │ │ │ │ -downloaded. 
finished4In this state the torrent has finished downloading but │ │ │ │ -still doesn't have the entire torrent. i.e. some pieces │ │ │ │ -are filtered and won't get downloaded.
oversized_file16this is not an enum value, but a flag that can be set in the return │ │ │ │ +from async_check_files, in case an existing file was found larger than │ │ │ │ +specified in the torrent. i.e. it has garbage at the end │ │ │ │ +the status_t field is used for this to preserve ABI.
seeding5In this state the torrent has finished downloading and │ │ │ │ -is a pure seeder.
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

enum move_flags_t

│ │ │ │ +

Declared in "libtorrent/storage_defs.hpp"

│ │ │ │ + │ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ │ │ │ │
namevaluedescription
unused_enum_for_backwards_compatibility_allocating6If the torrent was started in full allocation mode, this │ │ │ │ -indicates that the (disk) storage for the torrent is │ │ │ │ -allocated.
always_replace_files0replace any files in the destination when copying │ │ │ │ +or moving the storage
checking_resume_data7The torrent is currently checking the fast resume data and │ │ │ │ -comparing it to the files on disk. This is typically │ │ │ │ -completed in a fraction of a second, but if you add a │ │ │ │ -large number of torrents at once, they will queue up.
fail_if_exist1if any files that we want to copy exist in the destination │ │ │ │ +exist, fail the whole operation and don't perform │ │ │ │ +any copy or move. There is an inherent race condition │ │ │ │ +in this mode. The files are checked for existence before │ │ │ │ +the operation starts. In between the check and performing │ │ │ │ +the copy, the destination files may be created, in which │ │ │ │ +case they are replaced.
dont_replace2if any file exist in the target, take those files instead │ │ │ │ +of the ones we may have in the source.
│ │ │ │ -[report issue]
│ │ │ │ -
handle
│ │ │ │ -
a handle to the torrent whose status the object represents.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
errc
│ │ │ │ -
may be set to an error code describing why the torrent was paused, in │ │ │ │ -case it was paused by an error. If the torrent is not paused or if it's │ │ │ │ -paused but not because of an error, this error_code is not set. │ │ │ │ -if the error is attributed specifically to a file, error_file is set to │ │ │ │ -the index of that file in the .torrent file.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
error_file
│ │ │ │ -
if the torrent is stopped because of an disk I/O error, this field │ │ │ │ -contains the index of the file in the torrent that encountered the │ │ │ │ -error. If the error did not originate in a file in the torrent, there │ │ │ │ -are a few special values this can be set to: error_file_none, │ │ │ │ -error_file_ssl_ctx, error_file_exception, error_file_partfile or │ │ │ │ -error_file_metadata;
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
error_file_none
│ │ │ │ -
special values for error_file to describe which file or component │ │ │ │ -encountered the error (errc). │ │ │ │ -the error did not occur on a file
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
error_file_ssl_ctx
│ │ │ │ -
the error occurred setting up the SSL context
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
error_file_metadata
│ │ │ │ -
the error occurred while loading the metadata for the torrent
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
error_file_exception
│ │ │ │ -
there was a serious error reported in this torrent. The error code │ │ │ │ -or a torrent log alert may provide more information.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
error_file_partfile
│ │ │ │ -
the error occurred with the partfile
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
save_path
│ │ │ │ -
the path to the directory where this torrent's files are stored. │ │ │ │ -It's typically the path as was given to async_add_torrent() or │ │ │ │ -add_torrent() when this torrent was started. This field is only │ │ │ │ -included if the torrent status is queried with │ │ │ │ -torrent_handle::query_save_path.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
name
│ │ │ │ -
the name of the torrent. Typically this is derived from the │ │ │ │ -.torrent file. In case the torrent was started without metadata, │ │ │ │ -and hasn't completely received it yet, it returns the name given │ │ │ │ -to it when added to the session. See session::add_torrent. │ │ │ │ -This field is only included if the torrent status is queried │ │ │ │ -with torrent_handle::query_name.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
torrent_file
│ │ │ │ -
set to point to the torrent_info object for this torrent. It's │ │ │ │ -only included if the torrent status is queried with │ │ │ │ -torrent_handle::query_torrent_file.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
next_announce
│ │ │ │ -
the time until the torrent will announce itself to the tracker.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
current_tracker
│ │ │ │ -
the URL of the last working tracker. If no tracker request has │ │ │ │ -been successful yet, it's set to an empty string.
│ │ │ │ -
│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
total_download total_upload
│ │ │ │ -
the number of bytes downloaded and uploaded to all peers, accumulated, │ │ │ │ -this session only. The session is considered to restart when a │ │ │ │ -torrent is paused and restarted again. When a torrent is paused, these │ │ │ │ -counters are reset to 0. If you want complete, persistent, stats, see │ │ │ │ -all_time_upload and all_time_download.
│ │ │ │ -
│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
total_payload_download total_payload_upload
│ │ │ │ -
counts the amount of bytes send and received this session, but only │ │ │ │ -the actual payload data (i.e the interesting data), these counters │ │ │ │ -ignore any protocol overhead. The session is considered to restart │ │ │ │ -when a torrent is paused and restarted again. When a torrent is │ │ │ │ -paused, these counters are reset to 0.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
total_failed_bytes
│ │ │ │ -
the number of bytes that has been downloaded and that has failed the │ │ │ │ -piece hash test. In other words, this is just how much crap that has │ │ │ │ -been downloaded since the torrent was last started. If a torrent is │ │ │ │ -paused and then restarted again, this counter will be reset.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
total_redundant_bytes
│ │ │ │ -
the number of bytes that has been downloaded even though that data │ │ │ │ -already was downloaded. The reason for this is that in some situations │ │ │ │ -the same data can be downloaded by mistake. When libtorrent sends │ │ │ │ -requests to a peer, and the peer doesn't send a response within a │ │ │ │ -certain timeout, libtorrent will re-request that block. Another │ │ │ │ -situation when libtorrent may re-request blocks is when the requests │ │ │ │ -it sends out are not replied in FIFO-order (it will re-request blocks │ │ │ │ -that are skipped by an out of order block). This is supposed to be as │ │ │ │ -low as possible. This only counts bytes since the torrent was last │ │ │ │ -started. If a torrent is paused and then restarted again, this counter │ │ │ │ -will be reset.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
pieces
│ │ │ │ -
a bitmask that represents which pieces we have (set to true) and the │ │ │ │ -pieces we don't have. It's a pointer and may be set to 0 if the │ │ │ │ -torrent isn't downloading or seeding.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
verified_pieces
│ │ │ │ -
a bitmask representing which pieces has had their hash checked. This │ │ │ │ -only applies to torrents in seed mode. If the torrent is not in seed │ │ │ │ -mode, this bitmask may be empty.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
total_done
│ │ │ │ -
the total number of bytes of the file(s) that we have. All this does │ │ │ │ -not necessarily has to be downloaded during this session (that's │ │ │ │ -total_payload_download).
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
total
│ │ │ │ -
the total number of bytes to download for this torrent. This │ │ │ │ -may be less than the size of the torrent in case there are │ │ │ │ -pad files. This number only counts bytes that will actually │ │ │ │ -be requested from peers.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
total_wanted_done
│ │ │ │ -
the number of bytes we have downloaded, only counting the pieces that │ │ │ │ -we actually want to download. i.e. excluding any pieces that we have │ │ │ │ -but have priority 0 (i.e. not wanted). │ │ │ │ -Once a torrent becomes seed, any piece- and file priorities are │ │ │ │ -forgotten and all bytes are considered "wanted".
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
total_wanted
│ │ │ │ -
The total number of bytes we want to download. This may be smaller │ │ │ │ -than the total torrent size in case any pieces are prioritized to 0, │ │ │ │ -i.e. not wanted. │ │ │ │ -Once a torrent becomes seed, any piece- and file priorities are │ │ │ │ -forgotten and all bytes are considered "wanted".
│ │ │ │ -
│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
all_time_upload all_time_download
│ │ │ │ -
are accumulated upload and download payload byte counters. They are │ │ │ │ -saved in and restored from resume data to keep totals across sessions.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
added_time
│ │ │ │ -
the posix-time when this torrent was added. i.e. what time(nullptr) │ │ │ │ -returned at the time.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
completed_time
│ │ │ │ -
the posix-time when this torrent was finished. If the torrent is not │ │ │ │ -yet finished, this is 0.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
last_seen_complete
│ │ │ │ -
the time when we, or one of our peers, last saw a complete copy of │ │ │ │ -this torrent.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
storage_mode
│ │ │ │ -
The allocation mode for the torrent. See storage_mode_t for the │ │ │ │ -options. For more information, see storage allocation.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
progress
│ │ │ │ -
a value in the range [0, 1], that represents the progress of the │ │ │ │ -torrent's current task. It may be checking files or downloading.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
progress_ppm
│ │ │ │ -

progress parts per million (progress * 1000000) when disabling │ │ │ │ -floating point operations, this is the only option to query progress

│ │ │ │ -

reflects the same value as progress, but instead in a range [0, │ │ │ │ -1000000] (ppm = parts per million). When floating point operations are │ │ │ │ -disabled, this is the only alternative to the floating point value in │ │ │ │ -progress.

│ │ │ │ -
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
queue_position
│ │ │ │ -
the position this torrent has in the download │ │ │ │ -queue. If the torrent is a seed or finished, this is -1.
│ │ │ │ -
│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
download_rate upload_rate
│ │ │ │ -
the total rates for all peers for this torrent. These will usually │ │ │ │ -have better precision than summing the rates from all peers. The rates │ │ │ │ -are given as the number of bytes per second.
│ │ │ │ -
│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
download_payload_rate upload_payload_rate
│ │ │ │ -
the total transfer rate of payload only, not counting protocol │ │ │ │ -chatter. This might be slightly smaller than the other rates, but if │ │ │ │ -projected over a long time (e.g. when calculating ETA:s) the │ │ │ │ -difference may be noticeable.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
num_seeds
│ │ │ │ -
the number of peers that are seeding that this client is │ │ │ │ -currently connected to.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
num_peers
│ │ │ │ -
the number of peers this torrent currently is connected to. Peer │ │ │ │ -connections that are in the half-open state (is attempting to connect) │ │ │ │ -or are queued for later connection attempt do not count. Although they │ │ │ │ -are visible in the peer list when you call get_peer_info().
│ │ │ │ -
│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
num_complete num_incomplete
│ │ │ │ -
if the tracker sends scrape info in its announce reply, these fields │ │ │ │ -will be set to the total number of peers that have the whole file and │ │ │ │ -the total number of peers that are still downloading. set to -1 if the │ │ │ │ -tracker did not send any scrape data in its announce reply.
│ │ │ │ -
│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
list_seeds list_peers
│ │ │ │ -
the number of seeds in our peer list and the total number of peers │ │ │ │ -(including seeds). We are not necessarily connected to all the peers │ │ │ │ -in our peer list. This is the number of peers we know of in total, │ │ │ │ -including banned peers and peers that we have failed to connect to.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
connect_candidates
│ │ │ │ -
the number of peers in this torrent's peer list that is a candidate to │ │ │ │ -be connected to. i.e. It has fewer connect attempts than the max fail │ │ │ │ -count, it is not a seed if we are a seed, it is not banned etc. If │ │ │ │ -this is 0, it means we don't know of any more peers that we can try.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
num_pieces
│ │ │ │ -
the number of pieces that has been downloaded. It is equivalent to: │ │ │ │ -std::accumulate(pieces->begin(), pieces->end()). So you don't have │ │ │ │ -to count yourself. This can be used to see if anything has updated │ │ │ │ -since last time if you want to keep a graph of the pieces up to date.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
distributed_full_copies
│ │ │ │ -
the number of distributed copies of the torrent. Note that one copy │ │ │ │ -may be spread out among many peers. It tells how many copies there are │ │ │ │ -currently of the rarest piece(s) among the peers this client is │ │ │ │ -connected to.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
distributed_fraction
│ │ │ │ -

tells the share of pieces that have more copies than the rarest │ │ │ │ -piece(s). Divide this number by 1000 to get the fraction.

│ │ │ │ -

For example, if distributed_full_copies is 2 and │ │ │ │ -distributed_fraction is 500, it means that the rarest pieces have │ │ │ │ -only 2 copies among the peers this torrent is connected to, and that │ │ │ │ -50% of all the pieces have more than two copies.

│ │ │ │ -

If we are a seed, the piece picker is deallocated as an optimization, │ │ │ │ -and piece availability is no longer tracked. In this case the │ │ │ │ -distributed copies members are set to -1.

│ │ │ │ -
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
distributed_copies
│ │ │ │ -

the number of distributed copies of the file. note that one copy may │ │ │ │ -be spread out among many peers. This is a floating point │ │ │ │ -representation of the distributed copies.

│ │ │ │ -
│ │ │ │ -
the integer part tells how many copies
│ │ │ │ -
there are of the rarest piece(s)
│ │ │ │ -
the fractional part tells the fraction of pieces that
│ │ │ │ -
have more copies than the rarest piece(s).
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
block_size
│ │ │ │ -
the size of a block, in bytes. A block is a sub piece, it is the │ │ │ │ -number of bytes that each piece request asks for and the number of │ │ │ │ -bytes that each bit in the partial_piece_info's bitset represents, │ │ │ │ -see get_download_queue(). This is typically 16 kB, but it may be │ │ │ │ -smaller, if the pieces are smaller.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
num_uploads
│ │ │ │ -
the number of unchoked peers in this torrent.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
num_connections
│ │ │ │ -
the number of peer connections this torrent has, including half-open │ │ │ │ -connections that hasn't completed the bittorrent handshake yet. This │ │ │ │ -is always >= num_peers.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
uploads_limit
│ │ │ │ -
the set limit of upload slots (unchoked peers) for this torrent.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
connections_limit
│ │ │ │ -
the set limit of number of connections for this torrent.
│ │ │ │ -
│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
up_bandwidth_queue down_bandwidth_queue
│ │ │ │ -
the number of peers in this torrent that are waiting for more │ │ │ │ -bandwidth quota from the torrent rate limiter. This can determine if │ │ │ │ -the rate you get from this torrent is bound by the torrents limit or │ │ │ │ -not. If there is no limit set on this torrent, the peers might still │ │ │ │ -be waiting for bandwidth quota from the global limiter, but then they │ │ │ │ -are counted in the session_status object.
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
seed_rank
│ │ │ │ -
A rank of how important it is to seed the torrent, it is used to │ │ │ │ -determine which torrents to seed and which to queue. It is based on │ │ │ │ -the peer to seed ratio from the tracker scrape. For more information, │ │ │ │ -see queuing. Higher value means more important to seed
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
state
│ │ │ │ -
the main state the torrent is in. See torrent_status::state_t.
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

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;
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
message
│ │ │ │ +
if this tracker has returned an error or warning message │ │ │ │ +that message is stored here
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
need_save_resume
│ │ │ │ -
true if this torrent has unsaved changes │ │ │ │ -to its download state and statistics since the last resume data │ │ │ │ -was saved.
│ │ │ │ +[report issue]
│ │ │ │ +
last_error
│ │ │ │ +
if this tracker failed the last time it was contacted │ │ │ │ +this error code specifies what error occurred
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
is_seeding
│ │ │ │ -
true if all pieces have been downloaded.
│ │ │ │ + │ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
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.
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
is_finished
│ │ │ │ -
true if all pieces that have a priority > 0 are downloaded. There is │ │ │ │ -only a distinction between finished and seeding if some pieces or │ │ │ │ -files have been set to priority 0, i.e. are not downloaded.
│ │ │ │ +[report issue]
│ │ │ │ +
fails
│ │ │ │ +
the number of times in a row we have failed to announce to this │ │ │ │ +tracker.
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
has_metadata
│ │ │ │ -
true if this torrent has metadata (either it was started from a │ │ │ │ -.torrent file or the metadata has been downloaded). The only scenario │ │ │ │ -where this can be false is when the torrent was started torrent-less │ │ │ │ -(i.e. with just an info-hash and tracker ip, a magnet link for │ │ │ │ -instance).
│ │ │ │ +[report issue]
│ │ │ │ +
updating
│ │ │ │ +
true while we're waiting for a response from the tracker.
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
has_incoming
│ │ │ │ -
true if there has ever been an incoming connection attempt to this │ │ │ │ -torrent.
│ │ │ │ +[report issue]
│ │ │ │ +
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.
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
moving_storage
│ │ │ │ -
this is true if this torrent's storage is currently being moved from │ │ │ │ -one location to another. This may potentially be a long operation │ │ │ │ -if a large file ends up being copied from one drive to another.
│ │ │ │ +[report issue]
│ │ │ │ +
complete_sent
│ │ │ │ +
set to true when we send a event=completed.
│ │ │ │
│ │ │ │ - │ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
announcing_to_trackers announcing_to_lsd announcing_to_dht
│ │ │ │ -
these are set to true if this torrent is allowed to announce to the │ │ │ │ -respective peer source. Whether they are true or false is determined by │ │ │ │ -the queue logic/auto manager. Torrents that are not auto managed will │ │ │ │ -always be allowed to announce to all peer sources.
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

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;
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
local_endpoint
│ │ │ │ +
the local endpoint of the listen interface associated with this endpoint
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ +[report issue]
│ │ │ │
info_hashes
│ │ │ │ -
the info-hash for this torrent
│ │ │ │ -
│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
last_upload last_download
│ │ │ │ -
the timestamps of the last time this torrent uploaded or downloaded │ │ │ │ -payload to any peer.
│ │ │ │ -
│ │ │ │ - │ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
active_duration finished_duration seeding_duration
│ │ │ │ -
these are cumulative counters of for how long the torrent has been in │ │ │ │ -different states. active means not paused and added to session. Whether │ │ │ │ -it has found any peers or not is not relevant. │ │ │ │ -finished means all selected files/pieces were downloaded and available │ │ │ │ -to other peers (this is always a subset of active time). │ │ │ │ -seeding means all files/pieces were downloaded and available to │ │ │ │ -peers. Being available to peers does not imply there are other peers │ │ │ │ -asking for the payload.
│ │ │ │ +
info_hashes[0] is the v1 info hash (SHA1) │ │ │ │ +info_hashes[1] is the v2 info hash (truncated SHA-256)
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
flags
│ │ │ │ -
reflects several of the torrent's flags. For more │ │ │ │ -information, see torrent_handle::flags().
│ │ │ │ +[report issue]
│ │ │ │ +
enabled
│ │ │ │ +
set to false to not announce from this endpoint
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -

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

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

announce_entry

│ │ │ │ +

Declared in "libtorrent/announce_entry.hpp"

│ │ │ │ +

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

│ │ │ │ 
│ │ │ │ -struct peer_class_type_filter
│ │ │ │ +struct announce_entry
│ │ │ │  {
│ │ │ │ -   void add (socket_type_t const st, peer_class_t const peer_class);
│ │ │ │ -   void remove (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);
│ │ │ │ +   explicit announce_entry (string_view u);
│ │ │ │ +   announce_entry (announce_entry const&);
│ │ │ │ +   announce_entry& operator= (announce_entry const&) &;
│ │ │ │ +   announce_entry ();
│ │ │ │ +   ~announce_entry ();
│ │ │ │  
│ │ │ │ -   enum socket_type_t
│ │ │ │ +   enum tracker_source
│ │ │ │     {
│ │ │ │ -      tcp_socket,
│ │ │ │ -      utp_socket,
│ │ │ │ -      ssl_tcp_socket,
│ │ │ │ -      ssl_utp_socket,
│ │ │ │ -      i2p_socket,
│ │ │ │ -      num_socket_types,
│ │ │ │ +      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;
│ │ │ │  };
│ │ │ │
│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -

add() remove()

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

add() and remove() adds and removes a peer class to be added │ │ │ │ -to new peers based on socket type.

│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

disallow() allow()

│ │ │ │ -
│ │ │ │ -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);
│ │ │ │ -
│ │ │ │ -

disallow() and allow() adds and removes a peer class to be │ │ │ │ -removed from new peers based on socket type.

│ │ │ │ -

The peer_class argument cannot be greater than 31. The bitmasks representing │ │ │ │ -peer classes in the peer_class_type_filter are 32 bits.

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

apply()

│ │ │ │ + │ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +

~announce_entry() announce_entry() operator=()

│ │ │ │ 
│ │ │ │ -std::uint32_t apply (socket_type_t const st, std::uint32_t peer_class_mask);
│ │ │ │ +explicit announce_entry (string_view u);
│ │ │ │ +announce_entry (announce_entry const&);
│ │ │ │ +announce_entry& operator= (announce_entry const&) &;
│ │ │ │ +announce_entry ();
│ │ │ │ +~announce_entry ();
│ │ │ │
│ │ │ │ -

takes a bitmask of peer classes and returns a new bitmask of │ │ │ │ -peer classes after the rules have been applied, based on the socket type argument │ │ │ │ -(st).

│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

enum socket_type_t

│ │ │ │ -

Declared in "libtorrent/peer_class_type_filter.hpp"

│ │ │ │ +

constructs a tracker announce entry with u as the URL.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

enum tracker_source

│ │ │ │ +

Declared in "libtorrent/announce_entry.hpp"

│ │ │ │ │ │ │ │ │ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ + │ │ │ │ + │ │ │ │ + │ │ │ │ │ │ │ │ │ │ │ │
namevaluedescription
tcp_socket0these match the socket types from socket_type.hpp │ │ │ │ -shifted one down
utp_socket
source_torrent1 the tracker was part of the .torrent file
ssl_tcp_socket
source_client2 
ssl_utp_socket3 the tracker was added programmatically via the add_tracker() function
i2p_socket
source_magnet_link4 the tracker was part of a magnet link
num_socket_types5 
source_tex8the tracker was received from the swarm via tracker exchange
│ │ │ │ -[report issue]
│ │ │ │ +[report issue]
│ │ │ │ +
url
│ │ │ │ +
tracker URL as it appeared in the torrent file
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
trackerid
│ │ │ │ +
the current &trackerid= argument passed to the tracker. │ │ │ │ +this is optional and is normally empty (in which case no │ │ │ │ +trackerid is sent).
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
endpoints
│ │ │ │ +
each local listen socket (endpoint) will announce to the tracker. This │ │ │ │ +list contains state per endpoint.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
tier
│ │ │ │ +
the tier this tracker belongs to
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
fail_limit
│ │ │ │ +
the max number of failures to announce to this tracker in │ │ │ │ +a row, before this tracker is not used anymore. 0 means unlimited
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
source
│ │ │ │ +
a bitmask specifying which sources we got this tracker from.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
verified
│ │ │ │ +
set to true the first time we receive a valid response │ │ │ │ +from this tracker.
│ │ │ │ +
│ │ │ │ +

This section describes the functions and classes that are used │ │ │ │ +to create torrent files. It is a layered API with low level classes │ │ │ │ +and higher level convenience functions. A torrent is created in 4 │ │ │ │ +steps:

│ │ │ │ +
    │ │ │ │ +
  1. first the files that will be part of the torrent are determined.
    2. │ │ │ │ +
  2. the torrent properties are set, such as tracker url, web seeds, │ │ │ │ +DHT nodes etc.
    3. │ │ │ │ +
  3. Read through all the files in the torrent, SHA-1 all the data │ │ │ │ +and set the piece hashes.
    4. │ │ │ │ +
  4. The torrent is bencoded into a file or buffer.
    5. │ │ │ │ +
│ │ │ │ +

If there are a lot of files and or deep directory hierarchies to │ │ │ │ +traverse, step one can be time consuming.

│ │ │ │ +

Typically step 3 is by far the most time consuming step, since it │ │ │ │ +requires to read all the bytes from all the files in the torrent.

│ │ │ │ +

All of these classes and functions are declared by including │ │ │ │ +libtorrent/create_torrent.hpp.

│ │ │ │ +

example:

│ │ │ │ +
│ │ │ │ +file_storage fs;
│ │ │ │ +
│ │ │ │ +// recursively adds files in directories
│ │ │ │ +add_files(fs, "./my_torrent");
│ │ │ │ +
│ │ │ │ +create_torrent t(fs);
│ │ │ │ +t.add_tracker("http://my.tracker.com/announce");
│ │ │ │ +t.set_creator("libtorrent example");
│ │ │ │ +
│ │ │ │ +// reads the files and calculates the hashes
│ │ │ │ +set_piece_hashes(t, ".");
│ │ │ │ +
│ │ │ │ +ofstream out("my_torrent.torrent", std::ios_base::binary);
│ │ │ │ +std::vector<char> buf = t.generate_buf();
│ │ │ │ +out.write(buf.data(), buf.size());
│ │ │ │ +
│ │ │ │ +// alternatively, generate an entry and encode it directly to an ostream
│ │ │ │ +// iterator
│ │ │ │ +bencode(std::ostream_iterator<char>(out), t.generate());
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │
│ │ │ │ -
│ │ │ │ -

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.

│ │ │ │ +
│ │ │ │ +

create_torrent

│ │ │ │ +

Declared in "libtorrent/create_torrent.hpp"

│ │ │ │ +

This class holds state for creating a torrent. After having added │ │ │ │ +all information to it, call create_torrent::generate() to generate │ │ │ │ +the torrent. The entry that's returned can then be bencoded into a │ │ │ │ +.torrent file using bencode().

│ │ │ │ 
│ │ │ │ -struct peer_class_info
│ │ │ │ +struct create_torrent
│ │ │ │  {
│ │ │ │ -   bool ignore_unchoke_slots;
│ │ │ │ -   int connection_limit_factor;
│ │ │ │ -   std::string label;
│ │ │ │ -   int upload_limit;
│ │ │ │ -   int download_limit;
│ │ │ │ -   int upload_priority;
│ │ │ │ -   int download_priority;
│ │ │ │ +   explicit create_torrent (file_storage& fs, int piece_size = 0
│ │ │ │ +      , create_flags_t flags = {});
│ │ │ │ +   explicit create_torrent (torrent_info const& ti);
│ │ │ │ +   entry generate () const;
│ │ │ │ +   std::vector<char> generate_buf () const;
│ │ │ │ +   file_storage const& files () const;
│ │ │ │ +   void set_comment (char const* str);
│ │ │ │ +   void set_creator (char const* str);
│ │ │ │ +   void set_creation_date (std::time_t timestamp);
│ │ │ │ +   void set_hash (piece_index_t index, sha1_hash const& h);
│ │ │ │ +   void set_hash2 (file_index_t file, piece_index_t::diff_type piece, sha256_hash const& h);
│ │ │ │ +   void add_http_seed (string_view url);
│ │ │ │ +   void add_url_seed (string_view url);
│ │ │ │ +   void add_node (std::pair<std::string, int> node);
│ │ │ │ +   void add_tracker (string_view url, int tier = 0);
│ │ │ │ +   void set_root_cert (string_view cert);
│ │ │ │ +   bool priv () const;
│ │ │ │ +   void set_priv (bool p);
│ │ │ │ +   bool is_v1_only () const;
│ │ │ │ +   bool is_v2_only () const;
│ │ │ │ +   int num_pieces () const;
│ │ │ │ +   piece_index_t end_piece () const;
│ │ │ │ +   index_range<piece_index_t> piece_range () const noexcept;
│ │ │ │ +   file_index_t end_file () const;
│ │ │ │ +   index_range<file_index_t> file_range () const noexcept;
│ │ │ │ +   index_range<piece_index_t::diff_type> file_piece_range (file_index_t f);
│ │ │ │ +   std::int64_t total_size () const;
│ │ │ │ +   int piece_length () const;
│ │ │ │ +   int piece_size (piece_index_t i) const;
│ │ │ │ +   void add_collection (string_view c);
│ │ │ │ +   void add_similar_torrent (sha1_hash ih);
│ │ │ │ +
│ │ │ │ +   static constexpr create_flags_t modification_time  = 2_bit;
│ │ │ │ +   static constexpr create_flags_t symlinks  = 3_bit;
│ │ │ │ +   static constexpr create_flags_t v2_only  = 5_bit;
│ │ │ │ +   static constexpr create_flags_t v1_only  = 6_bit;
│ │ │ │ +   static constexpr create_flags_t canonical_files  = 7_bit;
│ │ │ │ +   static constexpr create_flags_t no_attributes  = 8_bit;
│ │ │ │ +   static constexpr create_flags_t canonical_files_no_tail_padding  = 9_bit;
│ │ │ │  };
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
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.
│ │ │ │ +[report issue]
│ │ │ │ +

create_torrent()

│ │ │ │ +
│ │ │ │ +explicit create_torrent (file_storage& fs, int piece_size = 0
│ │ │ │ +      , create_flags_t flags = {});
│ │ │ │ +explicit create_torrent (torrent_info const& ti);
│ │ │ │ +
│ │ │ │ +

The piece_size is the size of each piece in bytes. It must be a │ │ │ │ +power of 2 and a minimum of 16 kiB. If a piece size of 0 is │ │ │ │ +specified, a piece_size will be set automatically.

│ │ │ │ +

The flags arguments specifies options for the torrent creation. It can │ │ │ │ +be any combination of the flags defined by create_flags_t.

│ │ │ │ +

The file_storage (fs) parameter defines the files, sizes and │ │ │ │ +their properties for the torrent to be created. Set this up first, │ │ │ │ +before passing it to the create_torrent constructor.

│ │ │ │ +

The overload that takes a torrent_info object will make a verbatim │ │ │ │ +copy of its info dictionary (to preserve the info-hash). The copy of │ │ │ │ +the info dictionary will be used by create_torrent::generate(). This means │ │ │ │ +that none of the member functions of create_torrent that affects │ │ │ │ +the content of the info dictionary (such as set_hash()), will │ │ │ │ +have any affect. Instead of using this overload, consider using │ │ │ │ +write_torrent_file() instead.

│ │ │ │ +
│ │ │ │ +

Warning

│ │ │ │ +

The file_storage and torrent_info objects must stay alive for the │ │ │ │ +entire duration of the create_torrent object.

│ │ │ │ +
│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

generate() generate_buf()

│ │ │ │ +
│ │ │ │ +entry generate () const;
│ │ │ │ +std::vector<char> generate_buf () const;
│ │ │ │ +
│ │ │ │ +

This function will generate the .torrent file as a bencode tree, or a │ │ │ │ +bencoded into a buffer. │ │ │ │ +In order to encode the entry into a flat file, use the bencode() function.

│ │ │ │ +

The function returning an entry may be useful to add custom entries │ │ │ │ +to the torrent file before bencoding it and saving it to disk.

│ │ │ │ +

Whether the resulting torrent object is v1, v2 or hybrid depends on │ │ │ │ +whether any of the v1_only or v2_only flags were set on the │ │ │ │ +constructor. If neither were set, the resulting torrent depends on │ │ │ │ +which hashes were set. If both v1 and v2 hashes were set, a hybrid │ │ │ │ +torrent is created.

│ │ │ │ +

Any failure will cause this function to throw system_error, with an │ │ │ │ +appropriate error message. These are the reasons this call may throw:

│ │ │ │ +
    │ │ │ │ +
  • the file storage has 0 files
    • │ │ │ │ +
  • the total size of the file storage is 0 bytes (i.e. it only has │ │ │ │ +empty files)
    • │ │ │ │ +
  • not all v1 hashes (set_hash()) and not all v2 hashes (set_hash2()) │ │ │ │ +were set
    • │ │ │ │ +
  • for v2 torrents, you may not have a directory with the same name as │ │ │ │ +a file. If that's encountered in the file storage, generate() │ │ │ │ +fails.
    • │ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

files()

│ │ │ │ +
│ │ │ │ +file_storage const& files () const;
│ │ │ │ +
│ │ │ │ +

returns an immutable reference to the file_storage used to create │ │ │ │ +the torrent from.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

set_comment()

│ │ │ │ +
│ │ │ │ +void set_comment (char const* str);
│ │ │ │ +
│ │ │ │ +

Sets the comment for the torrent. The string str should be utf-8 encoded. │ │ │ │ +The comment in a torrent file is optional.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

set_creator()

│ │ │ │ +
│ │ │ │ +void set_creator (char const* str);
│ │ │ │ +
│ │ │ │ +

Sets the creator of the torrent. The string str should be utf-8 encoded. │ │ │ │ +This is optional.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

set_creation_date()

│ │ │ │ +
│ │ │ │ +void set_creation_date (std::time_t timestamp);
│ │ │ │ +
│ │ │ │ +

sets the "creation time" field. Defaults to the system clock at the │ │ │ │ +time of construction of the create_torrent object. The timestamp is │ │ │ │ +specified in seconds, posix time. If the creation date is set to 0, │ │ │ │ +the "creation date" field will be omitted from the generated torrent.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

set_hash()

│ │ │ │ +
│ │ │ │ +void set_hash (piece_index_t index, sha1_hash const& h);
│ │ │ │ +
│ │ │ │ +

This sets the SHA-1 hash for the specified piece (index). You are required │ │ │ │ +to set the hash for every piece in the torrent before generating it. If you have │ │ │ │ +the files on disk, you can use the high level convenience function to do this. │ │ │ │ +See set_piece_hashes(). │ │ │ │ +A SHA-1 hash of all zeros is internally used to indicate a hash that │ │ │ │ +has not been set. Setting such hash will not be considered set when │ │ │ │ +calling generate(). │ │ │ │ +This function will throw std::system_error if it is called on an │ │ │ │ +object constructed with the v2_only flag.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

set_hash2()

│ │ │ │ +
│ │ │ │ +void set_hash2 (file_index_t file, piece_index_t::diff_type piece, sha256_hash const& h);
│ │ │ │ +
│ │ │ │ +

sets the bittorrent v2 hash for file file of the piece piece. │ │ │ │ +piece is relative to the first piece of the file, starting at 0. The │ │ │ │ +first piece in the file can be computed with │ │ │ │ +file_storage::file_index_at_piece(). │ │ │ │ +The hash, h, is the root of the merkle tree formed by the piece's │ │ │ │ +16 kiB blocks. Note that piece sizes must be powers-of-2, so all │ │ │ │ +per-piece merkle trees are complete. │ │ │ │ +A SHA-256 hash of all zeros is internally used to indicate a hash │ │ │ │ +that has not been set. Setting such hash will not be considered set │ │ │ │ +when calling generate(). │ │ │ │ +This function will throw std::system_error if it is called on an │ │ │ │ +object constructed with the v1_only flag.

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

add_http_seed() add_url_seed()

│ │ │ │ +
│ │ │ │ +void add_http_seed (string_view url);
│ │ │ │ +void add_url_seed (string_view url);
│ │ │ │ +
│ │ │ │ +

This adds a url seed to the torrent. You can have any number of url seeds. For a │ │ │ │ +single file torrent, this should be an HTTP url, pointing to a file with identical │ │ │ │ +content as the file of the torrent. For a multi-file torrent, it should point to │ │ │ │ +a directory containing a directory with the same name as this torrent, and all the │ │ │ │ +files of the torrent in it.

│ │ │ │ +

The second function, add_http_seed() adds an HTTP seed instead.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

add_node()

│ │ │ │ +
│ │ │ │ +void add_node (std::pair<std::string, int> node);
│ │ │ │ +
│ │ │ │ +

This adds a DHT node to the torrent. This especially useful if you're creating a │ │ │ │ +tracker less torrent. It can be used by clients to bootstrap their DHT node from. │ │ │ │ +The node is a hostname and a port number where there is a DHT node running. │ │ │ │ +You can have any number of DHT nodes in a torrent.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

add_tracker()

│ │ │ │ +
│ │ │ │ +void add_tracker (string_view url, int tier = 0);
│ │ │ │ +
│ │ │ │ +

Adds a tracker to the torrent. This is not strictly required, but most torrents │ │ │ │ +use a tracker as their main source of peers. The url should be an http:// or udp:// │ │ │ │ +url to a machine running a bittorrent tracker that accepts announces for this torrent's │ │ │ │ +info-hash. The tier is the fallback priority of the tracker. All trackers with tier 0 are │ │ │ │ +tried first (in any order). If all fail, trackers with tier 1 are tried. If all of those │ │ │ │ +fail, trackers with tier 2 are tried, and so on.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

set_root_cert()

│ │ │ │ +
│ │ │ │ +void set_root_cert (string_view cert);
│ │ │ │ +
│ │ │ │ +

This function sets an X.509 certificate in PEM format to the torrent. This makes the │ │ │ │ +torrent an SSL torrent. An SSL torrent requires that each peer has a valid certificate │ │ │ │ +signed by this root certificate. For SSL torrents, all peers are connecting over SSL │ │ │ │ +connections. For more information, see the section on ssl torrents.

│ │ │ │ +

The string is not the path to the cert, it's the actual content of the │ │ │ │ +certificate.

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

priv() set_priv()

│ │ │ │ +
│ │ │ │ +bool priv () const;
│ │ │ │ +void set_priv (bool p);
│ │ │ │ +
│ │ │ │ +

Sets and queries the private flag of the torrent. │ │ │ │ +Torrents with the private flag set ask the client to not use any other │ │ │ │ +sources than the tracker for peers, and to not use DHT to advertise itself publicly, │ │ │ │ +only the tracker.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

num_pieces()

│ │ │ │ +
│ │ │ │ +int num_pieces () const;
│ │ │ │ +
│ │ │ │ +

returns the number of pieces in the associated file_storage object.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

piece_range()

│ │ │ │ +
│ │ │ │ +index_range<piece_index_t> piece_range () const noexcept;
│ │ │ │ +
│ │ │ │ +

all piece indices in the torrent to be created

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

file_range()

│ │ │ │ +
│ │ │ │ +index_range<file_index_t> file_range () const noexcept;
│ │ │ │ +
│ │ │ │ +

all file indices in the torrent to be created

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

file_piece_range()

│ │ │ │ +
│ │ │ │ +index_range<piece_index_t::diff_type> file_piece_range (file_index_t f);
│ │ │ │ +
│ │ │ │ +

for v2 and hybrid torrents only, the pieces in the │ │ │ │ +specified file, specified as delta from the first piece in the file. │ │ │ │ +i.e. the first index is 0.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

total_size()

│ │ │ │ +
│ │ │ │ +std::int64_t total_size () const;
│ │ │ │ +
│ │ │ │ +

the total number of bytes of all files and pad files

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

piece_size() piece_length()

│ │ │ │ +
│ │ │ │ +int piece_length () const;
│ │ │ │ +int piece_size (piece_index_t i) const;
│ │ │ │ +
│ │ │ │ +

piece_length() returns the piece size of all pieces but the │ │ │ │ +last one. piece_size() returns the size of the specified piece. │ │ │ │ +these functions are just forwarding to the associated file_storage.

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

add_similar_torrent() add_collection()

│ │ │ │ +
│ │ │ │ +void add_collection (string_view c);
│ │ │ │ +void add_similar_torrent (sha1_hash ih);
│ │ │ │ +
│ │ │ │ +

Add similar torrents (by info-hash) or collections of similar torrents. │ │ │ │ +Similar torrents are expected to share some files with this torrent. │ │ │ │ +Torrents sharing a collection name with this torrent are also expected │ │ │ │ +to share files with this torrent. A torrent may have more than one │ │ │ │ +collection and more than one similar torrents. For more information, │ │ │ │ +see BEP 38.

│ │ │ │ +[report issue]
│ │ │ │ +
modification_time
│ │ │ │ +
This will include the file modification time as part of the torrent. │ │ │ │ +This is not enabled by default, as it might cause problems when you │ │ │ │ +create a torrent from separate files with the same content, hoping to │ │ │ │ +yield the same info-hash. If the files have different modification times, │ │ │ │ +with this option enabled, you would get different info-hashes for the │ │ │ │ +files.
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
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.
│ │ │ │ +[report issue]
│ │ │ │ +
symlinks
│ │ │ │ +
If this flag is set, files that are symlinks get a symlink attribute │ │ │ │ +set on them and their data will not be included in the torrent. This │ │ │ │ +is useful if you need to reconstruct a file hierarchy which contains │ │ │ │ +symlinks.
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
label
│ │ │ │ -
not used by libtorrent. It's intended as a potentially user-facing │ │ │ │ -identifier of this peer class.
│ │ │ │ +[report issue]
│ │ │ │ +
v2_only
│ │ │ │ +
Do not generate v1 metadata. The resulting torrent will only be usable by │ │ │ │ +clients which support v2. This requires setting all v2 hashes, with │ │ │ │ +set_hash2() before calling generate(). Setting v1 hashes (with │ │ │ │ +set_hash()) is an error with this flag set.
│ │ │ │
│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
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.
│ │ │ │ +[report issue]
│ │ │ │ +
v1_only
│ │ │ │ +
do not generate v2 metadata or enforce v2 alignment and padding rules │ │ │ │ +this is mainly for tests, not recommended for production use. This │ │ │ │ +requires setting all v1 hashes, with set_hash(), before calling │ │ │ │ +generate(). Setting v2 hashes (with set_hash2()) is an error with │ │ │ │ +this flag set.
│ │ │ │
│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
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.
│ │ │ │ +[report issue]
│ │ │ │ +
canonical_files
│ │ │ │ +
This flag only affects v1-only torrents, and is only relevant │ │ │ │ +together with the v1_only_flag. This flag will force the │ │ │ │ +same file order and padding as a v2 (or hybrid) torrent would have. │ │ │ │ +It has the effect of ordering files and inserting pad files to align │ │ │ │ +them with piece boundaries.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
no_attributes
│ │ │ │ +
passing this flag to add_files() will ignore file attributes (such as │ │ │ │ +executable or hidden) when adding the files to the file storage. │ │ │ │ +Since not all filesystems and operating systems support all file │ │ │ │ +attributes the resulting torrent may differ depending on where it's │ │ │ │ +created. If it's important for torrents to be created consistently │ │ │ │ +across systems, this flag should be set.
│ │ │ │
│ │ │ │ +[report issue]
│ │ │ │ +
canonical_files_no_tail_padding
│ │ │ │ +
this flag enforces the file layout to be canonical according to the │ │ │ │ +bittorrent v2 specification (just like the canonical_files flag) │ │ │ │ +with the one exception that tail padding is not added to the last │ │ │ │ +file. │ │ │ │ +This behavior deviates from the specification but was the way │ │ │ │ +libtorrent created torrents in version up to and including 2.0.7. │ │ │ │ +This flag is here for backwards compatibility.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +

add_files()

│ │ │ │ +

Declared in "libtorrent/create_torrent.hpp"

│ │ │ │ +
│ │ │ │ +void add_files (file_storage& fs, std::string const& file
│ │ │ │ +   , create_flags_t flags = {});
│ │ │ │ +void add_files (file_storage& fs, std::string const& file
│ │ │ │ +   , std::function<bool(std::string)> p, create_flags_t flags = {});
│ │ │ │ +
│ │ │ │ +

Adds the file specified by path to the file_storage object. In case path │ │ │ │ +refers to a directory, files will be added recursively from the directory.

│ │ │ │ +

If specified, the predicate p is called once for every file and directory that │ │ │ │ +is encountered. Files for which p returns true are added, and directories for │ │ │ │ +which p returns true are traversed. p must have the following signature:

│ │ │ │ +
│ │ │ │ +bool Pred(std::string const& p);
│ │ │ │ +
│ │ │ │ +

The path that is passed in to the predicate is the full path of the file or │ │ │ │ +directory. If no predicate is specified, all files are added, and all directories │ │ │ │ +are traversed.

│ │ │ │ +

The ".." directory is never traversed.

│ │ │ │ +

The flags argument should be the same as the flags passed to the create_torrent │ │ │ │ +constructor.

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

set_piece_hashes()

│ │ │ │ +

Declared in "libtorrent/create_torrent.hpp"

│ │ │ │ +
│ │ │ │ +void set_piece_hashes (create_torrent& t, std::string const& p
│ │ │ │ +   , settings_interface const& settings, disk_io_constructor_type disk_io
│ │ │ │ +   , std::function<void(piece_index_t)> const& f, error_code& ec);
│ │ │ │ +inline void set_piece_hashes (create_torrent& t, std::string const& p
│ │ │ │ +   , settings_interface const& settings
│ │ │ │ +   , std::function<void(piece_index_t)> const& f);
│ │ │ │ +void set_piece_hashes (create_torrent& t, std::string const& p
│ │ │ │ +   , settings_interface const& settings
│ │ │ │ +   , std::function<void(piece_index_t)> const& f, error_code& ec);
│ │ │ │ +void set_piece_hashes (create_torrent& t, std::string const& p
│ │ │ │ +   , std::function<void(piece_index_t)> const& f, error_code& ec);
│ │ │ │ +inline void set_piece_hashes (create_torrent& t, std::string const& p
│ │ │ │ +   , std::function<void(piece_index_t)> const& f);
│ │ │ │ +inline void set_piece_hashes (create_torrent& t, std::string const& p);
│ │ │ │ +inline void set_piece_hashes (create_torrent& t, std::string const& p, error_code& ec);
│ │ │ │ +
│ │ │ │ +

This function will assume that the files added to the torrent file exists at path │ │ │ │ +p, read those files and hash the content and set the hashes in the create_torrent │ │ │ │ +object. The optional function f is called in between every hash that is set. f │ │ │ │ +must have the following signature:

│ │ │ │ +
│ │ │ │ +void Fun(piece_index_t);
│ │ │ │ +
│ │ │ │ +

The overloads taking a settings_pack may be used to configure the │ │ │ │ +underlying disk access. Such as settings_pack::aio_threads.

│ │ │ │ +

The overloads that don't take an error_code& may throw an exception in case of a │ │ │ │ +file error, the other overloads sets the error code to reflect the error, if any.

│ │ │ │ [report issue]
│ │ │ │
│ │ │ │

block_info

│ │ │ │

Declared in "libtorrent/torrent_handle.hpp"

│ │ │ │

holds the state of a block in a piece. Who we requested │ │ │ │ it from and how far along we are at downloading it.

│ │ │ │ 
│ │ │ │  struct block_info
│ │ │ │  {
│ │ │ │ -   void set_peer (tcp::endpoint const& ep);
│ │ │ │     tcp::endpoint peer () const;
│ │ │ │ +   void set_peer (tcp::endpoint const& ep);
│ │ │ │  
│ │ │ │     enum block_state_t
│ │ │ │     {
│ │ │ │        none,
│ │ │ │        requested,
│ │ │ │        writing,
│ │ │ │        finished,
│ │ │ │ @@ -17127,20 +18414,20 @@
│ │ │ │  
│ │ │ │     unsigned bytes_progress:15;
│ │ │ │     unsigned block_size:15;
│ │ │ │     unsigned state:2;
│ │ │ │     unsigned num_peers:14;
│ │ │ │  };
│ │ │ │
│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -

peer() set_peer()

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +

set_peer() peer()

│ │ │ │ 
│ │ │ │ -void set_peer (tcp::endpoint const& ep);
│ │ │ │  tcp::endpoint peer () const;
│ │ │ │ +void set_peer (tcp::endpoint const& ep);
│ │ │ │
│ │ │ │

The peer is the ip address of the peer this block was downloaded from.

│ │ │ │ [report issue]
│ │ │ │
│ │ │ │

enum block_state_t

│ │ │ │

Declared in "libtorrent/torrent_handle.hpp"

│ │ │ │ │ │ │ │ @@ -17268,109 +18555,109 @@ │ │ │ │ Which means you cannot perform any operation on it, unless you first │ │ │ │ assign it a valid handle. If you try to perform any operation on an │ │ │ │ uninitialized handle, it will throw invalid_handle.

│ │ │ │
│ │ │ │

Warning

│ │ │ │

All operations on a torrent_handle may throw system_error │ │ │ │ exception, in case the handle is no longer referring to a torrent. │ │ │ │ -There is one exception is_valid() will never throw. Since the torrents │ │ │ │ +There is one exception is_valid() will never throw. Since the torrents │ │ │ │ are processed by a background thread, there is no guarantee that a │ │ │ │ handle will remain valid between two calls.

│ │ │ │
│ │ │ │ 
│ │ │ │  struct torrent_handle
│ │ │ │  {
│ │ │ │     friend std::size_t hash_value (torrent_handle const& th);
│ │ │ │     torrent_handle () noexcept = default;
│ │ │ │ -   void add_piece (piece_index_t piece, std::vector<char> data, add_piece_flags_t flags = {}) const;
│ │ │ │     void add_piece (piece_index_t piece, char const* data, add_piece_flags_t flags = {}) const;
│ │ │ │ +   void add_piece (piece_index_t piece, std::vector<char> data, add_piece_flags_t flags = {}) const;
│ │ │ │     void read_piece (piece_index_t piece) const;
│ │ │ │     bool have_piece (piece_index_t piece) const;
│ │ │ │     void get_peer_info (std::vector<peer_info>& v) const;
│ │ │ │     torrent_status status (status_flags_t flags = status_flags_t::all()) const;
│ │ │ │ -   std::vector<partial_piece_info> get_download_queue () const;
│ │ │ │     void get_download_queue (std::vector<partial_piece_info>& queue) const;
│ │ │ │ -   void reset_piece_deadline (piece_index_t index) const;
│ │ │ │ -   void clear_piece_deadlines () const;
│ │ │ │ +   std::vector<partial_piece_info> get_download_queue () const;
│ │ │ │     void set_piece_deadline (piece_index_t index, int deadline, deadline_flags_t flags = {}) const;
│ │ │ │ -   std::vector<std::int64_t> file_progress (file_progress_flags_t flags = {}) const;
│ │ │ │ +   void clear_piece_deadlines () const;
│ │ │ │ +   void reset_piece_deadline (piece_index_t index) const;
│ │ │ │     void file_progress (std::vector<std::int64_t>& progress, file_progress_flags_t flags = {}) const;
│ │ │ │ +   std::vector<std::int64_t> file_progress (file_progress_flags_t flags = {}) const;
│ │ │ │     std::vector<open_file_state> file_status () const;
│ │ │ │     void clear_error () const;
│ │ │ │     void add_tracker (announce_entry const&) const;
│ │ │ │ -   void replace_trackers (std::vector<announce_entry> const&) const;
│ │ │ │     std::vector<announce_entry> trackers () const;
│ │ │ │ +   void replace_trackers (std::vector<announce_entry> const&) const;
│ │ │ │     void remove_url_seed (std::string const& url) const;
│ │ │ │     std::set<std::string> url_seeds () const;
│ │ │ │     void add_url_seed (std::string const& url) const;
│ │ │ │ -   void add_http_seed (std::string const& url) const;
│ │ │ │ -   std::set<std::string> http_seeds () const;
│ │ │ │     void remove_http_seed (std::string const& url) const;
│ │ │ │ +   std::set<std::string> http_seeds () const;
│ │ │ │ +   void add_http_seed (std::string const& url) const;
│ │ │ │     void add_extension (
│ │ │ │        std::function<std::shared_ptr<torrent_plugin>(torrent_handle const&, client_data_t)> const& ext
│ │ │ │        , client_data_t userdata = client_data_t{});
│ │ │ │     bool set_metadata (span<char const> metadata) const;
│ │ │ │     bool is_valid () const;
│ │ │ │     void resume () const;
│ │ │ │     void pause (pause_flags_t flags = {}) const;
│ │ │ │ -   void set_flags (torrent_flags_t flags) const;
│ │ │ │     void unset_flags (torrent_flags_t flags) const;
│ │ │ │     void set_flags (torrent_flags_t flags, torrent_flags_t mask) const;
│ │ │ │     torrent_flags_t flags () const;
│ │ │ │ +   void set_flags (torrent_flags_t flags) const;
│ │ │ │     void flush_cache () const;
│ │ │ │     void force_recheck () const;
│ │ │ │     void save_resume_data (resume_data_flags_t flags = {}) const;
│ │ │ │     bool need_save_resume_data () const;
│ │ │ │ -   void queue_position_down () const;
│ │ │ │ -   queue_position_t queue_position () const;
│ │ │ │     void queue_position_bottom () const;
│ │ │ │ -   void queue_position_top () const;
│ │ │ │     void queue_position_up () const;
│ │ │ │ +   void queue_position_top () const;
│ │ │ │ +   queue_position_t queue_position () const;
│ │ │ │ +   void queue_position_down () const;
│ │ │ │     void queue_position_set (queue_position_t p) const;
│ │ │ │ +   void set_ssl_certificate_buffer (std::string const& certificate
│ │ │ │ +      , std::string const& private_key
│ │ │ │ +      , std::string const& dh_params);
│ │ │ │     void set_ssl_certificate (std::string const& certificate
│ │ │ │        , std::string const& private_key
│ │ │ │        , std::string const& dh_params
│ │ │ │        , std::string const& passphrase = "");
│ │ │ │ -   void set_ssl_certificate_buffer (std::string const& certificate
│ │ │ │ -      , std::string const& private_key
│ │ │ │ -      , std::string const& dh_params);
│ │ │ │     std::shared_ptr<const torrent_info> torrent_file () const;
│ │ │ │     std::shared_ptr<torrent_info> torrent_file_with_hashes () const;
│ │ │ │     std::vector<std::vector<sha256_hash>> piece_layers () const;
│ │ │ │     void piece_availability (std::vector<int>& avail) const;
│ │ │ │     std::vector<download_priority_t> get_piece_priorities () const;
│ │ │ │     void piece_priority (piece_index_t index, download_priority_t priority) const;
│ │ │ │ -   void prioritize_pieces (std::vector<std::pair<piece_index_t, download_priority_t>> const& pieces) const;
│ │ │ │     download_priority_t piece_priority (piece_index_t index) const;
│ │ │ │     void prioritize_pieces (std::vector<download_priority_t> const& pieces) const;
│ │ │ │ -   void file_priority (file_index_t index, download_priority_t priority) const;
│ │ │ │ +   void prioritize_pieces (std::vector<std::pair<piece_index_t, download_priority_t>> const& pieces) const;
│ │ │ │     std::vector<download_priority_t> get_file_priorities () const;
│ │ │ │ +   void file_priority (file_index_t index, download_priority_t priority) const;
│ │ │ │     void prioritize_files (std::vector<download_priority_t> const& files) const;
│ │ │ │     download_priority_t file_priority (file_index_t index) const;
│ │ │ │ -   void force_lsd_announce () const;
│ │ │ │     void force_reannounce (int seconds = 0, int idx = -1, reannounce_flags_t = {}) const;
│ │ │ │     void force_dht_announce () const;
│ │ │ │ +   void force_lsd_announce () const;
│ │ │ │     void scrape_tracker (int idx = -1) const;
│ │ │ │ -   int download_limit () const;
│ │ │ │ -   void set_upload_limit (int limit) const;
│ │ │ │     void set_download_limit (int limit) const;
│ │ │ │ +   void set_upload_limit (int limit) const;
│ │ │ │ +   int download_limit () const;
│ │ │ │     int upload_limit () const;
│ │ │ │     void connect_peer (tcp::endpoint const& adr, peer_source_flags_t source = {}
│ │ │ │        , pex_flags_t flags = pex_encryption | pex_utp | pex_holepunch) const;
│ │ │ │     void clear_peers ();
│ │ │ │     int max_uploads () const;
│ │ │ │     void set_max_uploads (int max_uploads) const;
│ │ │ │     int max_connections () const;
│ │ │ │     void set_max_connections (int max_connections) const;
│ │ │ │     void move_storage (std::string const& save_path
│ │ │ │        , move_flags_t flags = move_flags_t::always_replace_files
│ │ │ │        ) const;
│ │ │ │     void rename_file (file_index_t index, std::string const& new_name) const;
│ │ │ │ -   sha1_hash info_hash () const;
│ │ │ │     info_hash_t info_hashes () const;
│ │ │ │ +   sha1_hash info_hash () const;
│ │ │ │     bool operator< (const torrent_handle& h) const;
│ │ │ │     bool operator== (const torrent_handle& h) const;
│ │ │ │     bool operator!= (const torrent_handle& h) const;
│ │ │ │     std::uint32_t id () const;
│ │ │ │     std::shared_ptr<torrent> native_handle () const;
│ │ │ │     client_data_t userdata () const;
│ │ │ │     bool in_session () const;
│ │ │ │ @@ -17395,21 +18682,21 @@
│ │ │ │
│ │ │ │ [report issue]
│ │ │ │

torrent_handle()

│ │ │ │ 
│ │ │ │  torrent_handle () noexcept = default;
│ │ │ │
│ │ │ │

constructs a torrent handle that does not refer to a torrent. │ │ │ │ -i.e. is_valid() will return false.

│ │ │ │ +i.e. is_valid() will return false.

│ │ │ │ [report issue]
│ │ │ │
│ │ │ │

add_piece()

│ │ │ │ 
│ │ │ │ -void add_piece (piece_index_t piece, std::vector<char> data, add_piece_flags_t flags = {}) const;
│ │ │ │  void add_piece (piece_index_t piece, char const* data, add_piece_flags_t flags = {}) const;
│ │ │ │ +void add_piece (piece_index_t piece, std::vector<char> data, add_piece_flags_t flags = {}) const;
│ │ │ │
│ │ │ │

This function will write data to the storage as piece piece, │ │ │ │ as if it had been downloaded from a peer.

│ │ │ │

By default, data that's already been downloaded is not overwritten by │ │ │ │ this buffer. If you trust this data to be correct (and pass the piece │ │ │ │ hash check) you may pass the overwrite_existing flag. This will │ │ │ │ instruct libtorrent to overwrite any data that may already have been │ │ │ │ @@ -17476,30 +18763,30 @@ │ │ │ │ filter them out.

│ │ │ │

By default everything is included. The flags you can use to decide │ │ │ │ what to include are defined in this class.

│ │ │ │ [report issue]
│ │ │ │
│ │ │ │

get_download_queue()

│ │ │ │ 
│ │ │ │ -std::vector<partial_piece_info> get_download_queue () const;
│ │ │ │  void get_download_queue (std::vector<partial_piece_info>& queue) const;
│ │ │ │ +std::vector<partial_piece_info> get_download_queue () const;
│ │ │ │
│ │ │ │

get_download_queue() returns a vector with information about pieces │ │ │ │ that are partially downloaded or not downloaded but partially │ │ │ │ requested. See partial_piece_info for the fields in the returned │ │ │ │ vector.

│ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

clear_piece_deadlines() set_piece_deadline() reset_piece_deadline()

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

reset_piece_deadline() set_piece_deadline() clear_piece_deadlines()

│ │ │ │ 
│ │ │ │ -void reset_piece_deadline (piece_index_t index) const;
│ │ │ │ -void clear_piece_deadlines () const;
│ │ │ │  void set_piece_deadline (piece_index_t index, int deadline, deadline_flags_t flags = {}) const;
│ │ │ │ +void clear_piece_deadlines () const;
│ │ │ │ +void reset_piece_deadline (piece_index_t index) const;
│ │ │ │
│ │ │ │

This function sets or resets the deadline associated with a specific │ │ │ │ piece index (index). libtorrent will attempt to download this │ │ │ │ entire piece before the deadline expires. This is not necessarily │ │ │ │ possible, but pieces with a more recent deadline will always be │ │ │ │ prioritized over pieces with a deadline further ahead in time. The │ │ │ │ deadline (and flags) of a piece can be changed by calling this │ │ │ │ @@ -17514,16 +18801,16 @@ │ │ │ │ priority.

│ │ │ │

clear_piece_deadlines() removes deadlines on all pieces in │ │ │ │ the torrent. As if reset_piece_deadline() was called on all pieces.

│ │ │ │ [report issue]
│ │ │ │
│ │ │ │

file_progress()

│ │ │ │ 
│ │ │ │ -std::vector<std::int64_t> file_progress (file_progress_flags_t flags = {}) const;
│ │ │ │  void file_progress (std::vector<std::int64_t>& progress, file_progress_flags_t flags = {}) const;
│ │ │ │ +std::vector<std::int64_t> file_progress (file_progress_flags_t flags = {}) const;
│ │ │ │
│ │ │ │

This function fills in the supplied vector, or returns a vector, with │ │ │ │ the number of bytes downloaded of each file in this torrent. The │ │ │ │ progress values are ordered the same as the files in the │ │ │ │ torrent_info.

│ │ │ │

This operation is not very cheap. Its complexity is O(n + mj). │ │ │ │ Where n is the number of files, m is the number of currently │ │ │ │ @@ -17559,16 +18846,16 @@ │ │ │ │ │ │ │ │ │ │ │ │ [report issue]

│ │ │ │
│ │ │ │

trackers() replace_trackers() add_tracker()

│ │ │ │ 
│ │ │ │  void add_tracker (announce_entry const&) const;
│ │ │ │ -void replace_trackers (std::vector<announce_entry> const&) const;
│ │ │ │  std::vector<announce_entry> trackers () const;
│ │ │ │ +void replace_trackers (std::vector<announce_entry> const&) const;
│ │ │ │
│ │ │ │

trackers() will return the list of trackers for this torrent. The │ │ │ │ announce entry contains both a string url which specify the │ │ │ │ announce url for the tracker as well as an int tier, which is │ │ │ │ specifies the order in which this tracker is tried. If you want │ │ │ │ libtorrent to use another list of trackers for this torrent, you can │ │ │ │ use replace_trackers() which takes a list of the same form as the │ │ │ │ @@ -17578,19 +18865,19 @@ │ │ │ │

add_tracker() will look if the specified tracker is already in the │ │ │ │ set. If it is, it doesn't do anything. If it's not in the current set │ │ │ │ of trackers, it will insert it in the tier specified in the │ │ │ │ announce_entry.

│ │ │ │

The updated set of trackers will be saved in the resume data, and when │ │ │ │ a torrent is started with resume data, the trackers from the resume │ │ │ │ data will replace the original ones.

│ │ │ │ - │ │ │ │ + │ │ │ │ │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

add_url_seed() url_seeds() remove_url_seed()

│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

remove_url_seed() url_seeds() add_url_seed()

│ │ │ │ 
│ │ │ │  void remove_url_seed (std::string const& url) const;
│ │ │ │  std::set<std::string> url_seeds () const;
│ │ │ │  void add_url_seed (std::string const& url) const;
│ │ │ │
│ │ │ │

add_url_seed() adds another url to the torrent's list of url │ │ │ │ seeds. If the given url already exists in that list, the call has no │ │ │ │ @@ -17603,17 +18890,17 @@ │ │ │ │

See http seeding for more information.

│ │ │ │ │ │ │ │ │ │ │ │ [report issue]
│ │ │ │
│ │ │ │

http_seeds() add_http_seed() remove_http_seed()

│ │ │ │ 
│ │ │ │ -void add_http_seed (std::string const& url) const;
│ │ │ │ -std::set<std::string> http_seeds () const;
│ │ │ │  void remove_http_seed (std::string const& url) const;
│ │ │ │ +std::set<std::string> http_seeds () const;
│ │ │ │ +void add_http_seed (std::string const& url) const;
│ │ │ │
│ │ │ │

These functions are identical as the *_url_seed() variants, but │ │ │ │ they operate on BEP 17 web seeds instead of BEP 19.

│ │ │ │

See http seeding for more information.

│ │ │ │ [report issue]
│ │ │ │
│ │ │ │

add_extension()

│ │ │ │ @@ -17649,24 +18936,24 @@ │ │ │ │

Returns true if this handle refers to a valid torrent and false if it │ │ │ │ hasn't been initialized or if the torrent it refers to has been │ │ │ │ removed from the session AND destructed.

│ │ │ │

To tell if the torrent_handle is in the session, use │ │ │ │ torrent_handle::in_session(). This will return true before │ │ │ │ session_handle::remove_torrent() is called, and false │ │ │ │ afterward.

│ │ │ │ -

Clients should only use is_valid() to determine if the result of │ │ │ │ +

Clients should only use is_valid() to determine if the result of │ │ │ │ session::find_torrent() was successful.

│ │ │ │ -

Unlike other member functions which return a value, is_valid() │ │ │ │ +

Unlike other member functions which return a value, is_valid() │ │ │ │ completes immediately, without blocking on a result from the │ │ │ │ network thread. Also unlike other functions, it never throws │ │ │ │ the system_error exception.

│ │ │ │ - │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

resume() pause()

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

pause() resume()

│ │ │ │ 
│ │ │ │  void resume () const;
│ │ │ │  void pause (pause_flags_t flags = {}) const;
│ │ │ │
│ │ │ │

pause(), and resume() will disconnect all peers and reconnect │ │ │ │ all peers respectively. When a torrent is paused, it will however │ │ │ │ remember all share ratios to all peers and remember all potential (not │ │ │ │ @@ -17680,24 +18967,24 @@ │ │ │ │

│ │ │ │

Note

│ │ │ │

Torrents that are auto-managed may be automatically resumed again. It │ │ │ │ does not make sense to pause an auto-managed torrent without making it │ │ │ │ not auto-managed first. Torrents are auto-managed by default when added │ │ │ │ to the session. For more information, see queuing.

│ │ │ │
│ │ │ │ - │ │ │ │ │ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -

set_flags() unset_flags() flags()

│ │ │ │ + │ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +

unset_flags() set_flags() flags()

│ │ │ │ 
│ │ │ │ -void set_flags (torrent_flags_t flags) const;
│ │ │ │  void unset_flags (torrent_flags_t flags) const;
│ │ │ │  void set_flags (torrent_flags_t flags, torrent_flags_t mask) const;
│ │ │ │  torrent_flags_t flags () const;
│ │ │ │ +void set_flags (torrent_flags_t flags) const;
│ │ │ │
│ │ │ │

sets and gets the torrent state flags. See torrent_flags_t. │ │ │ │ The set_flags overload that take a mask will affect all │ │ │ │ flags part of the mask, and set their values to what the │ │ │ │ flags argument is set to. This allows clearing and │ │ │ │ setting flags in a single function call. │ │ │ │ The set_flags overload that just takes flags, sets all │ │ │ │ @@ -17756,15 +19043,15 @@ │ │ │ │

  • No torrent state has changed since the last saving of resume │ │ │ │ data, and the only_if_modified flag is set. │ │ │ │ metadata (see libtorrent's metadata from peers extension)
    • │ │ │ │ │ │ │ │ │ │ │ │

    Note that some counters may be outdated by the time you receive the fast resume data

    │ │ │ │

    When saving resume data because of shutting down, make sure not to │ │ │ │ -remove_torrent() before you receive the save_resume_data_alert. │ │ │ │ +remove_torrent() before you receive the save_resume_data_alert. │ │ │ │ There's no need to pause the session or torrent when saving resume │ │ │ │ data.

    │ │ │ │

    The paused state of a torrent is saved in the resume data, so pausing │ │ │ │ all torrents before saving resume data will all torrents be restored │ │ │ │ in a paused state.

    │ │ │ │
    │ │ │ │

    Note

    │ │ │ │ @@ -17848,27 +19135,27 @@ │ │ │ │
    │ │ │ │

    Note

    │ │ │ │

    A torrent's resume data is considered saved as soon as the │ │ │ │ save_resume_data_alert is posted. It is important to make sure this │ │ │ │ alert is received and handled in order for this function to be │ │ │ │ meaningful.

    │ │ │ │
    │ │ │ │ + │ │ │ │ │ │ │ │ - │ │ │ │ │ │ │ │ - │ │ │ │ -[report issue]
    │ │ │ │ -
    │ │ │ │ -

    queue_position() queue_position_bottom() queue_position_up() queue_position_top() queue_position_down()

    │ │ │ │ + │ │ │ │ +[report issue]
    │ │ │ │ +
    │ │ │ │ +

    queue_position_down() queue_position() queue_position_up() queue_position_bottom() queue_position_top()

    │ │ │ │ 
    │ │ │ │ -void queue_position_down () const;
│ │ │ │ -queue_position_t queue_position () const;
│ │ │ │  void queue_position_bottom () const;
│ │ │ │ -void queue_position_top () const;
│ │ │ │  void queue_position_up () const;
│ │ │ │ +void queue_position_top () const;
│ │ │ │ +queue_position_t queue_position () const;
│ │ │ │ +void queue_position_down () const;
│ │ │ │
    │ │ │ │

    Every torrent that is added is assigned a queue position exactly one │ │ │ │ greater than the greatest queue position of all existing torrents. │ │ │ │ Torrents that are being seeded have -1 as their queue position, since │ │ │ │ they're no longer in line to be downloaded.

    │ │ │ │

    When a torrent is removed or turns into a seed, all torrents with │ │ │ │ greater queue positions have their positions decreased to fill in the │ │ │ │ @@ -17887,26 +19174,26 @@ │ │ │ │

    queue_position_set()

    │ │ │ │ 
    │ │ │ │  void queue_position_set (queue_position_t p) const;
│ │ │ │
    │ │ │ │

    updates the position in the queue for this torrent. The relative order │ │ │ │ of all other torrents remain intact but their numerical queue position │ │ │ │ shifts to make space for this torrent's new position

    │ │ │ │ - │ │ │ │ -[report issue]
    │ │ │ │ -
    │ │ │ │ -

    set_ssl_certificate_buffer() set_ssl_certificate()

    │ │ │ │ + │ │ │ │ +[report issue]
    │ │ │ │ +
    │ │ │ │ +

    set_ssl_certificate() set_ssl_certificate_buffer()

    │ │ │ │ 
    │ │ │ │ +void set_ssl_certificate_buffer (std::string const& certificate
│ │ │ │ +      , std::string const& private_key
│ │ │ │ +      , std::string const& dh_params);
│ │ │ │  void set_ssl_certificate (std::string const& certificate
│ │ │ │        , std::string const& private_key
│ │ │ │        , std::string const& dh_params
│ │ │ │        , std::string const& passphrase = "");
│ │ │ │ -void set_ssl_certificate_buffer (std::string const& certificate
│ │ │ │ -      , std::string const& private_key
│ │ │ │ -      , std::string const& dh_params);
│ │ │ │
    │ │ │ │

    For SSL torrents, use this to specify a path to a .pem file to use as │ │ │ │ this client's certificate. The certificate must be signed by the │ │ │ │ certificate in the .torrent file to be valid.

    │ │ │ │

    The set_ssl_certificate_buffer() overload takes the actual certificate, │ │ │ │ private key and DH params as strings, rather than paths to files.

    │ │ │ │

    cert is a path to the (signed) certificate in .pem format │ │ │ │ @@ -17922,18 +19209,18 @@ │ │ │ │

    Note that when a torrent first starts up, and it needs a certificate, │ │ │ │ it will suspend connecting to any peers until it has one. It's │ │ │ │ typically desirable to resume the torrent after setting the SSL │ │ │ │ certificate.

    │ │ │ │

    If you receive a torrent_need_cert_alert, you need to call this to │ │ │ │ provide a valid cert. If you don't have a cert you won't be allowed to │ │ │ │ connect to any peers.

    │ │ │ │ - │ │ │ │ -[report issue]
    │ │ │ │ -
    │ │ │ │ -

    torrent_file_with_hashes() torrent_file()

    │ │ │ │ + │ │ │ │ +[report issue]
    │ │ │ │ +
    │ │ │ │ +

    torrent_file() torrent_file_with_hashes()

    │ │ │ │ 
    │ │ │ │  std::shared_ptr<const torrent_info> torrent_file () const;
│ │ │ │  std::shared_ptr<torrent_info> torrent_file_with_hashes () const;
│ │ │ │
    │ │ │ │

    torrent_file() returns a pointer to the torrent_info object │ │ │ │ associated with this torrent. The torrent_info object may be a copy │ │ │ │ of the internal object. If the torrent doesn't have metadata, the │ │ │ │ @@ -17989,17 +19276,17 @@ │ │ │ │ │ │ │ │ [report issue]

    │ │ │ │
    │ │ │ │

    piece_priority() get_piece_priorities() prioritize_pieces()

    │ │ │ │ 
    │ │ │ │  std::vector<download_priority_t> get_piece_priorities () const;
│ │ │ │  void piece_priority (piece_index_t index, download_priority_t priority) const;
│ │ │ │ -void prioritize_pieces (std::vector<std::pair<piece_index_t, download_priority_t>> const& pieces) const;
│ │ │ │  download_priority_t piece_priority (piece_index_t index) const;
│ │ │ │  void prioritize_pieces (std::vector<download_priority_t> const& pieces) const;
│ │ │ │ +void prioritize_pieces (std::vector<std::pair<piece_index_t, download_priority_t>> const& pieces) const;
│ │ │ │
    │ │ │ │

    These functions are used to set and get the priority of individual │ │ │ │ pieces. By default all pieces have priority 4. That means that the │ │ │ │ random rarest first algorithm is effectively active for all pieces. │ │ │ │ You may however change the priority of individual pieces. There are 8 │ │ │ │ priority levels. 0 means not to download the piece at all. Otherwise, │ │ │ │ lower priority values means less likely to be picked. Piece priority │ │ │ │ @@ -18021,22 +19308,22 @@ │ │ │ │ Invalid entries, where the piece index or priority is out of range, are │ │ │ │ not allowed.

    │ │ │ │

    get_piece_priorities returns a vector with one element for each piece │ │ │ │ in the torrent. Each element is the current priority of that piece.

    │ │ │ │

    It's possible to cancel the effect of file priorities by setting the │ │ │ │ priorities for the affected pieces. Care has to be taken when mixing │ │ │ │ usage of file- and piece priorities.

    │ │ │ │ - │ │ │ │ │ │ │ │ -[report issue]
    │ │ │ │ -
    │ │ │ │ -

    prioritize_files() file_priority() get_file_priorities()

    │ │ │ │ + │ │ │ │ +[report issue]
    │ │ │ │ +
    │ │ │ │ +

    file_priority() get_file_priorities() prioritize_files()

    │ │ │ │ 
    │ │ │ │ -void file_priority (file_index_t index, download_priority_t priority) const;
│ │ │ │  std::vector<download_priority_t> get_file_priorities () const;
│ │ │ │ +void file_priority (file_index_t index, download_priority_t priority) const;
│ │ │ │  void prioritize_files (std::vector<download_priority_t> const& files) const;
│ │ │ │  download_priority_t file_priority (file_index_t index) const;
│ │ │ │
    │ │ │ │

    index must be in the range [0, number_of_files).

    │ │ │ │

    file_priority() queries or sets the priority of file index.

    │ │ │ │

    prioritize_files() takes a vector that has at as many elements as │ │ │ │ there are files in the torrent. Each entry is the priority of that │ │ │ │ @@ -18061,23 +19348,23 @@ │ │ │ │ file_prio_alert.

    │ │ │ │

    When combining file- and piece priorities, the resume file will record │ │ │ │ both. When loading the resume data, the file priorities will be applied │ │ │ │ first, then the piece priorities.

    │ │ │ │

    Moving data from a file into the part file is currently not │ │ │ │ supported. If a file has its priority set to 0 after it has already │ │ │ │ been created, it will not be moved into the partfile.

    │ │ │ │ - │ │ │ │ │ │ │ │ -[report issue]
    │ │ │ │ -
    │ │ │ │ -

    force_dht_announce() force_reannounce() force_lsd_announce()

    │ │ │ │ + │ │ │ │ +[report issue]
    │ │ │ │ +
    │ │ │ │ +

    force_reannounce() force_lsd_announce() force_dht_announce()

    │ │ │ │ 
    │ │ │ │ -void force_lsd_announce () const;
│ │ │ │  void force_reannounce (int seconds = 0, int idx = -1, reannounce_flags_t = {}) const;
│ │ │ │  void force_dht_announce () const;
│ │ │ │ +void force_lsd_announce () const;
│ │ │ │
    │ │ │ │

    force_reannounce() will force this torrent to do another tracker │ │ │ │ request, to receive new peers. The seconds argument specifies how │ │ │ │ many seconds from now to issue the tracker announces.

    │ │ │ │

    If the tracker's min_interval has not passed since the last │ │ │ │ announce, the forced announce will be scheduled to happen immediately │ │ │ │ as the min_interval expires. This is to honor trackers minimum │ │ │ │ @@ -18102,23 +19389,23 @@ │ │ │ │

    A scrape request queries the tracker for statistics such as total │ │ │ │ number of incomplete peers, complete peers, number of downloads etc.

    │ │ │ │

    This request will specifically update the num_complete and │ │ │ │ num_incomplete fields in the torrent_status struct once it │ │ │ │ completes. When it completes, it will generate a scrape_reply_alert. │ │ │ │ If it fails, it will generate a scrape_failed_alert.

    │ │ │ │ │ │ │ │ - │ │ │ │ │ │ │ │ -[report issue]
    │ │ │ │ -
    │ │ │ │ -

    download_limit() set_download_limit() set_upload_limit() upload_limit()

    │ │ │ │ + │ │ │ │ +[report issue]
    │ │ │ │ +
    │ │ │ │ +

    download_limit() set_upload_limit() set_download_limit() upload_limit()

    │ │ │ │ 
    │ │ │ │ -int download_limit () const;
│ │ │ │ -void set_upload_limit (int limit) const;
│ │ │ │  void set_download_limit (int limit) const;
│ │ │ │ +void set_upload_limit (int limit) const;
│ │ │ │ +int download_limit () const;
│ │ │ │  int upload_limit () const;
│ │ │ │
    │ │ │ │

    set_upload_limit will limit the upload bandwidth used by this │ │ │ │ particular torrent to the limit you set. It is given as the number of │ │ │ │ bytes per second the torrent is allowed to upload. │ │ │ │ set_download_limit works the same way but for download bandwidth │ │ │ │ instead of upload bandwidth. Note that setting a higher limit on a │ │ │ │ @@ -18165,18 +19452,18 @@ │ │ │ │ │ │ │ │

    set_max_uploads() sets the maximum number of peers that's unchoked │ │ │ │ at the same time on this torrent. If you set this to -1, there will be │ │ │ │ no limit. This defaults to infinite. The primary setting controlling │ │ │ │ this is the global unchoke slots limit, set by unchoke_slots_limit in │ │ │ │ settings_pack.

    │ │ │ │

    max_uploads() returns the current settings.

    │ │ │ │ - │ │ │ │ -[report issue]
    │ │ │ │ -
    │ │ │ │ -

    max_connections() set_max_connections()

    │ │ │ │ + │ │ │ │ +[report issue]
    │ │ │ │ +
    │ │ │ │ +

    set_max_connections() max_connections()

    │ │ │ │ 
    │ │ │ │  int max_connections () const;
│ │ │ │  void set_max_connections (int max_connections) const;
│ │ │ │
    │ │ │ │

    set_max_connections() sets the maximum number of connection this │ │ │ │ torrent will open. If all connections are used up, incoming │ │ │ │ connections may be refused or poor connections may be closed. This │ │ │ │ @@ -18242,21 +19529,21 @@ │ │ │ │

    rename_file()

    │ │ │ │ 
    │ │ │ │  void rename_file (file_index_t index, std::string const& new_name) const;
│ │ │ │
    │ │ │ │

    Renames the file with the given index asynchronously. The rename │ │ │ │ operation is complete when either a file_renamed_alert or │ │ │ │ file_rename_failed_alert is posted.

    │ │ │ │ - │ │ │ │ -[report issue]
    │ │ │ │ -
    │ │ │ │ -

    info_hash() info_hashes()

    │ │ │ │ + │ │ │ │ +[report issue]
    │ │ │ │ +
    │ │ │ │ +

    info_hashes() info_hash()

    │ │ │ │ 
    │ │ │ │ -sha1_hash info_hash () const;
│ │ │ │  info_hash_t info_hashes () const;
│ │ │ │ +sha1_hash info_hash () const;
│ │ │ │
    │ │ │ │

    returns the info-hash(es) of the torrent. If this handle is to a │ │ │ │ torrent that hasn't loaded yet (for instance by being added) by a │ │ │ │ URL, the returned value is undefined. │ │ │ │ The info_hash() returns the SHA-1 info-hash for v1 torrents and a │ │ │ │ truncated hash for v2 torrents. For the full v2 info-hash, use │ │ │ │ info_hashes() instead.

    │ │ │ │ @@ -18417,1585 +19704,14 @@ │ │ │ │
    │ │ │ │

    hash_value()

    │ │ │ │

    Declared in "libtorrent/torrent_handle.hpp"

    │ │ │ │ 
    │ │ │ │  std::size_t hash_value (torrent_handle const& h);
│ │ │ │
    │ │ │ │

    for std::hash (and to support using this type in unordered_map etc.)

    │ │ │ │ -[report issue]
    │ │ │ │ -
    │ │ │ │ -

    storage_error

    │ │ │ │ -

    Declared in "libtorrent/error_code.hpp"

    │ │ │ │ -

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

    │ │ │ │ -
    │ │ │ │ -struct storage_error
│ │ │ │ -{
│ │ │ │ -   explicit operator bool () const;
│ │ │ │ -   void file (file_index_t f);
│ │ │ │ -   file_index_t file () const;
│ │ │ │ -
│ │ │ │ -   error_code ec;
│ │ │ │ -   operation_t operation;
│ │ │ │ -};
│ │ │ │ -
    │ │ │ │ -[report issue]
    │ │ │ │ -

    bool()

    │ │ │ │ -
    │ │ │ │ -explicit operator bool () const;
│ │ │ │ -
    │ │ │ │ -

    explicitly converts to true if this object represents an error, and │ │ │ │ -false if it does not.

    │ │ │ │ -[report issue]
    │ │ │ │ -
    │ │ │ │ -

    file()

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

    set and query the index (in the torrent) of the file this error │ │ │ │ -occurred on. This may also have special values defined in │ │ │ │ -torrent_status.

    │ │ │ │ -[report issue]
    │ │ │ │ -
    ec
    │ │ │ │ -
    the error that occurred
    │ │ │ │ -
    │ │ │ │ -[report issue]
    │ │ │ │ -
    operation
    │ │ │ │ -
    A code from operation_t enum, indicating what │ │ │ │ -kind of operation failed.
    │ │ │ │ -
    │ │ │ │ -[report issue]
    │ │ │ │ -
    │ │ │ │ -
    │ │ │ │ -

    bdecode_category()

    │ │ │ │ -

    Declared in "libtorrent/bdecode.hpp"

    │ │ │ │ -
    │ │ │ │ -boost::system::error_category& bdecode_category ();
│ │ │ │ -
    │ │ │ │ -[report issue]
    │ │ │ │ -
    │ │ │ │ -

    i2p_category()

    │ │ │ │ -

    Declared in "libtorrent/i2p_stream.hpp"

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

    returns the error category for I2P errors

    │ │ │ │ -[report issue]
    │ │ │ │ -
    │ │ │ │ -

    socks_category()

    │ │ │ │ -

    Declared in "libtorrent/socks5_stream.hpp"

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

    returns the error_category for SOCKS5 errors

    │ │ │ │ -[report issue]
    │ │ │ │ -
    │ │ │ │ -

    pcp_category()

    │ │ │ │ -

    Declared in "libtorrent/natpmp.hpp"

    │ │ │ │ -
    │ │ │ │ -boost::system::error_category& pcp_category ();
│ │ │ │ -
    │ │ │ │ -[report issue]
    │ │ │ │ -
    │ │ │ │ -

    upnp_category()

    │ │ │ │ -

    Declared in "libtorrent/upnp.hpp"

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

    the boost.system error category for UPnP errors

    │ │ │ │ -[report issue]
    │ │ │ │ -
    │ │ │ │ -

    libtorrent_category()

    │ │ │ │ -

    Declared in "libtorrent/error_code.hpp"

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

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

    │ │ │ │ -[report issue]
    │ │ │ │ -
    │ │ │ │ -

    http_category()

    │ │ │ │ -

    Declared in "libtorrent/error_code.hpp"

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

    returns the error_category for HTTP errors

    │ │ │ │ -[report issue]
    │ │ │ │ -
    │ │ │ │ -

    gzip_category()

    │ │ │ │ -

    Declared in "libtorrent/gzip.hpp"

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

    get the error_category for zip errors

    │ │ │ │ -[report issue]
    │ │ │ │ -
    │ │ │ │ -

    enum error_code_enum

    │ │ │ │ -

    Declared in "libtorrent/bdecode.hpp"

    │ │ │ │ -
    │ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ -
    namevaluedescription
    no_error0Not an error
    expected_digit1expected digit in bencoded string
    expected_colon2expected colon in bencoded string
    unexpected_eof3unexpected end of file in bencoded string
    expected_value4expected value (list, dict, int or string) in bencoded string
    depth_exceeded5bencoded recursion depth limit exceeded
    limit_exceeded6bencoded item count limit exceeded
    overflow7integer overflow
    error_code_max8the number of error codes
    │ │ │ │ -[report issue]
    │ │ │ │ -
    │ │ │ │ -

    enum i2p_error_code

    │ │ │ │ -

    Declared in "libtorrent/i2p_stream.hpp"

    │ │ │ │ - │ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ -
    namevaluedescription
    no_error0 
    parse_failed1 
    cant_reach_peer2 
    i2p_error3 
    invalid_key4 
    invalid_id5 
    timeout6 
    key_not_found7 
    duplicated_id8 
    num_errors9 
    │ │ │ │ -[report issue]
    │ │ │ │ -
    │ │ │ │ -

    enum socks_error_code

    │ │ │ │ -

    Declared in "libtorrent/socks5_stream.hpp"

    │ │ │ │ - │ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ -
    namevaluedescription
    no_error0 
    unsupported_version1 
    unsupported_authentication_method2 
    unsupported_authentication_version3 
    authentication_error4 
    username_required5 
    general_failure6 
    command_not_supported7 
    no_identd8 
    identd_error9 
    num_errors10 
    │ │ │ │ -[report issue]
    │ │ │ │ -
    │ │ │ │ -

    enum pcp_errors

    │ │ │ │ -

    Declared in "libtorrent/natpmp.hpp"

    │ │ │ │ - │ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ -
    namevaluedescription
    pcp_success0 
    pcp_unsupp_version1 
    pcp_not_authorized2 
    pcp_malformed_request3 
    pcp_unsupp_opcode4 
    pcp_unsupp_option5 
    pcp_malformed_option6 
    pcp_network_failure7 
    pcp_no_resources8 
    pcp_unsupp_protocol9 
    pcp_user_ex_quota10 
    pcp_cannot_provide_external11 
    pcp_address_mismatch12 
    pcp_excessive_remote_peers13 
    │ │ │ │ -[report issue]
    │ │ │ │ -
    │ │ │ │ -

    enum error_code_enum

    │ │ │ │ -

    Declared in "libtorrent/upnp.hpp"

    │ │ │ │ - │ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ -
    namevaluedescription
    no_error0No error
    invalid_argument402One of the arguments in the request is invalid
    action_failed501The request failed
    value_not_in_array714The specified value does not exist in the array
    source_ip_cannot_be_wildcarded715The source IP address cannot be wild-carded, but │ │ │ │ -must be fully specified
    external_port_cannot_be_wildcarded716The external port cannot be a wildcard, but must │ │ │ │ -be specified
    port_mapping_conflict718The port mapping entry specified conflicts with a │ │ │ │ -mapping assigned previously to another client
    internal_port_must_match_external724Internal and external port value must be the same
    only_permanent_leases_supported725The NAT implementation only supports permanent │ │ │ │ -lease times on port mappings
    remote_host_must_be_wildcard726RemoteHost must be a wildcard and cannot be a │ │ │ │ -specific IP address or DNS name
    external_port_must_be_wildcard727ExternalPort must be a wildcard and cannot be a │ │ │ │ -specific port
    │ │ │ │ -[report issue]
    │ │ │ │ -
    │ │ │ │ -

    enum error_code_enum

    │ │ │ │ -

    Declared in "libtorrent/error_code.hpp"

    │ │ │ │ - │ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ -
    namevaluedescription
    no_error0Not an error
    file_collision1Two torrents has files which end up overwriting each other
    failed_hash_check2A piece did not match its piece hash
    torrent_is_no_dict3The .torrent file does not contain a bencoded dictionary at │ │ │ │ -its top level
    torrent_missing_info4The .torrent file does not have an info dictionary
    torrent_info_no_dict5The .torrent file's info entry is not a dictionary
    torrent_missing_piece_length6The .torrent file does not have a piece length entry
    torrent_missing_name7The .torrent file does not have a name entry
    torrent_invalid_name8The .torrent file's name entry is invalid
    torrent_invalid_length9The length of a file, or of the whole .torrent file is invalid. │ │ │ │ -Either negative or not an integer
    torrent_file_parse_failed10Failed to parse a file entry in the .torrent
    torrent_missing_pieces11The pieces field is missing or invalid in the .torrent file
    torrent_invalid_hashes12The pieces string has incorrect length
    too_many_pieces_in_torrent13The .torrent file has more pieces than is supported by libtorrent
    invalid_swarm_metadata14The metadata (.torrent file) that was received from the swarm │ │ │ │ -matched the info-hash, but failed to be parsed
    invalid_bencoding15The file or buffer is not correctly bencoded
    no_files_in_torrent16The .torrent file does not contain any files
    invalid_escaped_string17The string was not properly url-encoded as expected
    session_is_closing18Operation is not permitted since the session is shutting down
    duplicate_torrent19There's already a torrent with that info-hash added to the │ │ │ │ -session
    invalid_torrent_handle20The supplied torrent_handle is not referring to a valid torrent
    invalid_entry_type21The type requested from the entry did not match its type
    missing_info_hash_in_uri22The specified URI does not contain a valid info-hash
    file_too_short23One of the files in the torrent was unexpectedly small. This │ │ │ │ -might be caused by files being changed by an external process
    unsupported_url_protocol24The URL used an unknown protocol. Currently http and │ │ │ │ -https (if built with openssl support) are recognized. For │ │ │ │ -trackers udp is recognized as well.
    url_parse_error25The URL did not conform to URL syntax and failed to be parsed
    peer_sent_empty_piece26The peer sent a piece message of length 0
    parse_failed27A bencoded structure was corrupt and failed to be parsed
    invalid_file_tag28The fast resume file was missing or had an invalid file version │ │ │ │ -tag
    missing_info_hash29The fast resume file was missing or had an invalid info-hash
    mismatching_info_hash30The info-hash did not match the torrent
    invalid_hostname31The URL contained an invalid hostname
    invalid_port32The URL had an invalid port
    port_blocked33The port is blocked by the port-filter, and prevented the │ │ │ │ -connection
    expected_close_bracket_in_address34The IPv6 address was expected to end with "]"
    destructing_torrent35The torrent is being destructed, preventing the operation to │ │ │ │ -succeed
    timed_out36The connection timed out
    upload_upload_connection37The peer is upload only, and we are upload only. There's no point │ │ │ │ -in keeping the connection
    uninteresting_upload_peer38The peer is upload only, and we're not interested in it. There's │ │ │ │ -no point in keeping the connection
    invalid_info_hash39The peer sent an unknown info-hash
    torrent_paused40The torrent is paused, preventing the operation from succeeding
    invalid_have41The peer sent an invalid have message, either wrong size or │ │ │ │ -referring to a piece that doesn't exist in the torrent
    invalid_bitfield_size42The bitfield message had the incorrect size
    too_many_requests_when_choked43The peer kept requesting pieces after it was choked, possible │ │ │ │ -abuse attempt.
    invalid_piece44The peer sent a piece message that does not correspond to a │ │ │ │ -piece request sent by the client
    no_memory45memory allocation failed
    torrent_aborted46The torrent is aborted, preventing the operation to succeed
    self_connection47The peer is a connection to ourself, no point in keeping it
    invalid_piece_size48The peer sent a piece message with invalid size, either negative │ │ │ │ -or greater than one block
    timed_out_no_interest49The peer has not been interesting or interested in us for too │ │ │ │ -long, no point in keeping it around
    timed_out_inactivity50The peer has not said anything in a long time, possibly dead
    timed_out_no_handshake51The peer did not send a handshake within a reasonable amount of │ │ │ │ -time, it might not be a bittorrent peer
    timed_out_no_request52The peer has been unchoked for too long without requesting any │ │ │ │ -data. It might be lying about its interest in us
    invalid_choke53The peer sent an invalid choke message
    invalid_unchoke54The peer send an invalid unchoke message
    invalid_interested55The peer sent an invalid interested message
    invalid_not_interested56The peer sent an invalid not-interested message
    invalid_request57The peer sent an invalid piece request message
    invalid_hash_list58The peer sent an invalid hash-list message (this is part of the │ │ │ │ -merkle-torrent extension)
    invalid_hash_piece59The peer sent an invalid hash-piece message (this is part of the │ │ │ │ -merkle-torrent extension)
    invalid_cancel60The peer sent an invalid cancel message
    invalid_dht_port61The peer sent an invalid DHT port-message
    invalid_suggest62The peer sent an invalid suggest piece-message
    invalid_have_all63The peer sent an invalid have all-message
    invalid_have_none64The peer sent an invalid have none-message
    invalid_reject65The peer sent an invalid reject message
    invalid_allow_fast66The peer sent an invalid allow fast-message
    invalid_extended67The peer sent an invalid extension message ID
    invalid_message68The peer sent an invalid message ID
    sync_hash_not_found69The synchronization hash was not found in the encrypted handshake
    invalid_encryption_constant70The encryption constant in the handshake is invalid
    no_plaintext_mode71The peer does not support plain text, which is the selected mode
    no_rc4_mode72The peer does not support RC4, which is the selected mode
    unsupported_encryption_mode73The peer does not support any of the encryption modes that the │ │ │ │ -client supports
    unsupported_encryption_mode_selected74The peer selected an encryption mode that the client did not │ │ │ │ -advertise and does not support
    invalid_pad_size75The pad size used in the encryption handshake is of invalid size
    invalid_encrypt_handshake76The encryption handshake is invalid
    no_incoming_encrypted77The client is set to not support incoming encrypted connections │ │ │ │ -and this is an encrypted connection
    no_incoming_regular78The client is set to not support incoming regular bittorrent │ │ │ │ -connections, and this is a regular connection
    duplicate_peer_id79The client is already connected to this peer-ID
    torrent_removed80Torrent was removed
    packet_too_large81The packet size exceeded the upper sanity check-limit
    reserved82 
    http_error83The web server responded with an error
    missing_location84The web server response is missing a location header
    invalid_redirection85The web seed redirected to a path that no longer matches the │ │ │ │ -.torrent directory structure
    redirecting86The connection was closed because it redirected to a different │ │ │ │ -URL
    invalid_range87The HTTP range header is invalid
    no_content_length88The HTTP response did not have a content length
    banned_by_ip_filter89The IP is blocked by the IP filter
    too_many_connections90At the connection limit
    peer_banned91The peer is marked as banned
    stopping_torrent92The torrent is stopping, causing the operation to fail
    too_many_corrupt_pieces93The peer has sent too many corrupt pieces and is banned
    torrent_not_ready94The torrent is not ready to receive peers
    peer_not_constructed95The peer is not completely constructed yet
    session_closing96The session is closing, causing the operation to fail
    optimistic_disconnect97The peer was disconnected in order to leave room for a │ │ │ │ -potentially better peer
    torrent_finished98The torrent is finished
    no_router99No UPnP router found
    metadata_too_large100The metadata message says the metadata exceeds the limit
    invalid_metadata_request101The peer sent an invalid metadata request message
    invalid_metadata_size102The peer advertised an invalid metadata size
    invalid_metadata_offset103The peer sent a message with an invalid metadata offset
    invalid_metadata_message104The peer sent an invalid metadata message
    pex_message_too_large105The peer sent a peer exchange message that was too large
    invalid_pex_message106The peer sent an invalid peer exchange message
    invalid_lt_tracker_message107The peer sent an invalid tracker exchange message
    too_frequent_pex108The peer sent an pex messages too often. This is a possible │ │ │ │ -attempt of and attack
    no_metadata109The operation failed because it requires the torrent to have │ │ │ │ -the metadata (.torrent file) and it doesn't have it yet. │ │ │ │ -This happens for magnet links before they have downloaded the │ │ │ │ -metadata, and also torrents added by URL.
    invalid_dont_have110The peer sent an invalid dont_have message. The don't have │ │ │ │ -message is an extension to allow peers to advertise that the │ │ │ │ -no longer has a piece they previously had.
    requires_ssl_connection111The peer tried to connect to an SSL torrent without connecting │ │ │ │ -over SSL.
    invalid_ssl_cert112The peer tried to connect to a torrent with a certificate │ │ │ │ -for a different torrent.
    not_an_ssl_torrent113the torrent is not an SSL torrent, and the operation requires │ │ │ │ -an SSL torrent
    banned_by_port_filter114peer was banned because its listen port is within a banned port │ │ │ │ -range, as specified by the port_filter.
    invalid_session_handle115The session_handle is not referring to a valid session_impl
    invalid_listen_socket116the listen socket associated with this request was closed
    invalid_hash_request117 
    invalid_hashes118 
    invalid_hash_reject119 
    deprecated_120120 
    deprecated_121121 
    deprecated_122122 
    deprecated_123123 
    deprecated_124124 
    missing_file_sizes130The resume data file is missing the file sizes entry
    no_files_in_resume_data131The resume data file file sizes entry is empty
    missing_pieces132The resume data file is missing the pieces and slots entry
    mismatching_number_of_files133The number of files in the resume data does not match the number │ │ │ │ -of files in the torrent
    mismatching_file_size134One of the files on disk has a different size than in the fast │ │ │ │ -resume file
    mismatching_file_timestamp135One of the files on disk has a different timestamp than in the │ │ │ │ -fast resume file
    not_a_dictionary136The resume data file is not a dictionary
    invalid_blocks_per_piece137The blocks per piece entry is invalid in the resume data file
    missing_slots138The resume file is missing the slots entry, which is required │ │ │ │ -for torrents with compact allocation. DEPRECATED
    too_many_slots139The resume file contains more slots than the torrent
    invalid_slot_list140The slot entry is invalid in the resume data
    invalid_piece_index141One index in the slot list is invalid
    pieces_need_reorder142The pieces on disk needs to be re-ordered for the specified │ │ │ │ -allocation mode. This happens if you specify sparse allocation │ │ │ │ -and the files on disk are using compact storage. The pieces needs │ │ │ │ -to be moved to their right position. DEPRECATED
    resume_data_not_modified143this error is returned when asking to save resume data and │ │ │ │ -specifying the flag to only save when there's anything new to save │ │ │ │ -(torrent_handle::only_if_modified) and there wasn't anything changed.
    http_parse_error150The HTTP header was not correctly formatted
    http_missing_location151The HTTP response was in the 300-399 range but lacked a location │ │ │ │ -header
    http_failed_decompress152The HTTP response was encoded with gzip or deflate but │ │ │ │ -decompressing it failed
    no_i2p_router160The URL specified an i2p address, but no i2p router is configured
    no_i2p_endpoint161i2p acceptor is not available yet, can't announce without endpoint
    scrape_not_available170The tracker URL doesn't support transforming it into a scrape │ │ │ │ -URL. i.e. it doesn't contain "announce.
    invalid_tracker_response171invalid tracker response
    invalid_peer_dict172invalid peer dictionary entry. Not a dictionary
    tracker_failure173tracker sent a failure message
    invalid_files_entry174missing or invalid files entry
    invalid_hash_entry175missing or invalid hash entry
    invalid_peers_entry176missing or invalid peers and peers6 entry
    invalid_tracker_response_length177UDP tracker response packet has invalid size
    invalid_tracker_transaction_id178invalid transaction id in UDP tracker response
    invalid_tracker_action179invalid action field in UDP tracker response
    announce_skipped180skipped announce (because it's assumed to be unreachable over the │ │ │ │ -given source network interface)
    no_entropy200random number generation failed
    ssrf_mitigation201blocked by SSRF mitigation
    blocked_by_idna202blocked because IDNA host names are banned
    torrent_unknown_version210the torrent file has an unknown meta version
    torrent_missing_file_tree211the v2 torrent file has no file tree
    torrent_missing_meta_version212the torrent contains v2 keys but does not specify meta version 2
    torrent_inconsistent_files213the v1 and v2 file metadata does not match
    torrent_missing_piece_layer214one or more files are missing piece layer hashes
    torrent_invalid_piece_layer215a piece layer has the wrong size or failed hash check
    torrent_missing_pieces_root216a v2 file entry has no root hash
    torrent_inconsistent_hashes217the v1 and v2 hashes do not describe the same data
    torrent_invalid_pad_file218a file in the v2 metadata has the pad attribute set
    error_code_max219the number of error codes
    │ │ │ │ -[report issue]
    │ │ │ │ -
    │ │ │ │ -

    enum http_errors

    │ │ │ │ -

    Declared in "libtorrent/error_code.hpp"

    │ │ │ │ - │ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ -
    namevaluedescription
    cont100 
    ok200 
    created201 
    accepted202 
    no_content204 
    multiple_choices300 
    moved_permanently301 
    moved_temporarily302 
    not_modified304 
    bad_request400 
    unauthorized401 
    forbidden403 
    not_found404 
    internal_server_error500 
    not_implemented501 
    bad_gateway502 
    service_unavailable503 
    │ │ │ │ -[report issue]
    │ │ │ │ -
    │ │ │ │ -

    enum error_code_enum

    │ │ │ │ -

    Declared in "libtorrent/gzip.hpp"

    │ │ │ │ - │ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ -
    namevaluedescription
    no_error0Not an error
    invalid_gzip_header1the supplied gzip buffer has invalid header
    inflated_data_too_large2the gzip buffer would inflate to more bytes than the specified │ │ │ │ -maximum size, and was rejected.
    data_did_not_terminate3available inflate data did not terminate
    space_exhausted4output space exhausted before completing inflate
    invalid_block_type5invalid block type (type == 3)
    invalid_stored_block_length6stored block length did not match one's complement
    too_many_length_or_distance_codes7dynamic block code description: too many length or distance codes
    code_lengths_codes_incomplete8dynamic block code description: code lengths codes incomplete
    repeat_lengths_with_no_first_length9dynamic block code description: repeat lengths with no first length
    repeat_more_than_specified_lengths10dynamic block code description: repeat more than specified lengths
    invalid_literal_length_code_lengths11dynamic block code description: invalid literal/length code lengths
    invalid_distance_code_lengths12dynamic block code description: invalid distance code lengths
    invalid_literal_code_in_block13invalid literal/length or distance code in fixed or dynamic block
    distance_too_far_back_in_block14distance is too far back in fixed or dynamic block
    unknown_gzip_error15an unknown error occurred during gzip inflation
    error_code_max16the number of error codes
    │ │ │ │ -[report issue]
    │ │ │ │ -
    │ │ │ │ -

    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;
│ │ │ │ -};
│ │ │ │ -
    │ │ │ │ -[report issue]
    │ │ │ │ -
    message
    │ │ │ │ -
    if this tracker has returned an error or warning message │ │ │ │ -that message is stored here
    │ │ │ │ -
    │ │ │ │ -[report issue]
    │ │ │ │ -
    last_error
    │ │ │ │ -
    if this tracker failed the last time it was contacted │ │ │ │ -this error code specifies what error occurred
    │ │ │ │ -
    │ │ │ │ - │ │ │ │ - │ │ │ │ -[report issue]
    │ │ │ │ -
    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.
    │ │ │ │ -
    │ │ │ │ -[report issue]
    │ │ │ │ -
    fails
    │ │ │ │ -
    the number of times in a row we have failed to announce to this │ │ │ │ -tracker.
    │ │ │ │ -
    │ │ │ │ -[report issue]
    │ │ │ │ -
    updating
    │ │ │ │ -
    true while we're waiting for a response from the tracker.
    │ │ │ │ -
    │ │ │ │ -[report issue]
    │ │ │ │ -
    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.
    │ │ │ │ -
    │ │ │ │ -[report issue]
    │ │ │ │ -
    complete_sent
    │ │ │ │ -
    set to true when we send a event=completed.
    │ │ │ │ -
    │ │ │ │ -[report issue]
    │ │ │ │ -
    │ │ │ │ -

    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;
│ │ │ │ -};
│ │ │ │ -
    │ │ │ │ -[report issue]
    │ │ │ │ -
    local_endpoint
    │ │ │ │ -
    the local endpoint of the listen interface associated with this endpoint
    │ │ │ │ -
    │ │ │ │ -[report issue]
    │ │ │ │ -
    info_hashes
    │ │ │ │ -
    info_hashes[0] is the v1 info hash (SHA1) │ │ │ │ -info_hashes[1] is the v2 info hash (truncated SHA-256)
    │ │ │ │ -
    │ │ │ │ -[report issue]
    │ │ │ │ -
    enabled
    │ │ │ │ -
    set to false to not announce from this endpoint
    │ │ │ │ -
    │ │ │ │ -[report issue]
    │ │ │ │ -
    │ │ │ │ -

    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
│ │ │ │ -{
│ │ │ │ -   explicit announce_entry (string_view u);
│ │ │ │ -   announce_entry (announce_entry const&);
│ │ │ │ -   announce_entry ();
│ │ │ │ -   announce_entry& operator= (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;
│ │ │ │ -};
│ │ │ │ -
    │ │ │ │ - │ │ │ │ - │ │ │ │ -[report issue]
    │ │ │ │ -

    ~announce_entry() operator=() announce_entry()

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

    constructs a tracker announce entry with u as the URL.

    │ │ │ │ -[report issue]
    │ │ │ │ -
    │ │ │ │ -

    enum tracker_source

    │ │ │ │ -

    Declared in "libtorrent/announce_entry.hpp"

    │ │ │ │ - │ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ -│ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ - │ │ │ │ -
    namevaluedescription
    source_torrent1the tracker was part of the .torrent file
    source_client2the tracker was added programmatically via the add_tracker() function
    source_magnet_link4the tracker was part of a magnet link
    source_tex8the tracker was received from the swarm via tracker exchange
    │ │ │ │ -[report issue]
    │ │ │ │ -
    url
    │ │ │ │ -
    tracker URL as it appeared in the torrent file
    │ │ │ │ -
    │ │ │ │ -[report issue]
    │ │ │ │ -
    trackerid
    │ │ │ │ -
    the current &trackerid= argument passed to the tracker. │ │ │ │ -this is optional and is normally empty (in which case no │ │ │ │ -trackerid is sent).
    │ │ │ │ -
    │ │ │ │ -[report issue]
    │ │ │ │ -
    endpoints
    │ │ │ │ -
    each local listen socket (endpoint) will announce to the tracker. This │ │ │ │ -list contains state per endpoint.
    │ │ │ │ -
    │ │ │ │ -[report issue]
    │ │ │ │ -
    tier
    │ │ │ │ -
    the tier this tracker belongs to
    │ │ │ │ -
    │ │ │ │ -[report issue]
    │ │ │ │ -
    fail_limit
    │ │ │ │ -
    the max number of failures to announce to this tracker in │ │ │ │ -a row, before this tracker is not used anymore. 0 means unlimited
    │ │ │ │ -
    │ │ │ │ -[report issue]
    │ │ │ │ -
    source
    │ │ │ │ -
    a bitmask specifying which sources we got this tracker from.
    │ │ │ │ -
    │ │ │ │ -[report issue]
    │ │ │ │ -
    verified
    │ │ │ │ -
    set to true the first time we receive a valid response │ │ │ │ -from this tracker.
    │ │ │ │ -
    │ │ │ │ -[report issue]
    │ │ │ │ -
    │ │ │ │ -
    │ │ │ │ -

    dht_state

    │ │ │ │ -

    Declared in "libtorrent/kademlia/dht_state.hpp"

    │ │ │ │ -

    This structure helps to store and load the state │ │ │ │ -of the dht_tracker. │ │ │ │ -At this moment the library is only a dual stack │ │ │ │ -implementation of the DHT. See BEP 32

    │ │ │ │ -
    │ │ │ │ -struct dht_state
│ │ │ │ -{
│ │ │ │ -   void clear ();
│ │ │ │ -
│ │ │ │ -   node_ids_t nids;
│ │ │ │ -   std::vector<udp::endpoint> nodes;
│ │ │ │ -   std::vector<udp::endpoint> nodes6;
│ │ │ │ -};
│ │ │ │ -
    │ │ │ │ -[report issue]
    │ │ │ │ -
    nodes
    │ │ │ │ -
    the bootstrap nodes saved from the buckets node
    │ │ │ │ -
    │ │ │ │ -[report issue]
    │ │ │ │ -
    nodes6
    │ │ │ │ -
    the bootstrap nodes saved from the IPv6 buckets node
    │ │ │ │ -
    │ │ │ │ [report issue]
    │ │ │ │
    │ │ │ │

    dht_storage_counters

    │ │ │ │

    Declared in "libtorrent/kademlia/dht_storage.hpp"

    │ │ │ │

    This structure hold the relevant counters for the storage

    │ │ │ │ 
    │ │ │ │  struct dht_storage_counters
│ │ │ │ @@ -20219,16 +19935,42 @@
│ │ │ │  [report issue]
    │ │ │ │
    │ │ │ │

    counters()

    │ │ │ │ 
    │ │ │ │  virtual dht_storage_counters counters () const = 0;
│ │ │ │
    │ │ │ │

    return stats counters for the store

    │ │ │ │ -[report issue]
    │ │ │ │ +[report issue]
    │ │ │ │
    │ │ │ │ +
    │ │ │ │ +

    dht_state

    │ │ │ │ +

    Declared in "libtorrent/kademlia/dht_state.hpp"

    │ │ │ │ +

    This structure helps to store and load the state │ │ │ │ +of the dht_tracker. │ │ │ │ +At this moment the library is only a dual stack │ │ │ │ +implementation of the DHT. See BEP 32

    │ │ │ │ +
    │ │ │ │ +struct dht_state
│ │ │ │ +{
│ │ │ │ +   void clear ();
│ │ │ │ +
│ │ │ │ +   node_ids_t nids;
│ │ │ │ +   std::vector<udp::endpoint> nodes;
│ │ │ │ +   std::vector<udp::endpoint> nodes6;
│ │ │ │ +};
│ │ │ │ +
    │ │ │ │ +[report issue]
    │ │ │ │ +
    nodes
    │ │ │ │ +
    the bootstrap nodes saved from the buckets node
    │ │ │ │ +
    │ │ │ │ +[report issue]
    │ │ │ │ +
    nodes6
    │ │ │ │ +
    the bootstrap nodes saved from the IPv6 buckets node
    │ │ │ │ +
    │ │ │ │ +[report issue]
    │ │ │ │
    │ │ │ │

    sign_mutable_item()

    │ │ │ │

    Declared in "libtorrent/kademlia/item.hpp"

    │ │ │ │ 
    │ │ │ │  signature sign_mutable_item (
│ │ │ │     span<char const> v
│ │ │ │     , span<char const> salt
│ │ │ │ @@ -20267,74 +20009,74 @@
│ │ │ │  your source UDP port as your listen port, rather than the one specified in
│ │ │ │  the message. This may improve the chances of traversing NATs when using uTP.
│ │ │ │
    │ │ │ │
    │ │ │ │
    ssl_torrent
    │ │ │ │
    Specify the port number for the SSL listen socket in the DHT announce.
    │ │ │ │
    │ │ │ │ -[report issue]
    │ │ │ │ -
    │ │ │ │ -

    read_resume_data()

    │ │ │ │ -

    Declared in "libtorrent/read_resume_data.hpp"

    │ │ │ │ -
    │ │ │ │ -add_torrent_params read_resume_data (bdecode_node const& rd
│ │ │ │ -   , int piece_limit = 0x200000);
│ │ │ │ -add_torrent_params read_resume_data (span<char const> buffer
│ │ │ │ -   , load_torrent_limits const& cfg = {});
│ │ │ │ -add_torrent_params read_resume_data (bdecode_node const& rd
│ │ │ │ -   , error_code& ec, int piece_limit = 0x200000);
│ │ │ │ -add_torrent_params read_resume_data (span<char const> buffer
│ │ │ │ -   , error_code& ec, load_torrent_limits const& cfg = {});
│ │ │ │ -
    │ │ │ │ -

    these functions are used to parse resume data and populate the appropriate │ │ │ │ -fields in an add_torrent_params object. This object can then be used to add │ │ │ │ -the actual torrent_info object to and pass to session::add_torrent() or │ │ │ │ -session::async_add_torrent().

    │ │ │ │ -

    If the client wants to override any field that was loaded from the resume │ │ │ │ -data, e.g. save_path, those fields must be changed after loading resume │ │ │ │ -data but before adding the torrent.

    │ │ │ │ -

    The piece_limit parameter determines the largest number of pieces │ │ │ │ -allowed in the torrent that may be loaded as part of the resume data, if │ │ │ │ -it contains an info field. The overloads that take a flat buffer are │ │ │ │ -instead configured with limits on torrent sizes via load_torrent limits.

    │ │ │ │ -

    In order to support large torrents, it may also be necessary to raise the │ │ │ │ -settings_pack::max_piece_count setting and pass a higher limit to calls │ │ │ │ -to torrent_info::parse_info_section().

    │ │ │ │ - │ │ │ │ -[report issue]
    │ │ │ │ -
    │ │ │ │ -

    write_resume_data() write_resume_data_buf()

    │ │ │ │ + │ │ │ │ +[report issue]
    │ │ │ │ +
    │ │ │ │ +

    write_resume_data_buf() write_resume_data()

    │ │ │ │

    Declared in "libtorrent/write_resume_data.hpp"

    │ │ │ │ 
    │ │ │ │ -std::vector<char> write_resume_data_buf (add_torrent_params const& atp);
│ │ │ │  entry write_resume_data (add_torrent_params const& atp);
│ │ │ │ +std::vector<char> write_resume_data_buf (add_torrent_params const& atp);
│ │ │ │
    │ │ │ │

    this function turns the resume data in an add_torrent_params object │ │ │ │ into a bencoded structure

    │ │ │ │ │ │ │ │ [report issue]
    │ │ │ │
    │ │ │ │

    write_torrent_file_buf() write_torrent_file()

    │ │ │ │

    Declared in "libtorrent/write_resume_data.hpp"

    │ │ │ │ 
    │ │ │ │ -entry write_torrent_file (add_torrent_params const& atp);
│ │ │ │ -entry write_torrent_file (add_torrent_params const& atp, write_torrent_flags_t flags);
│ │ │ │  std::vector<char> write_torrent_file_buf (add_torrent_params const& atp
│ │ │ │     , write_torrent_flags_t flags);
│ │ │ │ +entry write_torrent_file (add_torrent_params const& atp);
│ │ │ │ +entry write_torrent_file (add_torrent_params const& atp, write_torrent_flags_t flags);
│ │ │ │
    │ │ │ │

    writes only the fields to create a .torrent file. This function may fail │ │ │ │ with a std::system_error exception if:

    │ │ │ │
      │ │ │ │
    • The add_torrent_params object passed to this function does not contain the │ │ │ │ info dictionary (the ti field)
      • │ │ │ │
    • The piece layers are not complete for all files that need them
      • │ │ │ │
    │ │ │ │

    The write_torrent_file_buf() overload returns the torrent file in │ │ │ │ bencoded buffer form. This overload may be faster at the expense of lost │ │ │ │ flexibility to add custom fields.

    │ │ │ │ +[report issue]
    │ │ │ │ +
    │ │ │ │ +

    read_resume_data()

    │ │ │ │ +

    Declared in "libtorrent/read_resume_data.hpp"

    │ │ │ │ +
    │ │ │ │ +add_torrent_params read_resume_data (bdecode_node const& rd
│ │ │ │ +   , error_code& ec, int piece_limit = 0x200000);
│ │ │ │ +add_torrent_params read_resume_data (span<char const> buffer
│ │ │ │ +   , error_code& ec, load_torrent_limits const& cfg = {});
│ │ │ │ +add_torrent_params read_resume_data (span<char const> buffer
│ │ │ │ +   , load_torrent_limits const& cfg = {});
│ │ │ │ +add_torrent_params read_resume_data (bdecode_node const& rd
│ │ │ │ +   , int piece_limit = 0x200000);
│ │ │ │ +
    │ │ │ │ +

    these functions are used to parse resume data and populate the appropriate │ │ │ │ +fields in an add_torrent_params object. This object can then be used to add │ │ │ │ +the actual torrent_info object to and pass to session::add_torrent() or │ │ │ │ +session::async_add_torrent().

    │ │ │ │ +

    If the client wants to override any field that was loaded from the resume │ │ │ │ +data, e.g. save_path, those fields must be changed after loading resume │ │ │ │ +data but before adding the torrent.

    │ │ │ │ +

    The piece_limit parameter determines the largest number of pieces │ │ │ │ +allowed in the torrent that may be loaded as part of the resume data, if │ │ │ │ +it contains an info field. The overloads that take a flat buffer are │ │ │ │ +instead configured with limits on torrent sizes via load_torrent limits.

    │ │ │ │ +

    In order to support large torrents, it may also be necessary to raise the │ │ │ │ +settings_pack::max_piece_count setting and pass a higher limit to calls │ │ │ │ +to torrent_info::parse_info_section().

    │ │ │ │ [report issue]
    │ │ │ │
    │ │ │ │

    write_torrent_flags_t

    │ │ │ │

    Declared in "libtorrent/write_resume_data.hpp"

    │ │ │ │
    │ │ │ │
    allow_missing_piece_layer
    │ │ │ │
    this makes write_torrent_file() not fail when attempting to write a │ │ │ │ @@ -20395,18 +20137,18 @@ │ │ │ │ │ │ │ │

    Verifies the signature on the given message using pk

    │ │ │ │ [report issue]
    │ │ │ │
    │ │ │ │

    ed25519_add_scalar()

    │ │ │ │

    Declared in "libtorrent/kademlia/ed25519.hpp"

    │ │ │ │ 
    │ │ │ │ -secret_key ed25519_add_scalar (secret_key const& sk
│ │ │ │ -   , std::array<char, 32> const& scalar);
│ │ │ │  public_key ed25519_add_scalar (public_key const& pk
│ │ │ │     , std::array<char, 32> const& scalar);
│ │ │ │ +secret_key ed25519_add_scalar (secret_key const& sk
│ │ │ │ +   , std::array<char, 32> const& scalar);
│ │ │ │
    │ │ │ │

    Adds a scalar to the given key pair where scalar is a 32 byte buffer │ │ │ │ (possibly generated with ed25519_create_seed), generating a new key pair.

    │ │ │ │

    You can calculate the public key sum without knowing the private key and │ │ │ │ vice versa by passing in null for the key you don't know. This is useful │ │ │ │ when a third party (an authoritative server for example) needs to enforce │ │ │ │ randomness on a key pair while only knowing the public key of the other │ │ │ │ ├── html2text {} │ │ │ │ │ @@ -4,367 +4,254 @@ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ [libtorrent_logo] │ │ │ │ │ Version: 2.0.8 │ │ │ │ │ home │ │ │ │ │ Table of contents │ │ │ │ │ - * bdecode_node │ │ │ │ │ - o bdecode_node() │ │ │ │ │ - o bdecode_node()_operator=() │ │ │ │ │ - o type() │ │ │ │ │ - o bool() │ │ │ │ │ - o non_owning() │ │ │ │ │ - o data_offset()_data_section() │ │ │ │ │ - o list_int_value_at()_list_size()_list_at()_list_string_value_at() │ │ │ │ │ - o dict_at()_dict_find_dict()_dict_find_int_value()_dict_find() │ │ │ │ │ - dict_find_int()_dict_at_node()_dict_find_string() │ │ │ │ │ - dict_find_string_value()_dict_find_list()_dict_size() │ │ │ │ │ - o int_value() │ │ │ │ │ - o string_ptr()_string_length()_string_offset()_string_value() │ │ │ │ │ - o clear() │ │ │ │ │ + * session_proxy │ │ │ │ │ + o session_proxy()_~session_proxy()_operator=() │ │ │ │ │ + * session │ │ │ │ │ + o session() │ │ │ │ │ + o session() │ │ │ │ │ + o ~session() │ │ │ │ │ + o abort() │ │ │ │ │ + * session_params │ │ │ │ │ + o session_params() │ │ │ │ │ + o session_params() │ │ │ │ │ + * session_handle │ │ │ │ │ + o is_valid() │ │ │ │ │ + o session_state() │ │ │ │ │ + o refresh_torrent_status()_get_torrent_status() │ │ │ │ │ + o post_torrent_updates() │ │ │ │ │ + o post_session_stats() │ │ │ │ │ + o post_dht_stats() │ │ │ │ │ + o set_dht_state() │ │ │ │ │ + o find_torrent()_get_torrents() │ │ │ │ │ + o add_torrent()_async_add_torrent() │ │ │ │ │ + o pause()_is_paused()_resume() │ │ │ │ │ + o is_dht_running() │ │ │ │ │ + o set_dht_storage() │ │ │ │ │ + o add_dht_node() │ │ │ │ │ + o dht_get_item() │ │ │ │ │ + o dht_get_item() │ │ │ │ │ + o dht_put_item() │ │ │ │ │ + o dht_put_item() │ │ │ │ │ + o dht_announce()_dht_get_peers() │ │ │ │ │ + o dht_live_nodes() │ │ │ │ │ + o dht_sample_infohashes() │ │ │ │ │ + o dht_direct_request() │ │ │ │ │ + o add_extension() │ │ │ │ │ + o get_ip_filter()_set_ip_filter() │ │ │ │ │ + o set_port_filter() │ │ │ │ │ + o ssl_listen_port()_is_listening()_listen_port() │ │ │ │ │ + o get_peer_class_filter()_set_peer_class_filter() │ │ │ │ │ + o set_peer_class_type_filter()_get_peer_class_type_filter() │ │ │ │ │ + o create_peer_class() │ │ │ │ │ + o delete_peer_class() │ │ │ │ │ + o set_peer_class()_get_peer_class() │ │ │ │ │ + o remove_torrent() │ │ │ │ │ + o get_settings()_apply_settings() │ │ │ │ │ + o wait_for_alert()_set_alert_notify()_pop_alerts() │ │ │ │ │ + o add_port_mapping()_delete_port_mapping() │ │ │ │ │ + o reopen_network_sockets() │ │ │ │ │ + o native_handle() │ │ │ │ │ + * write_session_params()_write_session_params_buf()_read_session_params() │ │ │ │ │ + * info_hash_t │ │ │ │ │ + o info_hash_t() │ │ │ │ │ + o has()_has_v1()_has_v2() │ │ │ │ │ + o get() │ │ │ │ │ + o get_best() │ │ │ │ │ + o for_each() │ │ │ │ │ + * peer_info │ │ │ │ │ + * piece_block │ │ │ │ │ + * peer_request │ │ │ │ │ + o operator==() │ │ │ │ │ + * load_torrent_file()_load_torrent_parsed()_load_torrent_buffer() │ │ │ │ │ + * truncate_files() │ │ │ │ │ + * make_magnet_uri() │ │ │ │ │ + * parse_magnet_uri() │ │ │ │ │ + * version() │ │ │ │ │ + * enum_protocol_version │ │ │ │ │ + * enum_event_t │ │ │ │ │ + * enum_connection_type │ │ │ │ │ + * enum_socket_type_t │ │ │ │ │ + * enum_portmap_transport │ │ │ │ │ + * enum_portmap_protocol │ │ │ │ │ + * download_priority_t │ │ │ │ │ + * pex_flags_t │ │ │ │ │ + * int │ │ │ │ │ + * torrent_flags_t │ │ │ │ │ + * char_const* │ │ │ │ │ + * std::uint64_t │ │ │ │ │ + * add_torrent_params │ │ │ │ │ + * client_data_t │ │ │ │ │ + o client_data_t() │ │ │ │ │ + o const*()_void*()_operator=() │ │ │ │ │ + * open_file_state │ │ │ │ │ + * disk_interface │ │ │ │ │ + o new_torrent() │ │ │ │ │ + o remove_torrent() │ │ │ │ │ + o async_write()_async_read() │ │ │ │ │ + o async_hash() │ │ │ │ │ + o async_hash2() │ │ │ │ │ + o async_move_storage() │ │ │ │ │ + o async_release_files() │ │ │ │ │ + o async_check_files() │ │ │ │ │ + o async_stop_torrent() │ │ │ │ │ + o async_rename_file() │ │ │ │ │ + o async_delete_files() │ │ │ │ │ + o async_set_file_priority() │ │ │ │ │ + o async_clear_piece() │ │ │ │ │ + o update_stats_counters() │ │ │ │ │ + o get_status() │ │ │ │ │ + o abort() │ │ │ │ │ + o submit_jobs() │ │ │ │ │ + o settings_updated() │ │ │ │ │ + * storage_holder │ │ │ │ │ + * settings_interface │ │ │ │ │ + * disk_observer │ │ │ │ │ + o on_disk() │ │ │ │ │ + * buffer_allocator_interface │ │ │ │ │ + * disk_buffer_holder │ │ │ │ │ + o disk_buffer_holder() │ │ │ │ │ + o disk_buffer_holder() │ │ │ │ │ + o ~disk_buffer_holder() │ │ │ │ │ + o data() │ │ │ │ │ + o reset() │ │ │ │ │ o swap() │ │ │ │ │ - o reserve() │ │ │ │ │ - o switch_underlying_buffer() │ │ │ │ │ - o has_soft_error() │ │ │ │ │ - o enum_type_t │ │ │ │ │ - * print_entry() │ │ │ │ │ - * bdecode() │ │ │ │ │ + o is_mutable() │ │ │ │ │ + o bool() │ │ │ │ │ + * file_open_mode_t │ │ │ │ │ * web_seed_entry │ │ │ │ │ o operator==() │ │ │ │ │ o operator<() │ │ │ │ │ o enum_type_t │ │ │ │ │ * load_torrent_limits │ │ │ │ │ * torrent_info │ │ │ │ │ o torrent_info() │ │ │ │ │ o ~torrent_info() │ │ │ │ │ o files()_orig_files() │ │ │ │ │ o rename_file() │ │ │ │ │ o remap_files() │ │ │ │ │ - o trackers()_clear_trackers()_add_tracker() │ │ │ │ │ + o clear_trackers()_trackers()_add_tracker() │ │ │ │ │ o collections()_similar_torrents() │ │ │ │ │ - o add_url_seed()_set_web_seeds()_add_http_seed()_web_seeds() │ │ │ │ │ + o set_web_seeds()_web_seeds()_add_http_seed()_add_url_seed() │ │ │ │ │ o total_size() │ │ │ │ │ o num_pieces()_piece_length() │ │ │ │ │ o last_piece()_end_piece()_piece_range() │ │ │ │ │ - o info_hash()_info_hashes() │ │ │ │ │ + o info_hashes()_info_hash() │ │ │ │ │ o v2()_v1() │ │ │ │ │ o num_files() │ │ │ │ │ o map_block() │ │ │ │ │ o map_file() │ │ │ │ │ o ssl_cert() │ │ │ │ │ o is_valid() │ │ │ │ │ o priv() │ │ │ │ │ o is_i2p() │ │ │ │ │ o piece_size() │ │ │ │ │ - o hash_for_piece()_hash_for_piece_ptr() │ │ │ │ │ + o hash_for_piece_ptr()_hash_for_piece() │ │ │ │ │ o name() │ │ │ │ │ o creation_date() │ │ │ │ │ o creator() │ │ │ │ │ o comment() │ │ │ │ │ o nodes() │ │ │ │ │ o add_node() │ │ │ │ │ o parse_info_section() │ │ │ │ │ o info() │ │ │ │ │ o info_section() │ │ │ │ │ o piece_layer() │ │ │ │ │ o free_piece_layers() │ │ │ │ │ - * entry │ │ │ │ │ - o type() │ │ │ │ │ - o entry() │ │ │ │ │ - o entry() │ │ │ │ │ - o entry() │ │ │ │ │ - o operator=() │ │ │ │ │ - o dict()_string()_list()_integer()_preformatted() │ │ │ │ │ - o swap() │ │ │ │ │ - o operator[]() │ │ │ │ │ - o find_key() │ │ │ │ │ - o to_string() │ │ │ │ │ - o enum_data_type │ │ │ │ │ - * operator<<() │ │ │ │ │ - * bencode() │ │ │ │ │ - * disk_observer │ │ │ │ │ - o on_disk() │ │ │ │ │ - * settings_interface │ │ │ │ │ - * buffer_allocator_interface │ │ │ │ │ - * disk_buffer_holder │ │ │ │ │ - o disk_buffer_holder() │ │ │ │ │ - o disk_buffer_holder() │ │ │ │ │ - o ~disk_buffer_holder() │ │ │ │ │ - o data() │ │ │ │ │ - o reset() │ │ │ │ │ - o swap() │ │ │ │ │ - o is_mutable() │ │ │ │ │ - o bool() │ │ │ │ │ - * open_file_state │ │ │ │ │ - * disk_interface │ │ │ │ │ - o new_torrent() │ │ │ │ │ - o remove_torrent() │ │ │ │ │ - o async_read()_async_write() │ │ │ │ │ - o async_hash() │ │ │ │ │ - o async_hash2() │ │ │ │ │ - o async_move_storage() │ │ │ │ │ - o async_release_files() │ │ │ │ │ - o async_check_files() │ │ │ │ │ - o async_stop_torrent() │ │ │ │ │ - o async_rename_file() │ │ │ │ │ - o async_delete_files() │ │ │ │ │ - o async_set_file_priority() │ │ │ │ │ - o async_clear_piece() │ │ │ │ │ - o update_stats_counters() │ │ │ │ │ - o get_status() │ │ │ │ │ - o abort() │ │ │ │ │ - o submit_jobs() │ │ │ │ │ - o settings_updated() │ │ │ │ │ - * storage_holder │ │ │ │ │ - * file_open_mode_t │ │ │ │ │ - * counters │ │ │ │ │ - o inc_stats_counter()_operator[]() │ │ │ │ │ - * stats_metric │ │ │ │ │ - * session_stats_metrics() │ │ │ │ │ - * find_metric_idx() │ │ │ │ │ - * enum_metric_type_t │ │ │ │ │ - * a_word_of_caution │ │ │ │ │ - * plugin-interface │ │ │ │ │ - * custom_alerts │ │ │ │ │ - * peer_connection_handle │ │ │ │ │ - * bt_peer_connection_handle │ │ │ │ │ - * plugin │ │ │ │ │ - o implemented_features() │ │ │ │ │ - o new_torrent() │ │ │ │ │ - o added() │ │ │ │ │ - o abort() │ │ │ │ │ - o on_dht_request() │ │ │ │ │ - o on_alert() │ │ │ │ │ - o on_unknown_torrent() │ │ │ │ │ - o on_tick() │ │ │ │ │ - o get_unchoke_priority() │ │ │ │ │ - o load_state() │ │ │ │ │ - * torrent_plugin │ │ │ │ │ - o new_connection() │ │ │ │ │ - o on_piece_pass()_on_piece_failed() │ │ │ │ │ - o tick() │ │ │ │ │ - o on_resume()_on_pause() │ │ │ │ │ - o on_files_checked() │ │ │ │ │ - o on_state() │ │ │ │ │ - o on_add_peer() │ │ │ │ │ - * peer_plugin │ │ │ │ │ - o type() │ │ │ │ │ - o add_handshake() │ │ │ │ │ - o on_disconnect() │ │ │ │ │ - o on_connected() │ │ │ │ │ - o on_handshake() │ │ │ │ │ - o on_extension_handshake() │ │ │ │ │ - o on_dont_have()_on_allowed_fast()_on_not_interested()_on_bitfield() │ │ │ │ │ - on_have_none()_on_have()_on_choke()_on_interested()_on_request() │ │ │ │ │ - on_unchoke()_on_have_all() │ │ │ │ │ - o on_piece() │ │ │ │ │ - o sent_have()_sent_unchoke()_sent_piece()_sent_interested() │ │ │ │ │ - sent_not_interested() │ │ │ │ │ - o sent_payload() │ │ │ │ │ - o can_disconnect() │ │ │ │ │ - o on_extended() │ │ │ │ │ - o on_unknown_message() │ │ │ │ │ - o on_piece_pass()_on_piece_failed() │ │ │ │ │ - o tick() │ │ │ │ │ - o write_request() │ │ │ │ │ - * crypto_plugin │ │ │ │ │ - o decrypt() │ │ │ │ │ - * create_ut_pex_plugin() │ │ │ │ │ - * create_ut_metadata_plugin() │ │ │ │ │ - * create_smart_ban_plugin() │ │ │ │ │ - * create_torrent │ │ │ │ │ - o create_torrent() │ │ │ │ │ - o generate_buf()_generate() │ │ │ │ │ - o files() │ │ │ │ │ - o set_comment() │ │ │ │ │ - o set_creator() │ │ │ │ │ - o set_creation_date() │ │ │ │ │ - o set_hash() │ │ │ │ │ - o set_hash2() │ │ │ │ │ - o add_url_seed()_add_http_seed() │ │ │ │ │ - o add_node() │ │ │ │ │ - o add_tracker() │ │ │ │ │ - o set_root_cert() │ │ │ │ │ - o priv()_set_priv() │ │ │ │ │ - o num_pieces() │ │ │ │ │ - o piece_range() │ │ │ │ │ - o file_range() │ │ │ │ │ - o file_piece_range() │ │ │ │ │ - o total_size() │ │ │ │ │ - o piece_size()_piece_length() │ │ │ │ │ - o add_similar_torrent()_add_collection() │ │ │ │ │ - * add_files() │ │ │ │ │ - * set_piece_hashes() │ │ │ │ │ - * piece_block │ │ │ │ │ - * info_hash_t │ │ │ │ │ - o info_hash_t() │ │ │ │ │ - o has()_has_v2()_has_v1() │ │ │ │ │ - o get() │ │ │ │ │ - o get_best() │ │ │ │ │ - o for_each() │ │ │ │ │ - * peer_info │ │ │ │ │ - * peer_request │ │ │ │ │ - o operator==() │ │ │ │ │ - * make_magnet_uri() │ │ │ │ │ - * parse_magnet_uri() │ │ │ │ │ - * load_torrent_buffer()_load_torrent_parsed()_load_torrent_file() │ │ │ │ │ - * version() │ │ │ │ │ - * truncate_files() │ │ │ │ │ - * enum_connection_type │ │ │ │ │ - * enum_event_t │ │ │ │ │ - * enum_socket_type_t │ │ │ │ │ - * enum_portmap_transport │ │ │ │ │ - * enum_portmap_protocol │ │ │ │ │ - * enum_protocol_version │ │ │ │ │ - * download_priority_t │ │ │ │ │ - * torrent_flags_t │ │ │ │ │ - * int │ │ │ │ │ - * char_const* │ │ │ │ │ - * std::uint64_t │ │ │ │ │ - * pex_flags_t │ │ │ │ │ - * ip_filter │ │ │ │ │ - o empty() │ │ │ │ │ - o add_rule() │ │ │ │ │ - o access() │ │ │ │ │ - o export_filter() │ │ │ │ │ - o enum_access_flags │ │ │ │ │ - * port_filter │ │ │ │ │ - o add_rule() │ │ │ │ │ - o access() │ │ │ │ │ - o enum_access_flags │ │ │ │ │ - * storage_params │ │ │ │ │ - * file_slice │ │ │ │ │ - * file_storage │ │ │ │ │ - o is_valid() │ │ │ │ │ - o reserve() │ │ │ │ │ - o add_file()_add_file_borrow() │ │ │ │ │ - o rename_file() │ │ │ │ │ - o map_block() │ │ │ │ │ - o map_file() │ │ │ │ │ - o num_files() │ │ │ │ │ - o end_file() │ │ │ │ │ - o file_range() │ │ │ │ │ - o total_size() │ │ │ │ │ - o num_pieces()_set_num_pieces() │ │ │ │ │ - o end_piece() │ │ │ │ │ - o last_piece() │ │ │ │ │ - o piece_range() │ │ │ │ │ - o set_piece_length()_piece_length() │ │ │ │ │ - o piece_size() │ │ │ │ │ - o piece_size2() │ │ │ │ │ - o blocks_in_piece2() │ │ │ │ │ - o set_name()_name() │ │ │ │ │ - o swap() │ │ │ │ │ - o canonicalize() │ │ │ │ │ - o file_size()_hash()_pad_file_at()_root()_file_offset()_root_ptr() │ │ │ │ │ - file_path()_file_name()_mtime()_symlink() │ │ │ │ │ - o file_num_pieces()_file_num_blocks()_file_piece_range() │ │ │ │ │ - o file_first_block_node()_file_first_piece_node() │ │ │ │ │ - o file_path_hash() │ │ │ │ │ - o all_path_hashes() │ │ │ │ │ - o file_flags() │ │ │ │ │ - o file_absolute_path() │ │ │ │ │ - o file_index_at_offset()_file_index_at_piece() │ │ │ │ │ - o file_index_for_root() │ │ │ │ │ - o piece_index_at_file() │ │ │ │ │ - o sanitize_symlinks() │ │ │ │ │ - o v2() │ │ │ │ │ - * posix_disk_io_constructor() │ │ │ │ │ - * mmap_disk_io_constructor() │ │ │ │ │ - * disabled_disk_io_constructor() │ │ │ │ │ - * default_disk_io_constructor() │ │ │ │ │ - * enum_storage_mode_t │ │ │ │ │ - * enum_status_t │ │ │ │ │ - * enum_move_flags_t │ │ │ │ │ * settings_pack │ │ │ │ │ - o set_str()_set_bool()_set_int() │ │ │ │ │ + o set_bool()_set_int()_set_str() │ │ │ │ │ o has_val() │ │ │ │ │ o clear() │ │ │ │ │ o clear() │ │ │ │ │ - o get_bool()_get_int()_get_str() │ │ │ │ │ + o get_int()_get_str()_get_bool() │ │ │ │ │ o enum_type_bases │ │ │ │ │ o enum_mmap_write_mode_t │ │ │ │ │ o enum_suggest_mode_t │ │ │ │ │ o enum_choking_algorithm_t │ │ │ │ │ o enum_seed_choking_algorithm_t │ │ │ │ │ o enum_io_buffer_mode_t │ │ │ │ │ o enum_bandwidth_mixed_algo_t │ │ │ │ │ o enum_enc_policy │ │ │ │ │ o enum_enc_level │ │ │ │ │ o enum_proxy_type_t │ │ │ │ │ - * generate_fingerprint() │ │ │ │ │ + * min_memory_usage()_high_performance_seed() │ │ │ │ │ * name_for_setting()_setting_by_name() │ │ │ │ │ * default_settings() │ │ │ │ │ - * high_performance_seed()_min_memory_usage() │ │ │ │ │ - * session_params │ │ │ │ │ - o session_params() │ │ │ │ │ - o session_params() │ │ │ │ │ - * session_proxy │ │ │ │ │ - o ~session_proxy()_operator=()_session_proxy() │ │ │ │ │ - * session │ │ │ │ │ - o session() │ │ │ │ │ - o session() │ │ │ │ │ - o ~session() │ │ │ │ │ - o abort() │ │ │ │ │ - * session_handle │ │ │ │ │ - o is_valid() │ │ │ │ │ - o session_state() │ │ │ │ │ - o get_torrent_status()_refresh_torrent_status() │ │ │ │ │ - o post_torrent_updates() │ │ │ │ │ - o post_session_stats() │ │ │ │ │ - o post_dht_stats() │ │ │ │ │ - o set_dht_state() │ │ │ │ │ - o find_torrent()_get_torrents() │ │ │ │ │ - o add_torrent()_async_add_torrent() │ │ │ │ │ - o resume()_pause()_is_paused() │ │ │ │ │ - o is_dht_running() │ │ │ │ │ - o set_dht_storage() │ │ │ │ │ - o add_dht_node() │ │ │ │ │ - o dht_get_item() │ │ │ │ │ - o dht_get_item() │ │ │ │ │ - o dht_put_item() │ │ │ │ │ - o dht_put_item() │ │ │ │ │ - o dht_get_peers()_dht_announce() │ │ │ │ │ - o dht_live_nodes() │ │ │ │ │ - o dht_sample_infohashes() │ │ │ │ │ - o dht_direct_request() │ │ │ │ │ - o add_extension() │ │ │ │ │ - o get_ip_filter()_set_ip_filter() │ │ │ │ │ - o set_port_filter() │ │ │ │ │ - o ssl_listen_port()_listen_port()_is_listening() │ │ │ │ │ - o set_peer_class_filter()_get_peer_class_filter() │ │ │ │ │ - o get_peer_class_type_filter()_set_peer_class_type_filter() │ │ │ │ │ - o create_peer_class() │ │ │ │ │ - o delete_peer_class() │ │ │ │ │ - o set_peer_class()_get_peer_class() │ │ │ │ │ - o remove_torrent() │ │ │ │ │ - o apply_settings()_get_settings() │ │ │ │ │ - o set_alert_notify()_pop_alerts()_wait_for_alert() │ │ │ │ │ - o delete_port_mapping()_add_port_mapping() │ │ │ │ │ - o reopen_network_sockets() │ │ │ │ │ - o native_handle() │ │ │ │ │ - * write_session_params_buf()_write_session_params()_read_session_params() │ │ │ │ │ - * alert │ │ │ │ │ - o timestamp() │ │ │ │ │ - o type() │ │ │ │ │ - o what() │ │ │ │ │ - o message() │ │ │ │ │ - o category() │ │ │ │ │ + * generate_fingerprint() │ │ │ │ │ + * bitfield │ │ │ │ │ + o bitfield() │ │ │ │ │ + o assign() │ │ │ │ │ + o operator[]()_get_bit() │ │ │ │ │ + o clear_bit()_set_bit() │ │ │ │ │ + o all_set() │ │ │ │ │ + o none_set() │ │ │ │ │ + o size() │ │ │ │ │ + o num_words() │ │ │ │ │ + o empty() │ │ │ │ │ + o data() │ │ │ │ │ + o swap() │ │ │ │ │ + o count() │ │ │ │ │ + o find_first_set() │ │ │ │ │ + o find_last_clear() │ │ │ │ │ + * hasher │ │ │ │ │ + o operator=()_hasher() │ │ │ │ │ + o update() │ │ │ │ │ + o final() │ │ │ │ │ + o reset() │ │ │ │ │ + * hasher256 │ │ │ │ │ + o hasher256()_operator=() │ │ │ │ │ + o update() │ │ │ │ │ + o final() │ │ │ │ │ + o reset() │ │ │ │ │ + * peer_class_type_filter │ │ │ │ │ + o add()_remove() │ │ │ │ │ + o disallow()_allow() │ │ │ │ │ + o apply() │ │ │ │ │ + o enum_socket_type_t │ │ │ │ │ + * peer_class_info │ │ │ │ │ + * storage_error │ │ │ │ │ + o bool() │ │ │ │ │ + o file() │ │ │ │ │ + * libtorrent_category() │ │ │ │ │ + * http_category() │ │ │ │ │ + * pcp_category() │ │ │ │ │ + * upnp_category() │ │ │ │ │ + * gzip_category() │ │ │ │ │ + * socks_category() │ │ │ │ │ + * i2p_category() │ │ │ │ │ + * bdecode_category() │ │ │ │ │ + * enum_error_code_enum │ │ │ │ │ + * enum_http_errors │ │ │ │ │ + * enum_pcp_errors │ │ │ │ │ + * enum_error_code_enum │ │ │ │ │ + * enum_error_code_enum │ │ │ │ │ + * enum_socks_error_code │ │ │ │ │ + * enum_i2p_error_code │ │ │ │ │ + * enum_error_code_enum │ │ │ │ │ + * counters │ │ │ │ │ + o operator[]()_inc_stats_counter() │ │ │ │ │ + * stats_metric │ │ │ │ │ + * session_stats_metrics() │ │ │ │ │ + * find_metric_idx() │ │ │ │ │ + * enum_metric_type_t │ │ │ │ │ * dht_routing_bucket │ │ │ │ │ * torrent_alert │ │ │ │ │ o message() │ │ │ │ │ * peer_alert │ │ │ │ │ * tracker_alert │ │ │ │ │ o tracker_url() │ │ │ │ │ * torrent_removed_alert │ │ │ │ │ * read_piece_alert │ │ │ │ │ * file_completed_alert │ │ │ │ │ * file_renamed_alert │ │ │ │ │ - o new_name()_old_name() │ │ │ │ │ + o old_name()_new_name() │ │ │ │ │ * file_rename_failed_alert │ │ │ │ │ * performance_alert │ │ │ │ │ o enum_performance_warning_t │ │ │ │ │ * state_changed_alert │ │ │ │ │ * tracker_error_alert │ │ │ │ │ o failure_reason() │ │ │ │ │ * tracker_warning_alert │ │ │ │ │ @@ -464,2829 +351,1140 @@ │ │ │ │ │ * dht_direct_response_alert │ │ │ │ │ * picker_log_alert │ │ │ │ │ * session_error_alert │ │ │ │ │ * dht_live_nodes_alert │ │ │ │ │ o num_nodes()_nodes() │ │ │ │ │ * session_stats_header_alert │ │ │ │ │ * dht_sample_infohashes_alert │ │ │ │ │ - o num_samples()_samples() │ │ │ │ │ + o samples()_num_samples() │ │ │ │ │ o num_nodes() │ │ │ │ │ o nodes() │ │ │ │ │ * block_uploaded_alert │ │ │ │ │ * alerts_dropped_alert │ │ │ │ │ * socks5_alert │ │ │ │ │ * file_prio_alert │ │ │ │ │ * oversized_file_alert │ │ │ │ │ * torrent_conflict_alert │ │ │ │ │ + * alert │ │ │ │ │ + o timestamp() │ │ │ │ │ + o type() │ │ │ │ │ + o what() │ │ │ │ │ + o message() │ │ │ │ │ + o category() │ │ │ │ │ * operation_name() │ │ │ │ │ * alert_cast() │ │ │ │ │ * enum_operation_t │ │ │ │ │ - * alert_category_t │ │ │ │ │ * int │ │ │ │ │ - * client_data_t │ │ │ │ │ - o client_data_t() │ │ │ │ │ - o const*()_operator=()_void*() │ │ │ │ │ - * add_torrent_params │ │ │ │ │ - * hasher │ │ │ │ │ - o hasher()_operator=() │ │ │ │ │ - o update() │ │ │ │ │ - o final() │ │ │ │ │ - o reset() │ │ │ │ │ - * hasher256 │ │ │ │ │ - o hasher256()_operator=() │ │ │ │ │ - o update() │ │ │ │ │ - o final() │ │ │ │ │ - o reset() │ │ │ │ │ - * bitfield │ │ │ │ │ - o bitfield() │ │ │ │ │ - o assign() │ │ │ │ │ - o operator[]()_get_bit() │ │ │ │ │ - o clear_bit()_set_bit() │ │ │ │ │ - o all_set() │ │ │ │ │ - o none_set() │ │ │ │ │ - o size() │ │ │ │ │ - o num_words() │ │ │ │ │ - o empty() │ │ │ │ │ - o data() │ │ │ │ │ - o swap() │ │ │ │ │ - o count() │ │ │ │ │ - o find_first_set() │ │ │ │ │ - o find_last_clear() │ │ │ │ │ + * alert_category_t │ │ │ │ │ * torrent_status │ │ │ │ │ o operator==() │ │ │ │ │ o enum_state_t │ │ │ │ │ - * peer_class_type_filter │ │ │ │ │ - o add()_remove() │ │ │ │ │ - o disallow()_allow() │ │ │ │ │ - o apply() │ │ │ │ │ - o enum_socket_type_t │ │ │ │ │ - * peer_class_info │ │ │ │ │ + * entry │ │ │ │ │ + o type() │ │ │ │ │ + o entry() │ │ │ │ │ + o entry() │ │ │ │ │ + o entry() │ │ │ │ │ + o operator=() │ │ │ │ │ + o preformatted()_integer()_list()_dict()_string() │ │ │ │ │ + o swap() │ │ │ │ │ + o operator[]() │ │ │ │ │ + o find_key() │ │ │ │ │ + o to_string() │ │ │ │ │ + o enum_data_type │ │ │ │ │ + * operator<<() │ │ │ │ │ + * bencode() │ │ │ │ │ + * a_word_of_caution │ │ │ │ │ + * plugin-interface │ │ │ │ │ + * custom_alerts │ │ │ │ │ + * plugin │ │ │ │ │ + o implemented_features() │ │ │ │ │ + o new_torrent() │ │ │ │ │ + o added() │ │ │ │ │ + o abort() │ │ │ │ │ + o on_dht_request() │ │ │ │ │ + o on_alert() │ │ │ │ │ + o on_unknown_torrent() │ │ │ │ │ + o on_tick() │ │ │ │ │ + o get_unchoke_priority() │ │ │ │ │ + o load_state() │ │ │ │ │ + * torrent_plugin │ │ │ │ │ + o new_connection() │ │ │ │ │ + o on_piece_failed()_on_piece_pass() │ │ │ │ │ + o tick() │ │ │ │ │ + o on_pause()_on_resume() │ │ │ │ │ + o on_files_checked() │ │ │ │ │ + o on_state() │ │ │ │ │ + o on_add_peer() │ │ │ │ │ + * peer_plugin │ │ │ │ │ + o type() │ │ │ │ │ + o add_handshake() │ │ │ │ │ + o on_disconnect() │ │ │ │ │ + o on_connected() │ │ │ │ │ + o on_handshake() │ │ │ │ │ + o on_extension_handshake() │ │ │ │ │ + o on_have()_on_have_all()_on_interested()_on_request()_on_bitfield() │ │ │ │ │ + on_dont_have()_on_allowed_fast()_on_unchoke()_on_have_none() │ │ │ │ │ + on_not_interested()_on_choke() │ │ │ │ │ + o on_piece() │ │ │ │ │ + o sent_piece()_sent_unchoke()_sent_interested()_sent_not_interested() │ │ │ │ │ + sent_have() │ │ │ │ │ + o sent_payload() │ │ │ │ │ + o can_disconnect() │ │ │ │ │ + o on_extended() │ │ │ │ │ + o on_unknown_message() │ │ │ │ │ + o on_piece_failed()_on_piece_pass() │ │ │ │ │ + o tick() │ │ │ │ │ + o write_request() │ │ │ │ │ + * crypto_plugin │ │ │ │ │ + o decrypt() │ │ │ │ │ + * peer_connection_handle │ │ │ │ │ + * bt_peer_connection_handle │ │ │ │ │ + * create_ut_metadata_plugin() │ │ │ │ │ + * create_smart_ban_plugin() │ │ │ │ │ + * create_ut_pex_plugin() │ │ │ │ │ + * ip_filter │ │ │ │ │ + o empty() │ │ │ │ │ + o add_rule() │ │ │ │ │ + o access() │ │ │ │ │ + o export_filter() │ │ │ │ │ + o enum_access_flags │ │ │ │ │ + * port_filter │ │ │ │ │ + o add_rule() │ │ │ │ │ + o access() │ │ │ │ │ + o enum_access_flags │ │ │ │ │ + * bdecode_node │ │ │ │ │ + o bdecode_node() │ │ │ │ │ + o bdecode_node()_operator=() │ │ │ │ │ + o type() │ │ │ │ │ + o bool() │ │ │ │ │ + o non_owning() │ │ │ │ │ + o data_offset()_data_section() │ │ │ │ │ + o list_string_value_at()_list_at()_list_int_value_at()_list_size() │ │ │ │ │ + o dict_find_string_value()_dict_find_int_value()_dict_find()_dict_at │ │ │ │ │ + ()_dict_find_dict()_dict_find_string()_dict_find_int()_dict_at_node │ │ │ │ │ + ()_dict_size()_dict_find_list() │ │ │ │ │ + o int_value() │ │ │ │ │ + o string_ptr()_string_offset()_string_value()_string_length() │ │ │ │ │ + o clear() │ │ │ │ │ + o swap() │ │ │ │ │ + o reserve() │ │ │ │ │ + o switch_underlying_buffer() │ │ │ │ │ + o has_soft_error() │ │ │ │ │ + o enum_type_t │ │ │ │ │ + * print_entry() │ │ │ │ │ + * bdecode() │ │ │ │ │ + * storage_params │ │ │ │ │ + * file_slice │ │ │ │ │ + * file_storage │ │ │ │ │ + o is_valid() │ │ │ │ │ + o reserve() │ │ │ │ │ + o add_file()_add_file_borrow() │ │ │ │ │ + o rename_file() │ │ │ │ │ + o map_block() │ │ │ │ │ + o map_file() │ │ │ │ │ + o num_files() │ │ │ │ │ + o end_file() │ │ │ │ │ + o file_range() │ │ │ │ │ + o total_size() │ │ │ │ │ + o num_pieces()_set_num_pieces() │ │ │ │ │ + o end_piece() │ │ │ │ │ + o last_piece() │ │ │ │ │ + o piece_range() │ │ │ │ │ + o set_piece_length()_piece_length() │ │ │ │ │ + o piece_size() │ │ │ │ │ + o piece_size2() │ │ │ │ │ + o blocks_in_piece2() │ │ │ │ │ + o set_name()_name() │ │ │ │ │ + o swap() │ │ │ │ │ + o canonicalize() │ │ │ │ │ + o file_name()_file_size()_file_offset()_mtime()_root()_file_path() │ │ │ │ │ + root_ptr()_symlink()_pad_file_at()_hash() │ │ │ │ │ + o file_num_pieces()_file_piece_range()_file_num_blocks() │ │ │ │ │ + o file_first_piece_node()_file_first_block_node() │ │ │ │ │ + o file_path_hash() │ │ │ │ │ + o all_path_hashes() │ │ │ │ │ + o file_flags() │ │ │ │ │ + o file_absolute_path() │ │ │ │ │ + o file_index_at_offset()_file_index_at_piece() │ │ │ │ │ + o file_index_for_root() │ │ │ │ │ + o piece_index_at_file() │ │ │ │ │ + o sanitize_symlinks() │ │ │ │ │ + o v2() │ │ │ │ │ + * default_disk_io_constructor() │ │ │ │ │ + * posix_disk_io_constructor() │ │ │ │ │ + * mmap_disk_io_constructor() │ │ │ │ │ + * disabled_disk_io_constructor() │ │ │ │ │ + * enum_storage_mode_t │ │ │ │ │ + * enum_status_t │ │ │ │ │ + * enum_move_flags_t │ │ │ │ │ + * announce_infohash │ │ │ │ │ + * announce_endpoint │ │ │ │ │ + * announce_entry │ │ │ │ │ + o ~announce_entry()_announce_entry()_operator=() │ │ │ │ │ + o enum_tracker_source │ │ │ │ │ + * create_torrent │ │ │ │ │ + o create_torrent() │ │ │ │ │ + o generate()_generate_buf() │ │ │ │ │ + o files() │ │ │ │ │ + o set_comment() │ │ │ │ │ + o set_creator() │ │ │ │ │ + o set_creation_date() │ │ │ │ │ + o set_hash() │ │ │ │ │ + o set_hash2() │ │ │ │ │ + o add_http_seed()_add_url_seed() │ │ │ │ │ + o add_node() │ │ │ │ │ + o add_tracker() │ │ │ │ │ + o set_root_cert() │ │ │ │ │ + o priv()_set_priv() │ │ │ │ │ + o num_pieces() │ │ │ │ │ + o piece_range() │ │ │ │ │ + o file_range() │ │ │ │ │ + o file_piece_range() │ │ │ │ │ + o total_size() │ │ │ │ │ + o piece_size()_piece_length() │ │ │ │ │ + o add_similar_torrent()_add_collection() │ │ │ │ │ + * add_files() │ │ │ │ │ + * set_piece_hashes() │ │ │ │ │ * block_info │ │ │ │ │ - o peer()_set_peer() │ │ │ │ │ + o set_peer()_peer() │ │ │ │ │ o enum_block_state_t │ │ │ │ │ * partial_piece_info │ │ │ │ │ * torrent_handle │ │ │ │ │ o torrent_handle() │ │ │ │ │ o add_piece() │ │ │ │ │ o read_piece() │ │ │ │ │ o have_piece() │ │ │ │ │ o get_peer_info() │ │ │ │ │ o status() │ │ │ │ │ o get_download_queue() │ │ │ │ │ - o clear_piece_deadlines()_set_piece_deadline()_reset_piece_deadline() │ │ │ │ │ + o reset_piece_deadline()_set_piece_deadline()_clear_piece_deadlines() │ │ │ │ │ o file_progress() │ │ │ │ │ o file_status() │ │ │ │ │ o clear_error() │ │ │ │ │ o trackers()_replace_trackers()_add_tracker() │ │ │ │ │ - o add_url_seed()_url_seeds()_remove_url_seed() │ │ │ │ │ + o remove_url_seed()_url_seeds()_add_url_seed() │ │ │ │ │ o http_seeds()_add_http_seed()_remove_http_seed() │ │ │ │ │ o add_extension() │ │ │ │ │ o set_metadata() │ │ │ │ │ o is_valid() │ │ │ │ │ - o resume()_pause() │ │ │ │ │ - o set_flags()_unset_flags()_flags() │ │ │ │ │ + o pause()_resume() │ │ │ │ │ + o unset_flags()_set_flags()_flags() │ │ │ │ │ o flush_cache() │ │ │ │ │ o force_recheck() │ │ │ │ │ o save_resume_data() │ │ │ │ │ o need_save_resume_data() │ │ │ │ │ - o queue_position()_queue_position_bottom()_queue_position_up() │ │ │ │ │ - queue_position_top()_queue_position_down() │ │ │ │ │ + o queue_position_down()_queue_position()_queue_position_up() │ │ │ │ │ + queue_position_bottom()_queue_position_top() │ │ │ │ │ o queue_position_set() │ │ │ │ │ - o set_ssl_certificate_buffer()_set_ssl_certificate() │ │ │ │ │ - o torrent_file_with_hashes()_torrent_file() │ │ │ │ │ + o set_ssl_certificate()_set_ssl_certificate_buffer() │ │ │ │ │ + o torrent_file()_torrent_file_with_hashes() │ │ │ │ │ o piece_layers() │ │ │ │ │ o piece_availability() │ │ │ │ │ o piece_priority()_get_piece_priorities()_prioritize_pieces() │ │ │ │ │ - o prioritize_files()_file_priority()_get_file_priorities() │ │ │ │ │ - o force_dht_announce()_force_reannounce()_force_lsd_announce() │ │ │ │ │ + o file_priority()_get_file_priorities()_prioritize_files() │ │ │ │ │ + o force_reannounce()_force_lsd_announce()_force_dht_announce() │ │ │ │ │ o scrape_tracker() │ │ │ │ │ - o download_limit()_set_download_limit()_set_upload_limit() │ │ │ │ │ + o download_limit()_set_upload_limit()_set_download_limit() │ │ │ │ │ upload_limit() │ │ │ │ │ o connect_peer() │ │ │ │ │ o clear_peers() │ │ │ │ │ o set_max_uploads()_max_uploads() │ │ │ │ │ - o max_connections()_set_max_connections() │ │ │ │ │ + o set_max_connections()_max_connections() │ │ │ │ │ o move_storage() │ │ │ │ │ o rename_file() │ │ │ │ │ - o info_hash()_info_hashes() │ │ │ │ │ + o info_hashes()_info_hash() │ │ │ │ │ o operator!=()_operator<()_operator==() │ │ │ │ │ o id() │ │ │ │ │ o native_handle() │ │ │ │ │ o userdata() │ │ │ │ │ o in_session() │ │ │ │ │ * hash_value() │ │ │ │ │ - * storage_error │ │ │ │ │ - o bool() │ │ │ │ │ - o file() │ │ │ │ │ - * bdecode_category() │ │ │ │ │ - * i2p_category() │ │ │ │ │ - * socks_category() │ │ │ │ │ - * pcp_category() │ │ │ │ │ - * upnp_category() │ │ │ │ │ - * libtorrent_category() │ │ │ │ │ - * http_category() │ │ │ │ │ - * gzip_category() │ │ │ │ │ - * enum_error_code_enum │ │ │ │ │ - * enum_i2p_error_code │ │ │ │ │ - * enum_socks_error_code │ │ │ │ │ - * enum_pcp_errors │ │ │ │ │ - * enum_error_code_enum │ │ │ │ │ - * enum_error_code_enum │ │ │ │ │ - * enum_http_errors │ │ │ │ │ - * enum_error_code_enum │ │ │ │ │ - * announce_infohash │ │ │ │ │ - * announce_endpoint │ │ │ │ │ - * announce_entry │ │ │ │ │ - o ~announce_entry()_operator=()_announce_entry() │ │ │ │ │ - o enum_tracker_source │ │ │ │ │ - * dht_state │ │ │ │ │ * dht_storage_counters │ │ │ │ │ o reset() │ │ │ │ │ * dht_storage_interface │ │ │ │ │ o update_node_ids() │ │ │ │ │ o get_peers() │ │ │ │ │ o announce_peer() │ │ │ │ │ o get_immutable_item() │ │ │ │ │ o put_immutable_item() │ │ │ │ │ o get_mutable_item_seq() │ │ │ │ │ o get_mutable_item() │ │ │ │ │ o put_mutable_item() │ │ │ │ │ o get_infohashes_sample() │ │ │ │ │ o tick() │ │ │ │ │ o counters() │ │ │ │ │ + * dht_state │ │ │ │ │ * sign_mutable_item() │ │ │ │ │ * dht_default_storage_constructor() │ │ │ │ │ * announce_flags_t │ │ │ │ │ - * read_resume_data() │ │ │ │ │ - * write_resume_data()_write_resume_data_buf() │ │ │ │ │ + * write_resume_data_buf()_write_resume_data() │ │ │ │ │ * write_torrent_file_buf()_write_torrent_file() │ │ │ │ │ + * read_resume_data() │ │ │ │ │ * write_torrent_flags_t │ │ │ │ │ * ed25519_create_seed() │ │ │ │ │ * ed25519_create_keypair() │ │ │ │ │ * ed25519_sign() │ │ │ │ │ * ed25519_verify() │ │ │ │ │ * ed25519_add_scalar() │ │ │ │ │ * ed25519_key_exchange() │ │ │ │ │ [report_issue] │ │ │ │ │ -****** bdecode_node ****** │ │ │ │ │ -Declared in "libtorrent/bdecode.hpp" │ │ │ │ │ -Sometimes it's important to get a non-owning reference to the root node ( to be │ │ │ │ │ -able to copy it as a reference for instance). For that, use the non_owning() │ │ │ │ │ -member function. │ │ │ │ │ -There are 5 different types of nodes, see type_t. │ │ │ │ │ -struct bdecode_node │ │ │ │ │ -{ │ │ │ │ │ - bdecode_node () = default; │ │ │ │ │ - bdecode_node (bdecode_node const&); │ │ │ │ │ - bdecode_node& operator= (bdecode_node&&) & = default; │ │ │ │ │ - bdecode_node& operator= (bdecode_node const&) &; │ │ │ │ │ - bdecode_node (bdecode_node&&) noexcept; │ │ │ │ │ - type_t type () const noexcept; │ │ │ │ │ - explicit operator bool () const noexcept; │ │ │ │ │ - bdecode_node non_owning () const; │ │ │ │ │ - std::ptrdiff_t data_offset () const noexcept; │ │ │ │ │ - span data_section () const noexcept; │ │ │ │ │ - string_view list_string_value_at (int i │ │ │ │ │ - , string_view default_val = string_view()) const; │ │ │ │ │ - std::int64_t list_int_value_at (int i │ │ │ │ │ - , std::int64_t default_val = 0) const; │ │ │ │ │ - int list_size () const; │ │ │ │ │ - bdecode_node list_at (int i) const; │ │ │ │ │ - bdecode_node dict_find_dict (string_view key) const; │ │ │ │ │ - string_view dict_find_string_value (string_view key │ │ │ │ │ - , string_view default_value = string_view()) const; │ │ │ │ │ - bdecode_node dict_find (string_view key) const; │ │ │ │ │ - std::int64_t dict_find_int_value (string_view key │ │ │ │ │ - , std::int64_t default_val = 0) const; │ │ │ │ │ - int dict_size () const; │ │ │ │ │ - std::pair dict_at_node (int i) const; │ │ │ │ │ - bdecode_node dict_find_list (string_view key) const; │ │ │ │ │ - bdecode_node dict_find_string (string_view key) const; │ │ │ │ │ - bdecode_node dict_find_int (string_view key) const; │ │ │ │ │ - std::pair dict_at (int i) const; │ │ │ │ │ - std::int64_t int_value () const; │ │ │ │ │ - string_view string_value () const; │ │ │ │ │ - std::ptrdiff_t string_offset () const; │ │ │ │ │ - char const* string_ptr () const; │ │ │ │ │ - int string_length () const; │ │ │ │ │ - void clear (); │ │ │ │ │ - void swap (bdecode_node& n); │ │ │ │ │ - void reserve (int tokens); │ │ │ │ │ - void switch_underlying_buffer (char const* buf) noexcept; │ │ │ │ │ - bool has_soft_error (span error) const; │ │ │ │ │ - │ │ │ │ │ - enum type_t │ │ │ │ │ - { │ │ │ │ │ - none_t, │ │ │ │ │ - dict_t, │ │ │ │ │ - list_t, │ │ │ │ │ - string_t, │ │ │ │ │ - int_t, │ │ │ │ │ - }; │ │ │ │ │ -}; │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** bdecode_node() ***** │ │ │ │ │ -bdecode_node () = default; │ │ │ │ │ -creates a default constructed node, it will have the type none_t. │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** bdecode_node() operator=() ***** │ │ │ │ │ -bdecode_node (bdecode_node const&); │ │ │ │ │ -bdecode_node& operator= (bdecode_node&&) & = default; │ │ │ │ │ -bdecode_node& operator= (bdecode_node const&) &; │ │ │ │ │ -bdecode_node (bdecode_node&&) noexcept; │ │ │ │ │ -For owning nodes, the copy will create a copy of the tree, but the underlying │ │ │ │ │ -buffer remains the same. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** type() ***** │ │ │ │ │ -type_t type () const noexcept; │ │ │ │ │ -the type of this node. See type_t. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** bool() ***** │ │ │ │ │ -explicit operator bool () const noexcept; │ │ │ │ │ -returns true if type() != none_t. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** non_owning() ***** │ │ │ │ │ -bdecode_node non_owning () const; │ │ │ │ │ -return a non-owning reference to this node. This is useful to refer to the root │ │ │ │ │ -node without copying it in assignments. │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** data_offset() data_section() ***** │ │ │ │ │ -std::ptrdiff_t data_offset () const noexcept; │ │ │ │ │ -span data_section () const noexcept; │ │ │ │ │ -returns the buffer and length of the section in the original bencoded buffer │ │ │ │ │ -where this node is defined. For a dictionary for instance, this starts with d │ │ │ │ │ -and ends with e, and has all the content of the dictionary in between. the │ │ │ │ │ -data_offset() function returns the byte-offset to this node in, starting from │ │ │ │ │ -the beginning of the buffer that was parsed. │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** list_int_value_at() list_size() list_at() list_string_value_at() ***** │ │ │ │ │ -string_view list_string_value_at (int i │ │ │ │ │ - , string_view default_val = string_view()) const; │ │ │ │ │ -std::int64_t list_int_value_at (int i │ │ │ │ │ - , std::int64_t default_val = 0) const; │ │ │ │ │ -int list_size () const; │ │ │ │ │ -bdecode_node list_at (int i) const; │ │ │ │ │ -functions with the list_ prefix operate on lists. These functions are only │ │ │ │ │ -valid if type() == list_t. list_at() returns the item in the list at index i. i │ │ │ │ │ -may not be greater than or equal to the size of the list. size() returns the │ │ │ │ │ -size of the list. │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** dict_at() dict_find_dict() dict_find_int_value() dict_find() │ │ │ │ │ -dict_find_int() dict_at_node() dict_find_string() dict_find_string_value() │ │ │ │ │ -dict_find_list() dict_size() ***** │ │ │ │ │ -bdecode_node dict_find_dict (string_view key) const; │ │ │ │ │ -string_view dict_find_string_value (string_view key │ │ │ │ │ - , string_view default_value = string_view()) const; │ │ │ │ │ -bdecode_node dict_find (string_view key) const; │ │ │ │ │ -std::int64_t dict_find_int_value (string_view key │ │ │ │ │ - , std::int64_t default_val = 0) const; │ │ │ │ │ -int dict_size () const; │ │ │ │ │ -std::pair dict_at_node (int i) const; │ │ │ │ │ -bdecode_node dict_find_list (string_view key) const; │ │ │ │ │ -bdecode_node dict_find_string (string_view key) const; │ │ │ │ │ -bdecode_node dict_find_int (string_view key) const; │ │ │ │ │ -std::pair dict_at (int i) const; │ │ │ │ │ -Functions with the dict_ prefix operates on dictionaries. They are only valid │ │ │ │ │ -if type() == dict_t. In case a key you're looking up contains a 0 byte, you │ │ │ │ │ -cannot use the 0-terminated string overloads, but have to use string_view │ │ │ │ │ -instead. dict_find_list will return a valid bdecode_node if the key is found │ │ │ │ │ -_and_ it is a list. Otherwise it will return a default-constructed │ │ │ │ │ -bdecode_node. │ │ │ │ │ -Functions with the _value suffix return the value of the node directly, rather │ │ │ │ │ -than the nodes. In case the node is not found, or it has a different type, a │ │ │ │ │ -default value is returned (which can be specified). │ │ │ │ │ -dict_at() returns the (key, value)-pair at the specified index in a dictionary. │ │ │ │ │ -Keys are only allowed to be strings. dict_at_node() also returns the (key, │ │ │ │ │ -value)-pair, but the key is returned as a bdecode_node (and it will always be a │ │ │ │ │ -string). │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** int_value() ***** │ │ │ │ │ -std::int64_t int_value () const; │ │ │ │ │ -this function is only valid if type() == int_t. It returns the value of the │ │ │ │ │ -integer. │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** string_ptr() string_length() string_offset() string_value() ***** │ │ │ │ │ -string_view string_value () const; │ │ │ │ │ -std::ptrdiff_t string_offset () const; │ │ │ │ │ -char const* string_ptr () const; │ │ │ │ │ -int string_length () const; │ │ │ │ │ -these functions are only valid if type() == string_t. They return the string │ │ │ │ │ -values. Note that string_ptr() is not 0-terminated. string_length() returns the │ │ │ │ │ -number of bytes in the string. string_offset() returns the byte offset from the │ │ │ │ │ -start of the parsed bencoded buffer this string can be found. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** clear() ***** │ │ │ │ │ -void clear (); │ │ │ │ │ -resets the bdecoded_node to a default constructed state. If this is an owning │ │ │ │ │ -node, the tree is freed and all child nodes are invalidated. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** swap() ***** │ │ │ │ │ -void swap (bdecode_node& n); │ │ │ │ │ -Swap contents. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** reserve() ***** │ │ │ │ │ -void reserve (int tokens); │ │ │ │ │ -preallocate memory for the specified numbers of tokens. This is useful if you │ │ │ │ │ -know approximately how many tokens are in the file you are about to parse. │ │ │ │ │ -Doing so will save realloc operations while parsing. You should only call this │ │ │ │ │ -on the root node, before passing it in to bdecode(). │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** switch_underlying_buffer() ***** │ │ │ │ │ -void switch_underlying_buffer (char const* buf) noexcept; │ │ │ │ │ -this buffer MUST be identical to the one originally parsed. This operation is │ │ │ │ │ -only defined on owning root nodes, i.e. the one passed in to decode(). │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** has_soft_error() ***** │ │ │ │ │ -bool has_soft_error (span error) const; │ │ │ │ │ -returns true if there is a non-fatal error in the bencoding of this node or its │ │ │ │ │ -children │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** enum type_t ***** │ │ │ │ │ -Declared in "libtorrent/bdecode.hpp" │ │ │ │ │ - _________________________________________________________________________ │ │ │ │ │ -|name____|value|description_______________________________________________| │ │ │ │ │ -|none_t |0 |uninitialized or default constructed. This is also used to| │ │ │ │ │ -|________|_____|indicate_that_a_node_was_not_found_in_some_cases._________| │ │ │ │ │ -|dict_t__|1____|a_dictionary_node._The_dict_find__functions_are_valid.____| │ │ │ │ │ -|list_t__|2____|a_list_node._The_list__functions_are_valid._______________| │ │ │ │ │ -|string_t|3____|a_string_node,_the_string__functions_are_valid.___________| │ │ │ │ │ -|int_t___|4____|an_integer_node._The_int__functions_are_valid.____________| │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** print_entry() ****** │ │ │ │ │ -Declared in "libtorrent/bdecode.hpp" │ │ │ │ │ -std::string print_entry (bdecode_node const& e │ │ │ │ │ - , bool single_line = false, int indent = 0); │ │ │ │ │ -print the bencoded structure in a human-readable format to a string that's │ │ │ │ │ -returned. │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** bdecode() ****** │ │ │ │ │ -Declared in "libtorrent/bdecode.hpp" │ │ │ │ │ -bdecode_node bdecode (span buffer │ │ │ │ │ - , error_code& ec, int* error_pos = nullptr, int depth_limit = 100 │ │ │ │ │ - , int token_limit = 2000000); │ │ │ │ │ -int bdecode (char const* start, char const* end, bdecode_node& ret │ │ │ │ │ - , error_code& ec, int* error_pos = nullptr, int depth_limit = 100 │ │ │ │ │ - , int token_limit = 2000000); │ │ │ │ │ -bdecode_node bdecode (span buffer │ │ │ │ │ - , int depth_limit = 100, int token_limit = 2000000); │ │ │ │ │ -This function decodes/parses bdecoded data (for example a .torrent file). The │ │ │ │ │ -data structure is returned in the ret argument. the buffer to parse is │ │ │ │ │ -specified by the start of the buffer as well as the end, i.e. one byte past the │ │ │ │ │ -end. If the buffer fails to parse, the function returns a non-zero value and │ │ │ │ │ -fills in ec with the error code. The optional argument error_pos, if set to │ │ │ │ │ -non-nullptr, will be set to the byte offset into the buffer where the parse │ │ │ │ │ -failure occurred. │ │ │ │ │ -depth_limit specifies the max number of nested lists or dictionaries are │ │ │ │ │ -allowed in the data structure. (This affects the stack usage of the function, │ │ │ │ │ -be careful not to set it too high). │ │ │ │ │ -token_limit is the max number of tokens allowed to be parsed from the buffer. │ │ │ │ │ -This is simply a sanity check to not have unbounded memory usage. │ │ │ │ │ -The resulting bdecode_node is an owning node. That means it will be holding the │ │ │ │ │ -whole parsed tree. When iterating lists and dictionaries, those bdecode_node │ │ │ │ │ -objects will simply have references to the root or owning bdecode_node. If the │ │ │ │ │ -root node is destructed, all other nodes that refer to anything in that tree │ │ │ │ │ -become invalid. │ │ │ │ │ -However, the underlying buffer passed in to this function (start, end) must │ │ │ │ │ -also remain valid while the bdecoded tree is used. The parsed tree produced by │ │ │ │ │ -this function does not copy any data out of the buffer, but simply produces │ │ │ │ │ -references back into it. │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** web_seed_entry ****** │ │ │ │ │ -Declared in "libtorrent/torrent_info.hpp" │ │ │ │ │ -the web_seed_entry holds information about a web seed (also known as URL seed │ │ │ │ │ -or HTTP seed). It is essentially a URL with some state associated with it. For │ │ │ │ │ -more information, see BEP_17 and BEP_19. │ │ │ │ │ -struct web_seed_entry │ │ │ │ │ -{ │ │ │ │ │ - bool operator== (web_seed_entry const& e) const; │ │ │ │ │ - bool operator< (web_seed_entry const& e) const; │ │ │ │ │ - │ │ │ │ │ - enum type_t │ │ │ │ │ - { │ │ │ │ │ - url_seed, │ │ │ │ │ - http_seed, │ │ │ │ │ - }; │ │ │ │ │ - │ │ │ │ │ - std::string url; │ │ │ │ │ - std::string auth; │ │ │ │ │ - headers_t extra_headers; │ │ │ │ │ - std::uint8_t type; │ │ │ │ │ -}; │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** operator==() ***** │ │ │ │ │ -bool operator== (web_seed_entry const& e) const; │ │ │ │ │ -URL and type comparison │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** operator<() ***** │ │ │ │ │ -bool operator< (web_seed_entry const& e) const; │ │ │ │ │ -URL and type less-than comparison │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** enum type_t ***** │ │ │ │ │ -Declared in "libtorrent/torrent_info.hpp" │ │ │ │ │ - ___________________________ │ │ │ │ │ -|name_____|value|description| │ │ │ │ │ -|url_seed_|0____| _________| │ │ │ │ │ -|http_seed|1____| _________| │ │ │ │ │ -[report_issue] │ │ │ │ │ - url │ │ │ │ │ - The URL of the web seed │ │ │ │ │ -[report_issue] │ │ │ │ │ - auth │ │ │ │ │ - Optional authentication. If this is set, it's passed in as HTTP basic │ │ │ │ │ - auth to the web seed. The format is: username:password. │ │ │ │ │ -[report_issue] │ │ │ │ │ - extra_headers │ │ │ │ │ - Any extra HTTP headers that need to be passed to the web seed │ │ │ │ │ -[report_issue] │ │ │ │ │ - type │ │ │ │ │ - The type of web seed (see type_t) │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** load_torrent_limits ****** │ │ │ │ │ -Declared in "libtorrent/torrent_info.hpp" │ │ │ │ │ -this object holds configuration options for limits to use when loading │ │ │ │ │ -torrents. They are meant to prevent loading potentially malicious torrents that │ │ │ │ │ -cause excessive memory allocations. │ │ │ │ │ -struct load_torrent_limits │ │ │ │ │ -{ │ │ │ │ │ - int max_buffer_size = 10000000; │ │ │ │ │ - int max_pieces = 0x200000; │ │ │ │ │ - int max_decode_depth = 100; │ │ │ │ │ - int max_decode_tokens = 3000000; │ │ │ │ │ -}; │ │ │ │ │ -[report_issue] │ │ │ │ │ - max_buffer_size │ │ │ │ │ - the max size of a .torrent file to load into RAM │ │ │ │ │ -[report_issue] │ │ │ │ │ - max_pieces │ │ │ │ │ - the max number of pieces allowed in the torrent │ │ │ │ │ -[report_issue] │ │ │ │ │ - max_decode_depth │ │ │ │ │ - the max recursion depth in the bdecoded structure │ │ │ │ │ -[report_issue] │ │ │ │ │ - max_decode_tokens │ │ │ │ │ - the max number of bdecode tokens │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** torrent_info ****** │ │ │ │ │ -Declared in "libtorrent/torrent_info.hpp" │ │ │ │ │ -the torrent_info class holds the information found in a .torrent file. │ │ │ │ │ -class torrent_info │ │ │ │ │ +****** session_proxy ****** │ │ │ │ │ +Declared in "libtorrent/session.hpp" │ │ │ │ │ +this is a holder for the internal session implementation object. Once the │ │ │ │ │ +session destruction is explicitly initiated, this holder is used to synchronize │ │ │ │ │ +the completion of the shutdown. The lifetime of this object may outlive │ │ │ │ │ +session, causing the session destructor to not block. The session_proxy │ │ │ │ │ +destructor will block however, until the underlying session is done shutting │ │ │ │ │ +down. │ │ │ │ │ +struct session_proxy │ │ │ │ │ { │ │ │ │ │ - explicit torrent_info (bdecode_node const& torrent_file); │ │ │ │ │ - torrent_info (std::string const& filename, load_torrent_limits const& cfg); │ │ │ │ │ - torrent_info (span buffer, load_torrent_limits const& cfg, │ │ │ │ │ -from_span_t); │ │ │ │ │ - torrent_info (char const* buffer, int size); │ │ │ │ │ - torrent_info (char const* buffer, int size, error_code& ec); │ │ │ │ │ - explicit torrent_info (std::string const& filename); │ │ │ │ │ - explicit torrent_info (info_hash_t const& info_hash); │ │ │ │ │ - torrent_info (std::string const& filename, error_code& ec); │ │ │ │ │ - explicit torrent_info (span buffer, from_span_t); │ │ │ │ │ - torrent_info (torrent_info const& t); │ │ │ │ │ - torrent_info (span buffer, error_code& ec, from_span_t); │ │ │ │ │ - torrent_info (bdecode_node const& torrent_file, error_code& ec); │ │ │ │ │ - torrent_info (bdecode_node const& torrent_file, load_torrent_limits const& │ │ │ │ │ -cfg); │ │ │ │ │ - ~torrent_info (); │ │ │ │ │ - file_storage const& orig_files () const; │ │ │ │ │ - file_storage const& files () const; │ │ │ │ │ - void rename_file (file_index_t index, std::string const& new_filename); │ │ │ │ │ - void remap_files (file_storage const& f); │ │ │ │ │ - void add_tracker (std::string const& url, int tier = 0); │ │ │ │ │ - void clear_trackers (); │ │ │ │ │ - std::vector const& trackers () const; │ │ │ │ │ - void add_tracker (std::string const& url, int tier │ │ │ │ │ - , announce_entry::tracker_source source); │ │ │ │ │ - std::vector collections () const; │ │ │ │ │ - std::vector similar_torrents () const; │ │ │ │ │ - void add_url_seed (std::string const& url │ │ │ │ │ - , std::string const& ext_auth = std::string() │ │ │ │ │ - , web_seed_entry::headers_t const& ext_headers = web_seed_entry:: │ │ │ │ │ -headers_t()); │ │ │ │ │ - void set_web_seeds (std::vector seeds); │ │ │ │ │ - std::vector const& web_seeds () const; │ │ │ │ │ - void add_http_seed (std::string const& url │ │ │ │ │ - , std::string const& extern_auth = std::string() │ │ │ │ │ - , web_seed_entry::headers_t const& extra_headers = web_seed_entry:: │ │ │ │ │ -headers_t()); │ │ │ │ │ - std::int64_t total_size () const; │ │ │ │ │ - int piece_length () const; │ │ │ │ │ - int num_pieces () const; │ │ │ │ │ - index_range piece_range () const; │ │ │ │ │ - piece_index_t end_piece () const; │ │ │ │ │ - piece_index_t last_piece () const; │ │ │ │ │ - info_hash_t const& info_hashes () const; │ │ │ │ │ - sha1_hash info_hash () const noexcept; │ │ │ │ │ - bool v2 () const; │ │ │ │ │ - bool v1 () const; │ │ │ │ │ - int num_files () const; │ │ │ │ │ - std::vector map_block (piece_index_t const piece │ │ │ │ │ - , std::int64_t offset, int size) const; │ │ │ │ │ - peer_request map_file (file_index_t const file, std::int64_t offset, int │ │ │ │ │ -size) const; │ │ │ │ │ - string_view ssl_cert () const; │ │ │ │ │ - bool is_valid () const; │ │ │ │ │ - bool priv () const; │ │ │ │ │ - bool is_i2p () const; │ │ │ │ │ - int piece_size (piece_index_t index) const; │ │ │ │ │ - char const* hash_for_piece_ptr (piece_index_t const index) const; │ │ │ │ │ - sha1_hash hash_for_piece (piece_index_t index) const; │ │ │ │ │ - bool is_loaded () const; │ │ │ │ │ - const std::string& name () const; │ │ │ │ │ - std::time_t creation_date () const; │ │ │ │ │ - const std::string& creator () const; │ │ │ │ │ - const std::string& comment () const; │ │ │ │ │ - std::vector> const& nodes () const; │ │ │ │ │ - void add_node (std::pair const& node); │ │ │ │ │ - bool parse_info_section (bdecode_node const& info, error_code& ec, int │ │ │ │ │ -max_pieces); │ │ │ │ │ - bdecode_node info (char const* key) const; │ │ │ │ │ - span info_section () const; │ │ │ │ │ - span piece_layer (file_index_t) const; │ │ │ │ │ - void free_piece_layers (); │ │ │ │ │ + session_proxy (); │ │ │ │ │ + session_proxy (session_proxy const&); │ │ │ │ │ + session_proxy (session_proxy&&) noexcept; │ │ │ │ │ + ~session_proxy (); │ │ │ │ │ + session_proxy& operator= (session_proxy&&) & noexcept; │ │ │ │ │ + session_proxy& operator= (session_proxy const&) &; │ │ │ │ │ }; │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** torrent_info() ***** │ │ │ │ │ -explicit torrent_info (bdecode_node const& torrent_file); │ │ │ │ │ -torrent_info (std::string const& filename, load_torrent_limits const& cfg); │ │ │ │ │ -torrent_info (span buffer, load_torrent_limits const& cfg, │ │ │ │ │ -from_span_t); │ │ │ │ │ -torrent_info (char const* buffer, int size); │ │ │ │ │ -torrent_info (char const* buffer, int size, error_code& ec); │ │ │ │ │ -explicit torrent_info (std::string const& filename); │ │ │ │ │ -explicit torrent_info (info_hash_t const& info_hash); │ │ │ │ │ -torrent_info (std::string const& filename, error_code& ec); │ │ │ │ │ -explicit torrent_info (span buffer, from_span_t); │ │ │ │ │ -torrent_info (torrent_info const& t); │ │ │ │ │ -torrent_info (span buffer, error_code& ec, from_span_t); │ │ │ │ │ -torrent_info (bdecode_node const& torrent_file, error_code& ec); │ │ │ │ │ -torrent_info (bdecode_node const& torrent_file, load_torrent_limits const& │ │ │ │ │ -cfg); │ │ │ │ │ -The constructor that takes an info-hash will initialize the info-hash to the │ │ │ │ │ -given value, but leave all other fields empty. This is used internally when │ │ │ │ │ -downloading torrents without the metadata. The metadata will be created by │ │ │ │ │ -libtorrent as soon as it has been downloaded from the swarm. │ │ │ │ │ -The constructor that takes a bdecode_node will create a torrent_info object │ │ │ │ │ -from the information found in the given torrent_file. The bdecode_node │ │ │ │ │ -represents a tree node in an bencoded file. To load an ordinary .torrent file │ │ │ │ │ -into a bdecode_node, use bdecode(). │ │ │ │ │ -The version that takes a buffer pointer and a size will decode it as a .torrent │ │ │ │ │ -file and initialize the torrent_info object for you. │ │ │ │ │ -The version that takes a filename will simply load the torrent file and decode │ │ │ │ │ -it inside the constructor, for convenience. This might not be the most suitable │ │ │ │ │ -for applications that want to be able to report detailed errors on what might │ │ │ │ │ -go wrong. │ │ │ │ │ -There is an upper limit on the size of the torrent file that will be loaded by │ │ │ │ │ -the overload taking a filename. If it's important that even very large torrent │ │ │ │ │ -files are loaded, use one of the other overloads. │ │ │ │ │ -The overloads that takes an error_code const& never throws if an error occur, │ │ │ │ │ -they will simply set the error code to describe what went wrong and not fully │ │ │ │ │ -initialize the torrent_info object. The overloads that do not take the extra │ │ │ │ │ -error_code parameter will always throw if an error occurs. These overloads are │ │ │ │ │ -not available when building without exception support. │ │ │ │ │ -The overload that takes a span also needs an extra parameter of type │ │ │ │ │ -from_span_t to disambiguate the std::string overload for string literals. There │ │ │ │ │ -is an object in the libtorrent namespace of this type called from_span. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** ~torrent_info() ***** │ │ │ │ │ -~torrent_info (); │ │ │ │ │ -frees all storage associated with this torrent_info object │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** files() orig_files() ***** │ │ │ │ │ -file_storage const& orig_files () const; │ │ │ │ │ -file_storage const& files () const; │ │ │ │ │ -The file_storage object contains the information on how to map the pieces to │ │ │ │ │ -files. It is separated from the torrent_info object because when creating │ │ │ │ │ -torrents a storage object needs to be created without having a torrent file. │ │ │ │ │ -When renaming files in a storage, the storage needs to make its own copy of the │ │ │ │ │ -file_storage in order to make its mapping differ from the one in the torrent │ │ │ │ │ -file. │ │ │ │ │ -orig_files() returns the original (unmodified) file storage for this torrent. │ │ │ │ │ -This is used by the web server connection, which needs to request files with │ │ │ │ │ -the original names. Filename may be changed using torrent_info::rename_file(). │ │ │ │ │ -For more information on the file_storage object, see the separate document on │ │ │ │ │ -how to create torrents. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** rename_file() ***** │ │ │ │ │ -void rename_file (file_index_t index, std::string const& new_filename); │ │ │ │ │ -Renames the file with the specified index to the new name. The new filename is │ │ │ │ │ -reflected by the file_storage returned by files() but not by the one returned │ │ │ │ │ -by orig_files(). │ │ │ │ │ -If you want to rename the base name of the torrent (for a multi file torrent), │ │ │ │ │ -you can copy the file_storage (see files() and orig_files() ), change the name, │ │ │ │ │ -and then use remap_files(). │ │ │ │ │ -The new_filename can both be a relative path, in which case the file name is │ │ │ │ │ -relative to the save_path of the torrent. If the new_filename is an absolute │ │ │ │ │ -path (i.e. is_complete(new_filename) == true), then the file is detached from │ │ │ │ │ -the save_path of the torrent. In this case the file is not moved when │ │ │ │ │ -move_storage() is invoked. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** remap_files() ***** │ │ │ │ │ -void remap_files (file_storage const& f); │ │ │ │ │ -Warning │ │ │ │ │ -Usingremap_files()is discouraged as it's incompatible with v2 torrents. This is │ │ │ │ │ -because the piece boundaries and piece hashes in v2 torrents are intimately │ │ │ │ │ -tied to the file boundaries. Instead, just rename individual files, or │ │ │ │ │ -implement a custom disk_interface to customize how to store files. │ │ │ │ │ -Remaps the file storage to a new file layout. This can be used to, for │ │ │ │ │ -instance, download all data in a torrent to a single file, or to a number of │ │ │ │ │ -fixed size sector aligned files, regardless of the number and sizes of the │ │ │ │ │ -files in the torrent. │ │ │ │ │ -The new specified file_storage must have the exact same size as the current │ │ │ │ │ -one. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** trackers() clear_trackers() add_tracker() ***** │ │ │ │ │ -void add_tracker (std::string const& url, int tier = 0); │ │ │ │ │ -void clear_trackers (); │ │ │ │ │ -std::vector const& trackers () const; │ │ │ │ │ -void add_tracker (std::string const& url, int tier │ │ │ │ │ - , announce_entry::tracker_source source); │ │ │ │ │ -add_tracker() adds a tracker to the announce-list. The tier determines the │ │ │ │ │ -order in which the trackers are to be tried. The trackers() function will │ │ │ │ │ -return a sorted vector of announce_entry. Each announce entry contains a │ │ │ │ │ -string, which is the tracker url, and a tier index. The tier index is the high- │ │ │ │ │ -level priority. No matter which trackers that works or not, the ones with lower │ │ │ │ │ -tier will always be tried before the one with higher tier number. For more │ │ │ │ │ -information, see announce_entry. │ │ │ │ │ -trackers() returns all entries from announce-list. │ │ │ │ │ -clear_trackers() removes all trackers from announce-list. │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** collections() similar_torrents() ***** │ │ │ │ │ -std::vector collections () const; │ │ │ │ │ -std::vector similar_torrents () const; │ │ │ │ │ -These two functions are related to BEP_38 (mutable torrents). The vectors │ │ │ │ │ -returned from these correspond to the "similar" and "collections" keys in the │ │ │ │ │ -.torrent file. Both info-hashes and collections from within the info-dict and │ │ │ │ │ -from outside of it are included. │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** add_url_seed() set_web_seeds() add_http_seed() web_seeds() ***** │ │ │ │ │ -void add_url_seed (std::string const& url │ │ │ │ │ - , std::string const& ext_auth = std::string() │ │ │ │ │ - , web_seed_entry::headers_t const& ext_headers = web_seed_entry:: │ │ │ │ │ -headers_t()); │ │ │ │ │ -void set_web_seeds (std::vector seeds); │ │ │ │ │ -std::vector const& web_seeds () const; │ │ │ │ │ -void add_http_seed (std::string const& url │ │ │ │ │ - , std::string const& extern_auth = std::string() │ │ │ │ │ - , web_seed_entry::headers_t const& extra_headers = web_seed_entry:: │ │ │ │ │ -headers_t()); │ │ │ │ │ -web_seeds() returns all url seeds and http seeds in the torrent. Each entry is │ │ │ │ │ -a web_seed_entry and may refer to either a url seed or http seed. │ │ │ │ │ -add_url_seed() and add_http_seed() adds one url to the list of url/http seeds. │ │ │ │ │ -set_web_seeds() replaces all web seeds with the ones specified in the seeds │ │ │ │ │ -vector. │ │ │ │ │ -The extern_auth argument can be used for other authorization schemes than basic │ │ │ │ │ -HTTP authorization. If set, it will override any username and password found in │ │ │ │ │ -the URL itself. The string will be sent as the HTTP authorization header's │ │ │ │ │ -value (without specifying "Basic"). │ │ │ │ │ -The extra_headers argument defaults to an empty list, but can be used to insert │ │ │ │ │ -custom HTTP headers in the requests to a specific web seed. │ │ │ │ │ -See http_seeding for more information. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** total_size() ***** │ │ │ │ │ -std::int64_t total_size () const; │ │ │ │ │ -total_size() returns the total number of bytes the torrent-file represents. │ │ │ │ │ -Note that this is the number of pieces times the piece size (modulo the last │ │ │ │ │ -piece possibly being smaller). With pad files, the total size will be larger │ │ │ │ │ -than the sum of all (regular) file sizes. │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** num_pieces() piece_length() ***** │ │ │ │ │ -int piece_length () const; │ │ │ │ │ -int num_pieces () const; │ │ │ │ │ -piece_length() and num_pieces() returns the number of byte for each piece and │ │ │ │ │ -the total number of pieces, respectively. The difference between piece_size() │ │ │ │ │ -and piece_length() is that piece_size() takes the piece index as argument and │ │ │ │ │ -gives you the exact size of that piece. It will always be the same as │ │ │ │ │ -piece_length() except in the case of the last piece, which may be smaller. │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** last_piece() end_piece() piece_range() ***** │ │ │ │ │ -index_range piece_range () const; │ │ │ │ │ -piece_index_t end_piece () const; │ │ │ │ │ -piece_index_t last_piece () const; │ │ │ │ │ -last_piece() returns the index to the last piece in the torrent and end_piece() │ │ │ │ │ -returns the index to the one-past-end piece in the torrent piece_range() │ │ │ │ │ -returns an implementation-defined type that can be used as the container in a │ │ │ │ │ -range-for loop. Where the values are the indices of all pieces in the │ │ │ │ │ -file_storage. │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** info_hash() info_hashes() ***** │ │ │ │ │ -info_hash_t const& info_hashes () const; │ │ │ │ │ -sha1_hash info_hash () const noexcept; │ │ │ │ │ -returns the info-hash of the torrent. For BitTorrent v2 support, use │ │ │ │ │ -info_hashes() to get an object that may hold both a v1 and v2 info-hash │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** v2() v1() ***** │ │ │ │ │ -bool v2 () const; │ │ │ │ │ -bool v1 () const; │ │ │ │ │ -returns whether this torrent has v1 and/or v2 metadata, respectively. Hybrid │ │ │ │ │ -torrents have both. These are shortcuts for info_hashes().has_v1() and │ │ │ │ │ -info_hashes().has_v2() calls. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** num_files() ***** │ │ │ │ │ -int num_files () const; │ │ │ │ │ -If you need index-access to files you can use the num_files() along with the │ │ │ │ │ -file_path(), file_size()-family of functions to access files using indices. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** map_block() ***** │ │ │ │ │ -std::vector map_block (piece_index_t const piece │ │ │ │ │ - , std::int64_t offset, int size) const; │ │ │ │ │ -This function will map a piece index, a byte offset within that piece and a │ │ │ │ │ -size (in bytes) into the corresponding files with offsets where that data for │ │ │ │ │ -that piece is supposed to be stored. See file_slice. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** map_file() ***** │ │ │ │ │ -peer_request map_file (file_index_t const file, std::int64_t offset, int size) │ │ │ │ │ -const; │ │ │ │ │ -This function will map a range in a specific file into a range in the torrent. │ │ │ │ │ -The file_offset parameter is the offset in the file, given in bytes, where 0 is │ │ │ │ │ -the start of the file. See peer_request. │ │ │ │ │ -The input range is assumed to be valid within the torrent. file_offset + size │ │ │ │ │ -is not allowed to be greater than the file size. file_index must refer to a │ │ │ │ │ -valid file, i.e. it cannot be >= num_files(). │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** ssl_cert() ***** │ │ │ │ │ -string_view ssl_cert () const; │ │ │ │ │ -Returns the SSL root certificate for the torrent, if it is an SSL torrent. │ │ │ │ │ -Otherwise returns an empty string. The certificate is the public certificate in │ │ │ │ │ -x509 format. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** is_valid() ***** │ │ │ │ │ -bool is_valid () const; │ │ │ │ │ -returns true if this torrent_info object has a torrent loaded. This is │ │ │ │ │ -primarily used to determine if a magnet link has had its metadata resolved yet │ │ │ │ │ -or not. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** priv() ***** │ │ │ │ │ -bool priv () const; │ │ │ │ │ -returns true if this torrent is private. i.e., the client should not advertise │ │ │ │ │ -itself on the trackerless network (the Kademlia DHT) for this torrent. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** is_i2p() ***** │ │ │ │ │ -bool is_i2p () const; │ │ │ │ │ -returns true if this is an i2p torrent. This is determined by whether or not it │ │ │ │ │ -has a tracker whose URL domain name ends with ".i2p". i2p torrents disable the │ │ │ │ │ -DHT and local peer discovery as well as talking to peers over anything other │ │ │ │ │ -than the i2p network. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** piece_size() ***** │ │ │ │ │ -int piece_size (piece_index_t index) const; │ │ │ │ │ -returns the piece size of file with index. This will be the same as │ │ │ │ │ -piece_length(), except for the last piece, which may be shorter. │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** hash_for_piece() hash_for_piece_ptr() ***** │ │ │ │ │ -char const* hash_for_piece_ptr (piece_index_t const index) const; │ │ │ │ │ -sha1_hash hash_for_piece (piece_index_t index) const; │ │ │ │ │ -hash_for_piece() takes a piece-index and returns the 20-bytes sha1-hash for │ │ │ │ │ -that piece and info_hash() returns the 20-bytes sha1-hash for the info-section │ │ │ │ │ -of the torrent file. hash_for_piece_ptr() returns a pointer to the 20 byte sha1 │ │ │ │ │ -digest for the piece. Note that the string is not 0-terminated. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** name() ***** │ │ │ │ │ -const std::string& name () const; │ │ │ │ │ -name() returns the name of the torrent. name contains UTF-8 encoded string. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** creation_date() ***** │ │ │ │ │ -std::time_t creation_date () const; │ │ │ │ │ -creation_date() returns the creation date of the torrent as time_t (posix │ │ │ │ │ -time). If there's no time stamp in the torrent file, 0 is returned. .. posix │ │ │ │ │ -time: http://www.opengroup.org/onlinepubs/009695399/functions/time.html │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** creator() ***** │ │ │ │ │ -const std::string& creator () const; │ │ │ │ │ -creator() returns the creator string in the torrent. If there is no creator │ │ │ │ │ -string it will return an empty string. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** comment() ***** │ │ │ │ │ -const std::string& comment () const; │ │ │ │ │ -comment() returns the comment associated with the torrent. If there's no │ │ │ │ │ -comment, it will return an empty string. comment contains UTF-8 encoded string. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** nodes() ***** │ │ │ │ │ -std::vector> const& nodes () const; │ │ │ │ │ -If this torrent contains any DHT nodes, they are put in this vector in their │ │ │ │ │ -original form (host name and port number). │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** add_node() ***** │ │ │ │ │ -void add_node (std::pair const& node); │ │ │ │ │ -This is used when creating torrent. Use this to add a known DHT node. It may be │ │ │ │ │ -used, by the client, to bootstrap into the DHT network. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** parse_info_section() ***** │ │ │ │ │ -bool parse_info_section (bdecode_node const& info, error_code& ec, int │ │ │ │ │ -max_pieces); │ │ │ │ │ -populates the torrent_info by providing just the info-dict buffer. This is used │ │ │ │ │ -when loading a torrent from a magnet link for instance, where we only have the │ │ │ │ │ -info-dict. The bdecode_node e points to a parsed info-dictionary. ec returns an │ │ │ │ │ -error code if something fails (typically if the info dictionary is malformed). │ │ │ │ │ -Themax_piecesparameter allows limiting the amount of memory dedicated to │ │ │ │ │ -loading the torrent, and fails for torrents that exceed the limit. To load │ │ │ │ │ -large torrents, this limit may also need to be raised in settings_pack:: │ │ │ │ │ -max_piece_count and in calls to read_resume_data(). │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** info() ***** │ │ │ │ │ -bdecode_node info (char const* key) const; │ │ │ │ │ -This function looks up keys from the info-dictionary of the loaded torrent │ │ │ │ │ -file. It can be used to access extension values put in the .torrent file. If │ │ │ │ │ -the specified key cannot be found, it returns nullptr. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** info_section() ***** │ │ │ │ │ -span info_section () const; │ │ │ │ │ -returns a the raw info section of the torrent file. The underlying buffer is │ │ │ │ │ -still owned by the torrent_info object │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** piece_layer() ***** │ │ │ │ │ -span piece_layer (file_index_t) const; │ │ │ │ │ -return the bytes of the piece layer hashes for the specified file. If the file │ │ │ │ │ -doesn't have a piece layer, an empty span is returned. The span size is │ │ │ │ │ -divisible by 32, the size of a SHA-256 hash. If the size of the file is smaller │ │ │ │ │ -than or equal to the piece size, the files "root hash" is the hash of the file │ │ │ │ │ -and is not saved separately in the "piece layers" field, but this function │ │ │ │ │ -still returns the root hash of the file in that case. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** free_piece_layers() ***** │ │ │ │ │ -void free_piece_layers (); │ │ │ │ │ -clears the piece layers from the torrent_info. This is done by the session when │ │ │ │ │ -a torrent is added, to avoid storing it twice. The piece layer (or other hashes │ │ │ │ │ -part of the merkle tree) are stored in the internal torrent object. │ │ │ │ │ -Bencoding is a common representation in bittorrent used for dictionary, list, │ │ │ │ │ -int and string hierarchies. It's used to encode .torrent files and some │ │ │ │ │ -messages in the network protocol. libtorrent also uses it to store settings, │ │ │ │ │ -resume data and other session state. │ │ │ │ │ -Strings in bencoded structures do not necessarily represent text. Strings are │ │ │ │ │ -raw byte buffers of a certain length. If a string is meant to be interpreted as │ │ │ │ │ -text, it is required to be UTF-8 encoded. See BEP_3. │ │ │ │ │ -The function for decoding bencoded data bdecode(), returning a bdecode_node. │ │ │ │ │ -This function builds a tree that points back into the original buffer. The │ │ │ │ │ -returned bdecode_node will not be valid once the buffer it was parsed out of is │ │ │ │ │ -discarded. │ │ │ │ │ -It's possible to construct an entry from a bdecode_node, if a structure needs │ │ │ │ │ -to be altered and re-encoded. │ │ │ │ │ +***** session_proxy() ~session_proxy() operator=() ***** │ │ │ │ │ +session_proxy (); │ │ │ │ │ +session_proxy (session_proxy const&); │ │ │ │ │ +session_proxy (session_proxy&&) noexcept; │ │ │ │ │ +~session_proxy (); │ │ │ │ │ +session_proxy& operator= (session_proxy&&) & noexcept; │ │ │ │ │ +session_proxy& operator= (session_proxy const&) &; │ │ │ │ │ +default constructor, does not refer to any session implementation object. │ │ │ │ │ [report_issue] │ │ │ │ │ -****** entry ****** │ │ │ │ │ -Declared in "libtorrent/entry.hpp" │ │ │ │ │ -The entry class represents one node in a bencoded hierarchy. It works as a │ │ │ │ │ -variant type, it can be either a list, a dictionary (std::map), an integer or a │ │ │ │ │ -string. │ │ │ │ │ -class entry │ │ │ │ │ +****** session ****** │ │ │ │ │ +Declared in "libtorrent/session.hpp" │ │ │ │ │ +The session holds all state that spans multiple torrents. Among other things it │ │ │ │ │ +runs the network loop and manages all torrents. Once it's created, the session │ │ │ │ │ +object will spawn the main thread that will do all the work. The main thread │ │ │ │ │ +will be idle as long it doesn't have any torrents to participate in. │ │ │ │ │ +You have some control over session configuration through the session_handle:: │ │ │ │ │ +apply_settings() member function. To change one or more configuration options, │ │ │ │ │ +create a settings_pack. object and fill it with the settings to be set and pass │ │ │ │ │ +it in to session::apply_settings(). │ │ │ │ │ +see apply_settings(). │ │ │ │ │ +struct session : session_handle │ │ │ │ │ { │ │ │ │ │ - data_type type () const; │ │ │ │ │ - entry (dictionary_type); │ │ │ │ │ - entry (span); │ │ │ │ │ - entry (integer_type); │ │ │ │ │ - entry (preformatted_type); │ │ │ │ │ - entry (list_type); │ │ │ │ │ - entry (U v); │ │ │ │ │ - entry (data_type t); │ │ │ │ │ - entry (bdecode_node const& n); │ │ │ │ │ - entry& operator= (dictionary_type) &; │ │ │ │ │ - entry& operator= (integer_type) &; │ │ │ │ │ - entry& operator= (bdecode_node const&) &; │ │ │ │ │ - entry& operator= (entry&&) & noexcept; │ │ │ │ │ - entry& operator= (span) &; │ │ │ │ │ - entry& operator= (list_type) &; │ │ │ │ │ - entry& operator= (entry const&) &; │ │ │ │ │ - entry& operator= (preformatted_type) &; │ │ │ │ │ - entry& operator= (U v) &; │ │ │ │ │ - string_type const& string () const; │ │ │ │ │ - preformatted_type const& preformatted () const; │ │ │ │ │ - integer_type& integer (); │ │ │ │ │ - dictionary_type& dict (); │ │ │ │ │ - integer_type const& integer () const; │ │ │ │ │ - dictionary_type const& dict () const; │ │ │ │ │ - list_type const& list () const; │ │ │ │ │ - list_type& list (); │ │ │ │ │ - string_type& string (); │ │ │ │ │ - preformatted_type& preformatted (); │ │ │ │ │ - void swap (entry& e); │ │ │ │ │ - entry const& operator[] (string_view key) const; │ │ │ │ │ - entry& operator[] (string_view key); │ │ │ │ │ - entry const* find_key (string_view key) const; │ │ │ │ │ - entry* find_key (string_view key); │ │ │ │ │ - std::string to_string (bool single_line = false) const; │ │ │ │ │ - │ │ │ │ │ - enum data_type │ │ │ │ │ - { │ │ │ │ │ - int_t, │ │ │ │ │ - string_t, │ │ │ │ │ - list_t, │ │ │ │ │ - dictionary_t, │ │ │ │ │ - undefined_t, │ │ │ │ │ - preformatted_t, │ │ │ │ │ - }; │ │ │ │ │ + explicit session (session_params&& params); │ │ │ │ │ + session (); │ │ │ │ │ + explicit session (session_params const& params); │ │ │ │ │ + session (session_params&& params, session_flags_t flags); │ │ │ │ │ + session (session_params const& params, session_flags_t flags); │ │ │ │ │ + session (session_params&& params, io_context& ios); │ │ │ │ │ + session (session_params const& params, io_context& ios, session_flags_t); │ │ │ │ │ + session (session_params&& params, io_context& ios, session_flags_t); │ │ │ │ │ + session (session_params const& params, io_context& ios); │ │ │ │ │ + ~session (); │ │ │ │ │ + session_proxy abort (); │ │ │ │ │ }; │ │ │ │ │ [report_issue] │ │ │ │ │ -***** type() ***** │ │ │ │ │ -data_type type () const; │ │ │ │ │ -returns the concrete type of the entry │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** entry() ***** │ │ │ │ │ -entry (dictionary_type); │ │ │ │ │ -entry (span); │ │ │ │ │ -entry (integer_type); │ │ │ │ │ -entry (preformatted_type); │ │ │ │ │ -entry (list_type); │ │ │ │ │ -constructors directly from a specific type. The content of the argument is │ │ │ │ │ -copied into the newly constructed entry │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** entry() ***** │ │ │ │ │ -entry (data_type t); │ │ │ │ │ -construct an empty entry of the specified type. see data_type enum. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** entry() ***** │ │ │ │ │ -entry (bdecode_node const& n); │ │ │ │ │ -construct from bdecode_node parsed form (see bdecode()) │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** operator=() ***** │ │ │ │ │ -entry& operator= (dictionary_type) &; │ │ │ │ │ -entry& operator= (integer_type) &; │ │ │ │ │ -entry& operator= (bdecode_node const&) &; │ │ │ │ │ -entry& operator= (entry&&) & noexcept; │ │ │ │ │ -entry& operator= (span) &; │ │ │ │ │ -entry& operator= (list_type) &; │ │ │ │ │ -entry& operator= (entry const&) &; │ │ │ │ │ -entry& operator= (preformatted_type) &; │ │ │ │ │ -copies the structure of the right hand side into this entry. │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** dict() string() list() integer() preformatted() ***** │ │ │ │ │ -string_type const& string () const; │ │ │ │ │ -preformatted_type const& preformatted () const; │ │ │ │ │ -integer_type& integer (); │ │ │ │ │ -dictionary_type& dict (); │ │ │ │ │ -integer_type const& integer () const; │ │ │ │ │ -dictionary_type const& dict () const; │ │ │ │ │ -list_type const& list () const; │ │ │ │ │ -list_type& list (); │ │ │ │ │ -string_type& string (); │ │ │ │ │ -preformatted_type& preformatted (); │ │ │ │ │ -The integer(), string(), list() and dict() functions are accessors that return │ │ │ │ │ -the respective type. If the entry object isn't of the type you request, the │ │ │ │ │ -accessor will throw system_error. You can ask an entry for its type through the │ │ │ │ │ -type() function. │ │ │ │ │ -If you want to create an entry you give it the type you want it to have in its │ │ │ │ │ -constructor, and then use one of the non-const accessors to get a reference │ │ │ │ │ -which you then can assign the value you want it to have. │ │ │ │ │ -The typical code to get info from a torrent file will then look like this: │ │ │ │ │ -entry torrent_file; │ │ │ │ │ -// ... │ │ │ │ │ - │ │ │ │ │ -// throws if this is not a dictionary │ │ │ │ │ -entry::dictionary_type const& dict = torrent_file.dict(); │ │ │ │ │ -entry::dictionary_type::const_iterator i; │ │ │ │ │ -i = dict.find("announce"); │ │ │ │ │ -if (i != dict.end()) │ │ │ │ │ -{ │ │ │ │ │ - std::string tracker_url = i->second.string(); │ │ │ │ │ - std::cout << tracker_url << "\n"; │ │ │ │ │ -} │ │ │ │ │ -The following code is equivalent, but a little bit shorter: │ │ │ │ │ -entry torrent_file; │ │ │ │ │ -// ... │ │ │ │ │ - │ │ │ │ │ -// throws if this is not a dictionary │ │ │ │ │ -if (entry* i = torrent_file.find_key("announce")) │ │ │ │ │ -{ │ │ │ │ │ - std::string tracker_url = i->string(); │ │ │ │ │ - std::cout << tracker_url << "\n"; │ │ │ │ │ -} │ │ │ │ │ -To make it easier to extract information from a torrent file, the class │ │ │ │ │ -torrent_info exists. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** swap() ***** │ │ │ │ │ -void swap (entry& e); │ │ │ │ │ -swaps the content of this with e. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** operator[]() ***** │ │ │ │ │ -entry const& operator[] (string_view key) const; │ │ │ │ │ -entry& operator[] (string_view key); │ │ │ │ │ -All of these functions requires the entry to be a dictionary, if it isn't they │ │ │ │ │ -will throw system_error. │ │ │ │ │ -The non-const versions of the operator[] will return a reference to either the │ │ │ │ │ -existing element at the given key or, if there is no element with the given │ │ │ │ │ -key, a reference to a newly inserted element at that key. │ │ │ │ │ -The const version of operator[] will only return a reference to an existing │ │ │ │ │ -element at the given key. If the key is not found, it will throw system_error. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** find_key() ***** │ │ │ │ │ -entry const* find_key (string_view key) const; │ │ │ │ │ -entry* find_key (string_view key); │ │ │ │ │ -These functions requires the entry to be a dictionary, if it isn't they will │ │ │ │ │ -throw system_error. │ │ │ │ │ -They will look for an element at the given key in the dictionary, if the │ │ │ │ │ -element cannot be found, they will return nullptr. If an element with the given │ │ │ │ │ -key is found, the return a pointer to it. │ │ │ │ │ +***** session() ***** │ │ │ │ │ +explicit session (session_params&& params); │ │ │ │ │ +session (); │ │ │ │ │ +explicit session (session_params const& params); │ │ │ │ │ +session (session_params&& params, session_flags_t flags); │ │ │ │ │ +session (session_params const& params, session_flags_t flags); │ │ │ │ │ +Constructs the session objects which acts as the container of torrents. In │ │ │ │ │ +order to avoid a race condition between starting the session and configuring │ │ │ │ │ +it, you can pass in a session_params object. Its settings will take effect │ │ │ │ │ +before the session starts up. │ │ │ │ │ +The overloads taking flags can be used to start a session in paused mode (by │ │ │ │ │ +passing in session::paused). Note that add_default_plugins do not have an │ │ │ │ │ +affect on constructors that take a session_params object. It already contains │ │ │ │ │ +the plugins to use. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** to_string() ***** │ │ │ │ │ -std::string to_string (bool single_line = false) const; │ │ │ │ │ -returns a pretty-printed string representation of the bencoded structure, with │ │ │ │ │ -JSON-style syntax │ │ │ │ │ +***** session() ***** │ │ │ │ │ +session (session_params&& params, io_context& ios); │ │ │ │ │ +session (session_params const& params, io_context& ios, session_flags_t); │ │ │ │ │ +session (session_params&& params, io_context& ios, session_flags_t); │ │ │ │ │ +session (session_params const& params, io_context& ios); │ │ │ │ │ +Overload of the constructor that takes an external io_context to run the │ │ │ │ │ +session object on. This is primarily useful for tests that may want to run │ │ │ │ │ +multiple sessions on a single io_context, or low resource systems where │ │ │ │ │ +additional threads are expensive and sharing an io_context with other events is │ │ │ │ │ +fine. │ │ │ │ │ +Warning │ │ │ │ │ +The session object does not cleanly terminate with an external io_context. The │ │ │ │ │ +io_context::run() call must have returned before it's safe to destruct the │ │ │ │ │ +session. Which means you MUST call session::abort() and save the session_proxy │ │ │ │ │ +first, then destruct the session object, then sync with the io_context, then │ │ │ │ │ +destruct the session_proxy object. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** enum data_type ***** │ │ │ │ │ -Declared in "libtorrent/entry.hpp" │ │ │ │ │ - ________________________________ │ │ │ │ │ -|name__________|value|description| │ │ │ │ │ -|int_t_________|0____| _________| │ │ │ │ │ -|string_t______|1____| _________| │ │ │ │ │ -|list_t________|2____| _________| │ │ │ │ │ -|dictionary_t__|3____| _________| │ │ │ │ │ -|undefined_t___|4____| _________| │ │ │ │ │ -|preformatted_t|5____| _________| │ │ │ │ │ +***** ~session() ***** │ │ │ │ │ +~session (); │ │ │ │ │ +The destructor of session will notify all trackers that our torrents have been │ │ │ │ │ +shut down. If some trackers are down, they will time out. All this before the │ │ │ │ │ +destructor of session returns. So, it's advised that any kind of interface │ │ │ │ │ +(such as windows) are closed before destructing the session object. Because it │ │ │ │ │ +can take a few second for it to finish. The timeout can be set with │ │ │ │ │ +apply_settings(). │ │ │ │ │ [report_issue] │ │ │ │ │ -****** operator<<() ****** │ │ │ │ │ -Declared in "libtorrent/entry.hpp" │ │ │ │ │ -inline std::ostream& operator<< (std::ostream& os, const entry& e); │ │ │ │ │ -prints the bencoded structure to the ostream as a JSON-style structure. │ │ │ │ │ +***** abort() ***** │ │ │ │ │ +session_proxy abort (); │ │ │ │ │ +In case you want to destruct the session asynchronously, you can request a │ │ │ │ │ +session destruction proxy. If you don't do this, the destructor of the session │ │ │ │ │ +object will block while the trackers are contacted. If you keep one │ │ │ │ │ +session_proxy to the session when destructing it, the destructor will not │ │ │ │ │ +block, but start to close down the session, the destructor of the proxy will │ │ │ │ │ +then synchronize the threads. So, the destruction of the session is performed │ │ │ │ │ +from the session destructor call until the session_proxy destructor call. The │ │ │ │ │ +session_proxy does not have any operations on it (since the session is being │ │ │ │ │ +closed down, no operations are allowed on it). The only valid operation is │ │ │ │ │ +calling the destructor: │ │ │ │ │ +struct session_proxy {}; │ │ │ │ │ [report_issue] │ │ │ │ │ -****** bencode() ****** │ │ │ │ │ -Declared in "libtorrent/bencode.hpp" │ │ │ │ │ -template int bencode (OutIt out, const entry& e); │ │ │ │ │ -This function will encode data to bencoded form. │ │ │ │ │ -The entry class is the internal representation of the bencoded data and it can │ │ │ │ │ -be used to retrieve information, an entry can also be build by the program and │ │ │ │ │ -given to bencode() to encode it into the OutIt iterator. │ │ │ │ │ -OutIt is an OutputIterator. It's a template and usually instantiated as │ │ │ │ │ -ostream_iterator or back_insert_iterator. This function assumes the value_type │ │ │ │ │ -of the iterator is a char. In order to encode entry e into a buffer, do: │ │ │ │ │ -std::vector buffer; │ │ │ │ │ -bencode(std::back_inserter(buf), e); │ │ │ │ │ -The disk I/O can be customized in libtorrent. In previous versions, the │ │ │ │ │ -customization was at the level of each torrent. Now, the customization point is │ │ │ │ │ -at the session level. All torrents added to a session will use the same disk I/ │ │ │ │ │ -O subsystem, as determined by the disk_io_constructor (in session_params). │ │ │ │ │ -This allows the disk subsystem to also customize threading and disk job │ │ │ │ │ -management. │ │ │ │ │ -To customize the disk subsystem, implement disk_interface and provide a factory │ │ │ │ │ -function to the session constructor (via session_params). │ │ │ │ │ -Example use: │ │ │ │ │ -struct temp_storage │ │ │ │ │ -{ │ │ │ │ │ - explicit temp_storage(lt::file_storage const& fs) : m_files(fs) {} │ │ │ │ │ - │ │ │ │ │ - lt::span 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 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 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 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((m_files.total_size() + │ │ │ │ │ -m_files.piece_length() - 1) / m_files.piece_length()); │ │ │ │ │ - return static_cast(piece) < num_pieces - 1 │ │ │ │ │ - ? m_files.piece_length() : static_cast(m_files.total_size() - std:: │ │ │ │ │ -int64_t(num_pieces - 1) * m_files.piece_length()); │ │ │ │ │ - } │ │ │ │ │ - │ │ │ │ │ - lt::file_storage const& m_files; │ │ │ │ │ - std::map> m_file_data; │ │ │ │ │ -}; │ │ │ │ │ - │ │ │ │ │ -lt::storage_index_t pop(std::vector& 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 │ │ │ │ │ +****** session_params ****** │ │ │ │ │ +Declared in "libtorrent/session_params.hpp" │ │ │ │ │ +The session_params is a parameters pack for configuring the session before it's │ │ │ │ │ +started. │ │ │ │ │ +struct session_params │ │ │ │ │ { │ │ │ │ │ - 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 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(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 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 b = m_torrents[storage]->readv(r, error); │ │ │ │ │ - │ │ │ │ │ - post(m_ioc, [handler, error, b, this] │ │ │ │ │ - { handler(lt::disk_buffer_holder(*this, const_cast(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 │ │ │ │ │ - , std::function handler │ │ │ │ │ - , lt::disk_job_flags_t) override │ │ │ │ │ - { │ │ │ │ │ - lt::span 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 block_hashes, lt::disk_job_flags_t │ │ │ │ │ - , std::function 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 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 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) override │ │ │ │ │ -{} │ │ │ │ │ - │ │ │ │ │ - void async_delete_files(lt::storage_index_t, lt::remove_flags_t │ │ │ │ │ - , std::function 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::function 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 handler) override │ │ │ │ │ - { │ │ │ │ │ - post(m_ioc, [=]{ handler(name, idx, lt::storage_error()); }); │ │ │ │ │ - } │ │ │ │ │ - │ │ │ │ │ - void async_stop_torrent(lt::storage_index_t, std::function handler) │ │ │ │ │ -override │ │ │ │ │ - { │ │ │ │ │ - post(m_ioc, handler); │ │ │ │ │ - } │ │ │ │ │ - │ │ │ │ │ - void async_set_file_priority(lt::storage_index_t │ │ │ │ │ - , lt::aux::vector prio │ │ │ │ │ - , std::function)> 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 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 get_status(lt::storage_index_t) const │ │ │ │ │ -override │ │ │ │ │ - { return {}; } │ │ │ │ │ - │ │ │ │ │ - void submit_jobs() override {} │ │ │ │ │ - │ │ │ │ │ -private: │ │ │ │ │ - │ │ │ │ │ - lt::aux::vector, lt::storage_index_t> │ │ │ │ │ -m_torrents; │ │ │ │ │ - │ │ │ │ │ - // slots that are unused in the m_torrents vector │ │ │ │ │ - std::vector m_free_slots; │ │ │ │ │ - │ │ │ │ │ - // callbacks are posted on this │ │ │ │ │ - lt::io_context& m_ioc; │ │ │ │ │ -}; │ │ │ │ │ + session_params (settings_pack const& sp); │ │ │ │ │ + session_params (settings_pack&& sp); │ │ │ │ │ + session_params (); │ │ │ │ │ + session_params (settings_pack&& sp │ │ │ │ │ + , std::vector> exts); │ │ │ │ │ + session_params (settings_pack const& sp │ │ │ │ │ + , std::vector> exts); │ │ │ │ │ │ │ │ │ │ -std::unique_ptr temp_disk_constructor( │ │ │ │ │ - lt::io_context& ioc, lt::settings_interface const&, lt::counters&) │ │ │ │ │ -{ │ │ │ │ │ - return std::make_unique(ioc); │ │ │ │ │ -} │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** disk_observer ****** │ │ │ │ │ -Declared in "libtorrent/disk_observer.hpp" │ │ │ │ │ -struct disk_observer │ │ │ │ │ -{ │ │ │ │ │ - virtual void on_disk () = 0; │ │ │ │ │ -}; │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** on_disk() ***** │ │ │ │ │ -virtual void on_disk () = 0; │ │ │ │ │ -called when the disk cache size has dropped below the low watermark again and │ │ │ │ │ -we can resume downloading from peers │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** settings_interface ****** │ │ │ │ │ -Declared in "libtorrent/settings_pack.hpp" │ │ │ │ │ -the common interface to settings_pack and the internal representation of │ │ │ │ │ -settings. │ │ │ │ │ -struct settings_interface │ │ │ │ │ -{ │ │ │ │ │ - virtual void set_str (int name, std::string val) = 0; │ │ │ │ │ - virtual void set_int (int name, int val) = 0; │ │ │ │ │ - virtual bool has_val (int name) const = 0; │ │ │ │ │ - virtual void set_bool (int name, bool 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; │ │ │ │ │ -}; │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** 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; │ │ │ │ │ -}; │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** 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; │ │ │ │ │ + settings_pack settings; │ │ │ │ │ + std::vector> extensions; │ │ │ │ │ + dht::dht_state dht_state; │ │ │ │ │ + dht::dht_storage_constructor_type dht_storage_constructor; │ │ │ │ │ + disk_io_constructor_type disk_io_constructor; │ │ │ │ │ + std::map ext_state; │ │ │ │ │ + libtorrent::ip_filter ip_filter; │ │ │ │ │ }; │ │ │ │ │ [report_issue] │ │ │ │ │ -***** disk_buffer_holder() ***** │ │ │ │ │ -disk_buffer_holder (buffer_allocator_interface& alloc │ │ │ │ │ - , char* buf, int sz) noexcept; │ │ │ │ │ -construct a buffer holder that will free the held buffer using a disk buffer │ │ │ │ │ -pool directly (there's only one disk_buffer_pool per session) │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** disk_buffer_holder() ***** │ │ │ │ │ -disk_buffer_holder () noexcept = default; │ │ │ │ │ -default construct a holder that does not own any buffer │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** ~disk_buffer_holder() ***** │ │ │ │ │ -~disk_buffer_holder (); │ │ │ │ │ -frees disk buffer held by this object │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** data() ***** │ │ │ │ │ -char* data () const noexcept; │ │ │ │ │ -return a pointer to the held buffer, if any. Otherwise returns nullptr. │ │ │ │ │ +***** session_params() ***** │ │ │ │ │ +session_params (settings_pack const& sp); │ │ │ │ │ +session_params (settings_pack&& sp); │ │ │ │ │ +session_params (); │ │ │ │ │ +This constructor can be used to start with the default plugins (ut_metadata, │ │ │ │ │ +ut_pex and smart_ban). Pass a settings_pack to set the initial settings when │ │ │ │ │ +the session starts. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** reset() ***** │ │ │ │ │ -void reset (); │ │ │ │ │ -free the held disk buffer, if any, and clear the holder. This sets the holder │ │ │ │ │ -object to a default-constructed state │ │ │ │ │ +***** session_params() ***** │ │ │ │ │ +session_params (settings_pack&& sp │ │ │ │ │ + , std::vector> exts); │ │ │ │ │ +session_params (settings_pack const& sp │ │ │ │ │ + , std::vector> exts); │ │ │ │ │ +This constructor helps to configure the set of initial plugins to be added to │ │ │ │ │ +the session before it's started. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** swap() ***** │ │ │ │ │ -void swap (disk_buffer_holder& h) noexcept; │ │ │ │ │ -swap pointers of two disk buffer holders. │ │ │ │ │ + settings │ │ │ │ │ + The settings to configure the session with │ │ │ │ │ [report_issue] │ │ │ │ │ -***** is_mutable() ***** │ │ │ │ │ -bool is_mutable () const noexcept; │ │ │ │ │ -if this returns true, the buffer may not be modified in place │ │ │ │ │ + extensions │ │ │ │ │ + the plugins to add to the session as it is constructed │ │ │ │ │ [report_issue] │ │ │ │ │ -***** bool() ***** │ │ │ │ │ -explicit operator bool () const noexcept; │ │ │ │ │ -implicitly convertible to true if the object is currently holding a buffer │ │ │ │ │ + dht_state │ │ │ │ │ + DHT node ID and node addresses to bootstrap the DHT with. │ │ │ │ │ [report_issue] │ │ │ │ │ -****** 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; │ │ │ │ │ -}; │ │ │ │ │ + dht_storage_constructor │ │ │ │ │ + function object to construct the storage object for DHT items. │ │ │ │ │ [report_issue] │ │ │ │ │ - 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. │ │ │ │ │ + disk_io_constructor │ │ │ │ │ + function object to create the disk I/O subsystem. Defaults to │ │ │ │ │ + default_disk_io_constructor. │ │ │ │ │ [report_issue] │ │ │ │ │ - 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. │ │ │ │ │ + ext_state │ │ │ │ │ + this container can be used by extensions/plugins to store settings. It's │ │ │ │ │ + primarily here to make it convenient to save and restore state across │ │ │ │ │ + sessions, using read_session_params() and write_session_params(). │ │ │ │ │ [report_issue] │ │ │ │ │ - last_use │ │ │ │ │ - a (high precision) timestamp of when the file was last used. │ │ │ │ │ + ip_filter │ │ │ │ │ + the IP filter to use for the session. This restricts which peers are │ │ │ │ │ + allowed to connect. As if passed to set_ip_filter(). │ │ │ │ │ [report_issue] │ │ │ │ │ -****** 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 │ │ │ │ │ +****** session_handle ****** │ │ │ │ │ +Declared in "libtorrent/session_handle.hpp" │ │ │ │ │ +this class provides a non-owning handle to a session and a subset of the │ │ │ │ │ +interface of the session class. If the underlying session is destructed any │ │ │ │ │ +handle to it will no longer be valid. is_valid() will return false and any │ │ │ │ │ +operation on it will throw a system_error exception, with error code │ │ │ │ │ +invalid_session_handle. │ │ │ │ │ +struct session_handle │ │ │ │ │ { │ │ │ │ │ - virtual storage_holder new_torrent (storage_params const& p │ │ │ │ │ - , std::shared_ptr 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 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 o │ │ │ │ │ - , std::function handler │ │ │ │ │ - , disk_job_flags_t flags = {}) = 0; │ │ │ │ │ - virtual void async_hash (storage_index_t storage, piece_index_t piece, │ │ │ │ │ -span v2 │ │ │ │ │ - , disk_job_flags_t flags │ │ │ │ │ - , std::function handler) = 0; │ │ │ │ │ - virtual void async_hash2 (storage_index_t storage, piece_index_t piece, int │ │ │ │ │ -offset, disk_job_flags_t flags │ │ │ │ │ - , std::function handler) = 0; │ │ │ │ │ - virtual void async_move_storage (storage_index_t storage, std::string p, │ │ │ │ │ -move_flags_t flags │ │ │ │ │ - , std::function │ │ │ │ │ -handler) = 0; │ │ │ │ │ - virtual void async_release_files (storage_index_t storage │ │ │ │ │ - , std::function handler = std::function()) = 0; │ │ │ │ │ - virtual void async_check_files (storage_index_t storage │ │ │ │ │ - , add_torrent_params const* resume_data │ │ │ │ │ - , aux::vector links │ │ │ │ │ - , std::function handler) = 0; │ │ │ │ │ - virtual void async_stop_torrent (storage_index_t storage │ │ │ │ │ - , std::function handler = std::function()) = 0; │ │ │ │ │ - virtual void async_rename_file (storage_index_t storage │ │ │ │ │ - , file_index_t index, std::string name │ │ │ │ │ - , std::function handler) = 0; │ │ │ │ │ - virtual void async_delete_files (storage_index_t storage, remove_flags_t │ │ │ │ │ -options │ │ │ │ │ - , std::function handler) = 0; │ │ │ │ │ - virtual void async_set_file_priority (storage_index_t storage │ │ │ │ │ - , aux::vector prio │ │ │ │ │ - , std::function)> handler) = 0; │ │ │ │ │ - virtual void async_clear_piece (storage_index_t storage, piece_index_t index │ │ │ │ │ - , std::function handler) = 0; │ │ │ │ │ - virtual void update_stats_counters (counters& c) const = 0; │ │ │ │ │ - virtual std::vector get_status (storage_index_t) const = 0; │ │ │ │ │ - virtual void abort (bool wait) = 0; │ │ │ │ │ - virtual void submit_jobs () = 0; │ │ │ │ │ - virtual void settings_updated () = 0; │ │ │ │ │ + bool is_valid () const; │ │ │ │ │ + session_params session_state (save_state_flags_t flags = │ │ │ │ │ +save_state_flags_t::all()) const; │ │ │ │ │ + void refresh_torrent_status (std::vector* ret │ │ │ │ │ + , status_flags_t flags = {}) const; │ │ │ │ │ + std::vector get_torrent_status ( │ │ │ │ │ + std::function const& pred │ │ │ │ │ + , status_flags_t flags = {}) const; │ │ │ │ │ + void post_torrent_updates (status_flags_t flags = status_flags_t::all()); │ │ │ │ │ + void post_session_stats (); │ │ │ │ │ + void post_dht_stats (); │ │ │ │ │ + void set_dht_state (dht::dht_state const& st); │ │ │ │ │ + void set_dht_state (dht::dht_state&& st); │ │ │ │ │ + torrent_handle find_torrent (sha1_hash const& info_hash) const; │ │ │ │ │ + std::vector get_torrents () const; │ │ │ │ │ + torrent_handle add_torrent (add_torrent_params const& params, error_code& │ │ │ │ │ +ec); │ │ │ │ │ + void async_add_torrent (add_torrent_params&& params); │ │ │ │ │ + void async_add_torrent (add_torrent_params const& params); │ │ │ │ │ + torrent_handle add_torrent (add_torrent_params&& params, error_code& ec); │ │ │ │ │ + torrent_handle add_torrent (add_torrent_params const& params); │ │ │ │ │ + torrent_handle add_torrent (add_torrent_params&& params); │ │ │ │ │ + void pause (); │ │ │ │ │ + void resume (); │ │ │ │ │ + bool is_paused () const; │ │ │ │ │ + bool is_dht_running () const; │ │ │ │ │ + void set_dht_storage (dht::dht_storage_constructor_type sc); │ │ │ │ │ + void add_dht_node (std::pair const& node); │ │ │ │ │ + void dht_get_item (sha1_hash const& target); │ │ │ │ │ + void dht_get_item (std::array key │ │ │ │ │ + , std::string salt = std::string()); │ │ │ │ │ + sha1_hash dht_put_item (entry data); │ │ │ │ │ + void dht_put_item (std::array key │ │ │ │ │ + , std::function& │ │ │ │ │ + , std::int64_t&, std::string const&)> cb │ │ │ │ │ + , std::string salt = std::string()); │ │ │ │ │ + void dht_announce (sha1_hash const& info_hash, int port = 0, dht:: │ │ │ │ │ +announce_flags_t flags = {}); │ │ │ │ │ + void dht_get_peers (sha1_hash const& info_hash); │ │ │ │ │ + void dht_live_nodes (sha1_hash const& nid); │ │ │ │ │ + void dht_sample_infohashes (udp::endpoint const& ep, sha1_hash const& │ │ │ │ │ +target); │ │ │ │ │ + void dht_direct_request (udp::endpoint const& ep, entry const& e, │ │ │ │ │ +client_data_t userdata = {}); │ │ │ │ │ + void add_extension (std::shared_ptr ext); │ │ │ │ │ + void add_extension (std::function( │ │ │ │ │ + torrent_handle const&, client_data_t)> ext); │ │ │ │ │ + ip_filter get_ip_filter () const; │ │ │ │ │ + void set_ip_filter (ip_filter f); │ │ │ │ │ + void set_port_filter (port_filter const& f); │ │ │ │ │ + unsigned short ssl_listen_port () const; │ │ │ │ │ + unsigned short listen_port () const; │ │ │ │ │ + bool is_listening () const; │ │ │ │ │ + ip_filter get_peer_class_filter () const; │ │ │ │ │ + void set_peer_class_filter (ip_filter const& f); │ │ │ │ │ + void set_peer_class_type_filter (peer_class_type_filter const& f); │ │ │ │ │ + peer_class_type_filter get_peer_class_type_filter () const; │ │ │ │ │ + peer_class_t create_peer_class (char const* name); │ │ │ │ │ + void delete_peer_class (peer_class_t cid); │ │ │ │ │ + void set_peer_class (peer_class_t cid, peer_class_info const& pci); │ │ │ │ │ + peer_class_info get_peer_class (peer_class_t cid) const; │ │ │ │ │ + void remove_torrent (const torrent_handle&, remove_flags_t = {}); │ │ │ │ │ + void apply_settings (settings_pack&&); │ │ │ │ │ + settings_pack get_settings () const; │ │ │ │ │ + void apply_settings (settings_pack const&); │ │ │ │ │ + alert* wait_for_alert (time_duration max_wait); │ │ │ │ │ + void set_alert_notify (std::function const& fun); │ │ │ │ │ + void pop_alerts (std::vector* alerts); │ │ │ │ │ + void delete_port_mapping (port_mapping_t handle); │ │ │ │ │ + std::vector add_port_mapping (portmap_protocol t, int │ │ │ │ │ +external_port, int local_port); │ │ │ │ │ + void reopen_network_sockets (reopen_network_flags_t options = │ │ │ │ │ +reopen_map_ports); │ │ │ │ │ + std::shared_ptr native_handle () const; │ │ │ │ │ │ │ │ │ │ - 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; │ │ │ │ │ + static constexpr save_state_flags_t save_settings = 0_bit; │ │ │ │ │ + static constexpr save_state_flags_t save_dht_state = 2_bit; │ │ │ │ │ + static constexpr save_state_flags_t save_extension_state = 11_bit; │ │ │ │ │ + static constexpr save_state_flags_t save_ip_filter = 12_bit; │ │ │ │ │ + static constexpr peer_class_t global_peer_class_id {0}; │ │ │ │ │ + static constexpr peer_class_t tcp_peer_class_id {1}; │ │ │ │ │ + static constexpr peer_class_t local_peer_class_id {2}; │ │ │ │ │ + static constexpr remove_flags_t delete_files = 0_bit; │ │ │ │ │ + static constexpr remove_flags_t delete_partfile = 1_bit; │ │ │ │ │ + static constexpr session_flags_t paused = 2_bit; │ │ │ │ │ + static constexpr portmap_protocol udp = portmap_protocol::udp; │ │ │ │ │ + static constexpr portmap_protocol tcp = portmap_protocol::tcp; │ │ │ │ │ + static constexpr reopen_network_flags_t reopen_map_ports = 0_bit; │ │ │ │ │ }; │ │ │ │ │ [report_issue] │ │ │ │ │ -***** new_torrent() ***** │ │ │ │ │ -virtual storage_holder new_torrent (storage_params const& p │ │ │ │ │ - , std::shared_ptr const& torrent) = 0; │ │ │ │ │ -this is called when a new torrent is added. The shared_ptr can be used to hold │ │ │ │ │ -the internal torrent object alive as long as there are outstanding disk │ │ │ │ │ -operations on the storage. The returned storage_holder is an owning reference │ │ │ │ │ -to the underlying storage that was just created. It is fundamentally a │ │ │ │ │ -storage_index_t │ │ │ │ │ +***** is_valid() ***** │ │ │ │ │ +bool is_valid () const; │ │ │ │ │ +returns true if this handle refers to a valid session object. If the session │ │ │ │ │ +has been destroyed, all session_handle objects will expire and not be valid. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** remove_torrent() ***** │ │ │ │ │ -virtual void remove_torrent (storage_index_t) = 0; │ │ │ │ │ -remove the storage with the specified index. This is not expected to delete any │ │ │ │ │ -files from disk, just to clean up any resources associated with the specified │ │ │ │ │ -storage. │ │ │ │ │ +***** session_state() ***** │ │ │ │ │ +session_params session_state (save_state_flags_t flags = save_state_flags_t:: │ │ │ │ │ +all()) const; │ │ │ │ │ +returns the current session state. This can be passed to write_session_params() │ │ │ │ │ +to save the state to disk and restored using read_session_params() when │ │ │ │ │ +constructing a new session. The kind of state that's included is all settings, │ │ │ │ │ +the DHT routing table, possibly plugin-specific state. the flags parameter can │ │ │ │ │ +be used to only save certain parts of the session state │ │ │ │ │ [report_issue] │ │ │ │ │ -***** async_read() async_write() ***** │ │ │ │ │ -virtual void async_read (storage_index_t storage, peer_request const& r │ │ │ │ │ - , std::function 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 o │ │ │ │ │ - , std::function handler │ │ │ │ │ - , disk_job_flags_t flags = {}) = 0; │ │ │ │ │ -perform a read or write operation from/to the specified storage index and the │ │ │ │ │ -specified request. When the operation completes, call handler possibly with a │ │ │ │ │ -disk_buffer_holder, holding the buffer with the result. Flags may be set to │ │ │ │ │ -affect the read operation. See disk_job_flags_t. │ │ │ │ │ -The disk_observer is a callback to indicate that the store buffer/disk write │ │ │ │ │ -queue is below the watermark to let peers start writing buffers to disk again. │ │ │ │ │ -When async_write() returns true, indicating the write queue is full, the peer │ │ │ │ │ -will stop further writes and wait for the passed-in disk_observer to be │ │ │ │ │ -notified before resuming. │ │ │ │ │ -Note that for async_read, the peer_request (r) is not necessarily aligned to │ │ │ │ │ -blocks (but it is most of the time). However, all writes (passed to │ │ │ │ │ -async_write) are guaranteed to be block aligned. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** async_hash() ***** │ │ │ │ │ -virtual void async_hash (storage_index_t storage, piece_index_t piece, │ │ │ │ │ -span v2 │ │ │ │ │ - , disk_job_flags_t flags │ │ │ │ │ - , std::function handler) = 0; │ │ │ │ │ -Compute hash(es) for the specified piece. Unless the v1_hash flag is set (in │ │ │ │ │ -flags), the SHA-1 hash of the whole piece does not need to be computed. │ │ │ │ │ -Thev2span is optional and can be empty, which means v2 hashes should not be │ │ │ │ │ -computed. If v2 is non-empty it must be at least large enough to hold all v2 │ │ │ │ │ -blocks in the piece, and this function will fill in the span with the SHA-256 │ │ │ │ │ -block hashes of the piece. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** async_hash2() ***** │ │ │ │ │ -virtual void async_hash2 (storage_index_t storage, piece_index_t piece, int │ │ │ │ │ -offset, disk_job_flags_t flags │ │ │ │ │ - , std::function handler) = 0; │ │ │ │ │ -computes the v2 hash (SHA-256) of a single block. The block at offset in piece │ │ │ │ │ -piece. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** async_move_storage() ***** │ │ │ │ │ -virtual void async_move_storage (storage_index_t storage, std::string p, │ │ │ │ │ -move_flags_t flags │ │ │ │ │ - , std::function │ │ │ │ │ -handler) = 0; │ │ │ │ │ -called to request the files for the specified storage/torrent be moved to a new │ │ │ │ │ -location. It is the disk I/O object's responsibility to synchronize this with │ │ │ │ │ -any currently outstanding disk operations to the storage. Whether files are │ │ │ │ │ -replaced at the destination path or not is controlled by flags (see │ │ │ │ │ -move_flags_t). │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** async_release_files() ***** │ │ │ │ │ -virtual void async_release_files (storage_index_t storage │ │ │ │ │ - , std::function handler = std::function()) = 0; │ │ │ │ │ -This is called on disk I/O objects to request they close all open files for the │ │ │ │ │ -specified storage/torrent. If file handles are not pooled/cached, it can be a │ │ │ │ │ -no-op. For truly asynchronous disk I/O, this should provide at least one point │ │ │ │ │ -in time when all files are closed. It is possible that later asynchronous │ │ │ │ │ -operations will re-open some of the files, by the time this completion handler │ │ │ │ │ -is called, that's fine. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** async_check_files() ***** │ │ │ │ │ -virtual void async_check_files (storage_index_t storage │ │ │ │ │ - , add_torrent_params const* resume_data │ │ │ │ │ - , aux::vector links │ │ │ │ │ - , std::function handler) = 0; │ │ │ │ │ -this is called when torrents are added to validate their resume data against │ │ │ │ │ -the files on disk. This function is expected to do a few things: │ │ │ │ │ -if links is non-empty, it contains a string for each file in the torrent. The │ │ │ │ │ -string being a path to an existing identical file. The default behavior is to │ │ │ │ │ -create hard links of those files into the storage of the new torrent (specified │ │ │ │ │ -by storage). An empty string indicates that there is no known identical file. │ │ │ │ │ -This is part of the "mutable torrent" feature, where files can be reused from │ │ │ │ │ -other torrents. │ │ │ │ │ -The resume_data points the resume data passed in by the client. │ │ │ │ │ -If the resume_data->flags field has the seed_mode flag set, all files/pieces │ │ │ │ │ -are expected to be on disk already. This should be verified. Not just the │ │ │ │ │ -existence of the file, but also that it has the correct size. │ │ │ │ │ -Any file with a piece set in the resume_data->have_pieces bitmask should exist │ │ │ │ │ -on disk, this should be verified. Pad files and files with zero priority may be │ │ │ │ │ -skipped. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** async_stop_torrent() ***** │ │ │ │ │ -virtual void async_stop_torrent (storage_index_t storage │ │ │ │ │ - , std::function handler = std::function()) = 0; │ │ │ │ │ -This is called when a torrent is stopped. It gives the disk I/O object an │ │ │ │ │ -opportunity to flush any data to disk that's currently kept cached. This │ │ │ │ │ -function should at least do the same thing as async_release_files(). │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** async_rename_file() ***** │ │ │ │ │ -virtual void async_rename_file (storage_index_t storage │ │ │ │ │ - , file_index_t index, std::string name │ │ │ │ │ - , std::function handler) = 0; │ │ │ │ │ -This function is called when the name of a file in the specified storage has │ │ │ │ │ -been requested to be renamed. The disk I/O object is responsible for renaming │ │ │ │ │ -the file without racing with other potentially outstanding operations against │ │ │ │ │ -the file (such as read, write, move, etc.). │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** async_delete_files() ***** │ │ │ │ │ -virtual void async_delete_files (storage_index_t storage, remove_flags_t │ │ │ │ │ -options │ │ │ │ │ - , std::function handler) = 0; │ │ │ │ │ -This function is called when some file(s) on disk have been requested to be │ │ │ │ │ -removed by the client. storage indicates which torrent is referred to. See │ │ │ │ │ -session_handle for remove_flags_t flags indicating which files are to be │ │ │ │ │ -removed. e.g. session_handle::delete_files - delete all files session_handle:: │ │ │ │ │ -delete_partfile - only delete part file. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** async_set_file_priority() ***** │ │ │ │ │ -virtual void async_set_file_priority (storage_index_t storage │ │ │ │ │ - , aux::vector prio │ │ │ │ │ - , std::function)> handler) = 0; │ │ │ │ │ -This is called to set the priority of some or all files. Changing the priority │ │ │ │ │ -from or to 0 may involve moving data to and from the partfile. The disk I/ │ │ │ │ │ -O object is responsible for correctly synchronizing this work to not race with │ │ │ │ │ -any potentially outstanding asynchronous operations affecting these files. │ │ │ │ │ -prio is a vector of the file priority for all files. If it's shorter than the │ │ │ │ │ -total number of files in the torrent, they are assumed to be set to the default │ │ │ │ │ -priority. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** async_clear_piece() ***** │ │ │ │ │ -virtual void async_clear_piece (storage_index_t storage, piece_index_t index │ │ │ │ │ - , std::function handler) = 0; │ │ │ │ │ -This is called when a piece fails the hash check, to ensure there are no │ │ │ │ │ -outstanding disk operations to the piece before blocks are re-requested from │ │ │ │ │ -peers to overwrite the existing blocks. The disk I/O object does not need to │ │ │ │ │ -perform any action other than synchronize with all outstanding disk operations │ │ │ │ │ -to the specified piece before posting the result back. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** update_stats_counters() ***** │ │ │ │ │ -virtual void update_stats_counters (counters& c) const = 0; │ │ │ │ │ -update_stats_counters() is called to give the disk storage an opportunity to │ │ │ │ │ -update gauges in the c stats counters, that aren't updated continuously as │ │ │ │ │ -operations are performed. This is called before a snapshot of the counters are │ │ │ │ │ -passed to the client. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** get_status() ***** │ │ │ │ │ -virtual std::vector get_status (storage_index_t) const = 0; │ │ │ │ │ -Return a list of all the files that are currently open for the specified │ │ │ │ │ -storage/torrent. This is is just used for the client to query the currently │ │ │ │ │ -open files, and which modes those files are open in. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** abort() ***** │ │ │ │ │ -virtual void abort (bool wait) = 0; │ │ │ │ │ -this is called when the session is starting to shut down. The disk I/O object │ │ │ │ │ -is expected to flush any outstanding write jobs, cancel hash jobs and initiate │ │ │ │ │ -tearing down of any internal threads. If wait is true, this should be │ │ │ │ │ -asynchronous. i.e. this call should not return until all threads have stopped │ │ │ │ │ -and all jobs have either been aborted or completed and the disk I/O object is │ │ │ │ │ -ready to be destructed. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** submit_jobs() ***** │ │ │ │ │ -virtual void submit_jobs () = 0; │ │ │ │ │ -This will be called after a batch of disk jobs has been issues (via the async_* │ │ │ │ │ -). It gives the disk I/O object an opportunity to notify any potential │ │ │ │ │ -condition variables to wake up the disk thread(s). The async_* calls can of │ │ │ │ │ -course also notify condition variables, but doing it in this call allows for │ │ │ │ │ -batching jobs, by issuing the notification once for a collection of jobs. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** settings_updated() ***** │ │ │ │ │ -virtual void settings_updated () = 0; │ │ │ │ │ -This is called to notify the disk I/O object that the settings have been │ │ │ │ │ -updated. In the disk io constructor, a settings_interface reference is passed │ │ │ │ │ -in. Whenever these settings are updated, this function is called to allow the │ │ │ │ │ -disk I/O object to react to any changed settings relevant to its operations. │ │ │ │ │ -[report_issue] │ │ │ │ │ - force_copy │ │ │ │ │ - force making a copy of the cached block, rather than getting a reference │ │ │ │ │ - to a block already in the cache. This is used the block is expected to be │ │ │ │ │ - overwritten very soon, by async_write()`, and we need access to the │ │ │ │ │ - previous content. │ │ │ │ │ -[report_issue] │ │ │ │ │ - sequential_access │ │ │ │ │ - hint that there may be more disk operations with sequential access to the │ │ │ │ │ - file │ │ │ │ │ -[report_issue] │ │ │ │ │ - volatile_read │ │ │ │ │ - don't keep the read block in cache. This is a hint that this block is │ │ │ │ │ - unlikely to be read again anytime soon, and caching it would be wasteful. │ │ │ │ │ -[report_issue] │ │ │ │ │ - v1_hash │ │ │ │ │ - compute a v1 piece hash. This is only used by the async_hash() call. If │ │ │ │ │ - this flag is not set in the async_hash() call, the SHA-1 piece hash does │ │ │ │ │ - not need to be computed. │ │ │ │ │ +***** refresh_torrent_status() get_torrent_status() ***** │ │ │ │ │ +void refresh_torrent_status (std::vector* ret │ │ │ │ │ + , status_flags_t flags = {}) const; │ │ │ │ │ +std::vector get_torrent_status ( │ │ │ │ │ + std::function const& pred │ │ │ │ │ + , status_flags_t flags = {}) const; │ │ │ │ │ +Note │ │ │ │ │ +these calls are potentially expensive and won't scale well with lots of │ │ │ │ │ +torrents. If you're concerned about performance, consider using │ │ │ │ │ +post_torrent_updates() instead. │ │ │ │ │ +get_torrent_status returns a vector of the torrent_status for every torrent │ │ │ │ │ +which satisfies pred, which is a predicate function which determines if a │ │ │ │ │ +torrent should be included in the returned set or not. Returning true means it │ │ │ │ │ +should be included and false means excluded. The flags argument is the same as │ │ │ │ │ +to torrent_handle::status(). Since pred is guaranteed to be called for every │ │ │ │ │ +torrent, it may be used to count the number of torrents of different categories │ │ │ │ │ +as well. │ │ │ │ │ +refresh_torrent_status takes a vector of torrent_status structs (for instance │ │ │ │ │ +the same vector that was returned by get_torrent_status() ) and refreshes the │ │ │ │ │ +status based on the handle member. It is possible to use this function by first │ │ │ │ │ +setting up a vector of default constructed torrent_status objects, only │ │ │ │ │ +initializing the handle member, in order to request the torrent status for │ │ │ │ │ +multiple torrents in a single call. This can save a significant amount of time │ │ │ │ │ +if you have a lot of torrents. │ │ │ │ │ +Any torrent_status object whose handle member is not referring to a valid │ │ │ │ │ +torrent are ignored. │ │ │ │ │ +The intended use of these functions is to start off by calling │ │ │ │ │ +get_torrent_status() to get a list of all torrents that match your criteria. │ │ │ │ │ +Then call refresh_torrent_status() on that list. This will only refresh the │ │ │ │ │ +status for the torrents in your list, and thus ignore all other torrents you │ │ │ │ │ +might be running. This may save a significant amount of time, especially if the │ │ │ │ │ +number of torrents you're interested in is small. In order to keep your list of │ │ │ │ │ +interested torrents up to date, you can either call get_torrent_status() from │ │ │ │ │ +time to time, to include torrents you might have become interested in since the │ │ │ │ │ +last time. In order to stop refreshing a certain torrent, simply remove it from │ │ │ │ │ +the list. │ │ │ │ │ [report_issue] │ │ │ │ │ - flush_piece │ │ │ │ │ - this flag instructs a hash job that we just completed this piece, and it │ │ │ │ │ - should be flushed to disk │ │ │ │ │ +***** post_torrent_updates() ***** │ │ │ │ │ +void post_torrent_updates (status_flags_t flags = status_flags_t::all()); │ │ │ │ │ +This functions instructs the session to post the state_update_alert, containing │ │ │ │ │ +the status of all torrents whose state changed since the last time this │ │ │ │ │ +function was called. │ │ │ │ │ +Only torrents who has the state subscription flag set will be included. This │ │ │ │ │ +flag is on by default. See add_torrent_params. the flags argument is the same │ │ │ │ │ +as for torrent_handle::status(). see status_flags_t in torrent_handle. │ │ │ │ │ [report_issue] │ │ │ │ │ -****** 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 (storage_index_t idx, disk_interface& disk_io); │ │ │ │ │ - ~storage_holder (); │ │ │ │ │ - storage_holder () = default; │ │ │ │ │ - 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; │ │ │ │ │ -}; │ │ │ │ │ +***** post_session_stats() ***** │ │ │ │ │ +void post_session_stats (); │ │ │ │ │ +This function will post a session_stats_alert object, containing a snapshot of │ │ │ │ │ +the performance counters from the internals of libtorrent. To interpret these │ │ │ │ │ +counters, query the session via session_stats_metrics(). │ │ │ │ │ +For more information, see the session_statistics section. │ │ │ │ │ [report_issue] │ │ │ │ │ -****** 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 │ │ │ │ │ +***** post_dht_stats() ***** │ │ │ │ │ +void post_dht_stats (); │ │ │ │ │ +This will cause a dht_stats_alert to be posted. │ │ │ │ │ [report_issue] │ │ │ │ │ -****** counters ****** │ │ │ │ │ -Declared in "libtorrent/performance_counters.hpp" │ │ │ │ │ -struct counters │ │ │ │ │ -{ │ │ │ │ │ - counters () ; │ │ │ │ │ - counters& operator= (counters const&) & ; │ │ │ │ │ - counters (counters const&) ; │ │ │ │ │ - std::int64_t operator[] (int i) const ; │ │ │ │ │ - std::int64_t inc_stats_counter (int c, std::int64_t value = 1) ; │ │ │ │ │ - void blend_stats_counter (int c, std::int64_t value, int ratio) ; │ │ │ │ │ - void set_value (int c, std::int64_t value) ; │ │ │ │ │ -}; │ │ │ │ │ +***** set_dht_state() ***** │ │ │ │ │ +void set_dht_state (dht::dht_state const& st); │ │ │ │ │ +void set_dht_state (dht::dht_state&& st); │ │ │ │ │ +set the DHT state for the session. This will be taken into account the next │ │ │ │ │ +time the DHT is started, as if it had been passed in via the session_params on │ │ │ │ │ +startup. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** inc_stats_counter() operator[]() ***** │ │ │ │ │ -std::int64_t operator[] (int i) const ; │ │ │ │ │ -std::int64_t inc_stats_counter (int c, std::int64_t value = 1) ; │ │ │ │ │ -returns the new value │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** stats_metric ****** │ │ │ │ │ -Declared in "libtorrent/session_stats.hpp" │ │ │ │ │ -describes one statistics metric from the session. For more information, see the │ │ │ │ │ -session_statistics section. │ │ │ │ │ -struct stats_metric │ │ │ │ │ -{ │ │ │ │ │ - char const* name; │ │ │ │ │ - int value_index; │ │ │ │ │ - metric_type_t type; │ │ │ │ │ -}; │ │ │ │ │ -[report_issue] │ │ │ │ │ - name │ │ │ │ │ - the name of the counter or gauge │ │ │ │ │ +***** find_torrent() get_torrents() ***** │ │ │ │ │ +torrent_handle find_torrent (sha1_hash const& info_hash) const; │ │ │ │ │ +std::vector get_torrents () const; │ │ │ │ │ +find_torrent() looks for a torrent with the given info-hash. In case there is │ │ │ │ │ +such a torrent in the session, a torrent_handle to that torrent is returned. In │ │ │ │ │ +case the torrent cannot be found, an invalid torrent_handle is returned. │ │ │ │ │ +See torrent_handle::is_valid() to know if the torrent was found or not. │ │ │ │ │ +get_torrents() returns a vector of torrent_handles to all the torrents │ │ │ │ │ +currently in the session. │ │ │ │ │ [report_issue] │ │ │ │ │ - value_index type │ │ │ │ │ - the index into the session stats array, where the underlying value of │ │ │ │ │ - this counter or gauge is found. The session stats array is part of the │ │ │ │ │ - session_stats_alert object. │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** session_stats_metrics() ****** │ │ │ │ │ -Declared in "libtorrent/session_stats.hpp" │ │ │ │ │ -std::vector session_stats_metrics (); │ │ │ │ │ -This free function returns the list of available metrics exposed by │ │ │ │ │ -libtorrent's statistics API. Each metric has a name and a value index. The │ │ │ │ │ -value index is the index into the array in session_stats_alert where this │ │ │ │ │ -metric's value can be found when the session stats is sampled (by calling │ │ │ │ │ -post_session_stats()). │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** find_metric_idx() ****** │ │ │ │ │ -Declared in "libtorrent/session_stats.hpp" │ │ │ │ │ -int find_metric_idx (string_view name); │ │ │ │ │ -given a name of a metric, this function returns the counter index of it, or - │ │ │ │ │ -1 if it could not be found. The counter index is the index into the values │ │ │ │ │ -array returned by session_stats_alert. │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** enum metric_type_t ****** │ │ │ │ │ -Declared in "libtorrent/session_stats.hpp" │ │ │ │ │ - _________________________ │ │ │ │ │ -|name___|value|description| │ │ │ │ │ -|counter|0____| _________| │ │ │ │ │ -|gauge__|1____| _________| │ │ │ │ │ -libtorrent has a plugin interface for implementing extensions to the protocol. │ │ │ │ │ -These can be general extensions for transferring metadata or peer exchange │ │ │ │ │ -extensions, or it could be used to provide a way to customize the protocol to │ │ │ │ │ -fit a particular (closed) network. │ │ │ │ │ -In short, the plugin interface makes it possible to: │ │ │ │ │ - * register extension messages (sent in the extension handshake), see │ │ │ │ │ - extensions. │ │ │ │ │ - * add data and parse data from the extension handshake. │ │ │ │ │ - * send extension messages and standard bittorrent messages. │ │ │ │ │ - * override or block the handling of standard bittorrent messages. │ │ │ │ │ - * save and restore state via the session state │ │ │ │ │ - * see all alerts that are posted │ │ │ │ │ -****** 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 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_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 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 = ; │ │ │ │ │ -virtual int type() const { return alert_type; } │ │ │ │ │ - │ │ │ │ │ -virtual std::string message() const; │ │ │ │ │ - │ │ │ │ │ -static const alert_category_t static_category = ; │ │ │ │ │ -virtual alert_category_t category() const { return static_category; } │ │ │ │ │ - │ │ │ │ │ -virtual char const* what() const { return ; } │ │ │ │ │ -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. │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** 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 impl); │ │ │ │ │ - connection_type type () const; │ │ │ │ │ - peer_plugin const* find_plugin (string_view type) const; │ │ │ │ │ - void add_extension (std::shared_ptr); │ │ │ │ │ - bool is_seed () const; │ │ │ │ │ - bool upload_only () const; │ │ │ │ │ - peer_id const& pid () const; │ │ │ │ │ - bool has_piece (piece_index_t i) const; │ │ │ │ │ - bool is_interesting () const; │ │ │ │ │ - bool is_choked () const; │ │ │ │ │ - bool is_peer_interested () const; │ │ │ │ │ - bool has_peer_choked () const; │ │ │ │ │ - void maybe_unchoke_this_peer (); │ │ │ │ │ - void choke_this_peer (); │ │ │ │ │ - void get_peer_info (peer_info& p) const; │ │ │ │ │ - torrent_handle associated_torrent () const; │ │ │ │ │ - tcp::endpoint const& remote () const; │ │ │ │ │ - tcp::endpoint local_endpoint () const; │ │ │ │ │ - bool is_connecting () const; │ │ │ │ │ - void disconnect (error_code const& ec, operation_t op │ │ │ │ │ - , disconnect_severity_t = peer_connection_interface::normal); │ │ │ │ │ - bool is_disconnecting () const; │ │ │ │ │ - bool is_outgoing () const; │ │ │ │ │ - bool ignore_unchoke_slots () const; │ │ │ │ │ - bool on_local_network () const; │ │ │ │ │ - bool failed () const; │ │ │ │ │ - bool should_log (peer_log_alert::direction_t direction) const; │ │ │ │ │ - void peer_log (peer_log_alert::direction_t direction │ │ │ │ │ - , char const* event, char const* fmt = "", ...) const TORRENT_FORMAT │ │ │ │ │ -(4,5); │ │ │ │ │ - bool can_disconnect (error_code const& ec) const; │ │ │ │ │ - bool has_metadata () const; │ │ │ │ │ - bool in_handshake () const; │ │ │ │ │ - void send_buffer (char const* begin, int size); │ │ │ │ │ - time_point time_of_last_unchoke () const; │ │ │ │ │ - std::time_t last_seen_complete () 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 native_handle () const; │ │ │ │ │ -}; │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** 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); │ │ │ │ │ - void switch_recv_crypto (std::shared_ptr crypto); │ │ │ │ │ - std::shared_ptr native_handle () const; │ │ │ │ │ -}; │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** 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 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 save_state () const; │ │ │ │ │ - virtual void load_state (std::map 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; │ │ │ │ │ -}; │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** implemented_features() ***** │ │ │ │ │ -virtual feature_flags_t implemented_features (); │ │ │ │ │ -This function is expected to return a bitmask indicating which features this │ │ │ │ │ -plugin implements. Some callbacks on this object may not be called unless the │ │ │ │ │ -corresponding feature flag is returned here. Note that callbacks may still be │ │ │ │ │ -called even if the corresponding feature is not specified in the return value │ │ │ │ │ -here. See feature_flags_t for possible flags to return. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** new_torrent() ***** │ │ │ │ │ -virtual std::shared_ptr new_torrent (torrent_handle const&, │ │ │ │ │ -client_data_t); │ │ │ │ │ -this is called by the session every time a new torrent is added. The torrent* │ │ │ │ │ -points to the internal torrent object created for the new torrent. The │ │ │ │ │ -client_data_t is the userdata pointer as passed in via add_torrent_params. │ │ │ │ │ -If the plugin returns a torrent_plugin instance, it will be added to the new │ │ │ │ │ -torrent. Otherwise, return an empty shared_ptr to a torrent_plugin (the │ │ │ │ │ -default). │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** added() ***** │ │ │ │ │ -virtual void added (session_handle const&); │ │ │ │ │ -called when plugin is added to a session │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** abort() ***** │ │ │ │ │ -virtual void abort (); │ │ │ │ │ -called when the session is aborted the plugin should perform any cleanup │ │ │ │ │ -necessary to allow the session's destruction (e.g. cancel outstanding async │ │ │ │ │ -operations) │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** on_dht_request() ***** │ │ │ │ │ -virtual bool on_dht_request (string_view /* query */ │ │ │ │ │ - , udp::endpoint const& /* source */, bdecode_node const& /* message */ │ │ │ │ │ - , entry& /* response */); │ │ │ │ │ -called when a dht request is received. If your plugin expects this to be │ │ │ │ │ -called, make sure to include the flag dht_request_feature in the return value │ │ │ │ │ -from implemented_features(). │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** on_alert() ***** │ │ │ │ │ -virtual void on_alert (alert const*); │ │ │ │ │ -called when an alert is posted alerts that are filtered are not posted. If your │ │ │ │ │ -plugin expects this to be called, make sure to include the flag alert_feature │ │ │ │ │ -in the return value from implemented_features(). │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** on_unknown_torrent() ***** │ │ │ │ │ -virtual bool on_unknown_torrent (info_hash_t const& /* info_hash */ │ │ │ │ │ - , peer_connection_handle const& /* pc */, add_torrent_params& /* p */); │ │ │ │ │ -return true if the add_torrent_params should be added │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** on_tick() ***** │ │ │ │ │ -virtual void on_tick (); │ │ │ │ │ -called once per second. If your plugin expects this to be called, make sure to │ │ │ │ │ -include the flag tick_feature in the return value from implemented_features(). │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** get_unchoke_priority() ***** │ │ │ │ │ -virtual uint64_t get_unchoke_priority (peer_connection_handle const& /* peer */ │ │ │ │ │ -); │ │ │ │ │ -called when choosing peers to optimistically unchoke. The return value │ │ │ │ │ -indicates the peer's priority for unchoking. Lower return values correspond to │ │ │ │ │ -higher priority. Priorities above 2^63-1 are reserved. If your plugin has no │ │ │ │ │ -priority to assign a peer it should return 2^64-1. If your plugin expects this │ │ │ │ │ -to be called, make sure to include the flag optimistic_unchoke_feature in the │ │ │ │ │ -return value from implemented_features(). If multiple plugins implement this │ │ │ │ │ -function the lowest return value (i.e. the highest priority) is used. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** load_state() ***** │ │ │ │ │ -virtual void load_state (std::map const&); │ │ │ │ │ -called on startup while loading settings state from the session_params │ │ │ │ │ +***** add_torrent() async_add_torrent() ***** │ │ │ │ │ +torrent_handle add_torrent (add_torrent_params const& params, error_code& ec); │ │ │ │ │ +void async_add_torrent (add_torrent_params&& params); │ │ │ │ │ +void async_add_torrent (add_torrent_params const& params); │ │ │ │ │ +torrent_handle add_torrent (add_torrent_params&& params, error_code& ec); │ │ │ │ │ +torrent_handle add_torrent (add_torrent_params const& params); │ │ │ │ │ +torrent_handle add_torrent (add_torrent_params&& params); │ │ │ │ │ +You add torrents through the add_torrent() function where you give an object │ │ │ │ │ +with all the parameters. The add_torrent() overloads will block until the │ │ │ │ │ +torrent has been added (or failed to be added) and returns an error code and a │ │ │ │ │ +torrent_handle. In order to add torrents more efficiently, consider using │ │ │ │ │ +async_add_torrent() which returns immediately, without waiting for the torrent │ │ │ │ │ +to add. Notification of the torrent being added is sent as add_torrent_alert. │ │ │ │ │ +The overload that does not take an error_code throws an exception on error and │ │ │ │ │ +is not available when building without exception support. The torrent_handle │ │ │ │ │ +returned by add_torrent() can be used to retrieve information about the │ │ │ │ │ +torrent's progress, its peers etc. It is also used to abort a torrent. │ │ │ │ │ +If the torrent you are trying to add already exists in the session (is either │ │ │ │ │ +queued for checking, being checked or downloading) add_torrent() will throw │ │ │ │ │ +system_error which derives from std::exception unless duplicate_is_error is set │ │ │ │ │ +to false. In that case, add_torrent() will return the handle to the existing │ │ │ │ │ +torrent. │ │ │ │ │ +The add_torrent_params class has a flags field. It can be used to control what │ │ │ │ │ +state the new torrent will be added in. Common flags to want to control are │ │ │ │ │ +torrent_flags::paused and torrent_flags::auto_managed. In order to add a magnet │ │ │ │ │ +link that will just download the metadata, but no payload, set the │ │ │ │ │ +torrent_flags::upload_mode flag. │ │ │ │ │ +Special consideration has to be taken when adding hybrid torrents (i.e. │ │ │ │ │ +torrents that are BitTorrent v2 torrents that are backwards compatible with │ │ │ │ │ +v1). For more details, see BitTorrent_v2_torrents. │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** pause() is_paused() resume() ***** │ │ │ │ │ +void pause (); │ │ │ │ │ +void resume (); │ │ │ │ │ +bool is_paused () const; │ │ │ │ │ +Pausing the session has the same effect as pausing every torrent in it, except │ │ │ │ │ +that torrents will not be resumed by the auto-manage mechanism. Resuming will │ │ │ │ │ +restore the torrents to their previous paused state. i.e. the session pause │ │ │ │ │ +state is separate from the torrent pause state. A torrent is inactive if it is │ │ │ │ │ +paused or if the session is paused. │ │ │ │ │ [report_issue] │ │ │ │ │ - optimistic_unchoke_feature │ │ │ │ │ - include this bit if your plugin needs to alter the order of the │ │ │ │ │ - optimistic unchoke of peers. i.e. have the on_optimistic_unchoke() │ │ │ │ │ - callback be called. │ │ │ │ │ +***** is_dht_running() ***** │ │ │ │ │ +bool is_dht_running () const; │ │ │ │ │ +is_dht_running() returns true if the DHT support has been started and false │ │ │ │ │ +otherwise. │ │ │ │ │ [report_issue] │ │ │ │ │ - tick_feature │ │ │ │ │ - include this bit if your plugin needs to have on_tick() called │ │ │ │ │ +***** set_dht_storage() ***** │ │ │ │ │ +void set_dht_storage (dht::dht_storage_constructor_type sc); │ │ │ │ │ +set_dht_storage set a dht custom storage constructor function to be used │ │ │ │ │ +internally when the dht is created. │ │ │ │ │ +Since the dht storage is a critical component for the dht behavior, this │ │ │ │ │ +function will only be effective the next time the dht is started. If you never │ │ │ │ │ +touch this feature, a default map-memory based storage is used. │ │ │ │ │ +If you want to make sure the dht is initially created with your custom storage, │ │ │ │ │ +create a session with the setting settings_pack::enable_dht to false, set your │ │ │ │ │ +constructor function and call apply_settings with settings_pack::enable_dht to │ │ │ │ │ +true. │ │ │ │ │ [report_issue] │ │ │ │ │ - dht_request_feature │ │ │ │ │ - include this bit if your plugin needs to have on_dht_request() called │ │ │ │ │ +***** add_dht_node() ***** │ │ │ │ │ +void add_dht_node (std::pair const& node); │ │ │ │ │ +add_dht_node takes a host name and port pair. That endpoint will be pinged, and │ │ │ │ │ +if a valid DHT reply is received, the node will be added to the routing table. │ │ │ │ │ [report_issue] │ │ │ │ │ - alert_feature │ │ │ │ │ - include this bit if your plugin needs to have on_alert() called │ │ │ │ │ +***** dht_get_item() ***** │ │ │ │ │ +void dht_get_item (sha1_hash const& target); │ │ │ │ │ +query the DHT for an immutable item at the target hash. the result is posted as │ │ │ │ │ +a dht_immutable_item_alert. │ │ │ │ │ [report_issue] │ │ │ │ │ -****** 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 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; │ │ │ │ │ -}; │ │ │ │ │ +***** dht_get_item() ***** │ │ │ │ │ +void dht_get_item (std::array key │ │ │ │ │ + , std::string salt = std::string()); │ │ │ │ │ +query the DHT for a mutable item under the public key key. this is an ed25519 │ │ │ │ │ +key. salt is optional and may be left as an empty string if no salt is to be │ │ │ │ │ +used. if the item is found in the DHT, a dht_mutable_item_alert is posted. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** new_connection() ***** │ │ │ │ │ -virtual std::shared_ptr new_connection (peer_connection_handle │ │ │ │ │ -const&); │ │ │ │ │ -This function is called each time a new peer is connected to the torrent. You │ │ │ │ │ -may choose to ignore this by just returning a default constructed shared_ptr │ │ │ │ │ -(in which case you don't need to override this member function). │ │ │ │ │ -If you need an extension to the peer connection (which most plugins do) you are │ │ │ │ │ -supposed to return an instance of your peer_plugin class. Which in turn will │ │ │ │ │ -have its hook functions called on event specific to that peer. │ │ │ │ │ -The peer_connection_handle will be valid as long as the shared_ptr is being │ │ │ │ │ -held by the torrent object. So, it is generally a good idea to not keep a │ │ │ │ │ -shared_ptr to your own peer_plugin. If you want to keep references to it, use │ │ │ │ │ -weak_ptr. │ │ │ │ │ -If this function throws an exception, the connection will be closed. │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** on_piece_pass() on_piece_failed() ***** │ │ │ │ │ -virtual void on_piece_failed (piece_index_t); │ │ │ │ │ -virtual void on_piece_pass (piece_index_t); │ │ │ │ │ -These hooks are called when a piece passes the hash check or fails the hash │ │ │ │ │ -check, respectively. The index is the piece index that was downloaded. It is │ │ │ │ │ -possible to access the list of peers that participated in sending the piece │ │ │ │ │ -through the torrent and the piece_picker. │ │ │ │ │ +***** dht_put_item() ***** │ │ │ │ │ +sha1_hash dht_put_item (entry data); │ │ │ │ │ +store the given bencoded data as an immutable item in the DHT. the returned │ │ │ │ │ +hash is the key that is to be used to look the item up again. It's just the │ │ │ │ │ +SHA-1 hash of the bencoded form of the structure. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** tick() ***** │ │ │ │ │ -virtual void tick (); │ │ │ │ │ -This hook is called approximately once per second. It is a way of making it │ │ │ │ │ -easy for plugins to do timed events, for sending messages or whatever. │ │ │ │ │ +***** dht_put_item() ***** │ │ │ │ │ +void dht_put_item (std::array key │ │ │ │ │ + , std::function& │ │ │ │ │ + , std::int64_t&, std::string const&)> cb │ │ │ │ │ + , std::string salt = std::string()); │ │ │ │ │ +store a mutable item. The key is the public key the blob is to be stored under. │ │ │ │ │ +The optional salt argument is a string that is to be mixed in with the key when │ │ │ │ │ +determining where in the DHT the value is to be stored. The callback function │ │ │ │ │ +is called from within the libtorrent network thread once we've found where to │ │ │ │ │ +store the blob, possibly with the current value stored under the key. The │ │ │ │ │ +values passed to the callback functions are: │ │ │ │ │ + entry& value │ │ │ │ │ + the current value stored under the key (may be empty). Also expected to │ │ │ │ │ + be set to the value to be stored by the function. │ │ │ │ │ + std::array& signature │ │ │ │ │ + the signature authenticating the current value. This may be zeros if │ │ │ │ │ + there is currently no value stored. The function is expected to fill in │ │ │ │ │ + this buffer with the signature of the new value to store. To generate the │ │ │ │ │ + signature, you may want to use the sign_mutable_item function. │ │ │ │ │ + std::int64_t& seq │ │ │ │ │ + current sequence number. May be zero if there is no current value. The │ │ │ │ │ + function is expected to set this to the new sequence number of the value │ │ │ │ │ + that is to be stored. Sequence numbers must be monotonically increasing. │ │ │ │ │ + Attempting to overwrite a value with a lower or equal sequence number │ │ │ │ │ + will fail, even if the signature is correct. │ │ │ │ │ + std::string const& salt │ │ │ │ │ + this is the salt that was used for this put call. │ │ │ │ │ +Since the callback function cb is called from within libtorrent, it is critical │ │ │ │ │ +to not perform any blocking operations. Ideally not even locking a mutex. Pass │ │ │ │ │ +any data required for this function along with the function object's context │ │ │ │ │ +and make the function entirely self-contained. The only reason data blob's │ │ │ │ │ +value is computed via a function instead of just passing in the new value is to │ │ │ │ │ +avoid race conditions. If you want to update the value in the DHT, you must │ │ │ │ │ +first retrieve it, then modify it, then write it back. The way the DHT works, │ │ │ │ │ +it is natural to always do a lookup before storing and calling the callback in │ │ │ │ │ +between is convenient. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** on_resume() on_pause() ***** │ │ │ │ │ -virtual bool on_resume (); │ │ │ │ │ -virtual bool on_pause (); │ │ │ │ │ -These hooks are called when the torrent is paused and resumed respectively. The │ │ │ │ │ -return value indicates if the event was handled. A return value of true │ │ │ │ │ -indicates that it was handled, and no other plugin after this one will have │ │ │ │ │ -this hook function called, and the standard handler will also not be invoked. │ │ │ │ │ -So, returning true effectively overrides the standard behavior of pause or │ │ │ │ │ -resume. │ │ │ │ │ -Note that if you call pause() or resume() on the torrent from your handler it │ │ │ │ │ -will recurse back into your handler, so in order to invoke the standard │ │ │ │ │ -handler, you have to keep your own state on whether you want standard behavior │ │ │ │ │ -or overridden behavior. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** on_files_checked() ***** │ │ │ │ │ -virtual void on_files_checked (); │ │ │ │ │ -This function is called when the initial files of the torrent have been │ │ │ │ │ -checked. If there are no files to check, this function is called immediately. │ │ │ │ │ -i.e. This function is always called when the torrent is in a state where it can │ │ │ │ │ -start downloading. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** on_state() ***** │ │ │ │ │ -virtual void on_state (torrent_status::state_t); │ │ │ │ │ -called when the torrent changes state the state is one of torrent_status:: │ │ │ │ │ -state_t enum members │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** on_add_peer() ***** │ │ │ │ │ -virtual void on_add_peer (tcp::endpoint const&, │ │ │ │ │ - peer_source_flags_t, add_peer_flags_t); │ │ │ │ │ -called every time a new peer is added to the peer list. This is before the peer │ │ │ │ │ -is connected to. For flags, see torrent_plugin::flags_t. The source argument │ │ │ │ │ -refers to the source where we learned about this peer from. It's a bitmask, │ │ │ │ │ -because many sources may have told us about the same peer. For peer source │ │ │ │ │ -flags, see peer_info::peer_source_flags. │ │ │ │ │ -[report_issue] │ │ │ │ │ - first_time │ │ │ │ │ - this is the first time we see this peer │ │ │ │ │ -[report_issue] │ │ │ │ │ - filtered │ │ │ │ │ - this peer was not added because it was filtered by the IP filter │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** 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); │ │ │ │ │ - virtual bool on_extension_handshake (bdecode_node const&); │ │ │ │ │ - virtual bool on_interested (); │ │ │ │ │ - virtual bool on_dont_have (piece_index_t); │ │ │ │ │ - virtual bool on_bitfield (bitfield const& /*bitfield*/); │ │ │ │ │ - virtual bool on_request (peer_request const&); │ │ │ │ │ - virtual bool on_have_none (); │ │ │ │ │ - virtual bool on_have_all (); │ │ │ │ │ - virtual bool on_unchoke (); │ │ │ │ │ - virtual bool on_choke (); │ │ │ │ │ - virtual bool on_not_interested (); │ │ │ │ │ - virtual bool on_have (piece_index_t); │ │ │ │ │ - virtual bool on_allowed_fast (piece_index_t); │ │ │ │ │ - virtual bool on_piece (peer_request const& /*piece*/ │ │ │ │ │ - , span /*buf*/); │ │ │ │ │ - virtual bool on_cancel (peer_request const&); │ │ │ │ │ - virtual bool on_suggest (piece_index_t); │ │ │ │ │ - virtual bool on_reject (peer_request const&); │ │ │ │ │ - virtual void sent_reject_request (peer_request const&); │ │ │ │ │ - virtual void sent_allow_fast (piece_index_t); │ │ │ │ │ - virtual void sent_suggest (piece_index_t); │ │ │ │ │ - virtual void sent_choke (); │ │ │ │ │ - virtual void sent_have_none (); │ │ │ │ │ - virtual void sent_request (peer_request const&); │ │ │ │ │ - virtual void sent_have_all (); │ │ │ │ │ - virtual void sent_cancel (peer_request const&); │ │ │ │ │ - virtual void sent_interested (); │ │ │ │ │ - virtual void sent_have (piece_index_t); │ │ │ │ │ - virtual void sent_not_interested (); │ │ │ │ │ - virtual void sent_unchoke (); │ │ │ │ │ - virtual void sent_piece (peer_request const&); │ │ │ │ │ - virtual void sent_payload (int /* bytes */); │ │ │ │ │ - virtual bool can_disconnect (error_code const& /*ec*/); │ │ │ │ │ - virtual bool on_extended (int /*length*/, int /*msg*/, │ │ │ │ │ - span /*body*/); │ │ │ │ │ - virtual bool on_unknown_message (int /*length*/, int /*msg*/, │ │ │ │ │ - span /*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&); │ │ │ │ │ -}; │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** type() ***** │ │ │ │ │ -virtual string_view type () const; │ │ │ │ │ -This function is expected to return the name of the plugin. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** add_handshake() ***** │ │ │ │ │ -virtual void add_handshake (entry&); │ │ │ │ │ -can add entries to the extension handshake this is not called for web seeds │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** on_disconnect() ***** │ │ │ │ │ -virtual void on_disconnect (error_code const&); │ │ │ │ │ -called when the peer is being disconnected. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** on_connected() ***** │ │ │ │ │ -virtual void on_connected (); │ │ │ │ │ -called when the peer is successfully connected. Note that incoming connections │ │ │ │ │ -will have been connected by the time the peer plugin is attached to it, and │ │ │ │ │ -won't have this hook called. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** on_handshake() ***** │ │ │ │ │ -virtual bool on_handshake (span); │ │ │ │ │ -this is called when the initial bittorrent handshake is received. Returning │ │ │ │ │ -false means that the other end doesn't support this extension and will remove │ │ │ │ │ -it from the list of plugins. this is not called for web seeds │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** on_extension_handshake() ***** │ │ │ │ │ -virtual bool on_extension_handshake (bdecode_node const&); │ │ │ │ │ -called when the extension handshake from the other end is received if this │ │ │ │ │ -returns false, it means that this extension isn't supported by this peer. It │ │ │ │ │ -will result in this peer_plugin being removed from the peer_connection and │ │ │ │ │ -destructed. this is not called for web seeds │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** on_dont_have() on_allowed_fast() on_not_interested() on_bitfield() │ │ │ │ │ -on_have_none() on_have() on_choke() on_interested() on_request() on_unchoke() │ │ │ │ │ -on_have_all() ***** │ │ │ │ │ -virtual bool on_interested (); │ │ │ │ │ -virtual bool on_dont_have (piece_index_t); │ │ │ │ │ -virtual bool on_bitfield (bitfield const& /*bitfield*/); │ │ │ │ │ -virtual bool on_request (peer_request const&); │ │ │ │ │ -virtual bool on_have_none (); │ │ │ │ │ -virtual bool on_have_all (); │ │ │ │ │ -virtual bool on_unchoke (); │ │ │ │ │ -virtual bool on_choke (); │ │ │ │ │ -virtual bool on_not_interested (); │ │ │ │ │ -virtual bool on_have (piece_index_t); │ │ │ │ │ -virtual bool on_allowed_fast (piece_index_t); │ │ │ │ │ -returning true from any of the message handlers indicates that the plugin has │ │ │ │ │ -handled the message. it will break the plugin chain traversing and not let │ │ │ │ │ -anyone else handle the message, including the default handler. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** on_piece() ***** │ │ │ │ │ -virtual bool on_piece (peer_request const& /*piece*/ │ │ │ │ │ - , span /*buf*/); │ │ │ │ │ -This function is called when the peer connection is receiving a piece. buf │ │ │ │ │ -points (non-owning pointer) to the data in an internal immutable disk buffer. │ │ │ │ │ -The length of the data is specified in the length member of the piece │ │ │ │ │ -parameter. returns true to indicate that the piece is handled and the rest of │ │ │ │ │ -the logic should be ignored. │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** sent_have() sent_unchoke() sent_piece() sent_interested() │ │ │ │ │ -sent_not_interested() ***** │ │ │ │ │ -virtual void sent_interested (); │ │ │ │ │ -virtual void sent_have (piece_index_t); │ │ │ │ │ -virtual void sent_not_interested (); │ │ │ │ │ -virtual void sent_unchoke (); │ │ │ │ │ -virtual void sent_piece (peer_request const&); │ │ │ │ │ -called after a choke message has been sent to the peer │ │ │ │ │ +***** dht_announce() dht_get_peers() ***** │ │ │ │ │ +void dht_announce (sha1_hash const& info_hash, int port = 0, dht:: │ │ │ │ │ +announce_flags_t flags = {}); │ │ │ │ │ +void dht_get_peers (sha1_hash const& info_hash); │ │ │ │ │ +dht_get_peers() will issue a DHT get_peer request to the DHT for the specified │ │ │ │ │ +info-hash. The response (the peers) will be posted back in a │ │ │ │ │ +dht_get_peers_reply_alert. │ │ │ │ │ +dht_announce() will issue a DHT announce request to the DHT to the specified │ │ │ │ │ +info-hash, advertising the specified port. If the port is left at its default, │ │ │ │ │ +0, the port will be implied by the DHT message's source port (which may improve │ │ │ │ │ +connectivity through a NAT). │ │ │ │ │ +Both these functions are exposed for advanced custom use of the DHT. All │ │ │ │ │ +torrents eligible to be announce to the DHT will be automatically, by │ │ │ │ │ +libtorrent. │ │ │ │ │ +For possible flags, see announce_flags_t. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** sent_payload() ***** │ │ │ │ │ -virtual void sent_payload (int /* bytes */); │ │ │ │ │ -called after piece data has been sent to the peer this can be used for stats │ │ │ │ │ -book keeping │ │ │ │ │ +***** dht_live_nodes() ***** │ │ │ │ │ +void dht_live_nodes (sha1_hash const& nid); │ │ │ │ │ +Retrieve all the live DHT (identified by nid) nodes. All the nodes id and │ │ │ │ │ +endpoint will be returned in the list of nodes in the alert │ │ │ │ │ +dht_live_nodes_alert. Since this alert is a response to an explicit call, it │ │ │ │ │ +will always be posted, regardless of the alert mask. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** can_disconnect() ***** │ │ │ │ │ -virtual bool can_disconnect (error_code const& /*ec*/); │ │ │ │ │ -called when libtorrent think this peer should be disconnected. if the plugin │ │ │ │ │ -returns false, the peer will not be disconnected. │ │ │ │ │ +***** dht_sample_infohashes() ***** │ │ │ │ │ +void dht_sample_infohashes (udp::endpoint const& ep, sha1_hash const& target); │ │ │ │ │ +Query the DHT node specified by ep to retrieve a sample of the info-hashes that │ │ │ │ │ +the node currently have in their storage. The target is included for iterative │ │ │ │ │ +lookups so that indexing nodes can perform a key space traversal with a single │ │ │ │ │ +RPC per node by adjusting the target value for each RPC. It has no effect on │ │ │ │ │ +the returned sample value. The result is posted as a │ │ │ │ │ +dht_sample_infohashes_alert. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** on_extended() ***** │ │ │ │ │ -virtual bool on_extended (int /*length*/, int /*msg*/, │ │ │ │ │ - span /*body*/); │ │ │ │ │ -called when an extended message is received. If returning true, the message is │ │ │ │ │ -not processed by any other plugin and if false is returned the next plugin in │ │ │ │ │ -the chain will receive it to be able to handle it. This is not called for web │ │ │ │ │ -seeds. thus function may be called more than once per incoming message, but │ │ │ │ │ -only the last of the calls will the body size equal the length. i.e. Every time │ │ │ │ │ -another fragment of the message is received, this function will be called, │ │ │ │ │ -until finally the whole message has been received. The purpose of this is to │ │ │ │ │ -allow early disconnects for invalid messages and for reporting progress of │ │ │ │ │ -receiving large messages. │ │ │ │ │ +***** dht_direct_request() ***** │ │ │ │ │ +void dht_direct_request (udp::endpoint const& ep, entry const& e, client_data_t │ │ │ │ │ +userdata = {}); │ │ │ │ │ +Send an arbitrary DHT request directly to the specified endpoint. This function │ │ │ │ │ +is intended for use by plugins. When a response is received or the request │ │ │ │ │ +times out, a dht_direct_response_alert will be posted with the response (if │ │ │ │ │ +any) and the userdata pointer passed in here. Since this alert is a response to │ │ │ │ │ +an explicit call, it will always be posted, regardless of the alert mask. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** on_unknown_message() ***** │ │ │ │ │ -virtual bool on_unknown_message (int /*length*/, int /*msg*/, │ │ │ │ │ - span /*body*/); │ │ │ │ │ -this is not called for web seeds │ │ │ │ │ +***** add_extension() ***** │ │ │ │ │ +void add_extension (std::shared_ptr ext); │ │ │ │ │ +void add_extension (std::function( │ │ │ │ │ + torrent_handle const&, client_data_t)> ext); │ │ │ │ │ +This function adds an extension to this session. The argument is a function │ │ │ │ │ +object that is called with a torrent_handle and which should return a std:: │ │ │ │ │ +shared_ptr. To write custom plugins, see libtorrent_plugins. │ │ │ │ │ +For the typical bittorrent client all of these extensions should be added. The │ │ │ │ │ +main plugins implemented in libtorrent are: │ │ │ │ │ + uTorrent metadata │ │ │ │ │ + Allows peers to download the metadata (.torrent files) from the swarm │ │ │ │ │ + directly. Makes it possible to join a swarm with just a tracker and info- │ │ │ │ │ + hash. │ │ │ │ │ +#include │ │ │ │ │ +ses.add_extension(<::create_ut_metadata_plugin); │ │ │ │ │ + uTorrent peer exchange │ │ │ │ │ + Exchanges peers between clients. │ │ │ │ │ +#include │ │ │ │ │ +ses.add_extension(<::create_ut_pex_plugin); │ │ │ │ │ + smart ban plugin │ │ │ │ │ + A plugin that, with a small overhead, can ban peers that sends bad data │ │ │ │ │ + with very high accuracy. Should eliminate most problems on poisoned │ │ │ │ │ + torrents. │ │ │ │ │ +#include │ │ │ │ │ +ses.add_extension(<::create_smart_ban_plugin); │ │ │ │ │ [report_issue] │ │ │ │ │ -***** on_piece_pass() on_piece_failed() ***** │ │ │ │ │ -virtual void on_piece_failed (piece_index_t); │ │ │ │ │ -virtual void on_piece_pass (piece_index_t); │ │ │ │ │ -called when a piece that this peer participated in either fails or passes the │ │ │ │ │ -hash_check │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** tick() ***** │ │ │ │ │ -virtual void tick (); │ │ │ │ │ -called approximately once every second │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** write_request() ***** │ │ │ │ │ -virtual bool write_request (peer_request const&); │ │ │ │ │ -called each time a request message is to be sent. If true is returned, the │ │ │ │ │ -original request message won't be sent and no other plugin will have this │ │ │ │ │ -function called. │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** crypto_plugin ****** │ │ │ │ │ -Declared in "libtorrent/extensions.hpp" │ │ │ │ │ -struct crypto_plugin │ │ │ │ │ -{ │ │ │ │ │ - virtual void set_incoming_key (span key) = 0; │ │ │ │ │ - virtual void set_outgoing_key (span key) = 0; │ │ │ │ │ - encrypt (span> /*send_vec*/) = 0; │ │ │ │ │ - virtual std::tuple decrypt (span> /*receive_vec*/ │ │ │ │ │ -) = 0; │ │ │ │ │ -}; │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** decrypt() ***** │ │ │ │ │ -virtual std::tuple decrypt (span> /*receive_vec*/) = │ │ │ │ │ -0; │ │ │ │ │ -decrypt the provided buffers. returns is a tuple representing the values │ │ │ │ │ -(consume, produce, packet_size) │ │ │ │ │ -consume is set to the number of bytes which should be trimmed from the head of │ │ │ │ │ -the buffers, default is 0 │ │ │ │ │ -produce is set to the number of bytes of payload which are now ready to be sent │ │ │ │ │ -to the upper layer. default is the number of bytes passed in receive_vec │ │ │ │ │ -packet_size is set to the minimum number of bytes which must be read to advance │ │ │ │ │ -the next step of decryption. default is 0 │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** create_ut_pex_plugin() ****** │ │ │ │ │ -Declared in "libtorrent/extensions/ut_pex.hpp" │ │ │ │ │ -std::shared_ptr 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(). │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** create_ut_metadata_plugin() ****** │ │ │ │ │ -Declared in "libtorrent/extensions/ut_metadata.hpp" │ │ │ │ │ -std::shared_ptr 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(). │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** create_smart_ban_plugin() ****** │ │ │ │ │ -Declared in "libtorrent/extensions/smart_ban.hpp" │ │ │ │ │ -std::shared_ptr 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(). │ │ │ │ │ -This section describes the functions and classes that are used to create │ │ │ │ │ -torrent files. It is a layered API with low level classes and higher level │ │ │ │ │ -convenience functions. A torrent is created in 4 steps: │ │ │ │ │ - 1. first the files that will be part of the torrent are determined. │ │ │ │ │ - 2. the torrent properties are set, such as tracker url, web seeds, DHT nodes │ │ │ │ │ - etc. │ │ │ │ │ - 3. Read through all the files in the torrent, SHA-1 all the data and set the │ │ │ │ │ - piece hashes. │ │ │ │ │ - 4. The torrent is bencoded into a file or buffer. │ │ │ │ │ -If there are a lot of files and or deep directory hierarchies to traverse, step │ │ │ │ │ -one can be time consuming. │ │ │ │ │ -Typically step 3 is by far the most time consuming step, since it requires to │ │ │ │ │ -read all the bytes from all the files in the torrent. │ │ │ │ │ -All of these classes and functions are declared by including libtorrent/ │ │ │ │ │ -create_torrent.hpp. │ │ │ │ │ -example: │ │ │ │ │ -file_storage fs; │ │ │ │ │ - │ │ │ │ │ -// recursively adds files in directories │ │ │ │ │ -add_files(fs, "./my_torrent"); │ │ │ │ │ - │ │ │ │ │ -create_torrent t(fs); │ │ │ │ │ -t.add_tracker("http://my.tracker.com/announce"); │ │ │ │ │ -t.set_creator("libtorrent example"); │ │ │ │ │ - │ │ │ │ │ -// reads the files and calculates the hashes │ │ │ │ │ -set_piece_hashes(t, "."); │ │ │ │ │ - │ │ │ │ │ -ofstream out("my_torrent.torrent", std::ios_base::binary); │ │ │ │ │ -std::vector buf = t.generate_buf(); │ │ │ │ │ -out.write(buf.data(), buf.size()); │ │ │ │ │ - │ │ │ │ │ -// alternatively, generate an entry and encode it directly to an ostream │ │ │ │ │ -// iterator │ │ │ │ │ -bencode(std::ostream_iterator(out), t.generate()); │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** create_torrent ****** │ │ │ │ │ -Declared in "libtorrent/create_torrent.hpp" │ │ │ │ │ -This class holds state for creating a torrent. After having added all │ │ │ │ │ -information to it, call create_torrent::generate() to generate the torrent. The │ │ │ │ │ -entry that's returned can then be bencoded into a .torrent file using bencode │ │ │ │ │ -(). │ │ │ │ │ -struct create_torrent │ │ │ │ │ -{ │ │ │ │ │ - explicit create_torrent (file_storage& fs, int piece_size = 0 │ │ │ │ │ - , create_flags_t flags = {}); │ │ │ │ │ - explicit create_torrent (torrent_info const& ti); │ │ │ │ │ - entry generate () const; │ │ │ │ │ - std::vector generate_buf () const; │ │ │ │ │ - file_storage const& files () const; │ │ │ │ │ - void set_comment (char const* str); │ │ │ │ │ - void set_creator (char const* str); │ │ │ │ │ - void set_creation_date (std::time_t timestamp); │ │ │ │ │ - void set_hash (piece_index_t index, sha1_hash const& h); │ │ │ │ │ - void set_hash2 (file_index_t file, piece_index_t::diff_type piece, │ │ │ │ │ -sha256_hash const& h); │ │ │ │ │ - void add_url_seed (string_view url); │ │ │ │ │ - void add_http_seed (string_view url); │ │ │ │ │ - void add_node (std::pair node); │ │ │ │ │ - void add_tracker (string_view url, int tier = 0); │ │ │ │ │ - void set_root_cert (string_view cert); │ │ │ │ │ - void set_priv (bool p); │ │ │ │ │ - bool priv () const; │ │ │ │ │ - bool is_v1_only () const; │ │ │ │ │ - bool is_v2_only () const; │ │ │ │ │ - int num_pieces () const; │ │ │ │ │ - piece_index_t end_piece () const; │ │ │ │ │ - index_range piece_range () const noexcept; │ │ │ │ │ - file_index_t end_file () const; │ │ │ │ │ - index_range file_range () const noexcept; │ │ │ │ │ - index_range file_piece_range (file_index_t f); │ │ │ │ │ - std::int64_t total_size () const; │ │ │ │ │ - int piece_length () const; │ │ │ │ │ - int piece_size (piece_index_t i) const; │ │ │ │ │ - void add_collection (string_view c); │ │ │ │ │ - void add_similar_torrent (sha1_hash ih); │ │ │ │ │ - │ │ │ │ │ - static constexpr create_flags_t modification_time = 2_bit; │ │ │ │ │ - static constexpr create_flags_t symlinks = 3_bit; │ │ │ │ │ - static constexpr create_flags_t v2_only = 5_bit; │ │ │ │ │ - static constexpr create_flags_t v1_only = 6_bit; │ │ │ │ │ - static constexpr create_flags_t canonical_files = 7_bit; │ │ │ │ │ - static constexpr create_flags_t no_attributes = 8_bit; │ │ │ │ │ - static constexpr create_flags_t canonical_files_no_tail_padding = 9_bit; │ │ │ │ │ -}; │ │ │ │ │ +***** get_ip_filter() set_ip_filter() ***** │ │ │ │ │ +ip_filter get_ip_filter () const; │ │ │ │ │ +void set_ip_filter (ip_filter f); │ │ │ │ │ +Sets a filter that will be used to reject and accept incoming as well as │ │ │ │ │ +outgoing connections based on their originating ip address. The default filter │ │ │ │ │ +will allow connections to any ip address. To build a set of rules for which │ │ │ │ │ +addresses are accepted and not, see ip_filter. │ │ │ │ │ +Each time a peer is blocked because of the IP filter, a peer_blocked_alert is │ │ │ │ │ +generated. get_ip_filter() Returns the ip_filter currently in the session. See │ │ │ │ │ +ip_filter. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** create_torrent() ***** │ │ │ │ │ -explicit create_torrent (file_storage& fs, int piece_size = 0 │ │ │ │ │ - , create_flags_t flags = {}); │ │ │ │ │ -explicit create_torrent (torrent_info const& ti); │ │ │ │ │ -The piece_size is the size of each piece in bytes. It must be a power of 2 and │ │ │ │ │ -a minimum of 16 kiB. If a piece size of 0 is specified, a piece_size will be │ │ │ │ │ -set automatically. │ │ │ │ │ -The flags arguments specifies options for the torrent creation. It can be any │ │ │ │ │ -combination of the flags defined by create_flags_t. │ │ │ │ │ -The file_storage (fs) parameter defines the files, sizes and their properties │ │ │ │ │ -for the torrent to be created. Set this up first, before passing it to the │ │ │ │ │ -create_torrent constructor. │ │ │ │ │ -The overload that takes a torrent_info object will make a verbatim copy of its │ │ │ │ │ -info dictionary (to preserve the info-hash). The copy of the info dictionary │ │ │ │ │ -will be used by create_torrent::generate(). This means that none of the member │ │ │ │ │ -functions of create_torrent that affects the content of the info dictionary │ │ │ │ │ -(such as set_hash()), will have any affect. Instead of using this overload, │ │ │ │ │ -consider using write_torrent_file() instead. │ │ │ │ │ -Warning │ │ │ │ │ -The file_storage and torrent_info objects must stay alive for the entire │ │ │ │ │ -duration of the create_torrent object. │ │ │ │ │ +***** set_port_filter() ***** │ │ │ │ │ +void set_port_filter (port_filter const& f); │ │ │ │ │ +apply port_filter f to incoming and outgoing peers. a port filter will reject │ │ │ │ │ +making outgoing peer connections to certain remote ports. The main intention is │ │ │ │ │ +to be able to avoid triggering certain anti-virus software by connecting to │ │ │ │ │ +SMTP, FTP ports. │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** ssl_listen_port() is_listening() listen_port() ***** │ │ │ │ │ +unsigned short ssl_listen_port () const; │ │ │ │ │ +unsigned short listen_port () const; │ │ │ │ │ +bool is_listening () const; │ │ │ │ │ +is_listening() will tell you whether or not the session has successfully opened │ │ │ │ │ +a listening port. If it hasn't, this function will return false, and then you │ │ │ │ │ +can set a new settings_pack::listen_interfaces to try another interface and │ │ │ │ │ +port to bind to. │ │ │ │ │ +listen_port() returns the port we ended up listening on. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** generate_buf() generate() ***** │ │ │ │ │ -entry generate () const; │ │ │ │ │ -std::vector generate_buf () const; │ │ │ │ │ -This function will generate the .torrent file as a bencode tree, or a bencoded │ │ │ │ │ -into a buffer. In order to encode the entry into a flat file, use the bencode() │ │ │ │ │ -function. │ │ │ │ │ -The function returning an entry may be useful to add custom entries to the │ │ │ │ │ -torrent file before bencoding it and saving it to disk. │ │ │ │ │ -Whether the resulting torrent object is v1, v2 or hybrid depends on whether any │ │ │ │ │ -of the v1_only or v2_only flags were set on the constructor. If neither were │ │ │ │ │ -set, the resulting torrent depends on which hashes were set. If both v1 and v2 │ │ │ │ │ -hashes were set, a hybrid torrent is created. │ │ │ │ │ -Any failure will cause this function to throw system_error, with an appropriate │ │ │ │ │ -error message. These are the reasons this call may throw: │ │ │ │ │ - * the file storage has 0 files │ │ │ │ │ - * the total size of the file storage is 0 bytes (i.e. it only has empty │ │ │ │ │ - files) │ │ │ │ │ - * not all v1 hashes (set_hash()) and not all v2 hashes (set_hash2()) were │ │ │ │ │ - set │ │ │ │ │ - * for v2 torrents, you may not have a directory with the same name as a │ │ │ │ │ - file. If that's encountered in the file storage, generate() fails. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** files() ***** │ │ │ │ │ -file_storage const& files () const; │ │ │ │ │ -returns an immutable reference to the file_storage used to create the torrent │ │ │ │ │ -from. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** set_comment() ***** │ │ │ │ │ -void set_comment (char const* str); │ │ │ │ │ -Sets the comment for the torrent. The string str should be utf-8 encoded. The │ │ │ │ │ -comment in a torrent file is optional. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** set_creator() ***** │ │ │ │ │ -void set_creator (char const* str); │ │ │ │ │ -Sets the creator of the torrent. The string str should be utf-8 encoded. This │ │ │ │ │ -is optional. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** set_creation_date() ***** │ │ │ │ │ -void set_creation_date (std::time_t timestamp); │ │ │ │ │ -sets the "creation time" field. Defaults to the system clock at the time of │ │ │ │ │ -construction of the create_torrent object. The timestamp is specified in │ │ │ │ │ -seconds, posix time. If the creation date is set to 0, the "creation date" │ │ │ │ │ -field will be omitted from the generated torrent. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** set_hash() ***** │ │ │ │ │ -void set_hash (piece_index_t index, sha1_hash const& h); │ │ │ │ │ -This sets the SHA-1 hash for the specified piece (index). You are required to │ │ │ │ │ -set the hash for every piece in the torrent before generating it. If you have │ │ │ │ │ -the files on disk, you can use the high level convenience function to do this. │ │ │ │ │ -See set_piece_hashes(). A SHA-1 hash of all zeros is internally used to │ │ │ │ │ -indicate a hash that has not been set. Setting such hash will not be considered │ │ │ │ │ -set when calling generate(). This function will throw std::system_error if it │ │ │ │ │ -is called on an object constructed with the v2_only flag. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** set_hash2() ***** │ │ │ │ │ -void set_hash2 (file_index_t file, piece_index_t::diff_type piece, sha256_hash │ │ │ │ │ -const& h); │ │ │ │ │ -sets the bittorrent v2 hash for filefileof the piecepiece.pieceis relative to │ │ │ │ │ -the first piece of the file, starting at 0. The first piece in the file can be │ │ │ │ │ -computed with file_storage::file_index_at_piece(). The hash,h, is the root of │ │ │ │ │ -the merkle tree formed by the piece's 16 kiB blocks. Note that piece sizes must │ │ │ │ │ -be powers-of-2, so all per-piece merkle trees are complete. A SHA-256 hash of │ │ │ │ │ -all zeros is internally used to indicate a hash that has not been set. Setting │ │ │ │ │ -such hash will not be considered set when calling generate(). This function │ │ │ │ │ -will throw std::system_error if it is called on an object constructed with the │ │ │ │ │ -v1_only flag. │ │ │ │ │ +***** get_peer_class_filter() set_peer_class_filter() ***** │ │ │ │ │ +ip_filter get_peer_class_filter () const; │ │ │ │ │ +void set_peer_class_filter (ip_filter const& f); │ │ │ │ │ +Sets the peer class filter for this session. All new peer connections will take │ │ │ │ │ +this into account and be added to the peer classes specified by this filter, │ │ │ │ │ +based on the peer's IP address. │ │ │ │ │ +The ip-filter essentially maps an IP -> uint32. Each bit in that 32 bit integer │ │ │ │ │ +represents a peer class. The least significant bit represents class 0, the next │ │ │ │ │ +bit class 1 and so on. │ │ │ │ │ +For more info, see ip_filter. │ │ │ │ │ +For example, to make all peers in the range 200.1.1.0 - 200.1.255.255 belong to │ │ │ │ │ +their own peer class, apply the following filter: │ │ │ │ │ +ip_filter f = ses.get_peer_class_filter(); │ │ │ │ │ +peer_class_t my_class = ses.create_peer_class("200.1.x.x IP range"); │ │ │ │ │ +f.add_rule(make_address("200.1.1.0"), make_address("200.1.255.255") │ │ │ │ │ + , 1 << static_cast(my_class)); │ │ │ │ │ +ses.set_peer_class_filter(f); │ │ │ │ │ +This setting only applies to new connections, it won't affect existing peer │ │ │ │ │ +connections. │ │ │ │ │ +This function is limited to only peer class 0-31, since there are only 32 bits │ │ │ │ │ +in the IP range mapping. Only the set bits matter; no peer class will be │ │ │ │ │ +removed from a peer as a result of this call, peer classes are only added. │ │ │ │ │ +The peer_class argument cannot be greater than 31. The bitmasks representing │ │ │ │ │ +peer classes in the peer_class_filter are 32 bits. │ │ │ │ │ +The get_peer_class_filter() function returns the current filter. │ │ │ │ │ +For more information, see peer_classes. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** add_url_seed() add_http_seed() ***** │ │ │ │ │ -void add_url_seed (string_view url); │ │ │ │ │ -void add_http_seed (string_view url); │ │ │ │ │ -This adds a url seed to the torrent. You can have any number of url seeds. For │ │ │ │ │ -a single file torrent, this should be an HTTP url, pointing to a file with │ │ │ │ │ -identical content as the file of the torrent. For a multi-file torrent, it │ │ │ │ │ -should point to a directory containing a directory with the same name as this │ │ │ │ │ -torrent, and all the files of the torrent in it. │ │ │ │ │ -The second function, add_http_seed() adds an HTTP seed instead. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** add_node() ***** │ │ │ │ │ -void add_node (std::pair node); │ │ │ │ │ -This adds a DHT node to the torrent. This especially useful if you're creating │ │ │ │ │ -a tracker less torrent. It can be used by clients to bootstrap their DHT node │ │ │ │ │ -from. The node is a hostname and a port number where there is a DHT node │ │ │ │ │ -running. You can have any number of DHT nodes in a torrent. │ │ │ │ │ +***** set_peer_class_type_filter() get_peer_class_type_filter() ***** │ │ │ │ │ +void set_peer_class_type_filter (peer_class_type_filter const& f); │ │ │ │ │ +peer_class_type_filter get_peer_class_type_filter () const; │ │ │ │ │ +Sets and gets the peer class type filter. This is controls automatic peer class │ │ │ │ │ +assignments to peers based on what kind of socket it is. │ │ │ │ │ +It does not only support assigning peer classes, it also supports removing peer │ │ │ │ │ +classes based on socket type. │ │ │ │ │ +The order of these rules being applied are: │ │ │ │ │ + 1. peer-class IP filter │ │ │ │ │ + 2. peer-class type filter, removing classes │ │ │ │ │ + 3. peer-class type filter, adding classes │ │ │ │ │ +For more information, see peer_classes. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** add_tracker() ***** │ │ │ │ │ -void add_tracker (string_view url, int tier = 0); │ │ │ │ │ -Adds a tracker to the torrent. This is not strictly required, but most torrents │ │ │ │ │ -use a tracker as their main source of peers. The url should be an http:// or │ │ │ │ │ -udp:// url to a machine running a bittorrent tracker that accepts announces for │ │ │ │ │ -this torrent's info-hash. The tier is the fallback priority of the tracker. All │ │ │ │ │ -trackers with tier 0 are tried first (in any order). If all fail, trackers with │ │ │ │ │ -tier 1 are tried. If all of those fail, trackers with tier 2 are tried, and so │ │ │ │ │ -on. │ │ │ │ │ +***** create_peer_class() ***** │ │ │ │ │ +peer_class_t create_peer_class (char const* name); │ │ │ │ │ +Creates a new peer class (see peer_classes) with the given name. The returned │ │ │ │ │ +integer is the new peer class identifier. Peer classes may have the same name, │ │ │ │ │ +so each invocation of this function creates a new class and returns a unique │ │ │ │ │ +identifier. │ │ │ │ │ +Identifiers are assigned from low numbers to higher. So if you plan on using │ │ │ │ │ +certain peer classes in a call to set_peer_class_filter(), make sure to create │ │ │ │ │ +those early on, to get low identifiers. │ │ │ │ │ +For more information on peer classes, see peer_classes. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** set_root_cert() ***** │ │ │ │ │ -void set_root_cert (string_view cert); │ │ │ │ │ -This function sets an X.509 certificate in PEM format to the torrent. This │ │ │ │ │ -makes the torrent an SSL torrent. An SSL torrent requires that each peer has a │ │ │ │ │ -valid certificate signed by this root certificate. For SSL torrents, all peers │ │ │ │ │ -are connecting over SSL connections. For more information, see the section on │ │ │ │ │ -ssl_torrents. │ │ │ │ │ -The string is not the path to the cert, it's the actual content of the │ │ │ │ │ -certificate. │ │ │ │ │ +***** delete_peer_class() ***** │ │ │ │ │ +void delete_peer_class (peer_class_t cid); │ │ │ │ │ +This call dereferences the reference count of the specified peer class. When │ │ │ │ │ +creating a peer class it's automatically referenced by 1. If you want to │ │ │ │ │ +recycle a peer class, you may call this function. You may only call this │ │ │ │ │ +function once per peer class you create. Calling it more than once for the same │ │ │ │ │ +class will lead to memory corruption. │ │ │ │ │ +Since peer classes are reference counted, this function will not remove the │ │ │ │ │ +peer class if it's still assigned to torrents or peers. It will however remove │ │ │ │ │ +it once the last peer and torrent drops their references to it. │ │ │ │ │ +There is no need to call this function for custom peer classes. All peer │ │ │ │ │ +classes will be properly destructed when the session object destructs. │ │ │ │ │ +For more information on peer classes, see peer_classes. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** priv() set_priv() ***** │ │ │ │ │ -void set_priv (bool p); │ │ │ │ │ -bool priv () const; │ │ │ │ │ -Sets and queries the private flag of the torrent. Torrents with the private │ │ │ │ │ -flag set ask the client to not use any other sources than the tracker for │ │ │ │ │ -peers, and to not use DHT to advertise itself publicly, only the tracker. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** num_pieces() ***** │ │ │ │ │ -int num_pieces () const; │ │ │ │ │ -returns the number of pieces in the associated file_storage object. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** piece_range() ***** │ │ │ │ │ -index_range piece_range () const noexcept; │ │ │ │ │ -all piece indices in the torrent to be created │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** file_range() ***** │ │ │ │ │ -index_range file_range () const noexcept; │ │ │ │ │ -all file indices in the torrent to be created │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** file_piece_range() ***** │ │ │ │ │ -index_range file_piece_range (file_index_t f); │ │ │ │ │ -for v2 and hybrid torrents only, the pieces in the specified file, specified as │ │ │ │ │ -delta from the first piece in the file. i.e. the first index is 0. │ │ │ │ │ +***** set_peer_class() get_peer_class() ***** │ │ │ │ │ +void set_peer_class (peer_class_t cid, peer_class_info const& pci); │ │ │ │ │ +peer_class_info get_peer_class (peer_class_t cid) const; │ │ │ │ │ +These functions queries information from a peer class and updates the │ │ │ │ │ +configuration of a peer class, respectively. │ │ │ │ │ +cid must refer to an existing peer class. If it does not, the return value of │ │ │ │ │ +get_peer_class() is undefined. │ │ │ │ │ +set_peer_class() sets all the information in the peer_class_info object in the │ │ │ │ │ +specified peer class. There is no option to only update a single property. │ │ │ │ │ +A peer or torrent belonging to more than one class, the highest priority among │ │ │ │ │ +any of its classes is the one that is taken into account. │ │ │ │ │ +For more information, see peer_classes. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** total_size() ***** │ │ │ │ │ -std::int64_t total_size () const; │ │ │ │ │ -the total number of bytes of all files and pad files │ │ │ │ │ +***** remove_torrent() ***** │ │ │ │ │ +void remove_torrent (const torrent_handle&, remove_flags_t = {}); │ │ │ │ │ +remove_torrent() will close all peer connections associated with the torrent │ │ │ │ │ +and tell the tracker that we've stopped participating in the swarm. This │ │ │ │ │ +operation cannot fail. When it completes, you will receive a │ │ │ │ │ +torrent_removed_alert. │ │ │ │ │ +remove_torrent() is non-blocking, but will remove the torrent from the session │ │ │ │ │ +synchronously. Calling session_handle::add_torrent() immediately afterward with │ │ │ │ │ +the same torrent will succeed. Note that this creates a new handle which is not │ │ │ │ │ +equal to the removed one. │ │ │ │ │ +The optional second argument options can be used to delete all the files │ │ │ │ │ +downloaded by this torrent. To do so, pass in the value session_handle:: │ │ │ │ │ +delete_files. Once the torrent is deleted, a torrent_deleted_alert is posted. │ │ │ │ │ +The torrent_handle remains valid for some time after remove_torrent() is │ │ │ │ │ +called. It will become invalid only after all libtorrent tasks (such as I/ │ │ │ │ │ +O tasks) release their references to the torrent. Until this happens, │ │ │ │ │ +torrent_handle::is_valid() will return true, and other calls such as │ │ │ │ │ +torrent_handle::status() will succeed. Because of this, and because │ │ │ │ │ +remove_torrent() is non-blocking, the following sequence usually succeeds (does │ │ │ │ │ +not throw system_error): .. code:: c++ │ │ │ │ │ + session.remove_handle(handle); handle.save_resume_data(); │ │ │ │ │ +Note that when a queued or downloading torrent is removed, its position in the │ │ │ │ │ +download queue is vacated and every subsequent torrent in the queue has their │ │ │ │ │ +queue positions updated. This can potentially cause a large state_update to be │ │ │ │ │ +posted. When removing all torrents, it is advised to remove them from the back │ │ │ │ │ +of the queue, to minimize the shifting. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** piece_size() piece_length() ***** │ │ │ │ │ -int piece_length () const; │ │ │ │ │ -int piece_size (piece_index_t i) const; │ │ │ │ │ -piece_length() returns the piece size of all pieces but the last one. │ │ │ │ │ -piece_size() returns the size of the specified piece. these functions are just │ │ │ │ │ -forwarding to the associated file_storage. │ │ │ │ │ +***** get_settings() apply_settings() ***** │ │ │ │ │ +void apply_settings (settings_pack&&); │ │ │ │ │ +settings_pack get_settings () const; │ │ │ │ │ +void apply_settings (settings_pack const&); │ │ │ │ │ +Applies the settings specified by the settings_pack s. This is an asynchronous │ │ │ │ │ +operation that will return immediately and actually apply the settings to the │ │ │ │ │ +main thread of libtorrent some time later. │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** wait_for_alert() set_alert_notify() pop_alerts() ***** │ │ │ │ │ +alert* wait_for_alert (time_duration max_wait); │ │ │ │ │ +void set_alert_notify (std::function const& fun); │ │ │ │ │ +void pop_alerts (std::vector* alerts); │ │ │ │ │ +Alerts is the main mechanism for libtorrent to report errors and events. │ │ │ │ │ +pop_alerts fills in the vector passed to it with pointers to new alerts. The │ │ │ │ │ +session still owns these alerts and they will stay valid until the next time │ │ │ │ │ +pop_alerts is called. You may not delete the alert objects. │ │ │ │ │ +It is safe to call pop_alerts from multiple different threads, as long as the │ │ │ │ │ +alerts themselves are not accessed once another thread calls pop_alerts. Doing │ │ │ │ │ +this requires manual synchronization between the popping threads. │ │ │ │ │ +wait_for_alert will block the current thread for max_wait time duration, or │ │ │ │ │ +until another alert is posted. If an alert is available at the time of the │ │ │ │ │ +call, it returns immediately. The returned alert pointer is the head of the │ │ │ │ │ +alert queue. wait_for_alert does not pop alerts from the queue, it merely peeks │ │ │ │ │ +at it. The returned alert will stay valid until pop_alerts is called twice. The │ │ │ │ │ +first time will pop it and the second will free it. │ │ │ │ │ +If there is no alert in the queue and no alert arrives within the specified │ │ │ │ │ +timeout, wait_for_alert returns nullptr. │ │ │ │ │ +In the python binding, wait_for_alert takes the number of milliseconds to wait │ │ │ │ │ +as an integer. │ │ │ │ │ +The alert queue in the session will not grow indefinitely. Make sure to pop │ │ │ │ │ +periodically to not miss notifications. To control the max number of alerts │ │ │ │ │ +that's queued by the session, see settings_pack::alert_queue_size. │ │ │ │ │ +Some alerts are considered so important that they are posted even when the │ │ │ │ │ +alert queue is full. Some alerts are considered mandatory and cannot be │ │ │ │ │ +disabled by the alert_mask. For instance, save_resume_data_alert and │ │ │ │ │ +save_resume_data_failed_alert are always posted, regardless of the alert mask. │ │ │ │ │ +To control which alerts are posted, set the alert_mask (settings_pack:: │ │ │ │ │ +alert_mask). │ │ │ │ │ +If the alert queue fills up to the point where alerts are dropped, this will be │ │ │ │ │ +indicated by a alerts_dropped_alert, which contains a bitmask of which types of │ │ │ │ │ +alerts were dropped. Generally it is a good idea to make sure the alert queue │ │ │ │ │ +is large enough, the alert_mask doesn't have unnecessary categories enabled and │ │ │ │ │ +to call pop_alert() frequently, to avoid alerts being dropped. │ │ │ │ │ +the set_alert_notify function lets the client set a function object to be │ │ │ │ │ +invoked every time the alert queue goes from having 0 alerts to 1 alert. This │ │ │ │ │ +function is called from within libtorrent, it may be the main thread, or it may │ │ │ │ │ +be from within a user call. The intention of of the function is that the client │ │ │ │ │ +wakes up its main thread, to poll for more alerts using pop_alerts(). If the │ │ │ │ │ +notify function fails to do so, it won't be called again, until pop_alerts is │ │ │ │ │ +called for some other reason. For instance, it could signal an eventfd, post a │ │ │ │ │ +message to an HWND or some other main message pump. The actual retrieval of │ │ │ │ │ +alerts should not be done in the callback. In fact, the callback should not │ │ │ │ │ +block. It should not perform any expensive work. It really should just notify │ │ │ │ │ +the main application thread. │ │ │ │ │ +The type of an alert is returned by the polymorphic function alert::type() but │ │ │ │ │ +can also be queries from a concrete type via T::alert_type, as a static │ │ │ │ │ +constant. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** add_similar_torrent() add_collection() ***** │ │ │ │ │ -void add_collection (string_view c); │ │ │ │ │ -void add_similar_torrent (sha1_hash ih); │ │ │ │ │ -Add similar torrents (by info-hash) or collections of similar torrents. Similar │ │ │ │ │ -torrents are expected to share some files with this torrent. Torrents sharing a │ │ │ │ │ -collection name with this torrent are also expected to share files with this │ │ │ │ │ -torrent. A torrent may have more than one collection and more than one similar │ │ │ │ │ -torrents. For more information, see BEP_38. │ │ │ │ │ +***** add_port_mapping() delete_port_mapping() ***** │ │ │ │ │ +void delete_port_mapping (port_mapping_t handle); │ │ │ │ │ +std::vector add_port_mapping (portmap_protocol t, int │ │ │ │ │ +external_port, int local_port); │ │ │ │ │ +add_port_mapping adds one or more port forwards on UPnP and/or NAT-PMP, │ │ │ │ │ +whichever is enabled. A mapping is created for each listen socket in the │ │ │ │ │ +session. The return values are all handles referring to the port mappings that │ │ │ │ │ +were just created. Pass them to delete_port_mapping() to remove them. │ │ │ │ │ [report_issue] │ │ │ │ │ - modification_time │ │ │ │ │ - This will include the file modification time as part of the torrent. This │ │ │ │ │ - is not enabled by default, as it might cause problems when you create a │ │ │ │ │ - torrent from separate files with the same content, hoping to yield the │ │ │ │ │ - same info-hash. If the files have different modification times, with this │ │ │ │ │ - option enabled, you would get different info-hashes for the files. │ │ │ │ │ +***** reopen_network_sockets() ***** │ │ │ │ │ +void reopen_network_sockets (reopen_network_flags_t options = │ │ │ │ │ +reopen_map_ports); │ │ │ │ │ +Instructs the session to reopen all listen and outgoing sockets. │ │ │ │ │ +It's useful in the case your platform doesn't support the built in IP notifier │ │ │ │ │ +mechanism, or if you have a better more reliable way to detect changes in the │ │ │ │ │ +IP routing table. │ │ │ │ │ [report_issue] │ │ │ │ │ - symlinks │ │ │ │ │ - If this flag is set, files that are symlinks get a symlink attribute set │ │ │ │ │ - on them and their data will not be included in the torrent. This is │ │ │ │ │ - useful if you need to reconstruct a file hierarchy which contains │ │ │ │ │ - symlinks. │ │ │ │ │ +***** native_handle() ***** │ │ │ │ │ +std::shared_ptr native_handle () const; │ │ │ │ │ +This function is intended only for use by plugins. This type does not have a │ │ │ │ │ +stable API and should be relied on as little as possible. │ │ │ │ │ [report_issue] │ │ │ │ │ - v2_only │ │ │ │ │ - Do not generate v1 metadata. The resulting torrent will only be usable by │ │ │ │ │ - clients which support v2. This requires setting all v2 hashes, with │ │ │ │ │ - set_hash2() before calling generate(). Setting v1 hashes (with set_hash │ │ │ │ │ - ()) is an error with this flag set. │ │ │ │ │ + save_settings │ │ │ │ │ + saves settings (i.e. the settings_pack) │ │ │ │ │ [report_issue] │ │ │ │ │ - v1_only │ │ │ │ │ - do not generate v2 metadata or enforce v2 alignment and padding rules │ │ │ │ │ - this is mainly for tests, not recommended for production use. This │ │ │ │ │ - requires setting all v1 hashes, with set_hash(), before calling generate │ │ │ │ │ - (). Setting v2 hashes (with set_hash2()) is an error with this flag set. │ │ │ │ │ + save_dht_state │ │ │ │ │ + saves dht state such as nodes and node-id, possibly accelerating joining │ │ │ │ │ + the DHT if provided at next session startup. │ │ │ │ │ [report_issue] │ │ │ │ │ - canonical_files │ │ │ │ │ - This flag only affects v1-only torrents, and is only relevant together │ │ │ │ │ - with the v1_only_flag. This flag will force the same file order and │ │ │ │ │ - padding as a v2 (or hybrid) torrent would have. It has the effect of │ │ │ │ │ - ordering files and inserting pad files to align them with piece │ │ │ │ │ - boundaries. │ │ │ │ │ + save_extension_state │ │ │ │ │ + load or save state from plugins │ │ │ │ │ [report_issue] │ │ │ │ │ - no_attributes │ │ │ │ │ - passing this flag to add_files() will ignore file attributes (such as │ │ │ │ │ - executable or hidden) when adding the files to the file storage. Since │ │ │ │ │ - not all filesystems and operating systems support all file attributes the │ │ │ │ │ - resulting torrent may differ depending on where it's created. If it's │ │ │ │ │ - important for torrents to be created consistently across systems, this │ │ │ │ │ - flag should be set. │ │ │ │ │ + save_ip_filter │ │ │ │ │ + load or save the IP filter set on the session │ │ │ │ │ + [report_issue] │ │ │ │ │ + global_peer_class_id tcp_peer_class_id local_peer_class_id │ │ │ │ │ + built-in peer classes │ │ │ │ │ [report_issue] │ │ │ │ │ - canonical_files_no_tail_padding │ │ │ │ │ - this flag enforces the file layout to be canonical according to the │ │ │ │ │ - bittorrent v2 specification (just like the canonical_files flag) with the │ │ │ │ │ - one exception that tail padding is not added to the last file. This │ │ │ │ │ - behavior deviates from the specification but was the way libtorrent │ │ │ │ │ - created torrents in version up to and including 2.0.7. This flag is here │ │ │ │ │ - for backwards compatibility. │ │ │ │ │ + delete_files │ │ │ │ │ + delete the files belonging to the torrent from disk. including the part- │ │ │ │ │ + file, if there is one │ │ │ │ │ [report_issue] │ │ │ │ │ -****** add_files() ****** │ │ │ │ │ -Declared in "libtorrent/create_torrent.hpp" │ │ │ │ │ -void add_files (file_storage& fs, std::string const& file │ │ │ │ │ - , create_flags_t flags = {}); │ │ │ │ │ -void add_files (file_storage& fs, std::string const& file │ │ │ │ │ - , std::function p, create_flags_t flags = {}); │ │ │ │ │ -Adds the file specified by path to the file_storage object. In case path refers │ │ │ │ │ -to a directory, files will be added recursively from the directory. │ │ │ │ │ -If specified, the predicate p is called once for every file and directory that │ │ │ │ │ -is encountered. Files for which p returns true are added, and directories for │ │ │ │ │ -which p returns true are traversed. p must have the following signature: │ │ │ │ │ -bool Pred(std::string const& p); │ │ │ │ │ -The path that is passed in to the predicate is the full path of the file or │ │ │ │ │ -directory. If no predicate is specified, all files are added, and all │ │ │ │ │ -directories are traversed. │ │ │ │ │ -The ".." directory is never traversed. │ │ │ │ │ -The flags argument should be the same as the flags passed to the create_torrent │ │ │ │ │ -constructor. │ │ │ │ │ + delete_partfile │ │ │ │ │ + delete just the part-file associated with this torrent │ │ │ │ │ [report_issue] │ │ │ │ │ -****** set_piece_hashes() ****** │ │ │ │ │ -Declared in "libtorrent/create_torrent.hpp" │ │ │ │ │ -inline void set_piece_hashes (create_torrent& t, std::string const& p); │ │ │ │ │ -void set_piece_hashes (create_torrent& t, std::string const& p │ │ │ │ │ - , settings_interface const& settings │ │ │ │ │ - , std::function const& f, error_code& ec); │ │ │ │ │ -inline void set_piece_hashes (create_torrent& t, std::string const& p │ │ │ │ │ - , settings_interface const& settings │ │ │ │ │ - , std::function const& f); │ │ │ │ │ -void set_piece_hashes (create_torrent& t, std::string const& p │ │ │ │ │ - , settings_interface const& settings, disk_io_constructor_type disk_io │ │ │ │ │ - , std::function const& f, error_code& ec); │ │ │ │ │ -void set_piece_hashes (create_torrent& t, std::string const& p │ │ │ │ │ - , std::function const& f, error_code& ec); │ │ │ │ │ -inline void set_piece_hashes (create_torrent& t, std::string const& p, │ │ │ │ │ -error_code& ec); │ │ │ │ │ -inline void set_piece_hashes (create_torrent& t, std::string const& p │ │ │ │ │ - , std::function const& f); │ │ │ │ │ -This function will assume that the files added to the torrent file exists at │ │ │ │ │ -path p, read those files and hash the content and set the hashes in the │ │ │ │ │ -create_torrent object. The optional function f is called in between every hash │ │ │ │ │ -that is set. f must have the following signature: │ │ │ │ │ -void Fun(piece_index_t); │ │ │ │ │ -The overloads taking a settings_pack may be used to configure the underlying │ │ │ │ │ -disk access. Such as settings_pack::aio_threads. │ │ │ │ │ -The overloads that don't take an error_code& may throw an exception in case of │ │ │ │ │ -a file error, the other overloads sets the error code to reflect the error, if │ │ │ │ │ -any. │ │ │ │ │ + paused │ │ │ │ │ + when set, the session will start paused. Call session_handle::resume() to │ │ │ │ │ + start │ │ │ │ │ + [report_issue] │ │ │ │ │ + udp tcp │ │ │ │ │ + protocols used by add_port_mapping() │ │ │ │ │ [report_issue] │ │ │ │ │ -****** 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; │ │ │ │ │ -}; │ │ │ │ │ + reopen_map_ports │ │ │ │ │ + This option indicates if the ports are mapped using natpmp and upnp. If │ │ │ │ │ + mapping was already made, they are deleted and added again. This only │ │ │ │ │ + works if natpmp and/or upnp are configured to be enable. │ │ │ │ │ + [report_issue] │ │ │ │ │ +****** write_session_params() write_session_params_buf() read_session_params() │ │ │ │ │ +****** │ │ │ │ │ +Declared in "libtorrent/session_params.hpp" │ │ │ │ │ +std::vector write_session_params_buf (session_params const& sp │ │ │ │ │ + , save_state_flags_t flags = save_state_flags_t::all()); │ │ │ │ │ +entry write_session_params (session_params const& sp │ │ │ │ │ + , save_state_flags_t flags = save_state_flags_t::all()); │ │ │ │ │ +session_params read_session_params (span buf │ │ │ │ │ + , save_state_flags_t flags = save_state_flags_t::all()); │ │ │ │ │ +session_params read_session_params (bdecode_node const& e │ │ │ │ │ + , save_state_flags_t flags = save_state_flags_t::all()); │ │ │ │ │ +These functions serialize and de-serialize a session_params object to and from │ │ │ │ │ +bencoded form. The session_params object is used to initialize a new session │ │ │ │ │ +using the state from a previous one (or by programmatically configure the │ │ │ │ │ +session up-front). The flags parameter can be used to only save and load │ │ │ │ │ +certain aspects of the session's state. The _buf suffix indicates the function │ │ │ │ │ +operates on buffer rather than the bencoded structure. The torrents in a │ │ │ │ │ +session are not part of the session_params state, they have to be restored │ │ │ │ │ +separately. │ │ │ │ │ [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; │ │ │ │ │ + info_hash_t (sha1_hash h1, sha256_hash h2) noexcept; │ │ │ │ │ explicit info_hash_t (sha1_hash h1) noexcept; │ │ │ │ │ + explicit info_hash_t (sha256_hash h2) noexcept; │ │ │ │ │ info_hash_t () noexcept = default; │ │ │ │ │ - info_hash_t (sha1_hash h1, sha256_hash h2) noexcept; │ │ │ │ │ - bool has_v2 () const; │ │ │ │ │ - bool has_v1 () const; │ │ │ │ │ bool has (protocol_version v) const; │ │ │ │ │ + bool has_v1 () 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 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] │ │ │ │ │ ***** 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; │ │ │ │ │ +explicit info_hash_t (sha256_hash h2) 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() has_v2() has_v1() ***** │ │ │ │ │ -bool has_v2 () const; │ │ │ │ │ -bool has_v1 () const; │ │ │ │ │ +***** has() has_v1() has_v2() ***** │ │ │ │ │ bool has (protocol_version v) const; │ │ │ │ │ +bool has_v1 () 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() ***** │ │ │ │ │ @@ -3663,14 +1861,29 @@ │ │ │ │ │ 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 (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; │ │ │ │ │ +}; │ │ │ │ │ +[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; │ │ │ │ │ @@ -3689,20 +1902,49 @@ │ │ │ │ │ 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] │ │ │ │ │ +****** load_torrent_file() load_torrent_parsed() load_torrent_buffer() ****** │ │ │ │ │ +Declared in "libtorrent/load_torrent.hpp" │ │ │ │ │ +add_torrent_params load_torrent_buffer ( │ │ │ │ │ + span buffer, 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_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 buffer); │ │ │ │ │ +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] │ │ │ │ │ +****** 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] │ │ │ │ │ ****** 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); │ │ │ │ │ +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 │ │ │ │ │ @@ -3717,76 +1959,55 @@ │ │ │ │ │ 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, 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); │ │ │ │ │ +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] │ │ │ │ │ -****** load_torrent_buffer() load_torrent_parsed() load_torrent_file() ****** │ │ │ │ │ -Declared in "libtorrent/load_torrent.hpp" │ │ │ │ │ -add_torrent_params load_torrent_buffer ( │ │ │ │ │ - span buffer); │ │ │ │ │ -add_torrent_params load_torrent_buffer ( │ │ │ │ │ - span buffer, 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_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_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: │ │ │ │ │ "..." │ │ │ │ │ [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 connection_type ****** │ │ │ │ │ -Declared in "libtorrent/peer_connection.hpp" │ │ │ │ │ - ____________________________ │ │ │ │ │ -|name______|value|description| │ │ │ │ │ -|bittorrent|0____| _________| │ │ │ │ │ -|url_seed__|1____| _________| │ │ │ │ │ -|http_seed_|2____| _________| │ │ │ │ │ +****** 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] │ │ │ │ │ ****** 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 connection_type ****** │ │ │ │ │ +Declared in "libtorrent/peer_connection.hpp" │ │ │ │ │ + ____________________________ │ │ │ │ │ +|name______|value|description| │ │ │ │ │ +|bittorrent|0____| _________| │ │ │ │ │ +|url_seed__|1____| _________| │ │ │ │ │ +|http_seed_|2____| _________| │ │ │ │ │ +[report_issue] │ │ │ │ │ ****** enum socket_type_t ****** │ │ │ │ │ Declared in "libtorrent/socket_type.hpp" │ │ │ │ │ ____________________________ │ │ │ │ │ |name______|value|description| │ │ │ │ │ |tcp_______|0____| _________| │ │ │ │ │ |socks5____|1____| _________| │ │ │ │ │ |http______|2____| _________| │ │ │ │ │ @@ -3808,34 +2029,50 @@ │ │ │ │ │ Declared in "libtorrent/portmap.hpp" │ │ │ │ │ ______________________ │ │ │ │ │ |name|value|description| │ │ │ │ │ |none|0____| _________| │ │ │ │ │ |tcp_|1____| _________| │ │ │ │ │ |udp_|2____| _________| │ │ │ │ │ [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] │ │ │ │ │ ****** 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. │ │ │ │ │ [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] │ │ │ │ │ +****** 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] │ │ │ │ │ ****** 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, │ │ │ │ │ @@ -3994,624 +2231,1221 @@ │ │ │ │ │ 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). │ │ │ │ │ all │ │ │ │ │ all torrent flags combined. Can conveniently be used when creating masks │ │ │ │ │ for flags │ │ │ │ │ [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 │ │ │ │ │ +****** 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 ti; │ │ │ │ │ + aux::noexcept_movable> trackers; │ │ │ │ │ + aux::noexcept_movable> tracker_tiers; │ │ │ │ │ + aux::noexcept_movable>> dht_nodes; │ │ │ │ │ + std::string name; │ │ │ │ │ + std::string save_path; │ │ │ │ │ + storage_mode_t storage_mode = storage_mode_sparse; │ │ │ │ │ + client_data_t userdata; │ │ │ │ │ + aux::noexcept_movable> 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> http_seeds; │ │ │ │ │ + aux::noexcept_movable> url_seeds; │ │ │ │ │ + aux::noexcept_movable> peers; │ │ │ │ │ + aux::noexcept_movable> banned_peers; │ │ │ │ │ + aux::noexcept_movable> unfinished_pieces; │ │ │ │ │ + typed_bitfield have_pieces; │ │ │ │ │ + typed_bitfield verified_pieces; │ │ │ │ │ + aux::noexcept_movable> piece_priorities; │ │ │ │ │ + aux::vector, file_index_t> merkle_trees; │ │ │ │ │ + aux::vector, file_index_t> merkle_tree_mask; │ │ │ │ │ + aux::vector, file_index_t> verified_leaf_hashes; │ │ │ │ │ + aux::noexcept_movable> renamed_files; │ │ │ │ │ + std::time_t last_download = 0; │ │ │ │ │ + std::time_t last_upload = 0; │ │ │ │ │ +}; │ │ │ │ │ [report_issue] │ │ │ │ │ -****** ip_filter ****** │ │ │ │ │ -Declared in "libtorrent/ip_filter.hpp" │ │ │ │ │ -The ip_filter class is a set of rules that uniquely categorizes all ip │ │ │ │ │ -addresses as allowed or disallowed. The default constructor creates a single │ │ │ │ │ -rule that allows all addresses (0.0.0.0 - 255.255.255.255 for the IPv4 range, │ │ │ │ │ -and the equivalent range covering all addresses for the IPv6 range). │ │ │ │ │ -A default constructed ip_filter does not filter any address. │ │ │ │ │ -struct ip_filter │ │ │ │ │ + version │ │ │ │ │ + filled in by the constructor and should be left untouched. It is used for │ │ │ │ │ + forward binary compatibility. │ │ │ │ │ +[report_issue] │ │ │ │ │ + ti │ │ │ │ │ + torrent_info object with the torrent to add. Unless the info_hash is set, │ │ │ │ │ + this is required to be initialized. │ │ │ │ │ +[report_issue] │ │ │ │ │ + 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. │ │ │ │ │ +[report_issue] │ │ │ │ │ + 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. │ │ │ │ │ +[report_issue] │ │ │ │ │ + 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. │ │ │ │ │ +[report_issue] │ │ │ │ │ + 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. │ │ │ │ │ +[report_issue] │ │ │ │ │ + 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. │ │ │ │ │ +[report_issue] │ │ │ │ │ + storage_mode │ │ │ │ │ + One of the values from storage_mode_t. For more information, see storage │ │ │ │ │ + allocation. │ │ │ │ │ +[report_issue] │ │ │ │ │ + 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(). │ │ │ │ │ +[report_issue] │ │ │ │ │ + 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. │ │ │ │ │ +[report_issue] │ │ │ │ │ + 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. │ │ │ │ │ +[report_issue] │ │ │ │ │ + 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. │ │ │ │ │ +[report_issue] │ │ │ │ │ + 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. │ │ │ │ │ + [report_issue] │ │ │ │ │ + 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. │ │ │ │ │ + [report_issue] │ │ │ │ │ + upload_limit download_limit │ │ │ │ │ + the upload and download rate limits for this torrent, specified in bytes │ │ │ │ │ + per second. -1 means unlimited. │ │ │ │ │ + [report_issue] │ │ │ │ │ + total_uploaded total_downloaded │ │ │ │ │ + the total number of bytes uploaded and downloaded by this torrent so far. │ │ │ │ │ + [report_issue] │ │ │ │ │ + active_time finished_time seeding_time │ │ │ │ │ + the number of seconds this torrent has spent in started, finished and │ │ │ │ │ + seeding state so far, respectively. │ │ │ │ │ + [report_issue] │ │ │ │ │ + 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. │ │ │ │ │ +[report_issue] │ │ │ │ │ + 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. │ │ │ │ │ + [report_issue] │ │ │ │ │ + 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. │ │ │ │ │ + [report_issue] │ │ │ │ │ + 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. │ │ │ │ │ +[report_issue] │ │ │ │ │ + peers │ │ │ │ │ + peers to add to the torrent, to be tried to be connected to as bittorrent │ │ │ │ │ + peers. │ │ │ │ │ +[report_issue] │ │ │ │ │ + banned_peers │ │ │ │ │ + peers banned from this torrent. The will not be connected to │ │ │ │ │ +[report_issue] │ │ │ │ │ + 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. │ │ │ │ │ +[report_issue] │ │ │ │ │ + have_pieces │ │ │ │ │ + this is a bitfield indicating which pieces we already have of this │ │ │ │ │ + torrent. │ │ │ │ │ +[report_issue] │ │ │ │ │ + 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. │ │ │ │ │ +[report_issue] │ │ │ │ │ + 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. │ │ │ │ │ +[report_issue] │ │ │ │ │ + merkle_trees │ │ │ │ │ + v2 hashes, if known │ │ │ │ │ +[report_issue] │ │ │ │ │ + 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. │ │ │ │ │ +[report_issue] │ │ │ │ │ + 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. │ │ │ │ │ +[report_issue] │ │ │ │ │ + renamed_files │ │ │ │ │ + this is a map of file indices in the torrent and new filenames to be │ │ │ │ │ + applied before the torrent is added. │ │ │ │ │ + [report_issue] │ │ │ │ │ + last_download last_upload │ │ │ │ │ + the posix time of the last time payload was received or sent for this │ │ │ │ │ + torrent, respectively. │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** 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 │ │ │ │ │ { │ │ │ │ │ - ip_filter (); │ │ │ │ │ - ip_filter (ip_filter&&); │ │ │ │ │ - ip_filter& operator= (ip_filter const&); │ │ │ │ │ - ip_filter& operator= (ip_filter&&); │ │ │ │ │ - ip_filter (ip_filter const&); │ │ │ │ │ - ~ip_filter (); │ │ │ │ │ - bool empty () const; │ │ │ │ │ - void add_rule (address const& first, address const& last, std::uint32_t │ │ │ │ │ -flags); │ │ │ │ │ - std::uint32_t access (address const& addr) const; │ │ │ │ │ - filter_tuple_t export_filter () const; │ │ │ │ │ + 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*) = delete; │ │ │ │ │ + operator void const* () const = delete; │ │ │ │ │ + client_data_t& operator= (void const*) = delete; │ │ │ │ │ + operator void* () const = delete; │ │ │ │ │ │ │ │ │ │ - enum access_flags │ │ │ │ │ - { │ │ │ │ │ - blocked, │ │ │ │ │ - }; │ │ │ │ │ + template ::value>::type> │ │ │ │ │ }; │ │ │ │ │ [report_issue] │ │ │ │ │ -***** empty() ***** │ │ │ │ │ -bool empty () const; │ │ │ │ │ -returns true if the filter does not contain any rules │ │ │ │ │ +***** client_data_t() ***** │ │ │ │ │ +client_data_t () = default; │ │ │ │ │ +construct a nullptr client data │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** const*() void*() operator=() ***** │ │ │ │ │ +client_data_t& operator= (void*) = delete; │ │ │ │ │ +operator void const* () const = delete; │ │ │ │ │ +client_data_t& operator= (void const*) = delete; │ │ │ │ │ +operator void* () const = delete; │ │ │ │ │ +we don't allow type-unsafe operations │ │ │ │ │ +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: │ │ │ │ │ [report_issue] │ │ │ │ │ -***** add_rule() ***** │ │ │ │ │ -void add_rule (address const& first, address const& last, std::uint32_t flags); │ │ │ │ │ -Adds a rule to the filter. first and last defines a range of ip addresses that │ │ │ │ │ -will be marked with the given flags. The flags can currently be 0, which means │ │ │ │ │ -allowed, or ip_filter::blocked, which means disallowed. │ │ │ │ │ -precondition: first.is_v4() == last.is_v4() && first.is_v6() == last.is_v6() │ │ │ │ │ -postcondition: access(x) == flags for every x in the range [first, last] │ │ │ │ │ -This means that in a case of overlapping ranges, the last one applied takes │ │ │ │ │ -precedence. │ │ │ │ │ +****** 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; │ │ │ │ │ +}; │ │ │ │ │ [report_issue] │ │ │ │ │ -***** access() ***** │ │ │ │ │ -std::uint32_t access (address const& addr) const; │ │ │ │ │ -Returns the access permissions for the given address (addr). The permission can │ │ │ │ │ -currently be 0 or ip_filter::blocked. The complexity of this operation is O(log │ │ │ │ │ -n), where n is the minimum number of non-overlapping ranges to describe the │ │ │ │ │ -current filter. │ │ │ │ │ + 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. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** export_filter() ***** │ │ │ │ │ -filter_tuple_t export_filter () const; │ │ │ │ │ -This function will return the current state of the filter in the minimum number │ │ │ │ │ -of ranges possible. They are sorted from ranges in low addresses to high │ │ │ │ │ -addresses. Each entry in the returned vector is a range with the access control │ │ │ │ │ -specified in its flags field. │ │ │ │ │ -The return value is a tuple containing two range-lists. One for IPv4 addresses │ │ │ │ │ -and one for IPv6 addresses. │ │ │ │ │ + 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. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** enum access_flags ***** │ │ │ │ │ -Declared in "libtorrent/ip_filter.hpp" │ │ │ │ │ - _____________________________________________________________________________ │ │ │ │ │ -|name___|value|description____________________________________________________| │ │ │ │ │ -|blocked|1 |indicates that IPs in this range should not be connected to nor| │ │ │ │ │ -|_______|_____|accepted_as_incoming_connections_______________________________| │ │ │ │ │ + last_use │ │ │ │ │ + a (high precision) timestamp of when the file was last used. │ │ │ │ │ [report_issue] │ │ │ │ │ -****** port_filter ****** │ │ │ │ │ -Declared in "libtorrent/ip_filter.hpp" │ │ │ │ │ -the port filter maps non-overlapping port ranges to flags. This is primarily │ │ │ │ │ -used to indicate whether a range of ports should be connected to or not. The │ │ │ │ │ -default is to have the full port range (0-65535) set to flag 0. │ │ │ │ │ -class port_filter │ │ │ │ │ +****** 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 │ │ │ │ │ { │ │ │ │ │ - port_filter (); │ │ │ │ │ - port_filter (port_filter const&); │ │ │ │ │ - port_filter& operator= (port_filter&&); │ │ │ │ │ - port_filter (port_filter&&); │ │ │ │ │ - ~port_filter (); │ │ │ │ │ - port_filter& operator= (port_filter const&); │ │ │ │ │ - void add_rule (std::uint16_t first, std::uint16_t last, std::uint32_t │ │ │ │ │ -flags); │ │ │ │ │ - std::uint32_t access (std::uint16_t port) const; │ │ │ │ │ + virtual storage_holder new_torrent (storage_params const& p │ │ │ │ │ + , std::shared_ptr const& torrent) = 0; │ │ │ │ │ + virtual void remove_torrent (storage_index_t) = 0; │ │ │ │ │ + virtual bool async_write (storage_index_t storage, peer_request const& r │ │ │ │ │ + , char const* buf, std::shared_ptr o │ │ │ │ │ + , std::function handler │ │ │ │ │ + , disk_job_flags_t flags = {}) = 0; │ │ │ │ │ + virtual void async_read (storage_index_t storage, peer_request const& r │ │ │ │ │ + , std::function handler │ │ │ │ │ + , disk_job_flags_t flags = {}) = 0; │ │ │ │ │ + virtual void async_hash (storage_index_t storage, piece_index_t piece, │ │ │ │ │ +span v2 │ │ │ │ │ + , disk_job_flags_t flags │ │ │ │ │ + , std::function handler) = 0; │ │ │ │ │ + virtual void async_hash2 (storage_index_t storage, piece_index_t piece, int │ │ │ │ │ +offset, disk_job_flags_t flags │ │ │ │ │ + , std::function handler) = 0; │ │ │ │ │ + virtual void async_move_storage (storage_index_t storage, std::string p, │ │ │ │ │ +move_flags_t flags │ │ │ │ │ + , std::function │ │ │ │ │ +handler) = 0; │ │ │ │ │ + virtual void async_release_files (storage_index_t storage │ │ │ │ │ + , std::function handler = std::function()) = 0; │ │ │ │ │ + virtual void async_check_files (storage_index_t storage │ │ │ │ │ + , add_torrent_params const* resume_data │ │ │ │ │ + , aux::vector links │ │ │ │ │ + , std::function handler) = 0; │ │ │ │ │ + virtual void async_stop_torrent (storage_index_t storage │ │ │ │ │ + , std::function handler = std::function()) = 0; │ │ │ │ │ + virtual void async_rename_file (storage_index_t storage │ │ │ │ │ + , file_index_t index, std::string name │ │ │ │ │ + , std::function handler) = 0; │ │ │ │ │ + virtual void async_delete_files (storage_index_t storage, remove_flags_t │ │ │ │ │ +options │ │ │ │ │ + , std::function handler) = 0; │ │ │ │ │ + virtual void async_set_file_priority (storage_index_t storage │ │ │ │ │ + , aux::vector prio │ │ │ │ │ + , std::function)> handler) = 0; │ │ │ │ │ + virtual void async_clear_piece (storage_index_t storage, piece_index_t index │ │ │ │ │ + , std::function handler) = 0; │ │ │ │ │ + virtual void update_stats_counters (counters& c) const = 0; │ │ │ │ │ + virtual std::vector get_status (storage_index_t) const = 0; │ │ │ │ │ + virtual void abort (bool wait) = 0; │ │ │ │ │ + virtual void submit_jobs () = 0; │ │ │ │ │ + virtual void settings_updated () = 0; │ │ │ │ │ │ │ │ │ │ - enum access_flags │ │ │ │ │ - { │ │ │ │ │ - blocked, │ │ │ │ │ - }; │ │ │ │ │ + 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; │ │ │ │ │ }; │ │ │ │ │ [report_issue] │ │ │ │ │ -***** add_rule() ***** │ │ │ │ │ -void add_rule (std::uint16_t first, std::uint16_t last, std::uint32_t flags); │ │ │ │ │ -set the flags for the specified port range (first, last) to flags overwriting │ │ │ │ │ -any existing rule for those ports. The range is inclusive, i.e. the port last │ │ │ │ │ -also has the flag set on it. │ │ │ │ │ +***** new_torrent() ***** │ │ │ │ │ +virtual storage_holder new_torrent (storage_params const& p │ │ │ │ │ + , std::shared_ptr const& torrent) = 0; │ │ │ │ │ +this is called when a new torrent is added. The shared_ptr can be used to hold │ │ │ │ │ +the internal torrent object alive as long as there are outstanding disk │ │ │ │ │ +operations on the storage. The returned storage_holder is an owning reference │ │ │ │ │ +to the underlying storage that was just created. It is fundamentally a │ │ │ │ │ +storage_index_t │ │ │ │ │ [report_issue] │ │ │ │ │ -***** access() ***** │ │ │ │ │ -std::uint32_t access (std::uint16_t port) const; │ │ │ │ │ -test the specified port (port) for whether it is blocked or not. The returned │ │ │ │ │ -value is the flags set for this port. see access_flags. │ │ │ │ │ +***** remove_torrent() ***** │ │ │ │ │ +virtual void remove_torrent (storage_index_t) = 0; │ │ │ │ │ +remove the storage with the specified index. This is not expected to delete any │ │ │ │ │ +files from disk, just to clean up any resources associated with the specified │ │ │ │ │ +storage. │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** async_write() async_read() ***** │ │ │ │ │ +virtual bool async_write (storage_index_t storage, peer_request const& r │ │ │ │ │ + , char const* buf, std::shared_ptr o │ │ │ │ │ + , std::function handler │ │ │ │ │ + , disk_job_flags_t flags = {}) = 0; │ │ │ │ │ +virtual void async_read (storage_index_t storage, peer_request const& r │ │ │ │ │ + , std::function handler │ │ │ │ │ + , disk_job_flags_t flags = {}) = 0; │ │ │ │ │ +perform a read or write operation from/to the specified storage index and the │ │ │ │ │ +specified request. When the operation completes, call handler possibly with a │ │ │ │ │ +disk_buffer_holder, holding the buffer with the result. Flags may be set to │ │ │ │ │ +affect the read operation. See disk_job_flags_t. │ │ │ │ │ +The disk_observer is a callback to indicate that the store buffer/disk write │ │ │ │ │ +queue is below the watermark to let peers start writing buffers to disk again. │ │ │ │ │ +When async_write() returns true, indicating the write queue is full, the peer │ │ │ │ │ +will stop further writes and wait for the passed-in disk_observer to be │ │ │ │ │ +notified before resuming. │ │ │ │ │ +Note that for async_read, the peer_request (r) is not necessarily aligned to │ │ │ │ │ +blocks (but it is most of the time). However, all writes (passed to │ │ │ │ │ +async_write) are guaranteed to be block aligned. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** enum access_flags ***** │ │ │ │ │ -Declared in "libtorrent/ip_filter.hpp" │ │ │ │ │ - ____________________________________________________________________________ │ │ │ │ │ -|name___|value|description___________________________________________________| │ │ │ │ │ -|blocked|1 |this flag indicates that destination ports in the range should| │ │ │ │ │ -|_______|_____|not_be_connected_to___________________________________________| │ │ │ │ │ +***** async_hash() ***** │ │ │ │ │ +virtual void async_hash (storage_index_t storage, piece_index_t piece, │ │ │ │ │ +span v2 │ │ │ │ │ + , disk_job_flags_t flags │ │ │ │ │ + , std::function handler) = 0; │ │ │ │ │ +Compute hash(es) for the specified piece. Unless the v1_hash flag is set (in │ │ │ │ │ +flags), the SHA-1 hash of the whole piece does not need to be computed. │ │ │ │ │ +Thev2span is optional and can be empty, which means v2 hashes should not be │ │ │ │ │ +computed. If v2 is non-empty it must be at least large enough to hold all v2 │ │ │ │ │ +blocks in the piece, and this function will fill in the span with the SHA-256 │ │ │ │ │ +block hashes of the piece. │ │ │ │ │ [report_issue] │ │ │ │ │ -****** storage_params ****** │ │ │ │ │ -Declared in "libtorrent/storage_defs.hpp" │ │ │ │ │ -a parameter pack used to construct the storage for a torrent, used in │ │ │ │ │ -disk_interface │ │ │ │ │ -struct storage_params │ │ │ │ │ +***** async_hash2() ***** │ │ │ │ │ +virtual void async_hash2 (storage_index_t storage, piece_index_t piece, int │ │ │ │ │ +offset, disk_job_flags_t flags │ │ │ │ │ + , std::function handler) = 0; │ │ │ │ │ +computes the v2 hash (SHA-256) of a single block. The block at offset in piece │ │ │ │ │ +piece. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** async_move_storage() ***** │ │ │ │ │ +virtual void async_move_storage (storage_index_t storage, std::string p, │ │ │ │ │ +move_flags_t flags │ │ │ │ │ + , std::function │ │ │ │ │ +handler) = 0; │ │ │ │ │ +called to request the files for the specified storage/torrent be moved to a new │ │ │ │ │ +location. It is the disk I/O object's responsibility to synchronize this with │ │ │ │ │ +any currently outstanding disk operations to the storage. Whether files are │ │ │ │ │ +replaced at the destination path or not is controlled by flags (see │ │ │ │ │ +move_flags_t). │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** async_release_files() ***** │ │ │ │ │ +virtual void async_release_files (storage_index_t storage │ │ │ │ │ + , std::function handler = std::function()) = 0; │ │ │ │ │ +This is called on disk I/O objects to request they close all open files for the │ │ │ │ │ +specified storage/torrent. If file handles are not pooled/cached, it can be a │ │ │ │ │ +no-op. For truly asynchronous disk I/O, this should provide at least one point │ │ │ │ │ +in time when all files are closed. It is possible that later asynchronous │ │ │ │ │ +operations will re-open some of the files, by the time this completion handler │ │ │ │ │ +is called, that's fine. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** async_check_files() ***** │ │ │ │ │ +virtual void async_check_files (storage_index_t storage │ │ │ │ │ + , add_torrent_params const* resume_data │ │ │ │ │ + , aux::vector links │ │ │ │ │ + , std::function handler) = 0; │ │ │ │ │ +this is called when torrents are added to validate their resume data against │ │ │ │ │ +the files on disk. This function is expected to do a few things: │ │ │ │ │ +if links is non-empty, it contains a string for each file in the torrent. The │ │ │ │ │ +string being a path to an existing identical file. The default behavior is to │ │ │ │ │ +create hard links of those files into the storage of the new torrent (specified │ │ │ │ │ +by storage). An empty string indicates that there is no known identical file. │ │ │ │ │ +This is part of the "mutable torrent" feature, where files can be reused from │ │ │ │ │ +other torrents. │ │ │ │ │ +The resume_data points the resume data passed in by the client. │ │ │ │ │ +If the resume_data->flags field has the seed_mode flag set, all files/pieces │ │ │ │ │ +are expected to be on disk already. This should be verified. Not just the │ │ │ │ │ +existence of the file, but also that it has the correct size. │ │ │ │ │ +Any file with a piece set in the resume_data->have_pieces bitmask should exist │ │ │ │ │ +on disk, this should be verified. Pad files and files with zero priority may be │ │ │ │ │ +skipped. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** async_stop_torrent() ***** │ │ │ │ │ +virtual void async_stop_torrent (storage_index_t storage │ │ │ │ │ + , std::function handler = std::function()) = 0; │ │ │ │ │ +This is called when a torrent is stopped. It gives the disk I/O object an │ │ │ │ │ +opportunity to flush any data to disk that's currently kept cached. This │ │ │ │ │ +function should at least do the same thing as async_release_files(). │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** async_rename_file() ***** │ │ │ │ │ +virtual void async_rename_file (storage_index_t storage │ │ │ │ │ + , file_index_t index, std::string name │ │ │ │ │ + , std::function handler) = 0; │ │ │ │ │ +This function is called when the name of a file in the specified storage has │ │ │ │ │ +been requested to be renamed. The disk I/O object is responsible for renaming │ │ │ │ │ +the file without racing with other potentially outstanding operations against │ │ │ │ │ +the file (such as read, write, move, etc.). │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** async_delete_files() ***** │ │ │ │ │ +virtual void async_delete_files (storage_index_t storage, remove_flags_t │ │ │ │ │ +options │ │ │ │ │ + , std::function handler) = 0; │ │ │ │ │ +This function is called when some file(s) on disk have been requested to be │ │ │ │ │ +removed by the client. storage indicates which torrent is referred to. See │ │ │ │ │ +session_handle for remove_flags_t flags indicating which files are to be │ │ │ │ │ +removed. e.g. session_handle::delete_files - delete all files session_handle:: │ │ │ │ │ +delete_partfile - only delete part file. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** async_set_file_priority() ***** │ │ │ │ │ +virtual void async_set_file_priority (storage_index_t storage │ │ │ │ │ + , aux::vector prio │ │ │ │ │ + , std::function)> handler) = 0; │ │ │ │ │ +This is called to set the priority of some or all files. Changing the priority │ │ │ │ │ +from or to 0 may involve moving data to and from the partfile. The disk I/ │ │ │ │ │ +O object is responsible for correctly synchronizing this work to not race with │ │ │ │ │ +any potentially outstanding asynchronous operations affecting these files. │ │ │ │ │ +prio is a vector of the file priority for all files. If it's shorter than the │ │ │ │ │ +total number of files in the torrent, they are assumed to be set to the default │ │ │ │ │ +priority. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** async_clear_piece() ***** │ │ │ │ │ +virtual void async_clear_piece (storage_index_t storage, piece_index_t index │ │ │ │ │ + , std::function handler) = 0; │ │ │ │ │ +This is called when a piece fails the hash check, to ensure there are no │ │ │ │ │ +outstanding disk operations to the piece before blocks are re-requested from │ │ │ │ │ +peers to overwrite the existing blocks. The disk I/O object does not need to │ │ │ │ │ +perform any action other than synchronize with all outstanding disk operations │ │ │ │ │ +to the specified piece before posting the result back. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** update_stats_counters() ***** │ │ │ │ │ +virtual void update_stats_counters (counters& c) const = 0; │ │ │ │ │ +update_stats_counters() is called to give the disk storage an opportunity to │ │ │ │ │ +update gauges in the c stats counters, that aren't updated continuously as │ │ │ │ │ +operations are performed. This is called before a snapshot of the counters are │ │ │ │ │ +passed to the client. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** get_status() ***** │ │ │ │ │ +virtual std::vector get_status (storage_index_t) const = 0; │ │ │ │ │ +Return a list of all the files that are currently open for the specified │ │ │ │ │ +storage/torrent. This is is just used for the client to query the currently │ │ │ │ │ +open files, and which modes those files are open in. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** abort() ***** │ │ │ │ │ +virtual void abort (bool wait) = 0; │ │ │ │ │ +this is called when the session is starting to shut down. The disk I/O object │ │ │ │ │ +is expected to flush any outstanding write jobs, cancel hash jobs and initiate │ │ │ │ │ +tearing down of any internal threads. If wait is true, this should be │ │ │ │ │ +asynchronous. i.e. this call should not return until all threads have stopped │ │ │ │ │ +and all jobs have either been aborted or completed and the disk I/O object is │ │ │ │ │ +ready to be destructed. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** submit_jobs() ***** │ │ │ │ │ +virtual void submit_jobs () = 0; │ │ │ │ │ +This will be called after a batch of disk jobs has been issues (via the async_* │ │ │ │ │ +). It gives the disk I/O object an opportunity to notify any potential │ │ │ │ │ +condition variables to wake up the disk thread(s). The async_* calls can of │ │ │ │ │ +course also notify condition variables, but doing it in this call allows for │ │ │ │ │ +batching jobs, by issuing the notification once for a collection of jobs. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** settings_updated() ***** │ │ │ │ │ +virtual void settings_updated () = 0; │ │ │ │ │ +This is called to notify the disk I/O object that the settings have been │ │ │ │ │ +updated. In the disk io constructor, a settings_interface reference is passed │ │ │ │ │ +in. Whenever these settings are updated, this function is called to allow the │ │ │ │ │ +disk I/O object to react to any changed settings relevant to its operations. │ │ │ │ │ +[report_issue] │ │ │ │ │ + force_copy │ │ │ │ │ + force making a copy of the cached block, rather than getting a reference │ │ │ │ │ + to a block already in the cache. This is used the block is expected to be │ │ │ │ │ + overwritten very soon, by async_write()`, and we need access to the │ │ │ │ │ + previous content. │ │ │ │ │ +[report_issue] │ │ │ │ │ + sequential_access │ │ │ │ │ + hint that there may be more disk operations with sequential access to the │ │ │ │ │ + file │ │ │ │ │ +[report_issue] │ │ │ │ │ + volatile_read │ │ │ │ │ + don't keep the read block in cache. This is a hint that this block is │ │ │ │ │ + unlikely to be read again anytime soon, and caching it would be wasteful. │ │ │ │ │ +[report_issue] │ │ │ │ │ + v1_hash │ │ │ │ │ + compute a v1 piece hash. This is only used by the async_hash() call. If │ │ │ │ │ + this flag is not set in the async_hash() call, the SHA-1 piece hash does │ │ │ │ │ + not need to be computed. │ │ │ │ │ +[report_issue] │ │ │ │ │ + flush_piece │ │ │ │ │ + this flag instructs a hash job that we just completed this piece, and it │ │ │ │ │ + should be flushed to disk │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** 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_params (file_storage const& f, file_storage const* mf │ │ │ │ │ - , std::string const& sp, storage_mode_t const sm │ │ │ │ │ - , aux::vector const& prio │ │ │ │ │ - , sha1_hash const& ih); │ │ │ │ │ + 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; │ │ │ │ │ +}; │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** 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_str (int name, std::string val) = 0; │ │ │ │ │ + virtual void set_bool (int name, bool val) = 0; │ │ │ │ │ + virtual void set_int (int name, int 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; │ │ │ │ │ +}; │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** disk_observer ****** │ │ │ │ │ +Declared in "libtorrent/disk_observer.hpp" │ │ │ │ │ +struct disk_observer │ │ │ │ │ +{ │ │ │ │ │ + virtual void on_disk () = 0; │ │ │ │ │ +}; │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** on_disk() ***** │ │ │ │ │ +virtual void on_disk () = 0; │ │ │ │ │ +called when the disk cache size has dropped below the low watermark again and │ │ │ │ │ +we can resume downloading from peers │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** 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; │ │ │ │ │ +}; │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** 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& operator= (disk_buffer_holder&&) & noexcept; │ │ │ │ │ + disk_buffer_holder (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; │ │ │ │ │ +}; │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** disk_buffer_holder() ***** │ │ │ │ │ +disk_buffer_holder (buffer_allocator_interface& alloc │ │ │ │ │ + , char* buf, int sz) noexcept; │ │ │ │ │ +construct a buffer holder that will free the held buffer using a disk buffer │ │ │ │ │ +pool directly (there's only one disk_buffer_pool per session) │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** disk_buffer_holder() ***** │ │ │ │ │ +disk_buffer_holder () noexcept = default; │ │ │ │ │ +default construct a holder that does not own any buffer │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** ~disk_buffer_holder() ***** │ │ │ │ │ +~disk_buffer_holder (); │ │ │ │ │ +frees disk buffer held by this object │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** data() ***** │ │ │ │ │ +char* data () const noexcept; │ │ │ │ │ +return a pointer to the held buffer, if any. Otherwise returns nullptr. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** reset() ***** │ │ │ │ │ +void reset (); │ │ │ │ │ +free the held disk buffer, if any, and clear the holder. This sets the holder │ │ │ │ │ +object to a default-constructed state │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** swap() ***** │ │ │ │ │ +void swap (disk_buffer_holder& h) noexcept; │ │ │ │ │ +swap pointers of two disk buffer holders. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** is_mutable() ***** │ │ │ │ │ +bool is_mutable () const noexcept; │ │ │ │ │ +if this returns true, the buffer may not be modified in place │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** bool() ***** │ │ │ │ │ +explicit operator bool () const noexcept; │ │ │ │ │ +implicitly convertible to true if the object is currently holding a buffer │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** 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 │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** web_seed_entry ****** │ │ │ │ │ +Declared in "libtorrent/torrent_info.hpp" │ │ │ │ │ +the web_seed_entry holds information about a web seed (also known as URL seed │ │ │ │ │ +or HTTP seed). It is essentially a URL with some state associated with it. For │ │ │ │ │ +more information, see BEP_17 and BEP_19. │ │ │ │ │ +struct web_seed_entry │ │ │ │ │ +{ │ │ │ │ │ + bool operator== (web_seed_entry const& e) const; │ │ │ │ │ + bool operator< (web_seed_entry const& e) const; │ │ │ │ │ │ │ │ │ │ - file_storage const& files; │ │ │ │ │ - file_storage const* mapped_files = nullptr; │ │ │ │ │ - std::string const& path; │ │ │ │ │ - storage_mode_t mode {storage_mode_sparse}; │ │ │ │ │ - aux::vector const& priorities; │ │ │ │ │ - sha1_hash info_hash; │ │ │ │ │ + enum type_t │ │ │ │ │ + { │ │ │ │ │ + url_seed, │ │ │ │ │ + http_seed, │ │ │ │ │ + }; │ │ │ │ │ + │ │ │ │ │ + std::string url; │ │ │ │ │ + std::string auth; │ │ │ │ │ + headers_t extra_headers; │ │ │ │ │ + std::uint8_t type; │ │ │ │ │ }; │ │ │ │ │ [report_issue] │ │ │ │ │ -****** file_slice ****** │ │ │ │ │ -Declared in "libtorrent/file_storage.hpp" │ │ │ │ │ -represents a window of a file in a torrent. │ │ │ │ │ -The file_index refers to the index of the file (in the torrent_info). To get │ │ │ │ │ -the path and filename, use file_path() and give the file_index as argument. The │ │ │ │ │ -offset is the byte offset in the file where the range starts, and size is the │ │ │ │ │ -number of bytes this range is. The size + offset will never be greater than the │ │ │ │ │ -file size. │ │ │ │ │ -struct file_slice │ │ │ │ │ +***** operator==() ***** │ │ │ │ │ +bool operator== (web_seed_entry const& e) const; │ │ │ │ │ +URL and type comparison │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** operator<() ***** │ │ │ │ │ +bool operator< (web_seed_entry const& e) const; │ │ │ │ │ +URL and type less-than comparison │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** enum type_t ***** │ │ │ │ │ +Declared in "libtorrent/torrent_info.hpp" │ │ │ │ │ + ___________________________ │ │ │ │ │ +|name_____|value|description| │ │ │ │ │ +|url_seed_|0____| _________| │ │ │ │ │ +|http_seed|1____| _________| │ │ │ │ │ +[report_issue] │ │ │ │ │ + url │ │ │ │ │ + The URL of the web seed │ │ │ │ │ +[report_issue] │ │ │ │ │ + auth │ │ │ │ │ + Optional authentication. If this is set, it's passed in as HTTP basic │ │ │ │ │ + auth to the web seed. The format is: username:password. │ │ │ │ │ +[report_issue] │ │ │ │ │ + extra_headers │ │ │ │ │ + Any extra HTTP headers that need to be passed to the web seed │ │ │ │ │ +[report_issue] │ │ │ │ │ + type │ │ │ │ │ + The type of web seed (see type_t) │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** load_torrent_limits ****** │ │ │ │ │ +Declared in "libtorrent/torrent_info.hpp" │ │ │ │ │ +this object holds configuration options for limits to use when loading │ │ │ │ │ +torrents. They are meant to prevent loading potentially malicious torrents that │ │ │ │ │ +cause excessive memory allocations. │ │ │ │ │ +struct load_torrent_limits │ │ │ │ │ { │ │ │ │ │ - file_index_t file_index; │ │ │ │ │ - std::int64_t offset; │ │ │ │ │ - std::int64_t size; │ │ │ │ │ + int max_buffer_size = 10000000; │ │ │ │ │ + int max_pieces = 0x200000; │ │ │ │ │ + int max_decode_depth = 100; │ │ │ │ │ + int max_decode_tokens = 3000000; │ │ │ │ │ }; │ │ │ │ │ [report_issue] │ │ │ │ │ - file_index │ │ │ │ │ - the index of the file │ │ │ │ │ + max_buffer_size │ │ │ │ │ + the max size of a .torrent file to load into RAM │ │ │ │ │ [report_issue] │ │ │ │ │ - offset │ │ │ │ │ - the offset from the start of the file, in bytes │ │ │ │ │ + max_pieces │ │ │ │ │ + the max number of pieces allowed in the torrent │ │ │ │ │ [report_issue] │ │ │ │ │ - size │ │ │ │ │ - the size of the window, in bytes │ │ │ │ │ + max_decode_depth │ │ │ │ │ + the max recursion depth in the bdecoded structure │ │ │ │ │ [report_issue] │ │ │ │ │ -****** file_storage ****** │ │ │ │ │ -Declared in "libtorrent/file_storage.hpp" │ │ │ │ │ -The file_storage class represents a file list and the piece size. Everything │ │ │ │ │ -necessary to interpret a regular bittorrent storage file structure. │ │ │ │ │ -class file_storage │ │ │ │ │ + max_decode_tokens │ │ │ │ │ + the max number of bdecode tokens │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** torrent_info ****** │ │ │ │ │ +Declared in "libtorrent/torrent_info.hpp" │ │ │ │ │ +the torrent_info class holds the information found in a .torrent file. │ │ │ │ │ +class torrent_info │ │ │ │ │ { │ │ │ │ │ - bool is_valid () const; │ │ │ │ │ - void reserve (int num_files); │ │ │ │ │ - void add_file_borrow (error_code& ec, string_view filename │ │ │ │ │ - , std::string const& path, std::int64_t file_size │ │ │ │ │ - , file_flags_t file_flags = {}, char const* filehash = nullptr │ │ │ │ │ - , std::int64_t mtime = 0, string_view symlink_path = string_view() │ │ │ │ │ - , char const* root_hash = nullptr); │ │ │ │ │ - void add_file (std::string const& path, std::int64_t file_size │ │ │ │ │ - , file_flags_t file_flags = {} │ │ │ │ │ - , std::time_t mtime = 0, string_view symlink_path = string_view() │ │ │ │ │ - , char const* root_hash = nullptr); │ │ │ │ │ - void add_file (error_code& ec, std::string const& path, std::int64_t │ │ │ │ │ -file_size │ │ │ │ │ - , file_flags_t file_flags = {} │ │ │ │ │ - , std::time_t mtime = 0, string_view symlink_path = string_view() │ │ │ │ │ - , char const* root_hash = nullptr); │ │ │ │ │ - void add_file_borrow (string_view filename │ │ │ │ │ - , std::string const& path, std::int64_t file_size │ │ │ │ │ - , file_flags_t file_flags = {}, char const* filehash = nullptr │ │ │ │ │ - , std::int64_t mtime = 0, string_view symlink_path = string_view() │ │ │ │ │ - , char const* root_hash = nullptr); │ │ │ │ │ + torrent_info (char const* buffer, int size, error_code& ec); │ │ │ │ │ + explicit torrent_info (std::string const& filename); │ │ │ │ │ + torrent_info (bdecode_node const& torrent_file, error_code& ec); │ │ │ │ │ + explicit torrent_info (span buffer, from_span_t); │ │ │ │ │ + torrent_info (std::string const& filename, load_torrent_limits const& cfg); │ │ │ │ │ + torrent_info (span buffer, load_torrent_limits const& cfg, │ │ │ │ │ +from_span_t); │ │ │ │ │ + torrent_info (span buffer, error_code& ec, from_span_t); │ │ │ │ │ + torrent_info (bdecode_node const& torrent_file, load_torrent_limits const& │ │ │ │ │ +cfg); │ │ │ │ │ + torrent_info (char const* buffer, int size); │ │ │ │ │ + torrent_info (std::string const& filename, error_code& ec); │ │ │ │ │ + explicit torrent_info (bdecode_node const& torrent_file); │ │ │ │ │ + explicit torrent_info (info_hash_t const& info_hash); │ │ │ │ │ + torrent_info (torrent_info const& t); │ │ │ │ │ + ~torrent_info (); │ │ │ │ │ + file_storage const& files () const; │ │ │ │ │ + file_storage const& orig_files () const; │ │ │ │ │ void rename_file (file_index_t index, std::string const& new_filename); │ │ │ │ │ - std::vector map_block (piece_index_t piece, std::int64_t offset │ │ │ │ │ - , std::int64_t size) const; │ │ │ │ │ - peer_request map_file (file_index_t file, std::int64_t offset, int size) │ │ │ │ │ -const; │ │ │ │ │ - int num_files () const noexcept; │ │ │ │ │ - file_index_t end_file () const noexcept; │ │ │ │ │ - index_range file_range () const noexcept; │ │ │ │ │ + void remap_files (file_storage const& f); │ │ │ │ │ + void add_tracker (std::string const& url, int tier = 0); │ │ │ │ │ + void clear_trackers (); │ │ │ │ │ + std::vector const& trackers () const; │ │ │ │ │ + void add_tracker (std::string const& url, int tier │ │ │ │ │ + , announce_entry::tracker_source source); │ │ │ │ │ + std::vector collections () const; │ │ │ │ │ + std::vector similar_torrents () const; │ │ │ │ │ + std::vector const& web_seeds () const; │ │ │ │ │ + void set_web_seeds (std::vector seeds); │ │ │ │ │ + void add_url_seed (std::string const& url │ │ │ │ │ + , std::string const& ext_auth = std::string() │ │ │ │ │ + , web_seed_entry::headers_t const& ext_headers = web_seed_entry:: │ │ │ │ │ +headers_t()); │ │ │ │ │ + void add_http_seed (std::string const& url │ │ │ │ │ + , std::string const& extern_auth = std::string() │ │ │ │ │ + , web_seed_entry::headers_t const& extra_headers = web_seed_entry:: │ │ │ │ │ +headers_t()); │ │ │ │ │ std::int64_t total_size () const; │ │ │ │ │ - void set_num_pieces (int n); │ │ │ │ │ + int piece_length () const; │ │ │ │ │ int num_pieces () const; │ │ │ │ │ + index_range piece_range () const; │ │ │ │ │ piece_index_t end_piece () const; │ │ │ │ │ piece_index_t last_piece () const; │ │ │ │ │ - index_range piece_range () const noexcept; │ │ │ │ │ - int piece_length () const; │ │ │ │ │ - void set_piece_length (int l); │ │ │ │ │ - int piece_size (piece_index_t index) const; │ │ │ │ │ - int piece_size2 (piece_index_t index) const; │ │ │ │ │ - int blocks_in_piece2 (piece_index_t index) const; │ │ │ │ │ - void set_name (std::string const& n); │ │ │ │ │ - std::string const& name () const; │ │ │ │ │ - void swap (file_storage& ti) noexcept; │ │ │ │ │ - void canonicalize (); │ │ │ │ │ - std::int64_t file_size (file_index_t index) const; │ │ │ │ │ - sha1_hash hash (file_index_t index) const; │ │ │ │ │ - std::string symlink (file_index_t index) const; │ │ │ │ │ - bool pad_file_at (file_index_t index) const; │ │ │ │ │ - std::time_t mtime (file_index_t index) const; │ │ │ │ │ - std::int64_t file_offset (file_index_t index) const; │ │ │ │ │ - sha256_hash root (file_index_t index) const; │ │ │ │ │ - string_view file_name (file_index_t index) const; │ │ │ │ │ - std::string file_path (file_index_t index, std::string const& save_path = │ │ │ │ │ -"") const; │ │ │ │ │ - char const* root_ptr (file_index_t const index) const; │ │ │ │ │ - int file_num_blocks (file_index_t index) const; │ │ │ │ │ - int file_num_pieces (file_index_t index) const; │ │ │ │ │ - index_range file_piece_range (file_index_t) const; │ │ │ │ │ - int file_first_piece_node (file_index_t index) const; │ │ │ │ │ - int file_first_block_node (file_index_t index) const; │ │ │ │ │ - std::uint32_t file_path_hash (file_index_t index, std::string const& │ │ │ │ │ -save_path) const; │ │ │ │ │ - void all_path_hashes (std::unordered_set& table) const; │ │ │ │ │ - file_flags_t file_flags (file_index_t index) const; │ │ │ │ │ - bool file_absolute_path (file_index_t index) const; │ │ │ │ │ - file_index_t file_index_at_offset (std::int64_t offset) const; │ │ │ │ │ - file_index_t file_index_at_piece (piece_index_t piece) const; │ │ │ │ │ - file_index_t file_index_for_root (sha256_hash const& root_hash) const; │ │ │ │ │ - piece_index_t piece_index_at_file (file_index_t f) const; │ │ │ │ │ - void sanitize_symlinks (); │ │ │ │ │ + info_hash_t const& info_hashes () const; │ │ │ │ │ + sha1_hash info_hash () const noexcept; │ │ │ │ │ + bool v1 () const; │ │ │ │ │ bool v2 () const; │ │ │ │ │ - │ │ │ │ │ - static constexpr file_flags_t flag_pad_file = 0_bit; │ │ │ │ │ - static constexpr file_flags_t flag_hidden = 1_bit; │ │ │ │ │ - static constexpr file_flags_t flag_executable = 2_bit; │ │ │ │ │ - static constexpr file_flags_t flag_symlink = 3_bit; │ │ │ │ │ + int num_files () const; │ │ │ │ │ + std::vector map_block (piece_index_t const piece │ │ │ │ │ + , std::int64_t offset, int size) const; │ │ │ │ │ + peer_request map_file (file_index_t const file, std::int64_t offset, int │ │ │ │ │ +size) const; │ │ │ │ │ + string_view ssl_cert () const; │ │ │ │ │ + bool is_valid () const; │ │ │ │ │ + bool priv () const; │ │ │ │ │ + bool is_i2p () const; │ │ │ │ │ + int piece_size (piece_index_t index) const; │ │ │ │ │ + char const* hash_for_piece_ptr (piece_index_t const index) const; │ │ │ │ │ + sha1_hash hash_for_piece (piece_index_t index) const; │ │ │ │ │ + bool is_loaded () const; │ │ │ │ │ + const std::string& name () const; │ │ │ │ │ + std::time_t creation_date () const; │ │ │ │ │ + const std::string& creator () const; │ │ │ │ │ + const std::string& comment () const; │ │ │ │ │ + std::vector> const& nodes () const; │ │ │ │ │ + void add_node (std::pair const& node); │ │ │ │ │ + bool parse_info_section (bdecode_node const& info, error_code& ec, int │ │ │ │ │ +max_pieces); │ │ │ │ │ + bdecode_node info (char const* key) const; │ │ │ │ │ + span info_section () const; │ │ │ │ │ + span piece_layer (file_index_t) const; │ │ │ │ │ + void free_piece_layers (); │ │ │ │ │ }; │ │ │ │ │ [report_issue] │ │ │ │ │ -***** is_valid() ***** │ │ │ │ │ -bool is_valid () const; │ │ │ │ │ -returns true if the piece length has been initialized on the file_storage. This │ │ │ │ │ -is typically taken as a proxy of whether the file_storage as a whole is │ │ │ │ │ -initialized or not. │ │ │ │ │ +***** torrent_info() ***** │ │ │ │ │ +torrent_info (char const* buffer, int size, error_code& ec); │ │ │ │ │ +explicit torrent_info (std::string const& filename); │ │ │ │ │ +torrent_info (bdecode_node const& torrent_file, error_code& ec); │ │ │ │ │ +explicit torrent_info (span buffer, from_span_t); │ │ │ │ │ +torrent_info (std::string const& filename, load_torrent_limits const& cfg); │ │ │ │ │ +torrent_info (span buffer, load_torrent_limits const& cfg, │ │ │ │ │ +from_span_t); │ │ │ │ │ +torrent_info (span buffer, error_code& ec, from_span_t); │ │ │ │ │ +torrent_info (bdecode_node const& torrent_file, load_torrent_limits const& │ │ │ │ │ +cfg); │ │ │ │ │ +torrent_info (char const* buffer, int size); │ │ │ │ │ +torrent_info (std::string const& filename, error_code& ec); │ │ │ │ │ +explicit torrent_info (bdecode_node const& torrent_file); │ │ │ │ │ +explicit torrent_info (info_hash_t const& info_hash); │ │ │ │ │ +torrent_info (torrent_info const& t); │ │ │ │ │ +The constructor that takes an info-hash will initialize the info-hash to the │ │ │ │ │ +given value, but leave all other fields empty. This is used internally when │ │ │ │ │ +downloading torrents without the metadata. The metadata will be created by │ │ │ │ │ +libtorrent as soon as it has been downloaded from the swarm. │ │ │ │ │ +The constructor that takes a bdecode_node will create a torrent_info object │ │ │ │ │ +from the information found in the given torrent_file. The bdecode_node │ │ │ │ │ +represents a tree node in an bencoded file. To load an ordinary .torrent file │ │ │ │ │ +into a bdecode_node, use bdecode(). │ │ │ │ │ +The version that takes a buffer pointer and a size will decode it as a .torrent │ │ │ │ │ +file and initialize the torrent_info object for you. │ │ │ │ │ +The version that takes a filename will simply load the torrent file and decode │ │ │ │ │ +it inside the constructor, for convenience. This might not be the most suitable │ │ │ │ │ +for applications that want to be able to report detailed errors on what might │ │ │ │ │ +go wrong. │ │ │ │ │ +There is an upper limit on the size of the torrent file that will be loaded by │ │ │ │ │ +the overload taking a filename. If it's important that even very large torrent │ │ │ │ │ +files are loaded, use one of the other overloads. │ │ │ │ │ +The overloads that takes an error_code const& never throws if an error occur, │ │ │ │ │ +they will simply set the error code to describe what went wrong and not fully │ │ │ │ │ +initialize the torrent_info object. The overloads that do not take the extra │ │ │ │ │ +error_code parameter will always throw if an error occurs. These overloads are │ │ │ │ │ +not available when building without exception support. │ │ │ │ │ +The overload that takes a span also needs an extra parameter of type │ │ │ │ │ +from_span_t to disambiguate the std::string overload for string literals. There │ │ │ │ │ +is an object in the libtorrent namespace of this type called from_span. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** reserve() ***** │ │ │ │ │ -void reserve (int num_files); │ │ │ │ │ -allocates space for num_files in the internal file list. This can be used to │ │ │ │ │ -avoid reallocating the internal file list when the number of files to be added │ │ │ │ │ -is known up-front. │ │ │ │ │ +***** ~torrent_info() ***** │ │ │ │ │ +~torrent_info (); │ │ │ │ │ +frees all storage associated with this torrent_info object │ │ │ │ │ [report_issue] │ │ │ │ │ -***** add_file() add_file_borrow() ***** │ │ │ │ │ -void add_file_borrow (error_code& ec, string_view filename │ │ │ │ │ - , std::string const& path, std::int64_t file_size │ │ │ │ │ - , file_flags_t file_flags = {}, char const* filehash = nullptr │ │ │ │ │ - , std::int64_t mtime = 0, string_view symlink_path = string_view() │ │ │ │ │ - , char const* root_hash = nullptr); │ │ │ │ │ -void add_file (std::string const& path, std::int64_t file_size │ │ │ │ │ - , file_flags_t file_flags = {} │ │ │ │ │ - , std::time_t mtime = 0, string_view symlink_path = string_view() │ │ │ │ │ - , char const* root_hash = nullptr); │ │ │ │ │ -void add_file (error_code& ec, std::string const& path, std::int64_t file_size │ │ │ │ │ - , file_flags_t file_flags = {} │ │ │ │ │ - , std::time_t mtime = 0, string_view symlink_path = string_view() │ │ │ │ │ - , char const* root_hash = nullptr); │ │ │ │ │ -void add_file_borrow (string_view filename │ │ │ │ │ - , std::string const& path, std::int64_t file_size │ │ │ │ │ - , file_flags_t file_flags = {}, char const* filehash = nullptr │ │ │ │ │ - , std::int64_t mtime = 0, string_view symlink_path = string_view() │ │ │ │ │ - , char const* root_hash = nullptr); │ │ │ │ │ -Adds a file to the file storage. The add_file_borrow version expects that │ │ │ │ │ -filename is the file name (without a path) of the file that's being added. This │ │ │ │ │ -memory is borrowed, i.e. it is the caller's responsibility to make sure it │ │ │ │ │ -stays valid throughout the lifetime of this file_storage object or any copy of │ │ │ │ │ -it. The same thing applies to filehash, which is an optional pointer to a 20 │ │ │ │ │ -byte binary SHA-1 hash of the file. │ │ │ │ │ -if filename is empty, the filename from path is used and not borrowed. │ │ │ │ │ -The path argument is the full path (in the torrent file) to the file to add. │ │ │ │ │ -Note that this is not supposed to be an absolute path, but it is expected to │ │ │ │ │ -include the name of the torrent as the first path element. │ │ │ │ │ -file_size is the size of the file in bytes. │ │ │ │ │ -The file_flags argument sets attributes on the file. The file attributes is an │ │ │ │ │ -extension and may not work in all bittorrent clients. │ │ │ │ │ -For possible file attributes, see file_storage::flags_t. │ │ │ │ │ -The mtime argument is optional and can be set to 0. If non-zero, it is the │ │ │ │ │ -posix time of the last modification time of this file. │ │ │ │ │ -symlink_path is the path the file is a symlink to. To make this a symlink you │ │ │ │ │ -also need to set the file_storage::flag_symlink file flag. │ │ │ │ │ -root_hash is an optional pointer to a 32 byte SHA-256 hash, being the merkle │ │ │ │ │ -tree root hash for this file. This is only used for v2 torrents. If the root │ │ │ │ │ -hash is specified for one file, it has to be specified for all, otherwise this │ │ │ │ │ -function will fail. Note that the buffer root_hash points to must out-live the │ │ │ │ │ -file_storage object, it will not be copied. This parameter is only used when │ │ │ │ │ -loading torrents, that already have their file hashes computed. When creating │ │ │ │ │ -torrents, the file hashes will be computed by the piece hashes. │ │ │ │ │ -If more files than one are added, certain restrictions to their paths apply. In │ │ │ │ │ -a multi-file file storage (torrent), all files must share the same root │ │ │ │ │ -directory. │ │ │ │ │ -That is, the first path element of all files must be the same. This shared path │ │ │ │ │ -element is also set to the name of the torrent. It can be changed by calling │ │ │ │ │ -set_name. │ │ │ │ │ -The overloads that take anerror_codereference will report failures via that │ │ │ │ │ -variable, otherwisesystem_erroris thrown. │ │ │ │ │ +***** files() orig_files() ***** │ │ │ │ │ +file_storage const& files () const; │ │ │ │ │ +file_storage const& orig_files () const; │ │ │ │ │ +The file_storage object contains the information on how to map the pieces to │ │ │ │ │ +files. It is separated from the torrent_info object because when creating │ │ │ │ │ +torrents a storage object needs to be created without having a torrent file. │ │ │ │ │ +When renaming files in a storage, the storage needs to make its own copy of the │ │ │ │ │ +file_storage in order to make its mapping differ from the one in the torrent │ │ │ │ │ +file. │ │ │ │ │ +orig_files() returns the original (unmodified) file storage for this torrent. │ │ │ │ │ +This is used by the web server connection, which needs to request files with │ │ │ │ │ +the original names. Filename may be changed using torrent_info::rename_file(). │ │ │ │ │ +For more information on the file_storage object, see the separate document on │ │ │ │ │ +how to create torrents. │ │ │ │ │ [report_issue] │ │ │ │ │ ***** rename_file() ***** │ │ │ │ │ void rename_file (file_index_t index, std::string const& new_filename); │ │ │ │ │ -renames the file at index to new_filename. Keep in mind that filenames are │ │ │ │ │ -expected to be UTF-8 encoded. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** map_block() ***** │ │ │ │ │ -std::vector map_block (piece_index_t piece, std::int64_t offset │ │ │ │ │ - , std::int64_t size) const; │ │ │ │ │ -returns a list of file_slice objects representing the portions of files the │ │ │ │ │ -specified piece index, byte offset and size range overlaps. this is the inverse │ │ │ │ │ -mapping of map_file(). │ │ │ │ │ -Preconditions of this function is that the input range is within the torrents │ │ │ │ │ -address space. piece may not be negative and │ │ │ │ │ - piece * piece_size + offset + size │ │ │ │ │ -may not exceed the total size of the torrent. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** map_file() ***** │ │ │ │ │ -peer_request map_file (file_index_t file, std::int64_t offset, int size) const; │ │ │ │ │ -returns a peer_request representing the piece index, byte offset and size the │ │ │ │ │ -specified file range overlaps. This is the inverse mapping over map_block(). │ │ │ │ │ -Note that the peer_request return type is meant to hold bittorrent block │ │ │ │ │ -requests, which may not be larger than 16 kiB. Mapping a range larger than that │ │ │ │ │ -may return an overflown integer. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** num_files() ***** │ │ │ │ │ -int num_files () const noexcept; │ │ │ │ │ -returns the number of files in the file_storage │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** end_file() ***** │ │ │ │ │ -file_index_t end_file () const noexcept; │ │ │ │ │ -returns the index of the one-past-end file in the file storage │ │ │ │ │ +Renames the file with the specified index to the new name. The new filename is │ │ │ │ │ +reflected by the file_storage returned by files() but not by the one returned │ │ │ │ │ +by orig_files(). │ │ │ │ │ +If you want to rename the base name of the torrent (for a multi file torrent), │ │ │ │ │ +you can copy the file_storage (see files() and orig_files() ), change the name, │ │ │ │ │ +and then use remap_files(). │ │ │ │ │ +The new_filename can both be a relative path, in which case the file name is │ │ │ │ │ +relative to the save_path of the torrent. If the new_filename is an absolute │ │ │ │ │ +path (i.e. is_complete(new_filename) == true), then the file is detached from │ │ │ │ │ +the save_path of the torrent. In this case the file is not moved when │ │ │ │ │ +move_storage() is invoked. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** file_range() ***** │ │ │ │ │ -index_range file_range () const noexcept; │ │ │ │ │ -returns an implementation-defined type that can be used as the container in a │ │ │ │ │ -range-for loop. Where the values are the indices of all files in the │ │ │ │ │ -file_storage. │ │ │ │ │ +***** remap_files() ***** │ │ │ │ │ +void remap_files (file_storage const& f); │ │ │ │ │ +Warning │ │ │ │ │ +Usingremap_files()is discouraged as it's incompatible with v2 torrents. This is │ │ │ │ │ +because the piece boundaries and piece hashes in v2 torrents are intimately │ │ │ │ │ +tied to the file boundaries. Instead, just rename individual files, or │ │ │ │ │ +implement a custom disk_interface to customize how to store files. │ │ │ │ │ +Remaps the file storage to a new file layout. This can be used to, for │ │ │ │ │ +instance, download all data in a torrent to a single file, or to a number of │ │ │ │ │ +fixed size sector aligned files, regardless of the number and sizes of the │ │ │ │ │ +files in the torrent. │ │ │ │ │ +The new specified file_storage must have the exact same size as the current │ │ │ │ │ +one. │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** clear_trackers() trackers() add_tracker() ***** │ │ │ │ │ +void add_tracker (std::string const& url, int tier = 0); │ │ │ │ │ +void clear_trackers (); │ │ │ │ │ +std::vector const& trackers () const; │ │ │ │ │ +void add_tracker (std::string const& url, int tier │ │ │ │ │ + , announce_entry::tracker_source source); │ │ │ │ │ +add_tracker() adds a tracker to the announce-list. The tier determines the │ │ │ │ │ +order in which the trackers are to be tried. The trackers() function will │ │ │ │ │ +return a sorted vector of announce_entry. Each announce entry contains a │ │ │ │ │ +string, which is the tracker url, and a tier index. The tier index is the high- │ │ │ │ │ +level priority. No matter which trackers that works or not, the ones with lower │ │ │ │ │ +tier will always be tried before the one with higher tier number. For more │ │ │ │ │ +information, see announce_entry. │ │ │ │ │ +trackers() returns all entries from announce-list. │ │ │ │ │ +clear_trackers() removes all trackers from announce-list. │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** collections() similar_torrents() ***** │ │ │ │ │ +std::vector collections () const; │ │ │ │ │ +std::vector similar_torrents () const; │ │ │ │ │ +These two functions are related to BEP_38 (mutable torrents). The vectors │ │ │ │ │ +returned from these correspond to the "similar" and "collections" keys in the │ │ │ │ │ +.torrent file. Both info-hashes and collections from within the info-dict and │ │ │ │ │ +from outside of it are included. │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** set_web_seeds() web_seeds() add_http_seed() add_url_seed() ***** │ │ │ │ │ +std::vector const& web_seeds () const; │ │ │ │ │ +void set_web_seeds (std::vector seeds); │ │ │ │ │ +void add_url_seed (std::string const& url │ │ │ │ │ + , std::string const& ext_auth = std::string() │ │ │ │ │ + , web_seed_entry::headers_t const& ext_headers = web_seed_entry:: │ │ │ │ │ +headers_t()); │ │ │ │ │ +void add_http_seed (std::string const& url │ │ │ │ │ + , std::string const& extern_auth = std::string() │ │ │ │ │ + , web_seed_entry::headers_t const& extra_headers = web_seed_entry:: │ │ │ │ │ +headers_t()); │ │ │ │ │ +web_seeds() returns all url seeds and http seeds in the torrent. Each entry is │ │ │ │ │ +a web_seed_entry and may refer to either a url seed or http seed. │ │ │ │ │ +add_url_seed() and add_http_seed() adds one url to the list of url/http seeds. │ │ │ │ │ +set_web_seeds() replaces all web seeds with the ones specified in the seeds │ │ │ │ │ +vector. │ │ │ │ │ +The extern_auth argument can be used for other authorization schemes than basic │ │ │ │ │ +HTTP authorization. If set, it will override any username and password found in │ │ │ │ │ +the URL itself. The string will be sent as the HTTP authorization header's │ │ │ │ │ +value (without specifying "Basic"). │ │ │ │ │ +The extra_headers argument defaults to an empty list, but can be used to insert │ │ │ │ │ +custom HTTP headers in the requests to a specific web seed. │ │ │ │ │ +See http_seeding for more information. │ │ │ │ │ [report_issue] │ │ │ │ │ ***** total_size() ***** │ │ │ │ │ std::int64_t total_size () const; │ │ │ │ │ -returns the total number of bytes all the files in this torrent spans │ │ │ │ │ +total_size() returns the total number of bytes the torrent-file represents. │ │ │ │ │ +Note that this is the number of pieces times the piece size (modulo the last │ │ │ │ │ +piece possibly being smaller). With pad files, the total size will be larger │ │ │ │ │ +than the sum of all (regular) file sizes. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** num_pieces() set_num_pieces() ***** │ │ │ │ │ -void set_num_pieces (int n); │ │ │ │ │ +***** num_pieces() piece_length() ***** │ │ │ │ │ +int piece_length () const; │ │ │ │ │ int num_pieces () const; │ │ │ │ │ -set and get the number of pieces in the torrent │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** end_piece() ***** │ │ │ │ │ +piece_length() and num_pieces() returns the number of byte for each piece and │ │ │ │ │ +the total number of pieces, respectively. The difference between piece_size() │ │ │ │ │ +and piece_length() is that piece_size() takes the piece index as argument and │ │ │ │ │ +gives you the exact size of that piece. It will always be the same as │ │ │ │ │ +piece_length() except in the case of the last piece, which may be smaller. │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** last_piece() end_piece() piece_range() ***** │ │ │ │ │ +index_range piece_range () const; │ │ │ │ │ piece_index_t end_piece () const; │ │ │ │ │ -returns the index of the one-past-end piece in the file storage │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** last_piece() ***** │ │ │ │ │ piece_index_t last_piece () const; │ │ │ │ │ -returns the index of the last piece in the torrent. The last piece is special │ │ │ │ │ -in that it may be smaller than the other pieces (and the other pieces are all │ │ │ │ │ -the same size). │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** piece_range() ***** │ │ │ │ │ -index_range piece_range () const noexcept; │ │ │ │ │ +last_piece() returns the index to the last piece in the torrent and end_piece() │ │ │ │ │ +returns the index to the one-past-end piece in the torrent piece_range() │ │ │ │ │ returns an implementation-defined type that can be used as the container in a │ │ │ │ │ range-for loop. Where the values are the indices of all pieces in the │ │ │ │ │ file_storage. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** set_piece_length() piece_length() ***** │ │ │ │ │ -int piece_length () const; │ │ │ │ │ -void set_piece_length (int l); │ │ │ │ │ -set and get the size of each piece in this torrent. It must be a power of two │ │ │ │ │ -and at least 16 kiB. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** piece_size() ***** │ │ │ │ │ -int piece_size (piece_index_t index) const; │ │ │ │ │ -returns the piece size of index. This will be the same as piece_length(), │ │ │ │ │ -except for the last piece, which may be shorter. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** piece_size2() ***** │ │ │ │ │ -int piece_size2 (piece_index_t index) const; │ │ │ │ │ -Returns the size of the given piece. If the piece spans multiple files, only │ │ │ │ │ -the first file is considered part of the piece. This is used for v2 torrents, │ │ │ │ │ -where all files are piece aligned and padded. i.e. The pad files are not │ │ │ │ │ -considered part of the piece for this purpose. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** blocks_in_piece2() ***** │ │ │ │ │ -int blocks_in_piece2 (piece_index_t index) const; │ │ │ │ │ -returns the number of blocks in the specified piece, for v2 torrents. │ │ │ │ │ +***** info_hashes() info_hash() ***** │ │ │ │ │ +info_hash_t const& info_hashes () const; │ │ │ │ │ +sha1_hash info_hash () const noexcept; │ │ │ │ │ +returns the info-hash of the torrent. For BitTorrent v2 support, use │ │ │ │ │ +info_hashes() to get an object that may hold both a v1 and v2 info-hash │ │ │ │ │ [report_issue] │ │ │ │ │ -***** set_name() name() ***** │ │ │ │ │ -void set_name (std::string const& n); │ │ │ │ │ -std::string const& name () const; │ │ │ │ │ -set and get the name of this torrent. For multi-file torrents, this is also the │ │ │ │ │ -name of the root directory all the files are stored in. │ │ │ │ │ +***** v2() v1() ***** │ │ │ │ │ +bool v1 () const; │ │ │ │ │ +bool v2 () const; │ │ │ │ │ +returns whether this torrent has v1 and/or v2 metadata, respectively. Hybrid │ │ │ │ │ +torrents have both. These are shortcuts for info_hashes().has_v1() and │ │ │ │ │ +info_hashes().has_v2() calls. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** swap() ***** │ │ │ │ │ -void swap (file_storage& ti) noexcept; │ │ │ │ │ -swap all content of this with ti. │ │ │ │ │ +***** num_files() ***** │ │ │ │ │ +int num_files () const; │ │ │ │ │ +If you need index-access to files you can use the num_files() along with the │ │ │ │ │ +file_path(), file_size()-family of functions to access files using indices. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** canonicalize() ***** │ │ │ │ │ -void canonicalize (); │ │ │ │ │ -arrange files and padding to match the canonical form required by BEP 52 │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** file_size() hash() pad_file_at() root() file_offset() root_ptr() │ │ │ │ │ -file_path() file_name() mtime() symlink() ***** │ │ │ │ │ -std::int64_t file_size (file_index_t index) const; │ │ │ │ │ -sha1_hash hash (file_index_t index) const; │ │ │ │ │ -std::string symlink (file_index_t index) const; │ │ │ │ │ -bool pad_file_at (file_index_t index) const; │ │ │ │ │ -std::time_t mtime (file_index_t index) const; │ │ │ │ │ -std::int64_t file_offset (file_index_t index) const; │ │ │ │ │ -sha256_hash root (file_index_t index) const; │ │ │ │ │ -string_view file_name (file_index_t index) const; │ │ │ │ │ -std::string file_path (file_index_t index, std::string const& save_path = "") │ │ │ │ │ -const; │ │ │ │ │ -char const* root_ptr (file_index_t const index) const; │ │ │ │ │ -These functions are used to query attributes of files at a given index. │ │ │ │ │ -The hash() is a SHA-1 hash of the file, or 0 if none was provided in the │ │ │ │ │ -torrent file. This can potentially be used to join a bittorrent network with │ │ │ │ │ -other file sharing networks. │ │ │ │ │ -root() returns the SHA-256 merkle tree root of the specified file, in case this │ │ │ │ │ -is a v2 torrent. Otherwise returns zeros. root_ptr() returns a pointer to the │ │ │ │ │ -SHA-256 merkle tree root hash for the specified file. The pointer points into │ │ │ │ │ -storage referred to when the file was added, it is not owned by this object. │ │ │ │ │ -Torrents that are not v2 torrents return nullptr. │ │ │ │ │ -The mtime() is the modification time is the posix time when a file was last │ │ │ │ │ -modified when the torrent was created, or 0 if it was not included in the │ │ │ │ │ -torrent file. │ │ │ │ │ -file_path() returns the full path to a file. │ │ │ │ │ -file_size() returns the size of a file. │ │ │ │ │ -pad_file_at() returns true if the file at the given index is a pad-file. │ │ │ │ │ -file_name() returns just the name of the file, whereas file_path() returns the │ │ │ │ │ -path (inside the torrent file) with the filename appended. │ │ │ │ │ -file_offset() returns the byte offset within the torrent file where this file │ │ │ │ │ -starts. It can be used to map the file to a piece index (given the piece size). │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** file_num_pieces() file_num_blocks() file_piece_range() ***** │ │ │ │ │ -int file_num_blocks (file_index_t index) const; │ │ │ │ │ -int file_num_pieces (file_index_t index) const; │ │ │ │ │ -index_range file_piece_range (file_index_t) const; │ │ │ │ │ -Returns the number of pieces or blocks the file atindexspans, under the │ │ │ │ │ -assumption that the file is aligned to the start of a piece. This is only │ │ │ │ │ -meaningful for v2 torrents, where files are guaranteed such alignment. These │ │ │ │ │ -numbers are used to size and navigate the merkle hash tree for each file. │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** file_first_block_node() file_first_piece_node() ***** │ │ │ │ │ -int file_first_piece_node (file_index_t index) const; │ │ │ │ │ -int file_first_block_node (file_index_t index) const; │ │ │ │ │ -index of first piece node in the merkle tree │ │ │ │ │ +***** map_block() ***** │ │ │ │ │ +std::vector map_block (piece_index_t const piece │ │ │ │ │ + , std::int64_t offset, int size) const; │ │ │ │ │ +This function will map a piece index, a byte offset within that piece and a │ │ │ │ │ +size (in bytes) into the corresponding files with offsets where that data for │ │ │ │ │ +that piece is supposed to be stored. See file_slice. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** file_path_hash() ***** │ │ │ │ │ -std::uint32_t file_path_hash (file_index_t index, std::string const& save_path) │ │ │ │ │ +***** map_file() ***** │ │ │ │ │ +peer_request map_file (file_index_t const file, std::int64_t offset, int size) │ │ │ │ │ const; │ │ │ │ │ -returns the crc32 hash of file_path(index) │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** all_path_hashes() ***** │ │ │ │ │ -void all_path_hashes (std::unordered_set& table) const; │ │ │ │ │ -this will add the CRC32 hash of all directory entries to the table. No filename │ │ │ │ │ -will be included, just directories. Every depth of directories are added │ │ │ │ │ -separately to allow test for collisions with files at all levels. i.e. if one │ │ │ │ │ -path in the torrent is foo/bar/baz, the CRC32 hashes for foo, foo/bar and foo/ │ │ │ │ │ -bar/baz will be added to the set. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** file_flags() ***** │ │ │ │ │ -file_flags_t file_flags (file_index_t index) const; │ │ │ │ │ -returns a bitmask of flags from file_flags_t that apply to file at index. │ │ │ │ │ +This function will map a range in a specific file into a range in the torrent. │ │ │ │ │ +The file_offset parameter is the offset in the file, given in bytes, where 0 is │ │ │ │ │ +the start of the file. See peer_request. │ │ │ │ │ +The input range is assumed to be valid within the torrent. file_offset + size │ │ │ │ │ +is not allowed to be greater than the file size. file_index must refer to a │ │ │ │ │ +valid file, i.e. it cannot be >= num_files(). │ │ │ │ │ [report_issue] │ │ │ │ │ -***** file_absolute_path() ***** │ │ │ │ │ -bool file_absolute_path (file_index_t index) const; │ │ │ │ │ -returns true if the file at the specified index has been renamed to have an │ │ │ │ │ -absolute path, i.e. is not anchored in the save path of the torrent. │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** file_index_at_offset() file_index_at_piece() ***** │ │ │ │ │ -file_index_t file_index_at_offset (std::int64_t offset) const; │ │ │ │ │ -file_index_t file_index_at_piece (piece_index_t piece) const; │ │ │ │ │ -returns the index of the file at the given offset in the torrent │ │ │ │ │ +***** ssl_cert() ***** │ │ │ │ │ +string_view ssl_cert () const; │ │ │ │ │ +Returns the SSL root certificate for the torrent, if it is an SSL torrent. │ │ │ │ │ +Otherwise returns an empty string. The certificate is the public certificate in │ │ │ │ │ +x509 format. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** file_index_for_root() ***** │ │ │ │ │ -file_index_t file_index_for_root (sha256_hash const& root_hash) const; │ │ │ │ │ -finds the file with the given root hash and returns its index if there is no │ │ │ │ │ -file with the root hash, file_index_t{-1} is returned │ │ │ │ │ +***** is_valid() ***** │ │ │ │ │ +bool is_valid () const; │ │ │ │ │ +returns true if this torrent_info object has a torrent loaded. This is │ │ │ │ │ +primarily used to determine if a magnet link has had its metadata resolved yet │ │ │ │ │ +or not. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** piece_index_at_file() ***** │ │ │ │ │ -piece_index_t piece_index_at_file (file_index_t f) const; │ │ │ │ │ -returns the piece index the given file starts at │ │ │ │ │ +***** priv() ***** │ │ │ │ │ +bool priv () const; │ │ │ │ │ +returns true if this torrent is private. i.e., the client should not advertise │ │ │ │ │ +itself on the trackerless network (the Kademlia DHT) for this torrent. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** sanitize_symlinks() ***** │ │ │ │ │ -void sanitize_symlinks (); │ │ │ │ │ -validate any symlinks, to ensure they all point to other files or directories │ │ │ │ │ -inside this storage. Any invalid symlinks are updated to point to themselves. │ │ │ │ │ +***** is_i2p() ***** │ │ │ │ │ +bool is_i2p () const; │ │ │ │ │ +returns true if this is an i2p torrent. This is determined by whether or not it │ │ │ │ │ +has a tracker whose URL domain name ends with ".i2p". i2p torrents disable the │ │ │ │ │ +DHT and local peer discovery as well as talking to peers over anything other │ │ │ │ │ +than the i2p network. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** v2() ***** │ │ │ │ │ -bool v2 () const; │ │ │ │ │ -returns true if this torrent contains v2 metadata. │ │ │ │ │ +***** piece_size() ***** │ │ │ │ │ +int piece_size (piece_index_t index) const; │ │ │ │ │ +returns the piece size of file with index. This will be the same as │ │ │ │ │ +piece_length(), except for the last piece, which may be shorter. │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** hash_for_piece_ptr() hash_for_piece() ***** │ │ │ │ │ +char const* hash_for_piece_ptr (piece_index_t const index) const; │ │ │ │ │ +sha1_hash hash_for_piece (piece_index_t index) const; │ │ │ │ │ +hash_for_piece() takes a piece-index and returns the 20-bytes sha1-hash for │ │ │ │ │ +that piece and info_hash() returns the 20-bytes sha1-hash for the info-section │ │ │ │ │ +of the torrent file. hash_for_piece_ptr() returns a pointer to the 20 byte sha1 │ │ │ │ │ +digest for the piece. Note that the string is not 0-terminated. │ │ │ │ │ [report_issue] │ │ │ │ │ - flag_pad_file │ │ │ │ │ - the file is a pad file. It's required to contain zeros at it will not be │ │ │ │ │ - saved to disk. Its purpose is to make the following file start on a piece │ │ │ │ │ - boundary. │ │ │ │ │ +***** name() ***** │ │ │ │ │ +const std::string& name () const; │ │ │ │ │ +name() returns the name of the torrent. name contains UTF-8 encoded string. │ │ │ │ │ [report_issue] │ │ │ │ │ - flag_hidden │ │ │ │ │ - this file has the hidden attribute set. This is primarily a windows │ │ │ │ │ - attribute │ │ │ │ │ +***** creation_date() ***** │ │ │ │ │ +std::time_t creation_date () const; │ │ │ │ │ +creation_date() returns the creation date of the torrent as time_t (posix │ │ │ │ │ +time). If there's no time stamp in the torrent file, 0 is returned. .. posix │ │ │ │ │ +time: http://www.opengroup.org/onlinepubs/009695399/functions/time.html │ │ │ │ │ [report_issue] │ │ │ │ │ - flag_executable │ │ │ │ │ - this file has the executable attribute set. │ │ │ │ │ +***** creator() ***** │ │ │ │ │ +const std::string& creator () const; │ │ │ │ │ +creator() returns the creator string in the torrent. If there is no creator │ │ │ │ │ +string it will return an empty string. │ │ │ │ │ [report_issue] │ │ │ │ │ - flag_symlink │ │ │ │ │ - this file is a symbolic link. It should have a link target string │ │ │ │ │ - associated with it. │ │ │ │ │ +***** comment() ***** │ │ │ │ │ +const std::string& comment () const; │ │ │ │ │ +comment() returns the comment associated with the torrent. If there's no │ │ │ │ │ +comment, it will return an empty string. comment contains UTF-8 encoded string. │ │ │ │ │ [report_issue] │ │ │ │ │ -****** posix_disk_io_constructor() ****** │ │ │ │ │ -Declared in "libtorrent/posix_disk_io.hpp" │ │ │ │ │ -std::unique_ptr posix_disk_io_constructor ( │ │ │ │ │ - io_context& ios, settings_interface const&, counters& cnt); │ │ │ │ │ -this is a simple posix disk I/O back-end, used for systems that don't have a 64 │ │ │ │ │ -bit virtual address space or don't support memory mapped files. It's │ │ │ │ │ -implemented using portable C file functions and is single-threaded. │ │ │ │ │ +***** nodes() ***** │ │ │ │ │ +std::vector> const& nodes () const; │ │ │ │ │ +If this torrent contains any DHT nodes, they are put in this vector in their │ │ │ │ │ +original form (host name and port number). │ │ │ │ │ [report_issue] │ │ │ │ │ -****** mmap_disk_io_constructor() ****** │ │ │ │ │ -Declared in "libtorrent/mmap_disk_io.hpp" │ │ │ │ │ -std::unique_ptr mmap_disk_io_constructor ( │ │ │ │ │ - io_context& ios, settings_interface const&, counters& cnt); │ │ │ │ │ -constructs a memory mapped file disk I/O object. │ │ │ │ │ +***** add_node() ***** │ │ │ │ │ +void add_node (std::pair const& node); │ │ │ │ │ +This is used when creating torrent. Use this to add a known DHT node. It may be │ │ │ │ │ +used, by the client, to bootstrap into the DHT network. │ │ │ │ │ [report_issue] │ │ │ │ │ -****** disabled_disk_io_constructor() ****** │ │ │ │ │ -Declared in "libtorrent/disabled_disk_io.hpp" │ │ │ │ │ -std::unique_ptr disabled_disk_io_constructor ( │ │ │ │ │ - io_context& ios, settings_interface const&, counters& cnt); │ │ │ │ │ -creates a disk io object that discards all data written to it, and only returns │ │ │ │ │ -zero-buffers when read from. May be useful for testing and benchmarking. │ │ │ │ │ +***** parse_info_section() ***** │ │ │ │ │ +bool parse_info_section (bdecode_node const& info, error_code& ec, int │ │ │ │ │ +max_pieces); │ │ │ │ │ +populates the torrent_info by providing just the info-dict buffer. This is used │ │ │ │ │ +when loading a torrent from a magnet link for instance, where we only have the │ │ │ │ │ +info-dict. The bdecode_node e points to a parsed info-dictionary. ec returns an │ │ │ │ │ +error code if something fails (typically if the info dictionary is malformed). │ │ │ │ │ +Themax_piecesparameter allows limiting the amount of memory dedicated to │ │ │ │ │ +loading the torrent, and fails for torrents that exceed the limit. To load │ │ │ │ │ +large torrents, this limit may also need to be raised in settings_pack:: │ │ │ │ │ +max_piece_count and in calls to read_resume_data(). │ │ │ │ │ [report_issue] │ │ │ │ │ -****** default_disk_io_constructor() ****** │ │ │ │ │ -Declared in "libtorrent/session.hpp" │ │ │ │ │ -std::unique_ptr default_disk_io_constructor ( │ │ │ │ │ - io_context& ios, settings_interface const&, counters& cnt); │ │ │ │ │ -the constructor function for the default storage. On systems that support │ │ │ │ │ -memory mapped files (and a 64 bit address space) the memory mapped storage will │ │ │ │ │ -be constructed, otherwise the portable posix storage. │ │ │ │ │ +***** info() ***** │ │ │ │ │ +bdecode_node info (char const* key) const; │ │ │ │ │ +This function looks up keys from the info-dictionary of the loaded torrent │ │ │ │ │ +file. It can be used to access extension values put in the .torrent file. If │ │ │ │ │ +the specified key cannot be found, it returns nullptr. │ │ │ │ │ [report_issue] │ │ │ │ │ -****** enum storage_mode_t ****** │ │ │ │ │ -Declared in "libtorrent/storage_defs.hpp" │ │ │ │ │ - ___________________________________________________________________________ │ │ │ │ │ -|name_________________|value|description____________________________________| │ │ │ │ │ -| | |All pieces will be written to their final | │ │ │ │ │ -| | |position, all files will be allocated in full | │ │ │ │ │ -|storage_mode_allocate|0 |when the torrent is first started. This mode | │ │ │ │ │ -| | |minimizes fragmentation but could be a costly | │ │ │ │ │ -|_____________________|_____|operation._____________________________________| │ │ │ │ │ -| | |All pieces will be written to the place where | │ │ │ │ │ -|storage_mode_sparse |1 |they belong and sparse files will be used. This| │ │ │ │ │ -|_____________________|_____|is_the_recommended,_and_default_mode.__________| │ │ │ │ │ +***** info_section() ***** │ │ │ │ │ +span info_section () const; │ │ │ │ │ +returns a the raw info section of the torrent file. The underlying buffer is │ │ │ │ │ +still owned by the torrent_info object │ │ │ │ │ [report_issue] │ │ │ │ │ -****** enum status_t ****** │ │ │ │ │ -Declared in "libtorrent/storage_defs.hpp" │ │ │ │ │ - ____________________________________________________________________________ │ │ │ │ │ -|name____________|value|description__________________________________________| │ │ │ │ │ -|no_error________|0____| ___________________________________________________| │ │ │ │ │ -|fatal_disk_error|1____| ___________________________________________________| │ │ │ │ │ -|need_full_check_|2____| ___________________________________________________| │ │ │ │ │ -|file_exist______|3____| ___________________________________________________| │ │ │ │ │ -| | |this is not an enum value, but a flag that can be set| │ │ │ │ │ -| | |in the return from async_check_files, in case an | │ │ │ │ │ -|oversized_file |16 |existing file was found larger than specified in the | │ │ │ │ │ -| | |torrent. i.e. it has garbage at the end the status_t | │ │ │ │ │ -|________________|_____|field_is_used_for_this_to_preserve_ABI.______________| │ │ │ │ │ +***** piece_layer() ***** │ │ │ │ │ +span piece_layer (file_index_t) const; │ │ │ │ │ +return the bytes of the piece layer hashes for the specified file. If the file │ │ │ │ │ +doesn't have a piece layer, an empty span is returned. The span size is │ │ │ │ │ +divisible by 32, the size of a SHA-256 hash. If the size of the file is smaller │ │ │ │ │ +than or equal to the piece size, the files "root hash" is the hash of the file │ │ │ │ │ +and is not saved separately in the "piece layers" field, but this function │ │ │ │ │ +still returns the root hash of the file in that case. │ │ │ │ │ [report_issue] │ │ │ │ │ -****** enum move_flags_t ****** │ │ │ │ │ -Declared in "libtorrent/storage_defs.hpp" │ │ │ │ │ - ____________________________________________________________________________ │ │ │ │ │ -|name________________|value|description______________________________________| │ │ │ │ │ -|always_replace_files|0 |replace any files in the destination when copying| │ │ │ │ │ -|____________________|_____|or_moving_the_storage____________________________| │ │ │ │ │ -| | |if any files that we want to copy exist in the | │ │ │ │ │ -| | |destination exist, fail the whole operation and | │ │ │ │ │ -| | |don't perform any copy or move. There is an | │ │ │ │ │ -|fail_if_exist |1 |inherent race condition in this mode. The files | │ │ │ │ │ -| | |are checked for existence before the operation | │ │ │ │ │ -| | |starts. In between the check and performing the | │ │ │ │ │ -| | |copy, the destination files may be created, in | │ │ │ │ │ -|____________________|_____|which_case_they_are_replaced.____________________| │ │ │ │ │ -|dont_replace |2 |if any file exist in the target, take those files| │ │ │ │ │ -|____________________|_____|instead_of_the_ones_we_may_have_in_the_source.___| │ │ │ │ │ +***** free_piece_layers() ***** │ │ │ │ │ +void free_piece_layers (); │ │ │ │ │ +clears the piece layers from the torrent_info. This is done by the session when │ │ │ │ │ +a torrent is added, to avoid storing it twice. The piece layer (or other hashes │ │ │ │ │ +part of the merkle tree) are stored in the internal torrent object. │ │ │ │ │ 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. │ │ │ │ │ @@ -6005,17 +4839,17 @@ │ │ │ │ │ limit is specified in 16 kiB blocks. │ │ │ │ │ struct settings_pack final : settings_interface │ │ │ │ │ { │ │ │ │ │ friend void apply_pack_impl (settings_pack const* │ │ │ │ │ , aux::session_settings_single_thread& │ │ │ │ │ , std::vector*); │ │ │ │ │ void set_str (int name, std::string val) override; │ │ │ │ │ - void set_int (int name, int val) override; │ │ │ │ │ void set_int (int name, flags::bitfield_flag const val); │ │ │ │ │ void set_bool (int name, bool val) override; │ │ │ │ │ + void set_int (int name, int val) override; │ │ │ │ │ bool has_val (int name) const override; │ │ │ │ │ void clear (); │ │ │ │ │ void clear (int name); │ │ │ │ │ int get_int (int name) const override; │ │ │ │ │ bool get_bool (int name) const override; │ │ │ │ │ std::string const& get_str (int name) const override; │ │ │ │ │ void for_each (Fun&& f) const; │ │ │ │ │ @@ -6092,19 +4926,19 @@ │ │ │ │ │ socks5_pw, │ │ │ │ │ http, │ │ │ │ │ http_pw, │ │ │ │ │ i2p_proxy, │ │ │ │ │ }; │ │ │ │ │ }; │ │ │ │ │ [report_issue] │ │ │ │ │ -***** set_str() set_bool() set_int() ***** │ │ │ │ │ +***** set_bool() set_int() set_str() ***** │ │ │ │ │ void set_str (int name, std::string val) override; │ │ │ │ │ -void set_int (int name, int val) override; │ │ │ │ │ void set_int (int name, flags::bitfield_flag const val); │ │ │ │ │ void set_bool (int name, bool val) override; │ │ │ │ │ +void set_int (int name, int val) override; │ │ │ │ │ set a configuration option in the settings_pack. name is one of the enum values │ │ │ │ │ from string_types, int_types or bool_types. They must match the respective type │ │ │ │ │ of the set_* function. │ │ │ │ │ [report_issue] │ │ │ │ │ ***** has_val() ***** │ │ │ │ │ bool has_val (int name) const override; │ │ │ │ │ queries whether the specified configuration option has a value set in this │ │ │ │ │ @@ -6115,15 +4949,15 @@ │ │ │ │ │ void clear (); │ │ │ │ │ clear the settings pack from all settings │ │ │ │ │ [report_issue] │ │ │ │ │ ***** clear() ***** │ │ │ │ │ void clear (int name); │ │ │ │ │ clear a specific setting from the pack │ │ │ │ │ [report_issue] │ │ │ │ │ -***** get_bool() get_int() get_str() ***** │ │ │ │ │ +***** get_int() get_str() get_bool() ***** │ │ │ │ │ int get_int (int name) const override; │ │ │ │ │ bool get_bool (int name) const override; │ │ │ │ │ std::string const& get_str (int name) const override; │ │ │ │ │ queries the current configuration option from the settings_pack. name is one of │ │ │ │ │ the enumeration values from string_types, int_types or bool_types. The enum │ │ │ │ │ value must match the type of the get_* function. If the specified setting field │ │ │ │ │ has not been set, the default value is returned. │ │ │ │ │ @@ -6253,14 +5087,50 @@ │ │ │ │ │ | | |trackers, a plain proxy will suffice. The proxy is assumed to| │ │ │ │ │ | | |not require authorization. The username and password will not| │ │ │ │ │ |_________|_____|be_used._____________________________________________________| │ │ │ │ │ | | |The server is assumed to be an HTTP proxy that requires user | │ │ │ │ │ |http_pw |5 |authorization. The username and password will be sent to the | │ │ │ │ │ |_________|_____|proxy._______________________________________________________| │ │ │ │ │ |i2p_proxy|6____|route_through_a_i2p_SAM_proxy________________________________| │ │ │ │ │ + [report_issue] │ │ │ │ │ +****** min_memory_usage() high_performance_seed() ****** │ │ │ │ │ +Declared in "libtorrent/session.hpp" │ │ │ │ │ +settings_pack min_memory_usage (); │ │ │ │ │ +settings_pack high_performance_seed (); │ │ │ │ │ +The default values of the session settings are set for a regular bittorrent │ │ │ │ │ +client running on a desktop system. There are functions that can set the │ │ │ │ │ +session settings to pre set settings for other environments. These can be used │ │ │ │ │ +for the basis, and should be tweaked to fit your needs better. │ │ │ │ │ +min_memory_usage returns settings that will use the minimal amount of RAM, at │ │ │ │ │ +the potential expense of upload and download performance. It adjusts the socket │ │ │ │ │ +buffer sizes, disables the disk cache, lowers the send buffer watermarks so │ │ │ │ │ +that each connection only has at most one block in use at any one time. It │ │ │ │ │ +lowers the outstanding blocks send to the disk I/O thread so that connections │ │ │ │ │ +only have one block waiting to be flushed to disk at any given time. It lowers │ │ │ │ │ +the max number of peers in the peer list for torrents. It performs multiple │ │ │ │ │ +smaller reads when it hashes pieces, instead of reading it all into memory │ │ │ │ │ +before hashing. │ │ │ │ │ +This configuration is intended to be the starting point for embedded devices. │ │ │ │ │ +It will significantly reduce memory usage. │ │ │ │ │ +high_performance_seed returns settings optimized for a seed box, serving many │ │ │ │ │ +peers and that doesn't do any downloading. It has a 128 MB disk cache and has a │ │ │ │ │ +limit of 400 files in its file pool. It support fast upload rates by allowing │ │ │ │ │ +large send buffers. │ │ │ │ │ + [report_issue] │ │ │ │ │ +****** name_for_setting() setting_by_name() ****** │ │ │ │ │ +Declared in "libtorrent/settings_pack.hpp" │ │ │ │ │ +char const* name_for_setting (int s); │ │ │ │ │ +int setting_by_name (string_view name); │ │ │ │ │ +converts a setting integer (from the enums string_types, int_types or │ │ │ │ │ +bool_types) to a string, and vice versa. │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** default_settings() ****** │ │ │ │ │ +Declared in "libtorrent/settings_pack.hpp" │ │ │ │ │ +settings_pack default_settings (); │ │ │ │ │ +returns a settings_pack with every setting set to its default value │ │ │ │ │ [report_issue] │ │ │ │ │ ****** generate_fingerprint() ****** │ │ │ │ │ Declared in "libtorrent/fingerprint.hpp" │ │ │ │ │ std::string generate_fingerprint (std::string name │ │ │ │ │ , int major, int minor = 0, int revision = 0, int tag = 0); │ │ │ │ │ This is a utility function to produce a client ID fingerprint formatted to the │ │ │ │ │ most common convention. The fingerprint can be set via the peer_fingerprint │ │ │ │ │ @@ -6278,862 +5148,970 @@ │ │ │ │ │ |BT______|BitTorrent__________| │ │ │ │ │ |DE______|Deluge______________| │ │ │ │ │ |AZ______|Azureus_____________| │ │ │ │ │ |TL______|Tribler_____________| │ │ │ │ │ There's an informal directory of client id's here. │ │ │ │ │ The major, minor, revision and tag parameters are used to identify the version │ │ │ │ │ of your client. │ │ │ │ │ - [report_issue] │ │ │ │ │ -****** name_for_setting() setting_by_name() ****** │ │ │ │ │ -Declared in "libtorrent/settings_pack.hpp" │ │ │ │ │ -int setting_by_name (string_view name); │ │ │ │ │ -char const* name_for_setting (int s); │ │ │ │ │ -converts a setting integer (from the enums string_types, int_types or │ │ │ │ │ -bool_types) to a string, and vice versa. │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** default_settings() ****** │ │ │ │ │ -Declared in "libtorrent/settings_pack.hpp" │ │ │ │ │ -settings_pack default_settings (); │ │ │ │ │ -returns a settings_pack with every setting set to its default value │ │ │ │ │ - [report_issue] │ │ │ │ │ -****** high_performance_seed() min_memory_usage() ****** │ │ │ │ │ -Declared in "libtorrent/session.hpp" │ │ │ │ │ -settings_pack min_memory_usage (); │ │ │ │ │ -settings_pack high_performance_seed (); │ │ │ │ │ -The default values of the session settings are set for a regular bittorrent │ │ │ │ │ -client running on a desktop system. There are functions that can set the │ │ │ │ │ -session settings to pre set settings for other environments. These can be used │ │ │ │ │ -for the basis, and should be tweaked to fit your needs better. │ │ │ │ │ -min_memory_usage returns settings that will use the minimal amount of RAM, at │ │ │ │ │ -the potential expense of upload and download performance. It adjusts the socket │ │ │ │ │ -buffer sizes, disables the disk cache, lowers the send buffer watermarks so │ │ │ │ │ -that each connection only has at most one block in use at any one time. It │ │ │ │ │ -lowers the outstanding blocks send to the disk I/O thread so that connections │ │ │ │ │ -only have one block waiting to be flushed to disk at any given time. It lowers │ │ │ │ │ -the max number of peers in the peer list for torrents. It performs multiple │ │ │ │ │ -smaller reads when it hashes pieces, instead of reading it all into memory │ │ │ │ │ -before hashing. │ │ │ │ │ -This configuration is intended to be the starting point for embedded devices. │ │ │ │ │ -It will significantly reduce memory usage. │ │ │ │ │ -high_performance_seed returns settings optimized for a seed box, serving many │ │ │ │ │ -peers and that doesn't do any downloading. It has a 128 MB disk cache and has a │ │ │ │ │ -limit of 400 files in its file pool. It support fast upload rates by allowing │ │ │ │ │ -large send buffers. │ │ │ │ │ [report_issue] │ │ │ │ │ -****** session_params ****** │ │ │ │ │ -Declared in "libtorrent/session_params.hpp" │ │ │ │ │ -The session_params is a parameters pack for configuring the session before it's │ │ │ │ │ -started. │ │ │ │ │ -struct session_params │ │ │ │ │ +****** bitfield ****** │ │ │ │ │ +Declared in "libtorrent/bitfield.hpp" │ │ │ │ │ +The bitfield type stores any number of bits as a bitfield in a heap allocated │ │ │ │ │ +array. │ │ │ │ │ +struct bitfield │ │ │ │ │ { │ │ │ │ │ - session_params (settings_pack const& sp); │ │ │ │ │ - session_params (); │ │ │ │ │ - session_params (settings_pack&& sp); │ │ │ │ │ - session_params (settings_pack const& sp │ │ │ │ │ - , std::vector> exts); │ │ │ │ │ - session_params (settings_pack&& sp │ │ │ │ │ - , std::vector> exts); │ │ │ │ │ - │ │ │ │ │ - settings_pack settings; │ │ │ │ │ - std::vector> extensions; │ │ │ │ │ - dht::dht_state dht_state; │ │ │ │ │ - dht::dht_storage_constructor_type dht_storage_constructor; │ │ │ │ │ - disk_io_constructor_type disk_io_constructor; │ │ │ │ │ - std::map ext_state; │ │ │ │ │ - libtorrent::ip_filter ip_filter; │ │ │ │ │ + explicit bitfield (int bits); │ │ │ │ │ + bitfield (char const* b, int bits); │ │ │ │ │ + bitfield (bitfield const& rhs); │ │ │ │ │ + bitfield (bitfield&& rhs) noexcept = default; │ │ │ │ │ + bitfield (int bits, bool val); │ │ │ │ │ + bitfield () noexcept = default; │ │ │ │ │ + void assign (char const* b, int const bits); │ │ │ │ │ + bool operator[] (int index) const noexcept; │ │ │ │ │ + bool get_bit (int index) const noexcept; │ │ │ │ │ + void clear_bit (int index) noexcept; │ │ │ │ │ + void set_bit (int index) noexcept; │ │ │ │ │ + bool all_set () const noexcept; │ │ │ │ │ + bool none_set () const noexcept; │ │ │ │ │ + int size () const noexcept; │ │ │ │ │ + int num_words () const noexcept; │ │ │ │ │ + bool empty () const noexcept; │ │ │ │ │ + char const* data () const noexcept; │ │ │ │ │ + char* data () noexcept; │ │ │ │ │ + void swap (bitfield& rhs) noexcept; │ │ │ │ │ + int count () const noexcept; │ │ │ │ │ + int find_first_set () const noexcept; │ │ │ │ │ + int find_last_clear () const noexcept; │ │ │ │ │ }; │ │ │ │ │ [report_issue] │ │ │ │ │ -***** session_params() ***** │ │ │ │ │ -session_params (settings_pack const& sp); │ │ │ │ │ -session_params (); │ │ │ │ │ -session_params (settings_pack&& sp); │ │ │ │ │ -This constructor can be used to start with the default plugins (ut_metadata, │ │ │ │ │ -ut_pex and smart_ban). Pass a settings_pack to set the initial settings when │ │ │ │ │ -the session starts. │ │ │ │ │ +***** bitfield() ***** │ │ │ │ │ +explicit bitfield (int bits); │ │ │ │ │ +bitfield (char const* b, int bits); │ │ │ │ │ +bitfield (bitfield const& rhs); │ │ │ │ │ +bitfield (bitfield&& rhs) noexcept = default; │ │ │ │ │ +bitfield (int bits, bool val); │ │ │ │ │ +bitfield () noexcept = default; │ │ │ │ │ +constructs a new bitfield. The default constructor creates an empty bitfield. │ │ │ │ │ +bits is the size of the bitfield (specified in bits). val is the value to │ │ │ │ │ +initialize the bits to. If not specified all bits are initialized to 0. │ │ │ │ │ +The constructor taking a pointer b and bits copies a bitfield from the │ │ │ │ │ +specified buffer, and bits number of bits (rounded up to the nearest byte │ │ │ │ │ +boundary). │ │ │ │ │ [report_issue] │ │ │ │ │ -***** session_params() ***** │ │ │ │ │ -session_params (settings_pack const& sp │ │ │ │ │ - , std::vector> exts); │ │ │ │ │ -session_params (settings_pack&& sp │ │ │ │ │ - , std::vector> exts); │ │ │ │ │ -This constructor helps to configure the set of initial plugins to be added to │ │ │ │ │ -the session before it's started. │ │ │ │ │ +***** assign() ***** │ │ │ │ │ +void assign (char const* b, int const bits); │ │ │ │ │ +copy bitfield from buffer b of bits number of bits, rounded up to the nearest │ │ │ │ │ +byte boundary. │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** operator[]() get_bit() ***** │ │ │ │ │ +bool operator[] (int index) const noexcept; │ │ │ │ │ +bool get_bit (int index) const noexcept; │ │ │ │ │ +query bit at index. Returns true if bit is 1, otherwise false. │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** clear_bit() set_bit() ***** │ │ │ │ │ +void clear_bit (int index) noexcept; │ │ │ │ │ +void set_bit (int index) noexcept; │ │ │ │ │ +set bit at index to 0 (clear_bit) or 1 (set_bit). │ │ │ │ │ [report_issue] │ │ │ │ │ - settings │ │ │ │ │ - The settings to configure the session with │ │ │ │ │ +***** all_set() ***** │ │ │ │ │ +bool all_set () const noexcept; │ │ │ │ │ +returns true if all bits in the bitfield are set │ │ │ │ │ [report_issue] │ │ │ │ │ - extensions │ │ │ │ │ - the plugins to add to the session as it is constructed │ │ │ │ │ +***** none_set() ***** │ │ │ │ │ +bool none_set () const noexcept; │ │ │ │ │ +returns true if no bit in the bitfield is set │ │ │ │ │ [report_issue] │ │ │ │ │ - dht_state │ │ │ │ │ - DHT node ID and node addresses to bootstrap the DHT with. │ │ │ │ │ +***** size() ***** │ │ │ │ │ +int size () const noexcept; │ │ │ │ │ +returns the size of the bitfield in bits. │ │ │ │ │ [report_issue] │ │ │ │ │ - dht_storage_constructor │ │ │ │ │ - function object to construct the storage object for DHT items. │ │ │ │ │ +***** num_words() ***** │ │ │ │ │ +int num_words () const noexcept; │ │ │ │ │ +returns the number of 32 bit words are needed to represent all bits in this │ │ │ │ │ +bitfield. │ │ │ │ │ [report_issue] │ │ │ │ │ - disk_io_constructor │ │ │ │ │ - function object to create the disk I/O subsystem. Defaults to │ │ │ │ │ - default_disk_io_constructor. │ │ │ │ │ +***** empty() ***** │ │ │ │ │ +bool empty () const noexcept; │ │ │ │ │ +returns true if the bitfield has zero size. │ │ │ │ │ [report_issue] │ │ │ │ │ - ext_state │ │ │ │ │ - this container can be used by extensions/plugins to store settings. It's │ │ │ │ │ - primarily here to make it convenient to save and restore state across │ │ │ │ │ - sessions, using read_session_params() and write_session_params(). │ │ │ │ │ +***** data() ***** │ │ │ │ │ +char const* data () const noexcept; │ │ │ │ │ +char* data () noexcept; │ │ │ │ │ +returns a pointer to the internal buffer of the bitfield, or nullptr if it's │ │ │ │ │ +empty. │ │ │ │ │ [report_issue] │ │ │ │ │ - ip_filter │ │ │ │ │ - the IP filter to use for the session. This restricts which peers are │ │ │ │ │ - allowed to connect. As if passed to set_ip_filter(). │ │ │ │ │ +***** swap() ***** │ │ │ │ │ +void swap (bitfield& rhs) noexcept; │ │ │ │ │ +swaps the bit-fields two variables refer to │ │ │ │ │ [report_issue] │ │ │ │ │ -****** session_proxy ****** │ │ │ │ │ -Declared in "libtorrent/session.hpp" │ │ │ │ │ -this is a holder for the internal session implementation object. Once the │ │ │ │ │ -session destruction is explicitly initiated, this holder is used to synchronize │ │ │ │ │ -the completion of the shutdown. The lifetime of this object may outlive │ │ │ │ │ -session, causing the session destructor to not block. The session_proxy │ │ │ │ │ -destructor will block however, until the underlying session is done shutting │ │ │ │ │ -down. │ │ │ │ │ -struct session_proxy │ │ │ │ │ +***** count() ***** │ │ │ │ │ +int count () const noexcept; │ │ │ │ │ +count the number of bits in the bitfield that are set to 1. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** find_first_set() ***** │ │ │ │ │ +int find_first_set () const noexcept; │ │ │ │ │ +returns the index of the first set bit in the bitfield, i.e. 1 bit. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** find_last_clear() ***** │ │ │ │ │ +int find_last_clear () const noexcept; │ │ │ │ │ +returns the index to the last cleared bit in the bitfield, i.e. 0 bit. │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** hasher ****** │ │ │ │ │ +Declared in "libtorrent/hasher.hpp" │ │ │ │ │ +this is a SHA-1 hash class. │ │ │ │ │ +You use it by first instantiating it, then call update() to feed it with data. │ │ │ │ │ +i.e. you don't have to keep the entire buffer of which you want to create the │ │ │ │ │ +hash in memory. You can feed the hasher parts of it at a time. When You have │ │ │ │ │ +fed the hasher with all the data, you call final() and it will return the sha1- │ │ │ │ │ +hash of the data. │ │ │ │ │ +The constructor that takes a char const* and an integer will construct the sha1 │ │ │ │ │ +context and feed it the data passed in. │ │ │ │ │ +If you want to reuse the hasher object once you have created a hash, you have │ │ │ │ │ +to call reset() to reinitialize it. │ │ │ │ │ +The built-in software version of sha1-algorithm was implemented by Steve Reid │ │ │ │ │ +and released as public domain. For more info, see src/sha1.cpp. │ │ │ │ │ +class hasher │ │ │ │ │ { │ │ │ │ │ - session_proxy (); │ │ │ │ │ - session_proxy (session_proxy&&) noexcept; │ │ │ │ │ - session_proxy (session_proxy const&); │ │ │ │ │ - session_proxy& operator= (session_proxy const&) &; │ │ │ │ │ - ~session_proxy (); │ │ │ │ │ - session_proxy& operator= (session_proxy&&) & noexcept; │ │ │ │ │ + hasher (); │ │ │ │ │ + hasher& operator= (hasher const&) &; │ │ │ │ │ + explicit hasher (span data); │ │ │ │ │ + hasher (char const* data, int len); │ │ │ │ │ + hasher (hasher const&); │ │ │ │ │ + hasher& update (char const* data, int len); │ │ │ │ │ + hasher& update (span data); │ │ │ │ │ + sha1_hash final (); │ │ │ │ │ + void reset (); │ │ │ │ │ }; │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** ~session_proxy() operator=() session_proxy() ***** │ │ │ │ │ -session_proxy (); │ │ │ │ │ -session_proxy (session_proxy&&) noexcept; │ │ │ │ │ -session_proxy (session_proxy const&); │ │ │ │ │ -session_proxy& operator= (session_proxy const&) &; │ │ │ │ │ -~session_proxy (); │ │ │ │ │ -session_proxy& operator= (session_proxy&&) & noexcept; │ │ │ │ │ -default constructor, does not refer to any session implementation object. │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** operator=() hasher() ***** │ │ │ │ │ +hasher& operator= (hasher const&) &; │ │ │ │ │ +explicit hasher (span data); │ │ │ │ │ +hasher (char const* data, int len); │ │ │ │ │ +hasher (hasher const&); │ │ │ │ │ +this is the same as default constructing followed by a call to update(data, │ │ │ │ │ +len). │ │ │ │ │ [report_issue] │ │ │ │ │ -****** session ****** │ │ │ │ │ -Declared in "libtorrent/session.hpp" │ │ │ │ │ -The session holds all state that spans multiple torrents. Among other things it │ │ │ │ │ -runs the network loop and manages all torrents. Once it's created, the session │ │ │ │ │ -object will spawn the main thread that will do all the work. The main thread │ │ │ │ │ -will be idle as long it doesn't have any torrents to participate in. │ │ │ │ │ -You have some control over session configuration through the session_handle:: │ │ │ │ │ -apply_settings() member function. To change one or more configuration options, │ │ │ │ │ -create a settings_pack. object and fill it with the settings to be set and pass │ │ │ │ │ -it in to session::apply_settings(). │ │ │ │ │ -see apply_settings(). │ │ │ │ │ -struct session : session_handle │ │ │ │ │ +***** update() ***** │ │ │ │ │ +hasher& update (char const* data, int len); │ │ │ │ │ +hasher& update (span data); │ │ │ │ │ +append the following bytes to what is being hashed │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** final() ***** │ │ │ │ │ +sha1_hash final (); │ │ │ │ │ +returns the SHA-1 digest of the buffers previously passed to update() and the │ │ │ │ │ +hasher constructor. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** reset() ***** │ │ │ │ │ +void reset (); │ │ │ │ │ +restore the hasher state to be as if the hasher has just been default │ │ │ │ │ +constructed. │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** hasher256 ****** │ │ │ │ │ +Declared in "libtorrent/hasher.hpp" │ │ │ │ │ +class hasher256 │ │ │ │ │ { │ │ │ │ │ - explicit session (session_params&& params); │ │ │ │ │ - explicit session (session_params const& params); │ │ │ │ │ - session (session_params const& params, session_flags_t flags); │ │ │ │ │ - session (session_params&& params, session_flags_t flags); │ │ │ │ │ - session (); │ │ │ │ │ - session (session_params&& params, io_context& ios, session_flags_t); │ │ │ │ │ - session (session_params&& params, io_context& ios); │ │ │ │ │ - session (session_params const& params, io_context& ios, session_flags_t); │ │ │ │ │ - session (session_params const& params, io_context& ios); │ │ │ │ │ - ~session (); │ │ │ │ │ - session_proxy abort (); │ │ │ │ │ + hasher256 (); │ │ │ │ │ + hasher256 (char const* data, int len); │ │ │ │ │ + explicit hasher256 (span data); │ │ │ │ │ + hasher256 (hasher256 const&); │ │ │ │ │ + hasher256& operator= (hasher256 const&) &; │ │ │ │ │ + hasher256& update (char const* data, int len); │ │ │ │ │ + hasher256& update (span data); │ │ │ │ │ + sha256_hash final (); │ │ │ │ │ + void reset (); │ │ │ │ │ + ~hasher256 (); │ │ │ │ │ }; │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** hasher256() operator=() ***** │ │ │ │ │ +hasher256 (char const* data, int len); │ │ │ │ │ +explicit hasher256 (span data); │ │ │ │ │ +hasher256 (hasher256 const&); │ │ │ │ │ +hasher256& operator= (hasher256 const&) &; │ │ │ │ │ +this is the same as default constructing followed by a call to update(data, │ │ │ │ │ +len). │ │ │ │ │ [report_issue] │ │ │ │ │ -***** session() ***** │ │ │ │ │ -explicit session (session_params&& params); │ │ │ │ │ -explicit session (session_params const& params); │ │ │ │ │ -session (session_params const& params, session_flags_t flags); │ │ │ │ │ -session (session_params&& params, session_flags_t flags); │ │ │ │ │ -session (); │ │ │ │ │ -Constructs the session objects which acts as the container of torrents. In │ │ │ │ │ -order to avoid a race condition between starting the session and configuring │ │ │ │ │ -it, you can pass in a session_params object. Its settings will take effect │ │ │ │ │ -before the session starts up. │ │ │ │ │ -The overloads taking flags can be used to start a session in paused mode (by │ │ │ │ │ -passing in session::paused). Note that add_default_plugins do not have an │ │ │ │ │ -affect on constructors that take a session_params object. It already contains │ │ │ │ │ -the plugins to use. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** session() ***** │ │ │ │ │ -session (session_params&& params, io_context& ios, session_flags_t); │ │ │ │ │ -session (session_params&& params, io_context& ios); │ │ │ │ │ -session (session_params const& params, io_context& ios, session_flags_t); │ │ │ │ │ -session (session_params const& params, io_context& ios); │ │ │ │ │ -Overload of the constructor that takes an external io_context to run the │ │ │ │ │ -session object on. This is primarily useful for tests that may want to run │ │ │ │ │ -multiple sessions on a single io_context, or low resource systems where │ │ │ │ │ -additional threads are expensive and sharing an io_context with other events is │ │ │ │ │ -fine. │ │ │ │ │ -Warning │ │ │ │ │ -The session object does not cleanly terminate with an external io_context. The │ │ │ │ │ -io_context::run() call must have returned before it's safe to destruct the │ │ │ │ │ -session. Which means you MUST call session::abort() and save the session_proxy │ │ │ │ │ -first, then destruct the session object, then sync with the io_context, then │ │ │ │ │ -destruct the session_proxy object. │ │ │ │ │ +***** update() ***** │ │ │ │ │ +hasher256& update (char const* data, int len); │ │ │ │ │ +hasher256& update (span data); │ │ │ │ │ +append the following bytes to what is being hashed │ │ │ │ │ [report_issue] │ │ │ │ │ -***** ~session() ***** │ │ │ │ │ -~session (); │ │ │ │ │ -The destructor of session will notify all trackers that our torrents have been │ │ │ │ │ -shut down. If some trackers are down, they will time out. All this before the │ │ │ │ │ -destructor of session returns. So, it's advised that any kind of interface │ │ │ │ │ -(such as windows) are closed before destructing the session object. Because it │ │ │ │ │ -can take a few second for it to finish. The timeout can be set with │ │ │ │ │ -apply_settings(). │ │ │ │ │ +***** final() ***** │ │ │ │ │ +sha256_hash final (); │ │ │ │ │ +returns the SHA-1 digest of the buffers previously passed to update() and the │ │ │ │ │ +hasher constructor. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** abort() ***** │ │ │ │ │ -session_proxy abort (); │ │ │ │ │ -In case you want to destruct the session asynchronously, you can request a │ │ │ │ │ -session destruction proxy. If you don't do this, the destructor of the session │ │ │ │ │ -object will block while the trackers are contacted. If you keep one │ │ │ │ │ -session_proxy to the session when destructing it, the destructor will not │ │ │ │ │ -block, but start to close down the session, the destructor of the proxy will │ │ │ │ │ -then synchronize the threads. So, the destruction of the session is performed │ │ │ │ │ -from the session destructor call until the session_proxy destructor call. The │ │ │ │ │ -session_proxy does not have any operations on it (since the session is being │ │ │ │ │ -closed down, no operations are allowed on it). The only valid operation is │ │ │ │ │ -calling the destructor: │ │ │ │ │ -struct session_proxy {}; │ │ │ │ │ +***** reset() ***** │ │ │ │ │ +void reset (); │ │ │ │ │ +restore the hasher state to be as if the hasher has just been default │ │ │ │ │ +constructed. │ │ │ │ │ [report_issue] │ │ │ │ │ -****** session_handle ****** │ │ │ │ │ -Declared in "libtorrent/session_handle.hpp" │ │ │ │ │ -this class provides a non-owning handle to a session and a subset of the │ │ │ │ │ -interface of the session class. If the underlying session is destructed any │ │ │ │ │ -handle to it will no longer be valid. is_valid() will return false and any │ │ │ │ │ -operation on it will throw a system_error exception, with error code │ │ │ │ │ -invalid_session_handle. │ │ │ │ │ -struct session_handle │ │ │ │ │ +****** 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 │ │ │ │ │ { │ │ │ │ │ - bool is_valid () const; │ │ │ │ │ - session_params session_state (save_state_flags_t flags = │ │ │ │ │ -save_state_flags_t::all()) const; │ │ │ │ │ - void refresh_torrent_status (std::vector* ret │ │ │ │ │ - , status_flags_t flags = {}) const; │ │ │ │ │ - std::vector get_torrent_status ( │ │ │ │ │ - std::function const& pred │ │ │ │ │ - , status_flags_t flags = {}) const; │ │ │ │ │ - void post_torrent_updates (status_flags_t flags = status_flags_t::all()); │ │ │ │ │ - void post_session_stats (); │ │ │ │ │ - void post_dht_stats (); │ │ │ │ │ - void set_dht_state (dht::dht_state const& st); │ │ │ │ │ - void set_dht_state (dht::dht_state&& st); │ │ │ │ │ - std::vector get_torrents () const; │ │ │ │ │ - torrent_handle find_torrent (sha1_hash const& info_hash) const; │ │ │ │ │ - torrent_handle add_torrent (add_torrent_params&& params, error_code& ec); │ │ │ │ │ - torrent_handle add_torrent (add_torrent_params const& params, error_code& │ │ │ │ │ -ec); │ │ │ │ │ - torrent_handle add_torrent (add_torrent_params&& params); │ │ │ │ │ - void async_add_torrent (add_torrent_params const& params); │ │ │ │ │ - void async_add_torrent (add_torrent_params&& params); │ │ │ │ │ - torrent_handle add_torrent (add_torrent_params const& params); │ │ │ │ │ - void pause (); │ │ │ │ │ - void resume (); │ │ │ │ │ - bool is_paused () const; │ │ │ │ │ - bool is_dht_running () const; │ │ │ │ │ - void set_dht_storage (dht::dht_storage_constructor_type sc); │ │ │ │ │ - void add_dht_node (std::pair const& node); │ │ │ │ │ - void dht_get_item (sha1_hash const& target); │ │ │ │ │ - void dht_get_item (std::array key │ │ │ │ │ - , std::string salt = std::string()); │ │ │ │ │ - sha1_hash dht_put_item (entry data); │ │ │ │ │ - void dht_put_item (std::array key │ │ │ │ │ - , std::function& │ │ │ │ │ - , std::int64_t&, std::string const&)> cb │ │ │ │ │ - , std::string salt = std::string()); │ │ │ │ │ - void dht_announce (sha1_hash const& info_hash, int port = 0, dht:: │ │ │ │ │ -announce_flags_t flags = {}); │ │ │ │ │ - void dht_get_peers (sha1_hash const& info_hash); │ │ │ │ │ - void dht_live_nodes (sha1_hash const& nid); │ │ │ │ │ - void dht_sample_infohashes (udp::endpoint const& ep, sha1_hash const& │ │ │ │ │ -target); │ │ │ │ │ - void dht_direct_request (udp::endpoint const& ep, entry const& e, │ │ │ │ │ -client_data_t userdata = {}); │ │ │ │ │ - void add_extension (std::function( │ │ │ │ │ - torrent_handle const&, client_data_t)> ext); │ │ │ │ │ - void add_extension (std::shared_ptr ext); │ │ │ │ │ - void set_ip_filter (ip_filter f); │ │ │ │ │ - ip_filter get_ip_filter () const; │ │ │ │ │ - void set_port_filter (port_filter const& f); │ │ │ │ │ - unsigned short ssl_listen_port () const; │ │ │ │ │ - unsigned short listen_port () const; │ │ │ │ │ - bool is_listening () const; │ │ │ │ │ - ip_filter get_peer_class_filter () const; │ │ │ │ │ - void set_peer_class_filter (ip_filter const& f); │ │ │ │ │ - void set_peer_class_type_filter (peer_class_type_filter const& f); │ │ │ │ │ - peer_class_type_filter get_peer_class_type_filter () const; │ │ │ │ │ - peer_class_t create_peer_class (char const* name); │ │ │ │ │ - void delete_peer_class (peer_class_t cid); │ │ │ │ │ - peer_class_info get_peer_class (peer_class_t cid) const; │ │ │ │ │ - void set_peer_class (peer_class_t cid, peer_class_info const& pci); │ │ │ │ │ - void remove_torrent (const torrent_handle&, remove_flags_t = {}); │ │ │ │ │ - void apply_settings (settings_pack&&); │ │ │ │ │ - void apply_settings (settings_pack const&); │ │ │ │ │ - settings_pack get_settings () const; │ │ │ │ │ - void set_alert_notify (std::function const& fun); │ │ │ │ │ - void pop_alerts (std::vector* alerts); │ │ │ │ │ - alert* wait_for_alert (time_duration max_wait); │ │ │ │ │ - std::vector add_port_mapping (portmap_protocol t, int │ │ │ │ │ -external_port, int local_port); │ │ │ │ │ - void delete_port_mapping (port_mapping_t handle); │ │ │ │ │ - void reopen_network_sockets (reopen_network_flags_t options = │ │ │ │ │ -reopen_map_ports); │ │ │ │ │ - std::shared_ptr native_handle () const; │ │ │ │ │ + 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); │ │ │ │ │ │ │ │ │ │ - static constexpr save_state_flags_t save_settings = 0_bit; │ │ │ │ │ - static constexpr save_state_flags_t save_dht_state = 2_bit; │ │ │ │ │ - static constexpr save_state_flags_t save_extension_state = 11_bit; │ │ │ │ │ - static constexpr save_state_flags_t save_ip_filter = 12_bit; │ │ │ │ │ - static constexpr peer_class_t global_peer_class_id {0}; │ │ │ │ │ - static constexpr peer_class_t tcp_peer_class_id {1}; │ │ │ │ │ - static constexpr peer_class_t local_peer_class_id {2}; │ │ │ │ │ - static constexpr remove_flags_t delete_files = 0_bit; │ │ │ │ │ - static constexpr remove_flags_t delete_partfile = 1_bit; │ │ │ │ │ - static constexpr session_flags_t paused = 2_bit; │ │ │ │ │ - static constexpr portmap_protocol udp = portmap_protocol::udp; │ │ │ │ │ - static constexpr portmap_protocol tcp = portmap_protocol::tcp; │ │ │ │ │ - static constexpr reopen_network_flags_t reopen_map_ports = 0_bit; │ │ │ │ │ + enum socket_type_t │ │ │ │ │ + { │ │ │ │ │ + tcp_socket, │ │ │ │ │ + utp_socket, │ │ │ │ │ + ssl_tcp_socket, │ │ │ │ │ + ssl_utp_socket, │ │ │ │ │ + i2p_socket, │ │ │ │ │ + num_socket_types, │ │ │ │ │ + }; │ │ │ │ │ }; │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** add() remove() ***** │ │ │ │ │ +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); │ │ │ │ │ +add() and remove() adds and removes a peer class to be added to new peers based │ │ │ │ │ +on socket type. │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** disallow() allow() ***** │ │ │ │ │ +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); │ │ │ │ │ +disallow() and allow() adds and removes a peer class to be removed from new │ │ │ │ │ +peers based on socket type. │ │ │ │ │ +The peer_class argument cannot be greater than 31. The bitmasks representing │ │ │ │ │ +peer classes in the peer_class_type_filter are 32 bits. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** is_valid() ***** │ │ │ │ │ -bool is_valid () const; │ │ │ │ │ -returns true if this handle refers to a valid session object. If the session │ │ │ │ │ -has been destroyed, all session_handle objects will expire and not be valid. │ │ │ │ │ +***** apply() ***** │ │ │ │ │ +std::uint32_t apply (socket_type_t const st, std::uint32_t peer_class_mask); │ │ │ │ │ +takes a bitmask of peer classes and returns a new bitmask of peer classes after │ │ │ │ │ +the rules have been applied, based on the socket type argument (st). │ │ │ │ │ [report_issue] │ │ │ │ │ -***** session_state() ***** │ │ │ │ │ -session_params session_state (save_state_flags_t flags = save_state_flags_t:: │ │ │ │ │ -all()) const; │ │ │ │ │ -returns the current session state. This can be passed to write_session_params() │ │ │ │ │ -to save the state to disk and restored using read_session_params() when │ │ │ │ │ -constructing a new session. The kind of state that's included is all settings, │ │ │ │ │ -the DHT routing table, possibly plugin-specific state. the flags parameter can │ │ │ │ │ -be used to only save certain parts of the session state │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** get_torrent_status() refresh_torrent_status() ***** │ │ │ │ │ -void refresh_torrent_status (std::vector* ret │ │ │ │ │ - , status_flags_t flags = {}) const; │ │ │ │ │ -std::vector get_torrent_status ( │ │ │ │ │ - std::function const& pred │ │ │ │ │ - , status_flags_t flags = {}) const; │ │ │ │ │ -Note │ │ │ │ │ -these calls are potentially expensive and won't scale well with lots of │ │ │ │ │ -torrents. If you're concerned about performance, consider using │ │ │ │ │ -post_torrent_updates() instead. │ │ │ │ │ -get_torrent_status returns a vector of the torrent_status for every torrent │ │ │ │ │ -which satisfies pred, which is a predicate function which determines if a │ │ │ │ │ -torrent should be included in the returned set or not. Returning true means it │ │ │ │ │ -should be included and false means excluded. The flags argument is the same as │ │ │ │ │ -to torrent_handle::status(). Since pred is guaranteed to be called for every │ │ │ │ │ -torrent, it may be used to count the number of torrents of different categories │ │ │ │ │ -as well. │ │ │ │ │ -refresh_torrent_status takes a vector of torrent_status structs (for instance │ │ │ │ │ -the same vector that was returned by get_torrent_status() ) and refreshes the │ │ │ │ │ -status based on the handle member. It is possible to use this function by first │ │ │ │ │ -setting up a vector of default constructed torrent_status objects, only │ │ │ │ │ -initializing the handle member, in order to request the torrent status for │ │ │ │ │ -multiple torrents in a single call. This can save a significant amount of time │ │ │ │ │ -if you have a lot of torrents. │ │ │ │ │ -Any torrent_status object whose handle member is not referring to a valid │ │ │ │ │ -torrent are ignored. │ │ │ │ │ -The intended use of these functions is to start off by calling │ │ │ │ │ -get_torrent_status() to get a list of all torrents that match your criteria. │ │ │ │ │ -Then call refresh_torrent_status() on that list. This will only refresh the │ │ │ │ │ -status for the torrents in your list, and thus ignore all other torrents you │ │ │ │ │ -might be running. This may save a significant amount of time, especially if the │ │ │ │ │ -number of torrents you're interested in is small. In order to keep your list of │ │ │ │ │ -interested torrents up to date, you can either call get_torrent_status() from │ │ │ │ │ -time to time, to include torrents you might have become interested in since the │ │ │ │ │ -last time. In order to stop refreshing a certain torrent, simply remove it from │ │ │ │ │ -the list. │ │ │ │ │ +***** enum socket_type_t ***** │ │ │ │ │ +Declared in "libtorrent/peer_class_type_filter.hpp" │ │ │ │ │ + ________________________________________________________________________ │ │ │ │ │ +|name____________|value|description______________________________________| │ │ │ │ │ +|tcp_socket |0 |these match the socket types from socket_type.hpp| │ │ │ │ │ +|________________|_____|shifted_one_down_________________________________| │ │ │ │ │ +|utp_socket______|1____| _______________________________________________| │ │ │ │ │ +|ssl_tcp_socket__|2____| _______________________________________________| │ │ │ │ │ +|ssl_utp_socket__|3____| _______________________________________________| │ │ │ │ │ +|i2p_socket______|4____| _______________________________________________| │ │ │ │ │ +|num_socket_types|5____| _______________________________________________| │ │ │ │ │ [report_issue] │ │ │ │ │ -***** post_torrent_updates() ***** │ │ │ │ │ -void post_torrent_updates (status_flags_t flags = status_flags_t::all()); │ │ │ │ │ -This functions instructs the session to post the state_update_alert, containing │ │ │ │ │ -the status of all torrents whose state changed since the last time this │ │ │ │ │ -function was called. │ │ │ │ │ -Only torrents who has the state subscription flag set will be included. This │ │ │ │ │ -flag is on by default. See add_torrent_params. the flags argument is the same │ │ │ │ │ -as for torrent_handle::status(). see status_flags_t in torrent_handle. │ │ │ │ │ +****** 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; │ │ │ │ │ +}; │ │ │ │ │ [report_issue] │ │ │ │ │ -***** post_session_stats() ***** │ │ │ │ │ -void post_session_stats (); │ │ │ │ │ -This function will post a session_stats_alert object, containing a snapshot of │ │ │ │ │ -the performance counters from the internals of libtorrent. To interpret these │ │ │ │ │ -counters, query the session via session_stats_metrics(). │ │ │ │ │ -For more information, see the session_statistics section. │ │ │ │ │ + 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. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** post_dht_stats() ***** │ │ │ │ │ -void post_dht_stats (); │ │ │ │ │ -This will cause a dht_stats_alert to be posted. │ │ │ │ │ + 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. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** set_dht_state() ***** │ │ │ │ │ -void set_dht_state (dht::dht_state const& st); │ │ │ │ │ -void set_dht_state (dht::dht_state&& st); │ │ │ │ │ -set the DHT state for the session. This will be taken into account the next │ │ │ │ │ -time the DHT is started, as if it had been passed in via the session_params on │ │ │ │ │ -startup. │ │ │ │ │ + label │ │ │ │ │ + not used by libtorrent. It's intended as a potentially user-facing │ │ │ │ │ + identifier of this peer class. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** find_torrent() get_torrents() ***** │ │ │ │ │ -std::vector get_torrents () const; │ │ │ │ │ -torrent_handle find_torrent (sha1_hash const& info_hash) const; │ │ │ │ │ -find_torrent() looks for a torrent with the given info-hash. In case there is │ │ │ │ │ -such a torrent in the session, a torrent_handle to that torrent is returned. In │ │ │ │ │ -case the torrent cannot be found, an invalid torrent_handle is returned. │ │ │ │ │ -See torrent_handle::is_valid() to know if the torrent was found or not. │ │ │ │ │ -get_torrents() returns a vector of torrent_handles to all the torrents │ │ │ │ │ -currently in the session. │ │ │ │ │ + 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. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** add_torrent() async_add_torrent() ***** │ │ │ │ │ -torrent_handle add_torrent (add_torrent_params&& params, error_code& ec); │ │ │ │ │ -torrent_handle add_torrent (add_torrent_params const& params, error_code& ec); │ │ │ │ │ -torrent_handle add_torrent (add_torrent_params&& params); │ │ │ │ │ -void async_add_torrent (add_torrent_params const& params); │ │ │ │ │ -void async_add_torrent (add_torrent_params&& params); │ │ │ │ │ -torrent_handle add_torrent (add_torrent_params const& params); │ │ │ │ │ -You add torrents through the add_torrent() function where you give an object │ │ │ │ │ -with all the parameters. The add_torrent() overloads will block until the │ │ │ │ │ -torrent has been added (or failed to be added) and returns an error code and a │ │ │ │ │ -torrent_handle. In order to add torrents more efficiently, consider using │ │ │ │ │ -async_add_torrent() which returns immediately, without waiting for the torrent │ │ │ │ │ -to add. Notification of the torrent being added is sent as add_torrent_alert. │ │ │ │ │ -The overload that does not take an error_code throws an exception on error and │ │ │ │ │ -is not available when building without exception support. The torrent_handle │ │ │ │ │ -returned by add_torrent() can be used to retrieve information about the │ │ │ │ │ -torrent's progress, its peers etc. It is also used to abort a torrent. │ │ │ │ │ -If the torrent you are trying to add already exists in the session (is either │ │ │ │ │ -queued for checking, being checked or downloading) add_torrent() will throw │ │ │ │ │ -system_error which derives from std::exception unless duplicate_is_error is set │ │ │ │ │ -to false. In that case, add_torrent() will return the handle to the existing │ │ │ │ │ -torrent. │ │ │ │ │ -The add_torrent_params class has a flags field. It can be used to control what │ │ │ │ │ -state the new torrent will be added in. Common flags to want to control are │ │ │ │ │ -torrent_flags::paused and torrent_flags::auto_managed. In order to add a magnet │ │ │ │ │ -link that will just download the metadata, but no payload, set the │ │ │ │ │ -torrent_flags::upload_mode flag. │ │ │ │ │ -Special consideration has to be taken when adding hybrid torrents (i.e. │ │ │ │ │ -torrents that are BitTorrent v2 torrents that are backwards compatible with │ │ │ │ │ -v1). For more details, see BitTorrent_v2_torrents. │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** resume() pause() is_paused() ***** │ │ │ │ │ -void pause (); │ │ │ │ │ -void resume (); │ │ │ │ │ -bool is_paused () const; │ │ │ │ │ -Pausing the session has the same effect as pausing every torrent in it, except │ │ │ │ │ -that torrents will not be resumed by the auto-manage mechanism. Resuming will │ │ │ │ │ -restore the torrents to their previous paused state. i.e. the session pause │ │ │ │ │ -state is separate from the torrent pause state. A torrent is inactive if it is │ │ │ │ │ -paused or if the session is paused. │ │ │ │ │ + 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. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** is_dht_running() ***** │ │ │ │ │ -bool is_dht_running () const; │ │ │ │ │ -is_dht_running() returns true if the DHT support has been started and false │ │ │ │ │ -otherwise. │ │ │ │ │ +****** storage_error ****** │ │ │ │ │ +Declared in "libtorrent/error_code.hpp" │ │ │ │ │ +used by storage to return errors also includes which underlying file the error │ │ │ │ │ +happened on │ │ │ │ │ +struct storage_error │ │ │ │ │ +{ │ │ │ │ │ + explicit operator bool () const; │ │ │ │ │ + file_index_t file () const; │ │ │ │ │ + void file (file_index_t f); │ │ │ │ │ + │ │ │ │ │ + error_code ec; │ │ │ │ │ + operation_t operation; │ │ │ │ │ +}; │ │ │ │ │ [report_issue] │ │ │ │ │ -***** set_dht_storage() ***** │ │ │ │ │ -void set_dht_storage (dht::dht_storage_constructor_type sc); │ │ │ │ │ -set_dht_storage set a dht custom storage constructor function to be used │ │ │ │ │ -internally when the dht is created. │ │ │ │ │ -Since the dht storage is a critical component for the dht behavior, this │ │ │ │ │ -function will only be effective the next time the dht is started. If you never │ │ │ │ │ -touch this feature, a default map-memory based storage is used. │ │ │ │ │ -If you want to make sure the dht is initially created with your custom storage, │ │ │ │ │ -create a session with the setting settings_pack::enable_dht to false, set your │ │ │ │ │ -constructor function and call apply_settings with settings_pack::enable_dht to │ │ │ │ │ -true. │ │ │ │ │ +***** bool() ***** │ │ │ │ │ +explicit operator bool () const; │ │ │ │ │ +explicitly converts to true if this object represents an error, and false if it │ │ │ │ │ +does not. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** add_dht_node() ***** │ │ │ │ │ -void add_dht_node (std::pair const& node); │ │ │ │ │ -add_dht_node takes a host name and port pair. That endpoint will be pinged, and │ │ │ │ │ -if a valid DHT reply is received, the node will be added to the routing table. │ │ │ │ │ +***** file() ***** │ │ │ │ │ +file_index_t file () const; │ │ │ │ │ +void file (file_index_t f); │ │ │ │ │ +set and query the index (in the torrent) of the file this error occurred on. │ │ │ │ │ +This may also have special values defined in torrent_status. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** dht_get_item() ***** │ │ │ │ │ -void dht_get_item (sha1_hash const& target); │ │ │ │ │ -query the DHT for an immutable item at the target hash. the result is posted as │ │ │ │ │ -a dht_immutable_item_alert. │ │ │ │ │ + ec │ │ │ │ │ + the error that occurred │ │ │ │ │ [report_issue] │ │ │ │ │ -***** dht_get_item() ***** │ │ │ │ │ -void dht_get_item (std::array key │ │ │ │ │ - , std::string salt = std::string()); │ │ │ │ │ -query the DHT for a mutable item under the public key key. this is an ed25519 │ │ │ │ │ -key. salt is optional and may be left as an empty string if no salt is to be │ │ │ │ │ -used. if the item is found in the DHT, a dht_mutable_item_alert is posted. │ │ │ │ │ + operation │ │ │ │ │ + A code from operation_t enum, indicating what kind of operation failed. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** dht_put_item() ***** │ │ │ │ │ -sha1_hash dht_put_item (entry data); │ │ │ │ │ -store the given bencoded data as an immutable item in the DHT. the returned │ │ │ │ │ -hash is the key that is to be used to look the item up again. It's just the │ │ │ │ │ -SHA-1 hash of the bencoded form of the structure. │ │ │ │ │ +****** libtorrent_category() ****** │ │ │ │ │ +Declared in "libtorrent/error_code.hpp" │ │ │ │ │ +boost::system::error_category& libtorrent_category (); │ │ │ │ │ +return the instance of the libtorrent_error_category which maps libtorrent │ │ │ │ │ +error codes to human readable error messages. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** dht_put_item() ***** │ │ │ │ │ -void dht_put_item (std::array key │ │ │ │ │ - , std::function& │ │ │ │ │ - , std::int64_t&, std::string const&)> cb │ │ │ │ │ - , std::string salt = std::string()); │ │ │ │ │ -store a mutable item. The key is the public key the blob is to be stored under. │ │ │ │ │ -The optional salt argument is a string that is to be mixed in with the key when │ │ │ │ │ -determining where in the DHT the value is to be stored. The callback function │ │ │ │ │ -is called from within the libtorrent network thread once we've found where to │ │ │ │ │ -store the blob, possibly with the current value stored under the key. The │ │ │ │ │ -values passed to the callback functions are: │ │ │ │ │ - entry& value │ │ │ │ │ - the current value stored under the key (may be empty). Also expected to │ │ │ │ │ - be set to the value to be stored by the function. │ │ │ │ │ - std::array& signature │ │ │ │ │ - the signature authenticating the current value. This may be zeros if │ │ │ │ │ - there is currently no value stored. The function is expected to fill in │ │ │ │ │ - this buffer with the signature of the new value to store. To generate the │ │ │ │ │ - signature, you may want to use the sign_mutable_item function. │ │ │ │ │ - std::int64_t& seq │ │ │ │ │ - current sequence number. May be zero if there is no current value. The │ │ │ │ │ - function is expected to set this to the new sequence number of the value │ │ │ │ │ - that is to be stored. Sequence numbers must be monotonically increasing. │ │ │ │ │ - Attempting to overwrite a value with a lower or equal sequence number │ │ │ │ │ - will fail, even if the signature is correct. │ │ │ │ │ - std::string const& salt │ │ │ │ │ - this is the salt that was used for this put call. │ │ │ │ │ -Since the callback function cb is called from within libtorrent, it is critical │ │ │ │ │ -to not perform any blocking operations. Ideally not even locking a mutex. Pass │ │ │ │ │ -any data required for this function along with the function object's context │ │ │ │ │ -and make the function entirely self-contained. The only reason data blob's │ │ │ │ │ -value is computed via a function instead of just passing in the new value is to │ │ │ │ │ -avoid race conditions. If you want to update the value in the DHT, you must │ │ │ │ │ -first retrieve it, then modify it, then write it back. The way the DHT works, │ │ │ │ │ -it is natural to always do a lookup before storing and calling the callback in │ │ │ │ │ -between is convenient. │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** dht_get_peers() dht_announce() ***** │ │ │ │ │ -void dht_announce (sha1_hash const& info_hash, int port = 0, dht:: │ │ │ │ │ -announce_flags_t flags = {}); │ │ │ │ │ -void dht_get_peers (sha1_hash const& info_hash); │ │ │ │ │ -dht_get_peers() will issue a DHT get_peer request to the DHT for the specified │ │ │ │ │ -info-hash. The response (the peers) will be posted back in a │ │ │ │ │ -dht_get_peers_reply_alert. │ │ │ │ │ -dht_announce() will issue a DHT announce request to the DHT to the specified │ │ │ │ │ -info-hash, advertising the specified port. If the port is left at its default, │ │ │ │ │ -0, the port will be implied by the DHT message's source port (which may improve │ │ │ │ │ -connectivity through a NAT). │ │ │ │ │ -Both these functions are exposed for advanced custom use of the DHT. All │ │ │ │ │ -torrents eligible to be announce to the DHT will be automatically, by │ │ │ │ │ -libtorrent. │ │ │ │ │ -For possible flags, see announce_flags_t. │ │ │ │ │ +****** http_category() ****** │ │ │ │ │ +Declared in "libtorrent/error_code.hpp" │ │ │ │ │ +boost::system::error_category& http_category (); │ │ │ │ │ +returns the error_category for HTTP errors │ │ │ │ │ [report_issue] │ │ │ │ │ -***** dht_live_nodes() ***** │ │ │ │ │ -void dht_live_nodes (sha1_hash const& nid); │ │ │ │ │ -Retrieve all the live DHT (identified by nid) nodes. All the nodes id and │ │ │ │ │ -endpoint will be returned in the list of nodes in the alert │ │ │ │ │ -dht_live_nodes_alert. Since this alert is a response to an explicit call, it │ │ │ │ │ -will always be posted, regardless of the alert mask. │ │ │ │ │ +****** pcp_category() ****** │ │ │ │ │ +Declared in "libtorrent/natpmp.hpp" │ │ │ │ │ +boost::system::error_category& pcp_category (); │ │ │ │ │ [report_issue] │ │ │ │ │ -***** dht_sample_infohashes() ***** │ │ │ │ │ -void dht_sample_infohashes (udp::endpoint const& ep, sha1_hash const& target); │ │ │ │ │ -Query the DHT node specified by ep to retrieve a sample of the info-hashes that │ │ │ │ │ -the node currently have in their storage. The target is included for iterative │ │ │ │ │ -lookups so that indexing nodes can perform a key space traversal with a single │ │ │ │ │ -RPC per node by adjusting the target value for each RPC. It has no effect on │ │ │ │ │ -the returned sample value. The result is posted as a │ │ │ │ │ -dht_sample_infohashes_alert. │ │ │ │ │ +****** upnp_category() ****** │ │ │ │ │ +Declared in "libtorrent/upnp.hpp" │ │ │ │ │ +boost::system::error_category& upnp_category (); │ │ │ │ │ +the boost.system error category for UPnP errors │ │ │ │ │ [report_issue] │ │ │ │ │ -***** dht_direct_request() ***** │ │ │ │ │ -void dht_direct_request (udp::endpoint const& ep, entry const& e, client_data_t │ │ │ │ │ -userdata = {}); │ │ │ │ │ -Send an arbitrary DHT request directly to the specified endpoint. This function │ │ │ │ │ -is intended for use by plugins. When a response is received or the request │ │ │ │ │ -times out, a dht_direct_response_alert will be posted with the response (if │ │ │ │ │ -any) and the userdata pointer passed in here. Since this alert is a response to │ │ │ │ │ -an explicit call, it will always be posted, regardless of the alert mask. │ │ │ │ │ +****** gzip_category() ****** │ │ │ │ │ +Declared in "libtorrent/gzip.hpp" │ │ │ │ │ +boost::system::error_category& gzip_category (); │ │ │ │ │ +get the error_category for zip errors │ │ │ │ │ [report_issue] │ │ │ │ │ -***** add_extension() ***** │ │ │ │ │ -void add_extension (std::function( │ │ │ │ │ - torrent_handle const&, client_data_t)> ext); │ │ │ │ │ -void add_extension (std::shared_ptr ext); │ │ │ │ │ -This function adds an extension to this session. The argument is a function │ │ │ │ │ -object that is called with a torrent_handle and which should return a std:: │ │ │ │ │ -shared_ptr. To write custom plugins, see libtorrent_plugins. │ │ │ │ │ -For the typical bittorrent client all of these extensions should be added. The │ │ │ │ │ -main plugins implemented in libtorrent are: │ │ │ │ │ - uTorrent metadata │ │ │ │ │ - Allows peers to download the metadata (.torrent files) from the swarm │ │ │ │ │ - directly. Makes it possible to join a swarm with just a tracker and info- │ │ │ │ │ - hash. │ │ │ │ │ -#include │ │ │ │ │ -ses.add_extension(<::create_ut_metadata_plugin); │ │ │ │ │ - uTorrent peer exchange │ │ │ │ │ - Exchanges peers between clients. │ │ │ │ │ -#include │ │ │ │ │ -ses.add_extension(<::create_ut_pex_plugin); │ │ │ │ │ - smart ban plugin │ │ │ │ │ - A plugin that, with a small overhead, can ban peers that sends bad data │ │ │ │ │ - with very high accuracy. Should eliminate most problems on poisoned │ │ │ │ │ - torrents. │ │ │ │ │ -#include │ │ │ │ │ -ses.add_extension(<::create_smart_ban_plugin); │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** get_ip_filter() set_ip_filter() ***** │ │ │ │ │ -void set_ip_filter (ip_filter f); │ │ │ │ │ -ip_filter get_ip_filter () const; │ │ │ │ │ -Sets a filter that will be used to reject and accept incoming as well as │ │ │ │ │ -outgoing connections based on their originating ip address. The default filter │ │ │ │ │ -will allow connections to any ip address. To build a set of rules for which │ │ │ │ │ -addresses are accepted and not, see ip_filter. │ │ │ │ │ -Each time a peer is blocked because of the IP filter, a peer_blocked_alert is │ │ │ │ │ -generated. get_ip_filter() Returns the ip_filter currently in the session. See │ │ │ │ │ -ip_filter. │ │ │ │ │ +****** socks_category() ****** │ │ │ │ │ +Declared in "libtorrent/socks5_stream.hpp" │ │ │ │ │ +boost::system::error_category& socks_category (); │ │ │ │ │ +returns the error_category for SOCKS5 errors │ │ │ │ │ [report_issue] │ │ │ │ │ -***** set_port_filter() ***** │ │ │ │ │ -void set_port_filter (port_filter const& f); │ │ │ │ │ -apply port_filter f to incoming and outgoing peers. a port filter will reject │ │ │ │ │ -making outgoing peer connections to certain remote ports. The main intention is │ │ │ │ │ -to be able to avoid triggering certain anti-virus software by connecting to │ │ │ │ │ -SMTP, FTP ports. │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** ssl_listen_port() listen_port() is_listening() ***** │ │ │ │ │ -unsigned short ssl_listen_port () const; │ │ │ │ │ -unsigned short listen_port () const; │ │ │ │ │ -bool is_listening () const; │ │ │ │ │ -is_listening() will tell you whether or not the session has successfully opened │ │ │ │ │ -a listening port. If it hasn't, this function will return false, and then you │ │ │ │ │ -can set a new settings_pack::listen_interfaces to try another interface and │ │ │ │ │ -port to bind to. │ │ │ │ │ -listen_port() returns the port we ended up listening on. │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** set_peer_class_filter() get_peer_class_filter() ***** │ │ │ │ │ -ip_filter get_peer_class_filter () const; │ │ │ │ │ -void set_peer_class_filter (ip_filter const& f); │ │ │ │ │ -Sets the peer class filter for this session. All new peer connections will take │ │ │ │ │ -this into account and be added to the peer classes specified by this filter, │ │ │ │ │ -based on the peer's IP address. │ │ │ │ │ -The ip-filter essentially maps an IP -> uint32. Each bit in that 32 bit integer │ │ │ │ │ -represents a peer class. The least significant bit represents class 0, the next │ │ │ │ │ -bit class 1 and so on. │ │ │ │ │ -For more info, see ip_filter. │ │ │ │ │ -For example, to make all peers in the range 200.1.1.0 - 200.1.255.255 belong to │ │ │ │ │ -their own peer class, apply the following filter: │ │ │ │ │ -ip_filter f = ses.get_peer_class_filter(); │ │ │ │ │ -peer_class_t my_class = ses.create_peer_class("200.1.x.x IP range"); │ │ │ │ │ -f.add_rule(make_address("200.1.1.0"), make_address("200.1.255.255") │ │ │ │ │ - , 1 << static_cast(my_class)); │ │ │ │ │ -ses.set_peer_class_filter(f); │ │ │ │ │ -This setting only applies to new connections, it won't affect existing peer │ │ │ │ │ -connections. │ │ │ │ │ -This function is limited to only peer class 0-31, since there are only 32 bits │ │ │ │ │ -in the IP range mapping. Only the set bits matter; no peer class will be │ │ │ │ │ -removed from a peer as a result of this call, peer classes are only added. │ │ │ │ │ -The peer_class argument cannot be greater than 31. The bitmasks representing │ │ │ │ │ -peer classes in the peer_class_filter are 32 bits. │ │ │ │ │ -The get_peer_class_filter() function returns the current filter. │ │ │ │ │ -For more information, see peer_classes. │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** get_peer_class_type_filter() set_peer_class_type_filter() ***** │ │ │ │ │ -void set_peer_class_type_filter (peer_class_type_filter const& f); │ │ │ │ │ -peer_class_type_filter get_peer_class_type_filter () const; │ │ │ │ │ -Sets and gets the peer class type filter. This is controls automatic peer class │ │ │ │ │ -assignments to peers based on what kind of socket it is. │ │ │ │ │ -It does not only support assigning peer classes, it also supports removing peer │ │ │ │ │ -classes based on socket type. │ │ │ │ │ -The order of these rules being applied are: │ │ │ │ │ - 1. peer-class IP filter │ │ │ │ │ - 2. peer-class type filter, removing classes │ │ │ │ │ - 3. peer-class type filter, adding classes │ │ │ │ │ -For more information, see peer_classes. │ │ │ │ │ +****** i2p_category() ****** │ │ │ │ │ +Declared in "libtorrent/i2p_stream.hpp" │ │ │ │ │ +boost::system::error_category& i2p_category (); │ │ │ │ │ +returns the error category for I2P errors │ │ │ │ │ [report_issue] │ │ │ │ │ -***** create_peer_class() ***** │ │ │ │ │ -peer_class_t create_peer_class (char const* name); │ │ │ │ │ -Creates a new peer class (see peer_classes) with the given name. The returned │ │ │ │ │ -integer is the new peer class identifier. Peer classes may have the same name, │ │ │ │ │ -so each invocation of this function creates a new class and returns a unique │ │ │ │ │ -identifier. │ │ │ │ │ -Identifiers are assigned from low numbers to higher. So if you plan on using │ │ │ │ │ -certain peer classes in a call to set_peer_class_filter(), make sure to create │ │ │ │ │ -those early on, to get low identifiers. │ │ │ │ │ -For more information on peer classes, see peer_classes. │ │ │ │ │ +****** bdecode_category() ****** │ │ │ │ │ +Declared in "libtorrent/bdecode.hpp" │ │ │ │ │ +boost::system::error_category& bdecode_category (); │ │ │ │ │ [report_issue] │ │ │ │ │ -***** delete_peer_class() ***** │ │ │ │ │ -void delete_peer_class (peer_class_t cid); │ │ │ │ │ -This call dereferences the reference count of the specified peer class. When │ │ │ │ │ -creating a peer class it's automatically referenced by 1. If you want to │ │ │ │ │ -recycle a peer class, you may call this function. You may only call this │ │ │ │ │ -function once per peer class you create. Calling it more than once for the same │ │ │ │ │ -class will lead to memory corruption. │ │ │ │ │ -Since peer classes are reference counted, this function will not remove the │ │ │ │ │ -peer class if it's still assigned to torrents or peers. It will however remove │ │ │ │ │ -it once the last peer and torrent drops their references to it. │ │ │ │ │ -There is no need to call this function for custom peer classes. All peer │ │ │ │ │ -classes will be properly destructed when the session object destructs. │ │ │ │ │ -For more information on peer classes, see peer_classes. │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** set_peer_class() get_peer_class() ***** │ │ │ │ │ -peer_class_info get_peer_class (peer_class_t cid) const; │ │ │ │ │ -void set_peer_class (peer_class_t cid, peer_class_info const& pci); │ │ │ │ │ -These functions queries information from a peer class and updates the │ │ │ │ │ -configuration of a peer class, respectively. │ │ │ │ │ -cid must refer to an existing peer class. If it does not, the return value of │ │ │ │ │ -get_peer_class() is undefined. │ │ │ │ │ -set_peer_class() sets all the information in the peer_class_info object in the │ │ │ │ │ -specified peer class. There is no option to only update a single property. │ │ │ │ │ -A peer or torrent belonging to more than one class, the highest priority among │ │ │ │ │ -any of its classes is the one that is taken into account. │ │ │ │ │ -For more information, see peer_classes. │ │ │ │ │ +****** enum error_code_enum ****** │ │ │ │ │ +Declared in "libtorrent/error_code.hpp" │ │ │ │ │ + _____________________________________________________________________________ │ │ │ │ │ +|name________________________________|value|description_______________________| │ │ │ │ │ +|no_error____________________________|0____|Not_an_error______________________| │ │ │ │ │ +|file_collision |1 |Two torrents has files which end | │ │ │ │ │ +|____________________________________|_____|up_overwriting_each_other_________| │ │ │ │ │ +|failed_hash_check |2 |A piece did not match its piece | │ │ │ │ │ +|____________________________________|_____|hash______________________________| │ │ │ │ │ +| | |The .torrent file does not contain| │ │ │ │ │ +|torrent_is_no_dict |3 |a bencoded dictionary at its top | │ │ │ │ │ +|____________________________________|_____|level_____________________________| │ │ │ │ │ +|torrent_missing_info |4 |The .torrent file does not have an| │ │ │ │ │ +|____________________________________|_____|info_dictionary___________________| │ │ │ │ │ +|torrent_info_no_dict |5 |The .torrent file's info entry is | │ │ │ │ │ +|____________________________________|_____|not_a_dictionary__________________| │ │ │ │ │ +|torrent_missing_piece_length |6 |The .torrent file does not have a | │ │ │ │ │ +|____________________________________|_____|piece_length_entry________________| │ │ │ │ │ +|torrent_missing_name |7 |The .torrent file does not have a | │ │ │ │ │ +|____________________________________|_____|name_entry________________________| │ │ │ │ │ +|torrent_invalid_name |8 |The .torrent file's name entry is | │ │ │ │ │ +|____________________________________|_____|invalid___________________________| │ │ │ │ │ +| | |The length of a file, or of the | │ │ │ │ │ +|torrent_invalid_length |9 |whole .torrent file is invalid. | │ │ │ │ │ +|____________________________________|_____|Either_negative_or_not_an_integer_| │ │ │ │ │ +|torrent_file_parse_failed |10 |Failed to parse a file entry in | │ │ │ │ │ +|____________________________________|_____|the_.torrent______________________| │ │ │ │ │ +|torrent_missing_pieces |11 |The pieces field is missing or | │ │ │ │ │ +|____________________________________|_____|invalid_in_the_.torrent_file______| │ │ │ │ │ +|torrent_invalid_hashes |12 |The pieces string has incorrect | │ │ │ │ │ +|____________________________________|_____|length____________________________| │ │ │ │ │ +|too_many_pieces_in_torrent |13 |The .torrent file has more pieces | │ │ │ │ │ +|____________________________________|_____|than_is_supported_by_libtorrent___| │ │ │ │ │ +| | |The metadata (.torrent file) that | │ │ │ │ │ +|invalid_swarm_metadata |14 |was received from the swarm | │ │ │ │ │ +| | |matched the info-hash, but failed | │ │ │ │ │ +|____________________________________|_____|to_be_parsed______________________| │ │ │ │ │ +|invalid_bencoding |15 |The file or buffer is not | │ │ │ │ │ +|____________________________________|_____|correctly_bencoded________________| │ │ │ │ │ +|no_files_in_torrent |16 |The .torrent file does not contain| │ │ │ │ │ +|____________________________________|_____|any_files_________________________| │ │ │ │ │ +|invalid_escaped_string |17 |The string was not properly url- | │ │ │ │ │ +|____________________________________|_____|encoded_as_expected_______________| │ │ │ │ │ +|session_is_closing |18 |Operation is not permitted since | │ │ │ │ │ +|____________________________________|_____|the_session_is_shutting_down______| │ │ │ │ │ +| | |There's already a torrent with | │ │ │ │ │ +|duplicate_torrent |19 |that info-hash added to the | │ │ │ │ │ +|____________________________________|_____|session___________________________| │ │ │ │ │ +|invalid_torrent_handle |20 |The supplied torrent_handle is not| │ │ │ │ │ +|____________________________________|_____|referring_to_a_valid_torrent______| │ │ │ │ │ +|invalid_entry_type |21 |The type requested from the entry | │ │ │ │ │ +|____________________________________|_____|did_not_match_its_type____________| │ │ │ │ │ +|missing_info_hash_in_uri |22 |The specified URI does not contain| │ │ │ │ │ +|____________________________________|_____|a_valid_info-hash_________________| │ │ │ │ │ +| | |One of the files in the torrent | │ │ │ │ │ +|file_too_short |23 |was unexpectedly small. This might| │ │ │ │ │ +| | |be caused by files being changed | │ │ │ │ │ +|____________________________________|_____|by_an_external_process____________| │ │ │ │ │ +| | |The URL used an unknown protocol. | │ │ │ │ │ +| | |Currently http and https (if built| │ │ │ │ │ +|unsupported_url_protocol |24 |with openssl support) are | │ │ │ │ │ +| | |recognized. For trackers udp is | │ │ │ │ │ +|____________________________________|_____|recognized_as_well._______________| │ │ │ │ │ +|url_parse_error |25 |The URL did not conform to URL | │ │ │ │ │ +|____________________________________|_____|syntax_and_failed_to_be_parsed____| │ │ │ │ │ +|peer_sent_empty_piece |26 |The peer sent a piece message of | │ │ │ │ │ +|____________________________________|_____|length_0__________________________| │ │ │ │ │ +|parse_failed |27 |A bencoded structure was corrupt | │ │ │ │ │ +|____________________________________|_____|and_failed_to_be_parsed___________| │ │ │ │ │ +|invalid_file_tag |28 |The fast resume file was missing | │ │ │ │ │ +|____________________________________|_____|or_had_an_invalid_file_version_tag| │ │ │ │ │ +|missing_info_hash |29 |The fast resume file was missing | │ │ │ │ │ +|____________________________________|_____|or_had_an_invalid_info-hash_______| │ │ │ │ │ +|mismatching_info_hash |30 |The info-hash did not match the | │ │ │ │ │ +|____________________________________|_____|torrent___________________________| │ │ │ │ │ +|invalid_hostname |31 |The URL contained an invalid | │ │ │ │ │ +|____________________________________|_____|hostname__________________________| │ │ │ │ │ +|invalid_port________________________|32___|The_URL_had_an_invalid_port_______| │ │ │ │ │ +| | |The port is blocked by the port- | │ │ │ │ │ +|port_blocked |33 |filter, and prevented the | │ │ │ │ │ +|____________________________________|_____|connection________________________| │ │ │ │ │ +|expected_close_bracket_in_address |34 |The IPv6 address was expected to | │ │ │ │ │ +|____________________________________|_____|end_with_"]"______________________| │ │ │ │ │ +| | |The torrent is being destructed, | │ │ │ │ │ +|destructing_torrent |35 |preventing the operation to | │ │ │ │ │ +|____________________________________|_____|succeed___________________________| │ │ │ │ │ +|timed_out___________________________|36___|The_connection_timed_out__________| │ │ │ │ │ +| | |The peer is upload only, and we | │ │ │ │ │ +|upload_upload_connection |37 |are upload only. There's no point | │ │ │ │ │ +|____________________________________|_____|in_keeping_the_connection_________| │ │ │ │ │ +| | |The peer is upload only, and we're| │ │ │ │ │ +|uninteresting_upload_peer |38 |not interested in it. There's no | │ │ │ │ │ +|____________________________________|_____|point_in_keeping_the_connection___| │ │ │ │ │ +|invalid_info_hash___________________|39___|The_peer_sent_an_unknown_info-hash| │ │ │ │ │ +|torrent_paused |40 |The torrent is paused, preventing | │ │ │ │ │ +|____________________________________|_____|the_operation_from_succeeding_____| │ │ │ │ │ +| | |The peer sent an invalid have | │ │ │ │ │ +|invalid_have |41 |message, either wrong size or | │ │ │ │ │ +| | |referring to a piece that doesn't | │ │ │ │ │ +|____________________________________|_____|exist_in_the_torrent______________| │ │ │ │ │ +|invalid_bitfield_size |42 |The bitfield message had the | │ │ │ │ │ +|____________________________________|_____|incorrect_size____________________| │ │ │ │ │ +| | |The peer kept requesting pieces | │ │ │ │ │ +|too_many_requests_when_choked |43 |after it was choked, possible | │ │ │ │ │ +|____________________________________|_____|abuse_attempt.____________________| │ │ │ │ │ +| | |The peer sent a piece message that| │ │ │ │ │ +|invalid_piece |44 |does not correspond to a piece | │ │ │ │ │ +|____________________________________|_____|request_sent_by_the_client________| │ │ │ │ │ +|no_memory___________________________|45___|memory_allocation_failed__________| │ │ │ │ │ +|torrent_aborted |46 |The torrent is aborted, preventing| │ │ │ │ │ +|____________________________________|_____|the_operation_to_succeed__________| │ │ │ │ │ +|self_connection |47 |The peer is a connection to | │ │ │ │ │ +|____________________________________|_____|ourself,_no_point_in_keeping_it___| │ │ │ │ │ +| | |The peer sent a piece message with| │ │ │ │ │ +|invalid_piece_size |48 |invalid size, either negative or | │ │ │ │ │ +|____________________________________|_____|greater_than_one_block____________| │ │ │ │ │ +| | |The peer has not been interesting | │ │ │ │ │ +|timed_out_no_interest |49 |or interested in us for too long, | │ │ │ │ │ +|____________________________________|_____|no_point_in_keeping_it_around_____| │ │ │ │ │ +|timed_out_inactivity |50 |The peer has not said anything in | │ │ │ │ │ +|____________________________________|_____|a_long_time,_possibly_dead________| │ │ │ │ │ +| | |The peer did not send a handshake | │ │ │ │ │ +|timed_out_no_handshake |51 |within a reasonable amount of | │ │ │ │ │ +| | |time, it might not be a bittorrent| │ │ │ │ │ +|____________________________________|_____|peer______________________________| │ │ │ │ │ +| | |The peer has been unchoked for too| │ │ │ │ │ +|timed_out_no_request |52 |long without requesting any data. | │ │ │ │ │ +| | |It might be lying about its | │ │ │ │ │ +|____________________________________|_____|interest_in_us____________________| │ │ │ │ │ +|invalid_choke |53 |The peer sent an invalid choke | │ │ │ │ │ +|____________________________________|_____|message___________________________| │ │ │ │ │ +|invalid_unchoke |54 |The peer send an invalid unchoke | │ │ │ │ │ +|____________________________________|_____|message___________________________| │ │ │ │ │ +|invalid_interested |55 |The peer sent an invalid | │ │ │ │ │ +|____________________________________|_____|interested_message________________| │ │ │ │ │ +|invalid_not_interested |56 |The peer sent an invalid not- | │ │ │ │ │ +|____________________________________|_____|interested_message________________| │ │ │ │ │ +|invalid_request |57 |The peer sent an invalid piece | │ │ │ │ │ +|____________________________________|_____|request_message___________________| │ │ │ │ │ +| | |The peer sent an invalid hash-list| │ │ │ │ │ +|invalid_hash_list |58 |message (this is part of the | │ │ │ │ │ +|____________________________________|_____|merkle-torrent_extension)_________| │ │ │ │ │ +| | |The peer sent an invalid hash- | │ │ │ │ │ +|invalid_hash_piece |59 |piece message (this is part of the| │ │ │ │ │ +|____________________________________|_____|merkle-torrent_extension)_________| │ │ │ │ │ +|invalid_cancel |60 |The peer sent an invalid cancel | │ │ │ │ │ +|____________________________________|_____|message___________________________| │ │ │ │ │ +|invalid_dht_port |61 |The peer sent an invalid DHT port-| │ │ │ │ │ +|____________________________________|_____|message___________________________| │ │ │ │ │ +|invalid_suggest |62 |The peer sent an invalid suggest | │ │ │ │ │ +|____________________________________|_____|piece-message_____________________| │ │ │ │ │ +|invalid_have_all |63 |The peer sent an invalid have all-| │ │ │ │ │ +|____________________________________|_____|message___________________________| │ │ │ │ │ +|invalid_have_none |64 |The peer sent an invalid have | │ │ │ │ │ +|____________________________________|_____|none-message______________________| │ │ │ │ │ +|invalid_reject |65 |The peer sent an invalid reject | │ │ │ │ │ +|____________________________________|_____|message___________________________| │ │ │ │ │ +|invalid_allow_fast |66 |The peer sent an invalid allow | │ │ │ │ │ +|____________________________________|_____|fast-message______________________| │ │ │ │ │ +|invalid_extended |67 |The peer sent an invalid extension| │ │ │ │ │ +|____________________________________|_____|message_ID________________________| │ │ │ │ │ +|invalid_message |68 |The peer sent an invalid message | │ │ │ │ │ +|____________________________________|_____|ID________________________________| │ │ │ │ │ +|sync_hash_not_found |69 |The synchronization hash was not | │ │ │ │ │ +|____________________________________|_____|found_in_the_encrypted_handshake__| │ │ │ │ │ +|invalid_encryption_constant |70 |The encryption constant in the | │ │ │ │ │ +|____________________________________|_____|handshake_is_invalid______________| │ │ │ │ │ +|no_plaintext_mode |71 |The peer does not support plain | │ │ │ │ │ +|____________________________________|_____|text,_which_is_the_selected_mode__| │ │ │ │ │ +|no_rc4_mode |72 |The peer does not support RC4, | │ │ │ │ │ +|____________________________________|_____|which_is_the_selected_mode________| │ │ │ │ │ +| | |The peer does not support any of | │ │ │ │ │ +|unsupported_encryption_mode |73 |the encryption modes that the | │ │ │ │ │ +|____________________________________|_____|client_supports___________________| │ │ │ │ │ +| | |The peer selected an encryption | │ │ │ │ │ +|unsupported_encryption_mode_selected|74 |mode that the client did not | │ │ │ │ │ +|____________________________________|_____|advertise_and_does_not_support____| │ │ │ │ │ +| | |The pad size used in the | │ │ │ │ │ +|invalid_pad_size |75 |encryption handshake is of invalid| │ │ │ │ │ +|____________________________________|_____|size______________________________| │ │ │ │ │ +|invalid_encrypt_handshake |76 |The encryption handshake is | │ │ │ │ │ +|____________________________________|_____|invalid___________________________| │ │ │ │ │ +| | |The client is set to not support | │ │ │ │ │ +|no_incoming_encrypted |77 |incoming encrypted connections and| │ │ │ │ │ +|____________________________________|_____|this_is_an_encrypted_connection___| │ │ │ │ │ +| | |The client is set to not support | │ │ │ │ │ +|no_incoming_regular |78 |incoming regular bittorrent | │ │ │ │ │ +| | |connections, and this is a regular| │ │ │ │ │ +|____________________________________|_____|connection________________________| │ │ │ │ │ +|duplicate_peer_id |79 |The client is already connected to| │ │ │ │ │ +|____________________________________|_____|this_peer-ID______________________| │ │ │ │ │ +|torrent_removed_____________________|80___|Torrent_was_removed_______________| │ │ │ │ │ +|packet_too_large |81 |The packet size exceeded the upper| │ │ │ │ │ +|____________________________________|_____|sanity_check-limit________________| │ │ │ │ │ +|reserved____________________________|82___| ________________________________| │ │ │ │ │ +|http_error |83 |The web server responded with an | │ │ │ │ │ +|____________________________________|_____|error_____________________________| │ │ │ │ │ +|missing_location |84 |The web server response is missing| │ │ │ │ │ +|____________________________________|_____|a_location_header_________________| │ │ │ │ │ +| | |The web seed redirected to a path | │ │ │ │ │ +|invalid_redirection |85 |that no longer matches the | │ │ │ │ │ +|____________________________________|_____|.torrent_directory_structure______| │ │ │ │ │ +|redirecting |86 |The connection was closed because | │ │ │ │ │ +|____________________________________|_____|it_redirected_to_a_different_URL__| │ │ │ │ │ +|invalid_range_______________________|87___|The_HTTP_range_header_is_invalid__| │ │ │ │ │ +|no_content_length |88 |The HTTP response did not have a | │ │ │ │ │ +|____________________________________|_____|content_length____________________| │ │ │ │ │ +|banned_by_ip_filter_________________|89___|The_IP_is_blocked_by_the_IP_filter| │ │ │ │ │ +|too_many_connections________________|90___|At_the_connection_limit___________| │ │ │ │ │ +|peer_banned_________________________|91___|The_peer_is_marked_as_banned______| │ │ │ │ │ +|stopping_torrent |92 |The torrent is stopping, causing | │ │ │ │ │ +|____________________________________|_____|the_operation_to_fail_____________| │ │ │ │ │ +|too_many_corrupt_pieces |93 |The peer has sent too many corrupt| │ │ │ │ │ +|____________________________________|_____|pieces_and_is_banned______________| │ │ │ │ │ +|torrent_not_ready |94 |The torrent is not ready to | │ │ │ │ │ +|____________________________________|_____|receive_peers_____________________| │ │ │ │ │ +|peer_not_constructed |95 |The peer is not completely | │ │ │ │ │ +|____________________________________|_____|constructed_yet___________________| │ │ │ │ │ +|session_closing |96 |The session is closing, causing | │ │ │ │ │ +|____________________________________|_____|the_operation_to_fail_____________| │ │ │ │ │ +| | |The peer was disconnected in order| │ │ │ │ │ +|optimistic_disconnect |97 |to leave room for a potentially | │ │ │ │ │ +|____________________________________|_____|better_peer_______________________| │ │ │ │ │ +|torrent_finished____________________|98___|The_torrent_is_finished___________| │ │ │ │ │ +|no_router___________________________|99___|No_UPnP_router_found______________| │ │ │ │ │ +|metadata_too_large |100 |The metadata message says the | │ │ │ │ │ +|____________________________________|_____|metadata_exceeds_the_limit________| │ │ │ │ │ +|invalid_metadata_request |101 |The peer sent an invalid metadata | │ │ │ │ │ +|____________________________________|_____|request_message___________________| │ │ │ │ │ +|invalid_metadata_size |102 |The peer advertised an invalid | │ │ │ │ │ +|____________________________________|_____|metadata_size_____________________| │ │ │ │ │ +|invalid_metadata_offset |103 |The peer sent a message with an | │ │ │ │ │ +|____________________________________|_____|invalid_metadata_offset___________| │ │ │ │ │ +|invalid_metadata_message |104 |The peer sent an invalid metadata | │ │ │ │ │ +|____________________________________|_____|message___________________________| │ │ │ │ │ +|pex_message_too_large |105 |The peer sent a peer exchange | │ │ │ │ │ +|____________________________________|_____|message_that_was_too_large________| │ │ │ │ │ +|invalid_pex_message |106 |The peer sent an invalid peer | │ │ │ │ │ +|____________________________________|_____|exchange_message__________________| │ │ │ │ │ +|invalid_lt_tracker_message |107 |The peer sent an invalid tracker | │ │ │ │ │ +|____________________________________|_____|exchange_message__________________| │ │ │ │ │ +| | |The peer sent an pex messages too | │ │ │ │ │ +|too_frequent_pex |108 |often. This is a possible attempt | │ │ │ │ │ +|____________________________________|_____|of_and_attack_____________________| │ │ │ │ │ +| | |The operation failed because it | │ │ │ │ │ +| | |requires the torrent to have the | │ │ │ │ │ +| | |metadata (.torrent file) and it | │ │ │ │ │ +|no_metadata |109 |doesn't have it yet. This happens | │ │ │ │ │ +| | |for magnet links before they have | │ │ │ │ │ +| | |downloaded the metadata, and also | │ │ │ │ │ +|____________________________________|_____|torrents_added_by_URL.____________| │ │ │ │ │ +| | |The peer sent an invalid dont_have| │ │ │ │ │ +| | |message. The don't have message is| │ │ │ │ │ +|invalid_dont_have |110 |an extension to allow peers to | │ │ │ │ │ +| | |advertise that the no longer has a| │ │ │ │ │ +|____________________________________|_____|piece_they_previously_had.________| │ │ │ │ │ +| | |The peer tried to connect to an | │ │ │ │ │ +|requires_ssl_connection |111 |SSL torrent without connecting | │ │ │ │ │ +|____________________________________|_____|over_SSL._________________________| │ │ │ │ │ +| | |The peer tried to connect to a | │ │ │ │ │ +|invalid_ssl_cert |112 |torrent with a certificate for a | │ │ │ │ │ +|____________________________________|_____|different_torrent.________________| │ │ │ │ │ +| | |the torrent is not an SSL torrent,| │ │ │ │ │ +|not_an_ssl_torrent |113 |and the operation requires an SSL | │ │ │ │ │ +|____________________________________|_____|torrent___________________________| │ │ │ │ │ +| | |peer was banned because its listen| │ │ │ │ │ +|banned_by_port_filter |114 |port is within a banned port | │ │ │ │ │ +| | |range, as specified by the | │ │ │ │ │ +|____________________________________|_____|port_filter.______________________| │ │ │ │ │ +|invalid_session_handle |115 |The session_handle is not | │ │ │ │ │ +|____________________________________|_____|referring_to_a_valid_session_impl_| │ │ │ │ │ +|invalid_listen_socket |116 |the listen socket associated with | │ │ │ │ │ +|____________________________________|_____|this_request_was_closed___________| │ │ │ │ │ +|invalid_hash_request________________|117__| ________________________________| │ │ │ │ │ +|invalid_hashes______________________|118__| ________________________________| │ │ │ │ │ +|invalid_hash_reject_________________|119__| ________________________________| │ │ │ │ │ +|deprecated_120______________________|120__| ________________________________| │ │ │ │ │ +|deprecated_121______________________|121__| ________________________________| │ │ │ │ │ +|deprecated_122______________________|122__| ________________________________| │ │ │ │ │ +|deprecated_123______________________|123__| ________________________________| │ │ │ │ │ +|deprecated_124______________________|124__| ________________________________| │ │ │ │ │ +|missing_file_sizes |130 |The resume data file is missing | │ │ │ │ │ +|____________________________________|_____|the_file_sizes_entry______________| │ │ │ │ │ +|no_files_in_resume_data |131 |The resume data file file sizes | │ │ │ │ │ +|____________________________________|_____|entry_is_empty____________________| │ │ │ │ │ +|missing_pieces |132 |The resume data file is missing | │ │ │ │ │ +|____________________________________|_____|the_pieces_and_slots_entry________| │ │ │ │ │ +| | |The number of files in the resume | │ │ │ │ │ +|mismatching_number_of_files |133 |data does not match the number of | │ │ │ │ │ +|____________________________________|_____|files_in_the_torrent______________| │ │ │ │ │ +| | |One of the files on disk has a | │ │ │ │ │ +|mismatching_file_size |134 |different size than in the fast | │ │ │ │ │ +|____________________________________|_____|resume_file_______________________| │ │ │ │ │ +| | |One of the files on disk has a | │ │ │ │ │ +|mismatching_file_timestamp |135 |different timestamp than in the | │ │ │ │ │ +|____________________________________|_____|fast_resume_file__________________| │ │ │ │ │ +|not_a_dictionary |136 |The resume data file is not a | │ │ │ │ │ +|____________________________________|_____|dictionary________________________| │ │ │ │ │ +|invalid_blocks_per_piece |137 |The blocks per piece entry is | │ │ │ │ │ +|____________________________________|_____|invalid_in_the_resume_data_file___| │ │ │ │ │ +| | |The resume file is missing the | │ │ │ │ │ +|missing_slots |138 |slots entry, which is required for| │ │ │ │ │ +| | |torrents with compact allocation. | │ │ │ │ │ +|____________________________________|_____|DEPRECATED________________________| │ │ │ │ │ +|too_many_slots |139 |The resume file contains more | │ │ │ │ │ +|____________________________________|_____|slots_than_the_torrent____________| │ │ │ │ │ +|invalid_slot_list |140 |The slot entry is invalid in the | │ │ │ │ │ +|____________________________________|_____|resume_data_______________________| │ │ │ │ │ +|invalid_piece_index |141 |One index in the slot list is | │ │ │ │ │ +|____________________________________|_____|invalid___________________________| │ │ │ │ │ +| | |The pieces on disk needs to be re-| │ │ │ │ │ +| | |ordered for the specified | │ │ │ │ │ +| | |allocation mode. This happens if | │ │ │ │ │ +|pieces_need_reorder |142 |you specify sparse allocation and | │ │ │ │ │ +| | |the files on disk are using | │ │ │ │ │ +| | |compact storage. The pieces needs | │ │ │ │ │ +| | |to be moved to their right | │ │ │ │ │ +|____________________________________|_____|position._DEPRECATED______________| │ │ │ │ │ +| | |this error is returned when asking| │ │ │ │ │ +| | |to save resume data and specifying| │ │ │ │ │ +|resume_data_not_modified |143 |the flag to only save when there's| │ │ │ │ │ +| | |anything new to save | │ │ │ │ │ +| | |(torrent_handle::only_if_modified)| │ │ │ │ │ +|____________________________________|_____|and_there_wasn't_anything_changed.| │ │ │ │ │ +|http_parse_error |150 |The HTTP header was not correctly | │ │ │ │ │ +|____________________________________|_____|formatted_________________________| │ │ │ │ │ +| | |The HTTP response was in the 300- | │ │ │ │ │ +|http_missing_location |151 |399 range but lacked a location | │ │ │ │ │ +|____________________________________|_____|header____________________________| │ │ │ │ │ +| | |The HTTP response was encoded with| │ │ │ │ │ +|http_failed_decompress |152 |gzip or deflate but decompressing | │ │ │ │ │ +|____________________________________|_____|it_failed_________________________| │ │ │ │ │ +|no_i2p_router |160 |The URL specified an i2p address, | │ │ │ │ │ +|____________________________________|_____|but_no_i2p_router_is_configured___| │ │ │ │ │ +|no_i2p_endpoint |161 |i2p acceptor is not available yet,| │ │ │ │ │ +|____________________________________|_____|can't_announce_without_endpoint___| │ │ │ │ │ +| | |The tracker URL doesn't support | │ │ │ │ │ +|scrape_not_available |170 |transforming it into a scrape URL.| │ │ │ │ │ +|____________________________________|_____|i.e._it_doesn't_contain_"announce.| │ │ │ │ │ +|invalid_tracker_response____________|171__|invalid_tracker_response__________| │ │ │ │ │ +|invalid_peer_dict |172 |invalid peer dictionary entry. Not| │ │ │ │ │ +|____________________________________|_____|a_dictionary______________________| │ │ │ │ │ +|tracker_failure_____________________|173__|tracker_sent_a_failure_message____| │ │ │ │ │ +|invalid_files_entry_________________|174__|missing_or_invalid_files_entry____| │ │ │ │ │ +|invalid_hash_entry__________________|175__|missing_or_invalid_hash_entry_____| │ │ │ │ │ +|invalid_peers_entry |176 |missing or invalid peers and | │ │ │ │ │ +|____________________________________|_____|peers6_entry______________________| │ │ │ │ │ +|invalid_tracker_response_length |177 |UDP tracker response packet has | │ │ │ │ │ +|____________________________________|_____|invalid_size______________________| │ │ │ │ │ +|invalid_tracker_transaction_id |178 |invalid transaction id in UDP | │ │ │ │ │ +|____________________________________|_____|tracker_response__________________| │ │ │ │ │ +|invalid_tracker_action |179 |invalid action field in UDP | │ │ │ │ │ +|____________________________________|_____|tracker_response__________________| │ │ │ │ │ +| | |skipped announce (because it's | │ │ │ │ │ +|announce_skipped |180 |assumed to be unreachable over the| │ │ │ │ │ +|____________________________________|_____|given_source_network_interface)___| │ │ │ │ │ +|no_entropy__________________________|200__|random_number_generation_failed___| │ │ │ │ │ +|ssrf_mitigation_____________________|201__|blocked_by_SSRF_mitigation________| │ │ │ │ │ +|blocked_by_idna |202 |blocked because IDNA host names | │ │ │ │ │ +|____________________________________|_____|are_banned________________________| │ │ │ │ │ +|torrent_unknown_version |210 |the torrent file has an unknown | │ │ │ │ │ +|____________________________________|_____|meta_version______________________| │ │ │ │ │ +|torrent_missing_file_tree |211 |the v2 torrent file has no file | │ │ │ │ │ +|____________________________________|_____|tree______________________________| │ │ │ │ │ +|torrent_missing_meta_version |212 |the torrent contains v2 keys but | │ │ │ │ │ +|____________________________________|_____|does_not_specify_meta_version_2___| │ │ │ │ │ +|torrent_inconsistent_files |213 |the v1 and v2 file metadata does | │ │ │ │ │ +|____________________________________|_____|not_match_________________________| │ │ │ │ │ +|torrent_missing_piece_layer |214 |one or more files are missing | │ │ │ │ │ +|____________________________________|_____|piece_layer_hashes________________| │ │ │ │ │ +|torrent_invalid_piece_layer |215 |a piece layer has the wrong size | │ │ │ │ │ +|____________________________________|_____|or_failed_hash_check______________| │ │ │ │ │ +|torrent_missing_pieces_root_________|216__|a_v2_file_entry_has_no_root_hash__| │ │ │ │ │ +|torrent_inconsistent_hashes |217 |the v1 and v2 hashes do not | │ │ │ │ │ +|____________________________________|_____|describe_the_same_data____________| │ │ │ │ │ +|torrent_invalid_pad_file |218 |a file in the v2 metadata has the | │ │ │ │ │ +|____________________________________|_____|pad_attribute_set_________________| │ │ │ │ │ +|error_code_max______________________|219__|the_number_of_error_codes_________| │ │ │ │ │ [report_issue] │ │ │ │ │ -***** remove_torrent() ***** │ │ │ │ │ -void remove_torrent (const torrent_handle&, remove_flags_t = {}); │ │ │ │ │ -remove_torrent() will close all peer connections associated with the torrent │ │ │ │ │ -and tell the tracker that we've stopped participating in the swarm. This │ │ │ │ │ -operation cannot fail. When it completes, you will receive a │ │ │ │ │ -torrent_removed_alert. │ │ │ │ │ -remove_torrent() is non-blocking, but will remove the torrent from the session │ │ │ │ │ -synchronously. Calling session_handle::add_torrent() immediately afterward with │ │ │ │ │ -the same torrent will succeed. Note that this creates a new handle which is not │ │ │ │ │ -equal to the removed one. │ │ │ │ │ -The optional second argument options can be used to delete all the files │ │ │ │ │ -downloaded by this torrent. To do so, pass in the value session_handle:: │ │ │ │ │ -delete_files. Once the torrent is deleted, a torrent_deleted_alert is posted. │ │ │ │ │ -The torrent_handle remains valid for some time after remove_torrent() is │ │ │ │ │ -called. It will become invalid only after all libtorrent tasks (such as I/ │ │ │ │ │ -O tasks) release their references to the torrent. Until this happens, │ │ │ │ │ -torrent_handle::is_valid() will return true, and other calls such as │ │ │ │ │ -torrent_handle::status() will succeed. Because of this, and because │ │ │ │ │ -remove_torrent() is non-blocking, the following sequence usually succeeds (does │ │ │ │ │ -not throw system_error): .. code:: c++ │ │ │ │ │ - session.remove_handle(handle); handle.save_resume_data(); │ │ │ │ │ -Note that when a queued or downloading torrent is removed, its position in the │ │ │ │ │ -download queue is vacated and every subsequent torrent in the queue has their │ │ │ │ │ -queue positions updated. This can potentially cause a large state_update to be │ │ │ │ │ -posted. When removing all torrents, it is advised to remove them from the back │ │ │ │ │ -of the queue, to minimize the shifting. │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** apply_settings() get_settings() ***** │ │ │ │ │ -void apply_settings (settings_pack&&); │ │ │ │ │ -void apply_settings (settings_pack const&); │ │ │ │ │ -settings_pack get_settings () const; │ │ │ │ │ -Applies the settings specified by the settings_pack s. This is an asynchronous │ │ │ │ │ -operation that will return immediately and actually apply the settings to the │ │ │ │ │ -main thread of libtorrent some time later. │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** set_alert_notify() pop_alerts() wait_for_alert() ***** │ │ │ │ │ -void set_alert_notify (std::function const& fun); │ │ │ │ │ -void pop_alerts (std::vector* alerts); │ │ │ │ │ -alert* wait_for_alert (time_duration max_wait); │ │ │ │ │ -Alerts is the main mechanism for libtorrent to report errors and events. │ │ │ │ │ -pop_alerts fills in the vector passed to it with pointers to new alerts. The │ │ │ │ │ -session still owns these alerts and they will stay valid until the next time │ │ │ │ │ -pop_alerts is called. You may not delete the alert objects. │ │ │ │ │ -It is safe to call pop_alerts from multiple different threads, as long as the │ │ │ │ │ -alerts themselves are not accessed once another thread calls pop_alerts. Doing │ │ │ │ │ -this requires manual synchronization between the popping threads. │ │ │ │ │ -wait_for_alert will block the current thread for max_wait time duration, or │ │ │ │ │ -until another alert is posted. If an alert is available at the time of the │ │ │ │ │ -call, it returns immediately. The returned alert pointer is the head of the │ │ │ │ │ -alert queue. wait_for_alert does not pop alerts from the queue, it merely peeks │ │ │ │ │ -at it. The returned alert will stay valid until pop_alerts is called twice. The │ │ │ │ │ -first time will pop it and the second will free it. │ │ │ │ │ -If there is no alert in the queue and no alert arrives within the specified │ │ │ │ │ -timeout, wait_for_alert returns nullptr. │ │ │ │ │ -In the python binding, wait_for_alert takes the number of milliseconds to wait │ │ │ │ │ -as an integer. │ │ │ │ │ -The alert queue in the session will not grow indefinitely. Make sure to pop │ │ │ │ │ -periodically to not miss notifications. To control the max number of alerts │ │ │ │ │ -that's queued by the session, see settings_pack::alert_queue_size. │ │ │ │ │ -Some alerts are considered so important that they are posted even when the │ │ │ │ │ -alert queue is full. Some alerts are considered mandatory and cannot be │ │ │ │ │ -disabled by the alert_mask. For instance, save_resume_data_alert and │ │ │ │ │ -save_resume_data_failed_alert are always posted, regardless of the alert mask. │ │ │ │ │ -To control which alerts are posted, set the alert_mask (settings_pack:: │ │ │ │ │ -alert_mask). │ │ │ │ │ -If the alert queue fills up to the point where alerts are dropped, this will be │ │ │ │ │ -indicated by a alerts_dropped_alert, which contains a bitmask of which types of │ │ │ │ │ -alerts were dropped. Generally it is a good idea to make sure the alert queue │ │ │ │ │ -is large enough, the alert_mask doesn't have unnecessary categories enabled and │ │ │ │ │ -to call pop_alert() frequently, to avoid alerts being dropped. │ │ │ │ │ -the set_alert_notify function lets the client set a function object to be │ │ │ │ │ -invoked every time the alert queue goes from having 0 alerts to 1 alert. This │ │ │ │ │ -function is called from within libtorrent, it may be the main thread, or it may │ │ │ │ │ -be from within a user call. The intention of of the function is that the client │ │ │ │ │ -wakes up its main thread, to poll for more alerts using pop_alerts(). If the │ │ │ │ │ -notify function fails to do so, it won't be called again, until pop_alerts is │ │ │ │ │ -called for some other reason. For instance, it could signal an eventfd, post a │ │ │ │ │ -message to an HWND or some other main message pump. The actual retrieval of │ │ │ │ │ -alerts should not be done in the callback. In fact, the callback should not │ │ │ │ │ -block. It should not perform any expensive work. It really should just notify │ │ │ │ │ -the main application thread. │ │ │ │ │ -The type of an alert is returned by the polymorphic function alert::type() but │ │ │ │ │ -can also be queries from a concrete type via T::alert_type, as a static │ │ │ │ │ -constant. │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** delete_port_mapping() add_port_mapping() ***** │ │ │ │ │ -std::vector add_port_mapping (portmap_protocol t, int │ │ │ │ │ -external_port, int local_port); │ │ │ │ │ -void delete_port_mapping (port_mapping_t handle); │ │ │ │ │ -add_port_mapping adds one or more port forwards on UPnP and/or NAT-PMP, │ │ │ │ │ -whichever is enabled. A mapping is created for each listen socket in the │ │ │ │ │ -session. The return values are all handles referring to the port mappings that │ │ │ │ │ -were just created. Pass them to delete_port_mapping() to remove them. │ │ │ │ │ +****** enum http_errors ****** │ │ │ │ │ +Declared in "libtorrent/error_code.hpp" │ │ │ │ │ + _______________________________________ │ │ │ │ │ +|name_________________|value|description| │ │ │ │ │ +|cont_________________|100__| _________| │ │ │ │ │ +|ok___________________|200__| _________| │ │ │ │ │ +|created______________|201__| _________| │ │ │ │ │ +|accepted_____________|202__| _________| │ │ │ │ │ +|no_content___________|204__| _________| │ │ │ │ │ +|multiple_choices_____|300__| _________| │ │ │ │ │ +|moved_permanently____|301__| _________| │ │ │ │ │ +|moved_temporarily____|302__| _________| │ │ │ │ │ +|not_modified_________|304__| _________| │ │ │ │ │ +|bad_request__________|400__| _________| │ │ │ │ │ +|unauthorized_________|401__| _________| │ │ │ │ │ +|forbidden____________|403__| _________| │ │ │ │ │ +|not_found____________|404__| _________| │ │ │ │ │ +|internal_server_error|500__| _________| │ │ │ │ │ +|not_implemented______|501__| _________| │ │ │ │ │ +|bad_gateway__________|502__| _________| │ │ │ │ │ +|service_unavailable__|503__| _________| │ │ │ │ │ [report_issue] │ │ │ │ │ -***** reopen_network_sockets() ***** │ │ │ │ │ -void reopen_network_sockets (reopen_network_flags_t options = │ │ │ │ │ -reopen_map_ports); │ │ │ │ │ -Instructs the session to reopen all listen and outgoing sockets. │ │ │ │ │ -It's useful in the case your platform doesn't support the built in IP notifier │ │ │ │ │ -mechanism, or if you have a better more reliable way to detect changes in the │ │ │ │ │ -IP routing table. │ │ │ │ │ +****** enum pcp_errors ****** │ │ │ │ │ +Declared in "libtorrent/natpmp.hpp" │ │ │ │ │ + _____________________________________________ │ │ │ │ │ +|name_______________________|value|description| │ │ │ │ │ +|pcp_success________________|0____| _________| │ │ │ │ │ +|pcp_unsupp_version_________|1____| _________| │ │ │ │ │ +|pcp_not_authorized_________|2____| _________| │ │ │ │ │ +|pcp_malformed_request______|3____| _________| │ │ │ │ │ +|pcp_unsupp_opcode__________|4____| _________| │ │ │ │ │ +|pcp_unsupp_option__________|5____| _________| │ │ │ │ │ +|pcp_malformed_option_______|6____| _________| │ │ │ │ │ +|pcp_network_failure________|7____| _________| │ │ │ │ │ +|pcp_no_resources___________|8____| _________| │ │ │ │ │ +|pcp_unsupp_protocol________|9____| _________| │ │ │ │ │ +|pcp_user_ex_quota__________|10___| _________| │ │ │ │ │ +|pcp_cannot_provide_external|11___| _________| │ │ │ │ │ +|pcp_address_mismatch_______|12___| _________| │ │ │ │ │ +|pcp_excessive_remote_peers_|13___| _________| │ │ │ │ │ [report_issue] │ │ │ │ │ -***** native_handle() ***** │ │ │ │ │ -std::shared_ptr native_handle () const; │ │ │ │ │ -This function is intended only for use by plugins. This type does not have a │ │ │ │ │ -stable API and should be relied on as little as possible. │ │ │ │ │ +****** enum error_code_enum ****** │ │ │ │ │ +Declared in "libtorrent/upnp.hpp" │ │ │ │ │ + _____________________________________________________________________________ │ │ │ │ │ +|name______________________________|value|description_________________________| │ │ │ │ │ +|no_error__________________________|0____|No_error____________________________| │ │ │ │ │ +|invalid_argument |402 |One of the arguments in the request | │ │ │ │ │ +|__________________________________|_____|is_invalid__________________________| │ │ │ │ │ +|action_failed_____________________|501__|The_request_failed__________________| │ │ │ │ │ +|value_not_in_array |714 |The specified value does not exist | │ │ │ │ │ +|__________________________________|_____|in_the_array________________________| │ │ │ │ │ +| | |The source IP address cannot be | │ │ │ │ │ +|source_ip_cannot_be_wildcarded |715 |wild-carded, but must be fully | │ │ │ │ │ +|__________________________________|_____|specified___________________________| │ │ │ │ │ +|external_port_cannot_be_wildcarded|716 |The external port cannot be a | │ │ │ │ │ +|__________________________________|_____|wildcard,_but_must_be_specified_____| │ │ │ │ │ +| | |The port mapping entry specified | │ │ │ │ │ +|port_mapping_conflict |718 |conflicts with a mapping assigned | │ │ │ │ │ +|__________________________________|_____|previously_to_another_client________| │ │ │ │ │ +|internal_port_must_match_external |724 |Internal and external port value | │ │ │ │ │ +|__________________________________|_____|must_be_the_same____________________| │ │ │ │ │ +| | |The NAT implementation only supports| │ │ │ │ │ +|only_permanent_leases_supported |725 |permanent lease times on port | │ │ │ │ │ +|__________________________________|_____|mappings____________________________| │ │ │ │ │ +| | |RemoteHost must be a wildcard and | │ │ │ │ │ +|remote_host_must_be_wildcard |726 |cannot be a specific IP address or | │ │ │ │ │ +|__________________________________|_____|DNS_name____________________________| │ │ │ │ │ +|external_port_must_be_wildcard |727 |ExternalPort must be a wildcard and | │ │ │ │ │ +|__________________________________|_____|cannot_be_a_specific_port___________| │ │ │ │ │ [report_issue] │ │ │ │ │ - save_settings │ │ │ │ │ - saves settings (i.e. the settings_pack) │ │ │ │ │ +****** enum error_code_enum ****** │ │ │ │ │ +Declared in "libtorrent/gzip.hpp" │ │ │ │ │ + _____________________________________________________________________________ │ │ │ │ │ +|name_______________________________|value|description________________________| │ │ │ │ │ +|no_error___________________________|0____|Not_an_error_______________________| │ │ │ │ │ +|invalid_gzip_header |1 |the supplied gzip buffer has | │ │ │ │ │ +|___________________________________|_____|invalid_header_____________________| │ │ │ │ │ +| | |the gzip buffer would inflate to | │ │ │ │ │ +|inflated_data_too_large |2 |more bytes than the specified | │ │ │ │ │ +|___________________________________|_____|maximum_size,_and_was_rejected.____| │ │ │ │ │ +|data_did_not_terminate |3 |available inflate data did not | │ │ │ │ │ +|___________________________________|_____|terminate__________________________| │ │ │ │ │ +|space_exhausted |4 |output space exhausted before | │ │ │ │ │ +|___________________________________|_____|completing_inflate_________________| │ │ │ │ │ +|invalid_block_type_________________|5____|invalid_block_type_(type_==_3)_____| │ │ │ │ │ +|invalid_stored_block_length |6 |stored block length did not match | │ │ │ │ │ +|___________________________________|_____|one's_complement___________________| │ │ │ │ │ +|too_many_length_or_distance_codes |7 |dynamic block code description: too| │ │ │ │ │ +|___________________________________|_____|many_length_or_distance_codes______| │ │ │ │ │ +|code_lengths_codes_incomplete |8 |dynamic block code description: | │ │ │ │ │ +|___________________________________|_____|code_lengths_codes_incomplete______| │ │ │ │ │ +|repeat_lengths_with_no_first_length|9 |dynamic block code description: | │ │ │ │ │ +|___________________________________|_____|repeat_lengths_with_no_first_length| │ │ │ │ │ +|repeat_more_than_specified_lengths |10 |dynamic block code description: | │ │ │ │ │ +|___________________________________|_____|repeat_more_than_specified_lengths_| │ │ │ │ │ +|invalid_literal_length_code_lengths|11 |dynamic block code description: | │ │ │ │ │ +|___________________________________|_____|invalid_literal/length_code_lengths| │ │ │ │ │ +|invalid_distance_code_lengths |12 |dynamic block code description: | │ │ │ │ │ +|___________________________________|_____|invalid_distance_code_lengths______| │ │ │ │ │ +|invalid_literal_code_in_block |13 |invalid literal/length or distance | │ │ │ │ │ +|___________________________________|_____|code_in_fixed_or_dynamic_block_____| │ │ │ │ │ +|distance_too_far_back_in_block |14 |distance is too far back in fixed | │ │ │ │ │ +|___________________________________|_____|or_dynamic_block___________________| │ │ │ │ │ +|unknown_gzip_error |15 |an unknown error occurred during | │ │ │ │ │ +|___________________________________|_____|gzip_inflation_____________________| │ │ │ │ │ +|error_code_max_____________________|16___|the_number_of_error_codes__________| │ │ │ │ │ [report_issue] │ │ │ │ │ - save_dht_state │ │ │ │ │ - saves dht state such as nodes and node-id, possibly accelerating joining │ │ │ │ │ - the DHT if provided at next session startup. │ │ │ │ │ +****** enum socks_error_code ****** │ │ │ │ │ +Declared in "libtorrent/socks5_stream.hpp" │ │ │ │ │ + ____________________________________________________ │ │ │ │ │ +|name______________________________|value|description| │ │ │ │ │ +|no_error__________________________|0____| _________| │ │ │ │ │ +|unsupported_version_______________|1____| _________| │ │ │ │ │ +|unsupported_authentication_method_|2____| _________| │ │ │ │ │ +|unsupported_authentication_version|3____| _________| │ │ │ │ │ +|authentication_error______________|4____| _________| │ │ │ │ │ +|username_required_________________|5____| _________| │ │ │ │ │ +|general_failure___________________|6____| _________| │ │ │ │ │ +|command_not_supported_____________|7____| _________| │ │ │ │ │ +|no_identd_________________________|8____| _________| │ │ │ │ │ +|identd_error______________________|9____| _________| │ │ │ │ │ +|num_errors________________________|10___| _________| │ │ │ │ │ [report_issue] │ │ │ │ │ - save_extension_state │ │ │ │ │ - load or save state from plugins │ │ │ │ │ +****** enum i2p_error_code ****** │ │ │ │ │ +Declared in "libtorrent/i2p_stream.hpp" │ │ │ │ │ + _________________________________ │ │ │ │ │ +|name___________|value|description| │ │ │ │ │ +|no_error_______|0____| _________| │ │ │ │ │ +|parse_failed___|1____| _________| │ │ │ │ │ +|cant_reach_peer|2____| _________| │ │ │ │ │ +|i2p_error______|3____| _________| │ │ │ │ │ +|invalid_key____|4____| _________| │ │ │ │ │ +|invalid_id_____|5____| _________| │ │ │ │ │ +|timeout________|6____| _________| │ │ │ │ │ +|key_not_found__|7____| _________| │ │ │ │ │ +|duplicated_id__|8____| _________| │ │ │ │ │ +|num_errors_____|9____| _________| │ │ │ │ │ [report_issue] │ │ │ │ │ - save_ip_filter │ │ │ │ │ - load or save the IP filter set on the session │ │ │ │ │ - [report_issue] │ │ │ │ │ - global_peer_class_id tcp_peer_class_id local_peer_class_id │ │ │ │ │ - built-in peer classes │ │ │ │ │ +****** enum error_code_enum ****** │ │ │ │ │ +Declared in "libtorrent/bdecode.hpp" │ │ │ │ │ + ___________________________________________________________________________ │ │ │ │ │ +|name__________|value|description___________________________________________| │ │ │ │ │ +|no_error______|0____|Not_an_error__________________________________________| │ │ │ │ │ +|expected_digit|1____|expected_digit_in_bencoded_string_____________________| │ │ │ │ │ +|expected_colon|2____|expected_colon_in_bencoded_string_____________________| │ │ │ │ │ +|unexpected_eof|3____|unexpected_end_of_file_in_bencoded_string_____________| │ │ │ │ │ +|expected_value|4 |expected value (list, dict, int or string) in bencoded| │ │ │ │ │ +|______________|_____|string________________________________________________| │ │ │ │ │ +|depth_exceeded|5____|bencoded_recursion_depth_limit_exceeded_______________| │ │ │ │ │ +|limit_exceeded|6____|bencoded_item_count_limit_exceeded____________________| │ │ │ │ │ +|overflow______|7____|integer_overflow______________________________________| │ │ │ │ │ +|error_code_max|8____|the_number_of_error_codes_____________________________| │ │ │ │ │ [report_issue] │ │ │ │ │ - delete_files │ │ │ │ │ - delete the files belonging to the torrent from disk. including the part- │ │ │ │ │ - file, if there is one │ │ │ │ │ +****** counters ****** │ │ │ │ │ +Declared in "libtorrent/performance_counters.hpp" │ │ │ │ │ +struct counters │ │ │ │ │ +{ │ │ │ │ │ + counters () ; │ │ │ │ │ + counters (counters const&) ; │ │ │ │ │ + counters& operator= (counters const&) & ; │ │ │ │ │ + std::int64_t inc_stats_counter (int c, std::int64_t value = 1) ; │ │ │ │ │ + std::int64_t operator[] (int i) const ; │ │ │ │ │ + void set_value (int c, std::int64_t value) ; │ │ │ │ │ + void blend_stats_counter (int c, std::int64_t value, int ratio) ; │ │ │ │ │ +}; │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** operator[]() inc_stats_counter() ***** │ │ │ │ │ +std::int64_t inc_stats_counter (int c, std::int64_t value = 1) ; │ │ │ │ │ +std::int64_t operator[] (int i) const ; │ │ │ │ │ +returns the new value │ │ │ │ │ [report_issue] │ │ │ │ │ - delete_partfile │ │ │ │ │ - delete just the part-file associated with this torrent │ │ │ │ │ +****** stats_metric ****** │ │ │ │ │ +Declared in "libtorrent/session_stats.hpp" │ │ │ │ │ +describes one statistics metric from the session. For more information, see the │ │ │ │ │ +session_statistics section. │ │ │ │ │ +struct stats_metric │ │ │ │ │ +{ │ │ │ │ │ + char const* name; │ │ │ │ │ + int value_index; │ │ │ │ │ + metric_type_t type; │ │ │ │ │ +}; │ │ │ │ │ [report_issue] │ │ │ │ │ - paused │ │ │ │ │ - when set, the session will start paused. Call session_handle::resume() to │ │ │ │ │ - start │ │ │ │ │ + name │ │ │ │ │ + the name of the counter or gauge │ │ │ │ │ [report_issue] │ │ │ │ │ - udp tcp │ │ │ │ │ - protocols used by add_port_mapping() │ │ │ │ │ + value_index type │ │ │ │ │ + the index into the session stats array, where the underlying value of │ │ │ │ │ + this counter or gauge is found. The session stats array is part of the │ │ │ │ │ + session_stats_alert object. │ │ │ │ │ [report_issue] │ │ │ │ │ - reopen_map_ports │ │ │ │ │ - This option indicates if the ports are mapped using natpmp and upnp. If │ │ │ │ │ - mapping was already made, they are deleted and added again. This only │ │ │ │ │ - works if natpmp and/or upnp are configured to be enable. │ │ │ │ │ - [report_issue] │ │ │ │ │ -****** write_session_params_buf() write_session_params() read_session_params() │ │ │ │ │ -****** │ │ │ │ │ -Declared in "libtorrent/session_params.hpp" │ │ │ │ │ -session_params read_session_params (bdecode_node const& e │ │ │ │ │ - , save_state_flags_t flags = save_state_flags_t::all()); │ │ │ │ │ -session_params read_session_params (span buf │ │ │ │ │ - , save_state_flags_t flags = save_state_flags_t::all()); │ │ │ │ │ -entry write_session_params (session_params const& sp │ │ │ │ │ - , save_state_flags_t flags = save_state_flags_t::all()); │ │ │ │ │ -std::vector write_session_params_buf (session_params const& sp │ │ │ │ │ - , save_state_flags_t flags = save_state_flags_t::all()); │ │ │ │ │ -These functions serialize and de-serialize a session_params object to and from │ │ │ │ │ -bencoded form. The session_params object is used to initialize a new session │ │ │ │ │ -using the state from a previous one (or by programmatically configure the │ │ │ │ │ -session up-front). The flags parameter can be used to only save and load │ │ │ │ │ -certain aspects of the session's state. The _buf suffix indicates the function │ │ │ │ │ -operates on buffer rather than the bencoded structure. The torrents in a │ │ │ │ │ -session are not part of the session_params state, they have to be restored │ │ │ │ │ -separately. │ │ │ │ │ +****** session_stats_metrics() ****** │ │ │ │ │ +Declared in "libtorrent/session_stats.hpp" │ │ │ │ │ +std::vector session_stats_metrics (); │ │ │ │ │ +This free function returns the list of available metrics exposed by │ │ │ │ │ +libtorrent's statistics API. Each metric has a name and a value index. The │ │ │ │ │ +value index is the index into the array in session_stats_alert where this │ │ │ │ │ +metric's value can be found when the session stats is sampled (by calling │ │ │ │ │ +post_session_stats()). │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** find_metric_idx() ****** │ │ │ │ │ +Declared in "libtorrent/session_stats.hpp" │ │ │ │ │ +int find_metric_idx (string_view name); │ │ │ │ │ +given a name of a metric, this function returns the counter index of it, or - │ │ │ │ │ +1 if it could not be found. The counter index is the index into the values │ │ │ │ │ +array returned by session_stats_alert. │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** enum metric_type_t ****** │ │ │ │ │ +Declared in "libtorrent/session_stats.hpp" │ │ │ │ │ + _________________________ │ │ │ │ │ +|name___|value|description| │ │ │ │ │ +|counter|0____| _________| │ │ │ │ │ +|gauge__|1____| _________| │ │ │ │ │ The pop_alerts() function on session is the main interface for retrieving │ │ │ │ │ alerts (warnings, messages and errors from libtorrent). If no alerts have been │ │ │ │ │ posted by libtorrent pop_alerts() will return an empty list. │ │ │ │ │ By default, only errors are reported. settings_pack::alert_mask can be used to │ │ │ │ │ specify which kinds of events should be reported. The alert mask is a │ │ │ │ │ combination of the alert_category_t flags in the alert class. │ │ │ │ │ Every alert belongs to one or more category. There is a cost associated with │ │ │ │ │ @@ -7146,103 +6124,14 @@ │ │ │ │ │ that are generated for a specific torrent are derived from torrent_alert, and │ │ │ │ │ tracker events derive from tracker_alert. │ │ │ │ │ Alerts returned by pop_alerts() are only valid until the next call to │ │ │ │ │ pop_alerts(). You may not copy an alert object to access it after the next call │ │ │ │ │ to pop_alerts(). Internal members of alerts also become invalid once pop_alerts │ │ │ │ │ () is called again. │ │ │ │ │ [report_issue] │ │ │ │ │ -****** alert ****** │ │ │ │ │ -Declared in "libtorrent/alert.hpp" │ │ │ │ │ -The alert class is the base class that specific messages are derived from. │ │ │ │ │ -alert types are not copyable, and cannot be constructed by the client. The │ │ │ │ │ -pointers returned by libtorrent are short lived (the details are described │ │ │ │ │ -under session_handle::pop_alerts()) │ │ │ │ │ -struct alert │ │ │ │ │ -{ │ │ │ │ │ - time_point timestamp () const; │ │ │ │ │ - virtual int type () const noexcept = 0; │ │ │ │ │ - virtual char const* what () const noexcept = 0; │ │ │ │ │ - virtual std::string message () const = 0; │ │ │ │ │ - virtual alert_category_t category () const noexcept = 0; │ │ │ │ │ - │ │ │ │ │ - static constexpr alert_category_t error_notification = 0_bit; │ │ │ │ │ - static constexpr alert_category_t peer_notification = 1_bit; │ │ │ │ │ - static constexpr alert_category_t port_mapping_notification = 2_bit; │ │ │ │ │ - static constexpr alert_category_t storage_notification = 3_bit; │ │ │ │ │ - static constexpr alert_category_t tracker_notification = 4_bit; │ │ │ │ │ - static constexpr alert_category_t connect_notification = 5_bit; │ │ │ │ │ - static constexpr alert_category_t status_notification = 6_bit; │ │ │ │ │ - static constexpr alert_category_t ip_block_notification = 8_bit; │ │ │ │ │ - static constexpr alert_category_t performance_warning = 9_bit; │ │ │ │ │ - static constexpr alert_category_t dht_notification = 10_bit; │ │ │ │ │ - static constexpr alert_category_t session_log_notification = 13_bit; │ │ │ │ │ - static constexpr alert_category_t torrent_log_notification = 14_bit; │ │ │ │ │ - static constexpr alert_category_t peer_log_notification = 15_bit; │ │ │ │ │ - static constexpr alert_category_t incoming_request_notification = 16_bit; │ │ │ │ │ - static constexpr alert_category_t dht_log_notification = 17_bit; │ │ │ │ │ - static constexpr alert_category_t dht_operation_notification = 18_bit; │ │ │ │ │ - static constexpr alert_category_t port_mapping_log_notification = 19_bit; │ │ │ │ │ - static constexpr alert_category_t picker_log_notification = 20_bit; │ │ │ │ │ - static constexpr alert_category_t file_progress_notification = 21_bit; │ │ │ │ │ - static constexpr alert_category_t piece_progress_notification = 22_bit; │ │ │ │ │ - static constexpr alert_category_t upload_notification = 23_bit; │ │ │ │ │ - static constexpr alert_category_t block_progress_notification = 24_bit; │ │ │ │ │ - static constexpr alert_category_t all_categories = alert_category_t::all(); │ │ │ │ │ -}; │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** timestamp() ***** │ │ │ │ │ -time_point timestamp () const; │ │ │ │ │ -a timestamp is automatically created in the constructor │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** type() ***** │ │ │ │ │ -virtual int type () const noexcept = 0; │ │ │ │ │ -returns an integer that is unique to this alert type. It can be compared │ │ │ │ │ -against a specific alert by querying a static constant called alert_type in the │ │ │ │ │ -alert. It can be used to determine the run-time type of an alert* in order to │ │ │ │ │ -cast to that alert type and access specific members. │ │ │ │ │ -e.g: │ │ │ │ │ -std::vector alerts; │ │ │ │ │ -ses.pop_alerts(&alerts); │ │ │ │ │ -for (alert* a : alerts) { │ │ │ │ │ - switch (a->type()) { │ │ │ │ │ - │ │ │ │ │ - case read_piece_alert::alert_type: │ │ │ │ │ - { │ │ │ │ │ - auto* p = static_cast(a); │ │ │ │ │ - if (p->ec) { │ │ │ │ │ - // read_piece failed │ │ │ │ │ - break; │ │ │ │ │ - } │ │ │ │ │ - // use p │ │ │ │ │ - break; │ │ │ │ │ - } │ │ │ │ │ - case file_renamed_alert::alert_type: │ │ │ │ │ - { │ │ │ │ │ - // etc... │ │ │ │ │ - } │ │ │ │ │ - } │ │ │ │ │ -} │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** what() ***** │ │ │ │ │ -virtual char const* what () const noexcept = 0; │ │ │ │ │ -returns a string literal describing the type of the alert. It does not include │ │ │ │ │ -any information that might be bundled with the alert. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** message() ***** │ │ │ │ │ -virtual std::string message () const = 0; │ │ │ │ │ -generate a string describing the alert and the information bundled with it. │ │ │ │ │ -This is mainly intended for debug and development use. It is not suitable to │ │ │ │ │ -use this for applications that may be localized. Instead, handle each alert │ │ │ │ │ -type individually and extract and render the information from the alert │ │ │ │ │ -depending on the locale. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** category() ***** │ │ │ │ │ -virtual alert_category_t category () const noexcept = 0; │ │ │ │ │ -returns a bitmask specifying which categories this alert belong to. │ │ │ │ │ -[report_issue] │ │ │ │ │ ****** dht_routing_bucket ****** │ │ │ │ │ Declared in "libtorrent/alert_types.hpp" │ │ │ │ │ struct to hold information about a single DHT routing table bucket │ │ │ │ │ struct dht_routing_bucket │ │ │ │ │ { │ │ │ │ │ int num_nodes; │ │ │ │ │ int num_replacements; │ │ │ │ │ @@ -7384,25 +6273,25 @@ │ │ │ │ │ ****** file_renamed_alert ****** │ │ │ │ │ Declared in "libtorrent/alert_types.hpp" │ │ │ │ │ This is posted as a response to a torrent_handle::rename_file() call, if the │ │ │ │ │ rename operation succeeds. │ │ │ │ │ struct file_renamed_alert final : torrent_alert │ │ │ │ │ { │ │ │ │ │ std::string message () const override; │ │ │ │ │ - char const* old_name () const; │ │ │ │ │ char const* new_name () const; │ │ │ │ │ + char const* old_name () const; │ │ │ │ │ │ │ │ │ │ static constexpr alert_category_t static_category = alert_category:: │ │ │ │ │ storage; │ │ │ │ │ file_index_t const index; │ │ │ │ │ }; │ │ │ │ │ [report_issue] │ │ │ │ │ -***** new_name() old_name() ***** │ │ │ │ │ -char const* old_name () const; │ │ │ │ │ +***** old_name() new_name() ***** │ │ │ │ │ char const* new_name () const; │ │ │ │ │ +char const* old_name () const; │ │ │ │ │ returns the new and previous file name, respectively. │ │ │ │ │ [report_issue] │ │ │ │ │ index │ │ │ │ │ refers to the index of the file that was renamed, │ │ │ │ │ [report_issue] │ │ │ │ │ ****** file_rename_failed_alert ****** │ │ │ │ │ Declared in "libtorrent/alert_types.hpp" │ │ │ │ │ @@ -9272,24 +8161,24 @@ │ │ │ │ │ ****** dht_live_nodes_alert ****** │ │ │ │ │ Declared in "libtorrent/alert_types.hpp" │ │ │ │ │ posted in response to a call to session::dht_live_nodes(). It contains the live │ │ │ │ │ nodes from the DHT routing table of one of the DHT nodes running locally. │ │ │ │ │ struct dht_live_nodes_alert final : alert │ │ │ │ │ { │ │ │ │ │ std::string message () const override; │ │ │ │ │ - std::vector> nodes () const; │ │ │ │ │ int num_nodes () const; │ │ │ │ │ + std::vector> nodes () const; │ │ │ │ │ │ │ │ │ │ static constexpr alert_category_t static_category = alert_category::dht; │ │ │ │ │ sha1_hash node_id; │ │ │ │ │ }; │ │ │ │ │ [report_issue] │ │ │ │ │ ***** num_nodes() nodes() ***** │ │ │ │ │ -std::vector> nodes () const; │ │ │ │ │ int num_nodes () const; │ │ │ │ │ +std::vector> nodes () const; │ │ │ │ │ the number of nodes in the routing table and the actual nodes. │ │ │ │ │ [report_issue] │ │ │ │ │ node_id │ │ │ │ │ the local DHT node's node-ID this routing table belongs to │ │ │ │ │ [report_issue] │ │ │ │ │ ****** session_stats_header_alert ****** │ │ │ │ │ Declared in "libtorrent/alert_types.hpp" │ │ │ │ │ @@ -9323,15 +8212,15 @@ │ │ │ │ │ dht_operation; │ │ │ │ │ sha1_hash node_id; │ │ │ │ │ aux::noexcept_movable endpoint; │ │ │ │ │ time_duration const interval; │ │ │ │ │ int const num_infohashes; │ │ │ │ │ }; │ │ │ │ │ [report_issue] │ │ │ │ │ -***** num_samples() samples() ***** │ │ │ │ │ +***** samples() num_samples() ***** │ │ │ │ │ int num_samples () const; │ │ │ │ │ std::vector samples () const; │ │ │ │ │ returns the number of info-hashes returned by the node, as well as the actual │ │ │ │ │ info-hashes. num_samples() is more efficient than samples().size(). │ │ │ │ │ [report_issue] │ │ │ │ │ ***** num_nodes() ***** │ │ │ │ │ int num_nodes () const; │ │ │ │ │ @@ -9378,17 +8267,17 @@ │ │ │ │ │ Declared in "libtorrent/alert_types.hpp" │ │ │ │ │ this alert is posted to indicate to the client that some alerts were dropped. │ │ │ │ │ Dropped meaning that the alert failed to be delivered to the client. The most │ │ │ │ │ common cause of such failure is that the internal alert queue grew too big │ │ │ │ │ (controlled by alert_queue_size). │ │ │ │ │ struct alerts_dropped_alert final : alert │ │ │ │ │ { │ │ │ │ │ + std::string message () const override; │ │ │ │ │ static_assert (num_alert_types <= abi_alert_count, "need to increase bitset. │ │ │ │ │ This is an ABI break"); │ │ │ │ │ - std::string message () const override; │ │ │ │ │ │ │ │ │ │ static constexpr alert_category_t static_category = alert_category::error; │ │ │ │ │ std::bitset dropped_alerts; │ │ │ │ │ }; │ │ │ │ │ [report_issue] │ │ │ │ │ dropped_alerts │ │ │ │ │ a bitmask indicating which alerts were dropped. Each bit represents the │ │ │ │ │ @@ -9480,24 +8369,113 @@ │ │ │ │ │ collided with this swarm's info-hash. │ │ │ │ │ [report_issue] │ │ │ │ │ metadata │ │ │ │ │ the metadata that was received by one of the torrents in conflict. One │ │ │ │ │ way to resolve the conflict is to remove both failing torrents and re-add │ │ │ │ │ it using this metadata │ │ │ │ │ [report_issue] │ │ │ │ │ +****** alert ****** │ │ │ │ │ +Declared in "libtorrent/alert.hpp" │ │ │ │ │ +The alert class is the base class that specific messages are derived from. │ │ │ │ │ +alert types are not copyable, and cannot be constructed by the client. The │ │ │ │ │ +pointers returned by libtorrent are short lived (the details are described │ │ │ │ │ +under session_handle::pop_alerts()) │ │ │ │ │ +struct alert │ │ │ │ │ +{ │ │ │ │ │ + time_point timestamp () const; │ │ │ │ │ + virtual int type () const noexcept = 0; │ │ │ │ │ + virtual char const* what () const noexcept = 0; │ │ │ │ │ + virtual std::string message () const = 0; │ │ │ │ │ + virtual alert_category_t category () const noexcept = 0; │ │ │ │ │ + │ │ │ │ │ + static constexpr alert_category_t error_notification = 0_bit; │ │ │ │ │ + static constexpr alert_category_t peer_notification = 1_bit; │ │ │ │ │ + static constexpr alert_category_t port_mapping_notification = 2_bit; │ │ │ │ │ + static constexpr alert_category_t storage_notification = 3_bit; │ │ │ │ │ + static constexpr alert_category_t tracker_notification = 4_bit; │ │ │ │ │ + static constexpr alert_category_t connect_notification = 5_bit; │ │ │ │ │ + static constexpr alert_category_t status_notification = 6_bit; │ │ │ │ │ + static constexpr alert_category_t ip_block_notification = 8_bit; │ │ │ │ │ + static constexpr alert_category_t performance_warning = 9_bit; │ │ │ │ │ + static constexpr alert_category_t dht_notification = 10_bit; │ │ │ │ │ + static constexpr alert_category_t session_log_notification = 13_bit; │ │ │ │ │ + static constexpr alert_category_t torrent_log_notification = 14_bit; │ │ │ │ │ + static constexpr alert_category_t peer_log_notification = 15_bit; │ │ │ │ │ + static constexpr alert_category_t incoming_request_notification = 16_bit; │ │ │ │ │ + static constexpr alert_category_t dht_log_notification = 17_bit; │ │ │ │ │ + static constexpr alert_category_t dht_operation_notification = 18_bit; │ │ │ │ │ + static constexpr alert_category_t port_mapping_log_notification = 19_bit; │ │ │ │ │ + static constexpr alert_category_t picker_log_notification = 20_bit; │ │ │ │ │ + static constexpr alert_category_t file_progress_notification = 21_bit; │ │ │ │ │ + static constexpr alert_category_t piece_progress_notification = 22_bit; │ │ │ │ │ + static constexpr alert_category_t upload_notification = 23_bit; │ │ │ │ │ + static constexpr alert_category_t block_progress_notification = 24_bit; │ │ │ │ │ + static constexpr alert_category_t all_categories = alert_category_t::all(); │ │ │ │ │ +}; │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** timestamp() ***** │ │ │ │ │ +time_point timestamp () const; │ │ │ │ │ +a timestamp is automatically created in the constructor │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** type() ***** │ │ │ │ │ +virtual int type () const noexcept = 0; │ │ │ │ │ +returns an integer that is unique to this alert type. It can be compared │ │ │ │ │ +against a specific alert by querying a static constant called alert_type in the │ │ │ │ │ +alert. It can be used to determine the run-time type of an alert* in order to │ │ │ │ │ +cast to that alert type and access specific members. │ │ │ │ │ +e.g: │ │ │ │ │ +std::vector alerts; │ │ │ │ │ +ses.pop_alerts(&alerts); │ │ │ │ │ +for (alert* a : alerts) { │ │ │ │ │ + switch (a->type()) { │ │ │ │ │ + │ │ │ │ │ + case read_piece_alert::alert_type: │ │ │ │ │ + { │ │ │ │ │ + auto* p = static_cast(a); │ │ │ │ │ + if (p->ec) { │ │ │ │ │ + // read_piece failed │ │ │ │ │ + break; │ │ │ │ │ + } │ │ │ │ │ + // use p │ │ │ │ │ + break; │ │ │ │ │ + } │ │ │ │ │ + case file_renamed_alert::alert_type: │ │ │ │ │ + { │ │ │ │ │ + // etc... │ │ │ │ │ + } │ │ │ │ │ + } │ │ │ │ │ +} │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** what() ***** │ │ │ │ │ +virtual char const* what () const noexcept = 0; │ │ │ │ │ +returns a string literal describing the type of the alert. It does not include │ │ │ │ │ +any information that might be bundled with the alert. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** message() ***** │ │ │ │ │ +virtual std::string message () const = 0; │ │ │ │ │ +generate a string describing the alert and the information bundled with it. │ │ │ │ │ +This is mainly intended for debug and development use. It is not suitable to │ │ │ │ │ +use this for applications that may be localized. Instead, handle each alert │ │ │ │ │ +type individually and extract and render the information from the alert │ │ │ │ │ +depending on the locale. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** category() ***** │ │ │ │ │ +virtual alert_category_t category () const noexcept = 0; │ │ │ │ │ +returns a bitmask specifying which categories this alert belong to. │ │ │ │ │ +[report_issue] │ │ │ │ │ ****** operation_name() ****** │ │ │ │ │ Declared in "libtorrent/operations.hpp" │ │ │ │ │ char const* operation_name (operation_t op); │ │ │ │ │ maps an operation id (from peer_error_alert and peer_disconnected_alert) to its │ │ │ │ │ name. See operation_t for the constants │ │ │ │ │ [report_issue] │ │ │ │ │ ****** alert_cast() ****** │ │ │ │ │ Declared in "libtorrent/alert.hpp" │ │ │ │ │ -template T const* alert_cast (alert const* a); │ │ │ │ │ template T* alert_cast (alert* a); │ │ │ │ │ +template T const* alert_cast (alert const* a); │ │ │ │ │ When you get an alert, you can use alert_cast<> to attempt to cast the pointer │ │ │ │ │ to a specific alert type, in order to query it for more information. │ │ │ │ │ Note │ │ │ │ │ alert_cast<> can only cast to an exact alert type, not a base class │ │ │ │ │ [report_issue] │ │ │ │ │ ****** enum operation_t ****** │ │ │ │ │ Declared in "libtorrent/operations.hpp" │ │ │ │ │ @@ -9556,14 +8534,21 @@ │ │ │ │ │ |enum_route_________|42___|enumeration_of_network_routes______________________| │ │ │ │ │ |file_seek |43 |moving read/write position in a file, operation_t::| │ │ │ │ │ |___________________|_____|hostname_lookup____________________________________| │ │ │ │ │ |timer______________|44___|an_async_wait_operation_on_a_timer_________________| │ │ │ │ │ |file_mmap__________|45___|call_to_mmap()_(or_windows_counterpart)____________| │ │ │ │ │ |file_truncate______|46___|call_to_ftruncate()_(or_SetEndOfFile()_on_windows)_| │ │ │ │ │ [report_issue] │ │ │ │ │ +****** int ****** │ │ │ │ │ +Declared in "libtorrent/alert_types.hpp" │ │ │ │ │ + user_alert_id │ │ │ │ │ + user defined alerts should use IDs greater than this │ │ │ │ │ + num_alert_types │ │ │ │ │ + this constant represents "max_alert_index" + 1 │ │ │ │ │ +[report_issue] │ │ │ │ │ ****** alert_category_t ****** │ │ │ │ │ Declared in "libtorrent/alert.hpp" │ │ │ │ │ error │ │ │ │ │ Enables alerts that report an error. This includes: │ │ │ │ │ * tracker errors │ │ │ │ │ * tracker warnings │ │ │ │ │ * file errors │ │ │ │ │ @@ -9635,498 +8620,14 @@ │ │ │ │ │ rate. │ │ │ │ │ all │ │ │ │ │ The full bitmask, representing all available categories. │ │ │ │ │ since the enum is signed, make sure this isn't interpreted as -1. For │ │ │ │ │ instance, boost.python does that and fails when assigning it to an │ │ │ │ │ unsigned parameter. │ │ │ │ │ [report_issue] │ │ │ │ │ -****** int ****** │ │ │ │ │ -Declared in "libtorrent/alert_types.hpp" │ │ │ │ │ - user_alert_id │ │ │ │ │ - user defined alerts should use IDs greater than this │ │ │ │ │ - num_alert_types │ │ │ │ │ - this constant represents "max_alert_index" + 1 │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** 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*) = delete; │ │ │ │ │ - operator void* () const = delete; │ │ │ │ │ - operator void const* () const = delete; │ │ │ │ │ - client_data_t& operator= (void const*) = delete; │ │ │ │ │ - │ │ │ │ │ - template ::value>::type> │ │ │ │ │ -}; │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** client_data_t() ***** │ │ │ │ │ -client_data_t () = default; │ │ │ │ │ -construct a nullptr client data │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** const*() operator=() void*() ***** │ │ │ │ │ -client_data_t& operator= (void*) = delete; │ │ │ │ │ -operator void* () const = delete; │ │ │ │ │ -operator void const* () const = delete; │ │ │ │ │ -client_data_t& operator= (void const*) = delete; │ │ │ │ │ -we don't allow type-unsafe operations │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** 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 ti; │ │ │ │ │ - aux::noexcept_movable> trackers; │ │ │ │ │ - aux::noexcept_movable> tracker_tiers; │ │ │ │ │ - aux::noexcept_movable>> dht_nodes; │ │ │ │ │ - std::string name; │ │ │ │ │ - std::string save_path; │ │ │ │ │ - storage_mode_t storage_mode = storage_mode_sparse; │ │ │ │ │ - client_data_t userdata; │ │ │ │ │ - aux::noexcept_movable> 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> http_seeds; │ │ │ │ │ - aux::noexcept_movable> url_seeds; │ │ │ │ │ - aux::noexcept_movable> peers; │ │ │ │ │ - aux::noexcept_movable> banned_peers; │ │ │ │ │ - aux::noexcept_movable> unfinished_pieces; │ │ │ │ │ - typed_bitfield have_pieces; │ │ │ │ │ - typed_bitfield verified_pieces; │ │ │ │ │ - aux::noexcept_movable> piece_priorities; │ │ │ │ │ - aux::vector, file_index_t> merkle_trees; │ │ │ │ │ - aux::vector, file_index_t> merkle_tree_mask; │ │ │ │ │ - aux::vector, file_index_t> verified_leaf_hashes; │ │ │ │ │ - aux::noexcept_movable> renamed_files; │ │ │ │ │ - std::time_t last_download = 0; │ │ │ │ │ - std::time_t last_upload = 0; │ │ │ │ │ -}; │ │ │ │ │ -[report_issue] │ │ │ │ │ - version │ │ │ │ │ - filled in by the constructor and should be left untouched. It is used for │ │ │ │ │ - forward binary compatibility. │ │ │ │ │ -[report_issue] │ │ │ │ │ - ti │ │ │ │ │ - torrent_info object with the torrent to add. Unless the info_hash is set, │ │ │ │ │ - this is required to be initialized. │ │ │ │ │ -[report_issue] │ │ │ │ │ - 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. │ │ │ │ │ -[report_issue] │ │ │ │ │ - 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. │ │ │ │ │ -[report_issue] │ │ │ │ │ - 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. │ │ │ │ │ -[report_issue] │ │ │ │ │ - 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. │ │ │ │ │ -[report_issue] │ │ │ │ │ - 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. │ │ │ │ │ -[report_issue] │ │ │ │ │ - storage_mode │ │ │ │ │ - One of the values from storage_mode_t. For more information, see storage │ │ │ │ │ - allocation. │ │ │ │ │ -[report_issue] │ │ │ │ │ - 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(). │ │ │ │ │ -[report_issue] │ │ │ │ │ - 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. │ │ │ │ │ -[report_issue] │ │ │ │ │ - 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. │ │ │ │ │ -[report_issue] │ │ │ │ │ - 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. │ │ │ │ │ -[report_issue] │ │ │ │ │ - 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. │ │ │ │ │ - [report_issue] │ │ │ │ │ - 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. │ │ │ │ │ - [report_issue] │ │ │ │ │ - upload_limit download_limit │ │ │ │ │ - the upload and download rate limits for this torrent, specified in bytes │ │ │ │ │ - per second. -1 means unlimited. │ │ │ │ │ - [report_issue] │ │ │ │ │ - total_uploaded total_downloaded │ │ │ │ │ - the total number of bytes uploaded and downloaded by this torrent so far. │ │ │ │ │ - [report_issue] │ │ │ │ │ - active_time finished_time seeding_time │ │ │ │ │ - the number of seconds this torrent has spent in started, finished and │ │ │ │ │ - seeding state so far, respectively. │ │ │ │ │ - [report_issue] │ │ │ │ │ - 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. │ │ │ │ │ -[report_issue] │ │ │ │ │ - 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. │ │ │ │ │ - [report_issue] │ │ │ │ │ - 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. │ │ │ │ │ - [report_issue] │ │ │ │ │ - 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. │ │ │ │ │ -[report_issue] │ │ │ │ │ - peers │ │ │ │ │ - peers to add to the torrent, to be tried to be connected to as bittorrent │ │ │ │ │ - peers. │ │ │ │ │ -[report_issue] │ │ │ │ │ - banned_peers │ │ │ │ │ - peers banned from this torrent. The will not be connected to │ │ │ │ │ -[report_issue] │ │ │ │ │ - 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. │ │ │ │ │ -[report_issue] │ │ │ │ │ - have_pieces │ │ │ │ │ - this is a bitfield indicating which pieces we already have of this │ │ │ │ │ - torrent. │ │ │ │ │ -[report_issue] │ │ │ │ │ - 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. │ │ │ │ │ -[report_issue] │ │ │ │ │ - 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. │ │ │ │ │ -[report_issue] │ │ │ │ │ - merkle_trees │ │ │ │ │ - v2 hashes, if known │ │ │ │ │ -[report_issue] │ │ │ │ │ - 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. │ │ │ │ │ -[report_issue] │ │ │ │ │ - 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. │ │ │ │ │ -[report_issue] │ │ │ │ │ - renamed_files │ │ │ │ │ - this is a map of file indices in the torrent and new filenames to be │ │ │ │ │ - applied before the torrent is added. │ │ │ │ │ - [report_issue] │ │ │ │ │ - last_download last_upload │ │ │ │ │ - the posix time of the last time payload was received or sent for this │ │ │ │ │ - torrent, respectively. │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** hasher ****** │ │ │ │ │ -Declared in "libtorrent/hasher.hpp" │ │ │ │ │ -this is a SHA-1 hash class. │ │ │ │ │ -You use it by first instantiating it, then call update() to feed it with data. │ │ │ │ │ -i.e. you don't have to keep the entire buffer of which you want to create the │ │ │ │ │ -hash in memory. You can feed the hasher parts of it at a time. When You have │ │ │ │ │ -fed the hasher with all the data, you call final() and it will return the sha1- │ │ │ │ │ -hash of the data. │ │ │ │ │ -The constructor that takes a char const* and an integer will construct the sha1 │ │ │ │ │ -context and feed it the data passed in. │ │ │ │ │ -If you want to reuse the hasher object once you have created a hash, you have │ │ │ │ │ -to call reset() to reinitialize it. │ │ │ │ │ -The built-in software version of sha1-algorithm was implemented by Steve Reid │ │ │ │ │ -and released as public domain. For more info, see src/sha1.cpp. │ │ │ │ │ -class hasher │ │ │ │ │ -{ │ │ │ │ │ - hasher (); │ │ │ │ │ - hasher& operator= (hasher const&) &; │ │ │ │ │ - hasher (hasher const&); │ │ │ │ │ - explicit hasher (span data); │ │ │ │ │ - hasher (char const* data, int len); │ │ │ │ │ - hasher& update (span data); │ │ │ │ │ - hasher& update (char const* data, int len); │ │ │ │ │ - sha1_hash final (); │ │ │ │ │ - void reset (); │ │ │ │ │ -}; │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** hasher() operator=() ***** │ │ │ │ │ -hasher& operator= (hasher const&) &; │ │ │ │ │ -hasher (hasher const&); │ │ │ │ │ -explicit hasher (span data); │ │ │ │ │ -hasher (char const* data, int len); │ │ │ │ │ -this is the same as default constructing followed by a call to update(data, │ │ │ │ │ -len). │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** update() ***** │ │ │ │ │ -hasher& update (span data); │ │ │ │ │ -hasher& update (char const* data, int len); │ │ │ │ │ -append the following bytes to what is being hashed │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** final() ***** │ │ │ │ │ -sha1_hash final (); │ │ │ │ │ -returns the SHA-1 digest of the buffers previously passed to update() and the │ │ │ │ │ -hasher constructor. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** reset() ***** │ │ │ │ │ -void reset (); │ │ │ │ │ -restore the hasher state to be as if the hasher has just been default │ │ │ │ │ -constructed. │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** hasher256 ****** │ │ │ │ │ -Declared in "libtorrent/hasher.hpp" │ │ │ │ │ -class hasher256 │ │ │ │ │ -{ │ │ │ │ │ - hasher256 (); │ │ │ │ │ - hasher256 (hasher256 const&); │ │ │ │ │ - hasher256& operator= (hasher256 const&) &; │ │ │ │ │ - explicit hasher256 (span data); │ │ │ │ │ - hasher256 (char const* data, int len); │ │ │ │ │ - hasher256& update (span data); │ │ │ │ │ - hasher256& update (char const* data, int len); │ │ │ │ │ - sha256_hash final (); │ │ │ │ │ - void reset (); │ │ │ │ │ - ~hasher256 (); │ │ │ │ │ -}; │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** hasher256() operator=() ***** │ │ │ │ │ -hasher256 (hasher256 const&); │ │ │ │ │ -hasher256& operator= (hasher256 const&) &; │ │ │ │ │ -explicit hasher256 (span data); │ │ │ │ │ -hasher256 (char const* data, int len); │ │ │ │ │ -this is the same as default constructing followed by a call to update(data, │ │ │ │ │ -len). │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** update() ***** │ │ │ │ │ -hasher256& update (span data); │ │ │ │ │ -hasher256& update (char const* data, int len); │ │ │ │ │ -append the following bytes to what is being hashed │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** final() ***** │ │ │ │ │ -sha256_hash final (); │ │ │ │ │ -returns the SHA-1 digest of the buffers previously passed to update() and the │ │ │ │ │ -hasher constructor. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** reset() ***** │ │ │ │ │ -void reset (); │ │ │ │ │ -restore the hasher state to be as if the hasher has just been default │ │ │ │ │ -constructed. │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** bitfield ****** │ │ │ │ │ -Declared in "libtorrent/bitfield.hpp" │ │ │ │ │ -The bitfield type stores any number of bits as a bitfield in a heap allocated │ │ │ │ │ -array. │ │ │ │ │ -struct bitfield │ │ │ │ │ -{ │ │ │ │ │ - bitfield (int bits, bool val); │ │ │ │ │ - bitfield (bitfield const& rhs); │ │ │ │ │ - bitfield (bitfield&& rhs) noexcept = default; │ │ │ │ │ - bitfield (char const* b, int bits); │ │ │ │ │ - bitfield () noexcept = default; │ │ │ │ │ - explicit bitfield (int bits); │ │ │ │ │ - void assign (char const* b, int const bits); │ │ │ │ │ - bool operator[] (int index) const noexcept; │ │ │ │ │ - bool get_bit (int index) const noexcept; │ │ │ │ │ - void clear_bit (int index) noexcept; │ │ │ │ │ - void set_bit (int index) noexcept; │ │ │ │ │ - bool all_set () const noexcept; │ │ │ │ │ - bool none_set () const noexcept; │ │ │ │ │ - int size () const noexcept; │ │ │ │ │ - int num_words () const noexcept; │ │ │ │ │ - bool empty () const noexcept; │ │ │ │ │ - char* data () noexcept; │ │ │ │ │ - char const* data () const noexcept; │ │ │ │ │ - void swap (bitfield& rhs) noexcept; │ │ │ │ │ - int count () const noexcept; │ │ │ │ │ - int find_first_set () const noexcept; │ │ │ │ │ - int find_last_clear () const noexcept; │ │ │ │ │ -}; │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** bitfield() ***** │ │ │ │ │ -bitfield (int bits, bool val); │ │ │ │ │ -bitfield (bitfield const& rhs); │ │ │ │ │ -bitfield (bitfield&& rhs) noexcept = default; │ │ │ │ │ -bitfield (char const* b, int bits); │ │ │ │ │ -bitfield () noexcept = default; │ │ │ │ │ -explicit bitfield (int bits); │ │ │ │ │ -constructs a new bitfield. The default constructor creates an empty bitfield. │ │ │ │ │ -bits is the size of the bitfield (specified in bits). val is the value to │ │ │ │ │ -initialize the bits to. If not specified all bits are initialized to 0. │ │ │ │ │ -The constructor taking a pointer b and bits copies a bitfield from the │ │ │ │ │ -specified buffer, and bits number of bits (rounded up to the nearest byte │ │ │ │ │ -boundary). │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** assign() ***** │ │ │ │ │ -void assign (char const* b, int const bits); │ │ │ │ │ -copy bitfield from buffer b of bits number of bits, rounded up to the nearest │ │ │ │ │ -byte boundary. │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** operator[]() get_bit() ***** │ │ │ │ │ -bool operator[] (int index) const noexcept; │ │ │ │ │ -bool get_bit (int index) const noexcept; │ │ │ │ │ -query bit at index. Returns true if bit is 1, otherwise false. │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** clear_bit() set_bit() ***** │ │ │ │ │ -void clear_bit (int index) noexcept; │ │ │ │ │ -void set_bit (int index) noexcept; │ │ │ │ │ -set bit at index to 0 (clear_bit) or 1 (set_bit). │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** all_set() ***** │ │ │ │ │ -bool all_set () const noexcept; │ │ │ │ │ -returns true if all bits in the bitfield are set │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** none_set() ***** │ │ │ │ │ -bool none_set () const noexcept; │ │ │ │ │ -returns true if no bit in the bitfield is set │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** size() ***** │ │ │ │ │ -int size () const noexcept; │ │ │ │ │ -returns the size of the bitfield in bits. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** num_words() ***** │ │ │ │ │ -int num_words () const noexcept; │ │ │ │ │ -returns the number of 32 bit words are needed to represent all bits in this │ │ │ │ │ -bitfield. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** empty() ***** │ │ │ │ │ -bool empty () const noexcept; │ │ │ │ │ -returns true if the bitfield has zero size. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** data() ***** │ │ │ │ │ -char* data () noexcept; │ │ │ │ │ -char const* data () const noexcept; │ │ │ │ │ -returns a pointer to the internal buffer of the bitfield, or nullptr if it's │ │ │ │ │ -empty. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** swap() ***** │ │ │ │ │ -void swap (bitfield& rhs) noexcept; │ │ │ │ │ -swaps the bit-fields two variables refer to │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** count() ***** │ │ │ │ │ -int count () const noexcept; │ │ │ │ │ -count the number of bits in the bitfield that are set to 1. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** find_first_set() ***** │ │ │ │ │ -int find_first_set () const noexcept; │ │ │ │ │ -returns the index of the first set bit in the bitfield, i.e. 1 bit. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** find_last_clear() ***** │ │ │ │ │ -int find_last_clear () const noexcept; │ │ │ │ │ -returns the index to the last cleared bit in the bitfield, i.e. 0 bit. │ │ │ │ │ -[report_issue] │ │ │ │ │ ****** torrent_status ****** │ │ │ │ │ Declared in "libtorrent/torrent_status.hpp" │ │ │ │ │ holds a snapshot of the status of a torrent, as queried by torrent_handle:: │ │ │ │ │ status(). │ │ │ │ │ struct torrent_status │ │ │ │ │ { │ │ │ │ │ bool operator== (torrent_status const& st) const; │ │ │ │ │ @@ -10595,126 +9096,2086 @@ │ │ │ │ │ is always a subset of active time). seeding means all files/pieces were │ │ │ │ │ downloaded and available to peers. Being available to peers does not │ │ │ │ │ imply there are other peers asking for the payload. │ │ │ │ │ [report_issue] │ │ │ │ │ flags │ │ │ │ │ reflects several of the torrent's flags. For more information, see │ │ │ │ │ torrent_handle::flags(). │ │ │ │ │ +Bencoding is a common representation in bittorrent used for dictionary, list, │ │ │ │ │ +int and string hierarchies. It's used to encode .torrent files and some │ │ │ │ │ +messages in the network protocol. libtorrent also uses it to store settings, │ │ │ │ │ +resume data and other session state. │ │ │ │ │ +Strings in bencoded structures do not necessarily represent text. Strings are │ │ │ │ │ +raw byte buffers of a certain length. If a string is meant to be interpreted as │ │ │ │ │ +text, it is required to be UTF-8 encoded. See BEP_3. │ │ │ │ │ +The function for decoding bencoded data bdecode(), returning a bdecode_node. │ │ │ │ │ +This function builds a tree that points back into the original buffer. The │ │ │ │ │ +returned bdecode_node will not be valid once the buffer it was parsed out of is │ │ │ │ │ +discarded. │ │ │ │ │ +It's possible to construct an entry from a bdecode_node, if a structure needs │ │ │ │ │ +to be altered and re-encoded. │ │ │ │ │ [report_issue] │ │ │ │ │ -****** 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 │ │ │ │ │ +****** entry ****** │ │ │ │ │ +Declared in "libtorrent/entry.hpp" │ │ │ │ │ +The entry class represents one node in a bencoded hierarchy. It works as a │ │ │ │ │ +variant type, it can be either a list, a dictionary (std::map), an integer or a │ │ │ │ │ +string. │ │ │ │ │ +class entry │ │ │ │ │ { │ │ │ │ │ - void add (socket_type_t const st, peer_class_t const peer_class); │ │ │ │ │ - void remove (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); │ │ │ │ │ + data_type type () const; │ │ │ │ │ + entry (span); │ │ │ │ │ + entry (preformatted_type); │ │ │ │ │ + entry (list_type); │ │ │ │ │ + entry (dictionary_type); │ │ │ │ │ + entry (integer_type); │ │ │ │ │ + entry (U v); │ │ │ │ │ + entry (data_type t); │ │ │ │ │ + entry (bdecode_node const& n); │ │ │ │ │ + entry& operator= (span) &; │ │ │ │ │ + entry& operator= (entry&&) & noexcept; │ │ │ │ │ + entry& operator= (preformatted_type) &; │ │ │ │ │ + entry& operator= (entry const&) &; │ │ │ │ │ + entry& operator= (list_type) &; │ │ │ │ │ + entry& operator= (integer_type) &; │ │ │ │ │ + entry& operator= (dictionary_type) &; │ │ │ │ │ + entry& operator= (bdecode_node const&) &; │ │ │ │ │ + entry& operator= (U v) &; │ │ │ │ │ + preformatted_type& preformatted (); │ │ │ │ │ + dictionary_type& dict (); │ │ │ │ │ + string_type const& string () const; │ │ │ │ │ + list_type& list (); │ │ │ │ │ + integer_type const& integer () const; │ │ │ │ │ + list_type const& list () const; │ │ │ │ │ + string_type& string (); │ │ │ │ │ + preformatted_type const& preformatted () const; │ │ │ │ │ + integer_type& integer (); │ │ │ │ │ + dictionary_type const& dict () const; │ │ │ │ │ + void swap (entry& e); │ │ │ │ │ + entry const& operator[] (string_view key) const; │ │ │ │ │ + entry& operator[] (string_view key); │ │ │ │ │ + entry* find_key (string_view key); │ │ │ │ │ + entry const* find_key (string_view key) const; │ │ │ │ │ + std::string to_string (bool single_line = false) const; │ │ │ │ │ │ │ │ │ │ - enum socket_type_t │ │ │ │ │ + enum data_type │ │ │ │ │ { │ │ │ │ │ - tcp_socket, │ │ │ │ │ - utp_socket, │ │ │ │ │ - ssl_tcp_socket, │ │ │ │ │ - ssl_utp_socket, │ │ │ │ │ - i2p_socket, │ │ │ │ │ - num_socket_types, │ │ │ │ │ + int_t, │ │ │ │ │ + string_t, │ │ │ │ │ + list_t, │ │ │ │ │ + dictionary_t, │ │ │ │ │ + undefined_t, │ │ │ │ │ + preformatted_t, │ │ │ │ │ }; │ │ │ │ │ }; │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** type() ***** │ │ │ │ │ +data_type type () const; │ │ │ │ │ +returns the concrete type of the entry │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** entry() ***** │ │ │ │ │ +entry (span); │ │ │ │ │ +entry (preformatted_type); │ │ │ │ │ +entry (list_type); │ │ │ │ │ +entry (dictionary_type); │ │ │ │ │ +entry (integer_type); │ │ │ │ │ +constructors directly from a specific type. The content of the argument is │ │ │ │ │ +copied into the newly constructed entry │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** entry() ***** │ │ │ │ │ +entry (data_type t); │ │ │ │ │ +construct an empty entry of the specified type. see data_type enum. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** entry() ***** │ │ │ │ │ +entry (bdecode_node const& n); │ │ │ │ │ +construct from bdecode_node parsed form (see bdecode()) │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** operator=() ***** │ │ │ │ │ +entry& operator= (span) &; │ │ │ │ │ +entry& operator= (entry&&) & noexcept; │ │ │ │ │ +entry& operator= (preformatted_type) &; │ │ │ │ │ +entry& operator= (entry const&) &; │ │ │ │ │ +entry& operator= (list_type) &; │ │ │ │ │ +entry& operator= (integer_type) &; │ │ │ │ │ +entry& operator= (dictionary_type) &; │ │ │ │ │ +entry& operator= (bdecode_node const&) &; │ │ │ │ │ +copies the structure of the right hand side into this entry. │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** preformatted() integer() list() dict() string() ***** │ │ │ │ │ +preformatted_type& preformatted (); │ │ │ │ │ +dictionary_type& dict (); │ │ │ │ │ +string_type const& string () const; │ │ │ │ │ +list_type& list (); │ │ │ │ │ +integer_type const& integer () const; │ │ │ │ │ +list_type const& list () const; │ │ │ │ │ +string_type& string (); │ │ │ │ │ +preformatted_type const& preformatted () const; │ │ │ │ │ +integer_type& integer (); │ │ │ │ │ +dictionary_type const& dict () const; │ │ │ │ │ +The integer(), string(), list() and dict() functions are accessors that return │ │ │ │ │ +the respective type. If the entry object isn't of the type you request, the │ │ │ │ │ +accessor will throw system_error. You can ask an entry for its type through the │ │ │ │ │ +type() function. │ │ │ │ │ +If you want to create an entry you give it the type you want it to have in its │ │ │ │ │ +constructor, and then use one of the non-const accessors to get a reference │ │ │ │ │ +which you then can assign the value you want it to have. │ │ │ │ │ +The typical code to get info from a torrent file will then look like this: │ │ │ │ │ +entry torrent_file; │ │ │ │ │ +// ... │ │ │ │ │ + │ │ │ │ │ +// throws if this is not a dictionary │ │ │ │ │ +entry::dictionary_type const& dict = torrent_file.dict(); │ │ │ │ │ +entry::dictionary_type::const_iterator i; │ │ │ │ │ +i = dict.find("announce"); │ │ │ │ │ +if (i != dict.end()) │ │ │ │ │ +{ │ │ │ │ │ + std::string tracker_url = i->second.string(); │ │ │ │ │ + std::cout << tracker_url << "\n"; │ │ │ │ │ +} │ │ │ │ │ +The following code is equivalent, but a little bit shorter: │ │ │ │ │ +entry torrent_file; │ │ │ │ │ +// ... │ │ │ │ │ + │ │ │ │ │ +// throws if this is not a dictionary │ │ │ │ │ +if (entry* i = torrent_file.find_key("announce")) │ │ │ │ │ +{ │ │ │ │ │ + std::string tracker_url = i->string(); │ │ │ │ │ + std::cout << tracker_url << "\n"; │ │ │ │ │ +} │ │ │ │ │ +To make it easier to extract information from a torrent file, the class │ │ │ │ │ +torrent_info exists. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** swap() ***** │ │ │ │ │ +void swap (entry& e); │ │ │ │ │ +swaps the content of this with e. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** operator[]() ***** │ │ │ │ │ +entry const& operator[] (string_view key) const; │ │ │ │ │ +entry& operator[] (string_view key); │ │ │ │ │ +All of these functions requires the entry to be a dictionary, if it isn't they │ │ │ │ │ +will throw system_error. │ │ │ │ │ +The non-const versions of the operator[] will return a reference to either the │ │ │ │ │ +existing element at the given key or, if there is no element with the given │ │ │ │ │ +key, a reference to a newly inserted element at that key. │ │ │ │ │ +The const version of operator[] will only return a reference to an existing │ │ │ │ │ +element at the given key. If the key is not found, it will throw system_error. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** find_key() ***** │ │ │ │ │ +entry* find_key (string_view key); │ │ │ │ │ +entry const* find_key (string_view key) const; │ │ │ │ │ +These functions requires the entry to be a dictionary, if it isn't they will │ │ │ │ │ +throw system_error. │ │ │ │ │ +They will look for an element at the given key in the dictionary, if the │ │ │ │ │ +element cannot be found, they will return nullptr. If an element with the given │ │ │ │ │ +key is found, the return a pointer to it. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** to_string() ***** │ │ │ │ │ +std::string to_string (bool single_line = false) const; │ │ │ │ │ +returns a pretty-printed string representation of the bencoded structure, with │ │ │ │ │ +JSON-style syntax │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** enum data_type ***** │ │ │ │ │ +Declared in "libtorrent/entry.hpp" │ │ │ │ │ + ________________________________ │ │ │ │ │ +|name__________|value|description| │ │ │ │ │ +|int_t_________|0____| _________| │ │ │ │ │ +|string_t______|1____| _________| │ │ │ │ │ +|list_t________|2____| _________| │ │ │ │ │ +|dictionary_t__|3____| _________| │ │ │ │ │ +|undefined_t___|4____| _________| │ │ │ │ │ +|preformatted_t|5____| _________| │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** operator<<() ****** │ │ │ │ │ +Declared in "libtorrent/entry.hpp" │ │ │ │ │ +inline std::ostream& operator<< (std::ostream& os, const entry& e); │ │ │ │ │ +prints the bencoded structure to the ostream as a JSON-style structure. │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** bencode() ****** │ │ │ │ │ +Declared in "libtorrent/bencode.hpp" │ │ │ │ │ +template int bencode (OutIt out, const entry& e); │ │ │ │ │ +This function will encode data to bencoded form. │ │ │ │ │ +The entry class is the internal representation of the bencoded data and it can │ │ │ │ │ +be used to retrieve information, an entry can also be build by the program and │ │ │ │ │ +given to bencode() to encode it into the OutIt iterator. │ │ │ │ │ +OutIt is an OutputIterator. It's a template and usually instantiated as │ │ │ │ │ +ostream_iterator or back_insert_iterator. This function assumes the value_type │ │ │ │ │ +of the iterator is a char. In order to encode entry e into a buffer, do: │ │ │ │ │ +std::vector buffer; │ │ │ │ │ +bencode(std::back_inserter(buf), e); │ │ │ │ │ +libtorrent has a plugin interface for implementing extensions to the protocol. │ │ │ │ │ +These can be general extensions for transferring metadata or peer exchange │ │ │ │ │ +extensions, or it could be used to provide a way to customize the protocol to │ │ │ │ │ +fit a particular (closed) network. │ │ │ │ │ +In short, the plugin interface makes it possible to: │ │ │ │ │ + * register extension messages (sent in the extension handshake), see │ │ │ │ │ + extensions. │ │ │ │ │ + * add data and parse data from the extension handshake. │ │ │ │ │ + * send extension messages and standard bittorrent messages. │ │ │ │ │ + * override or block the handling of standard bittorrent messages. │ │ │ │ │ + * save and restore state via the session state │ │ │ │ │ + * see all alerts that are posted │ │ │ │ │ +****** 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 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_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 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 = ; │ │ │ │ │ +virtual int type() const { return alert_type; } │ │ │ │ │ + │ │ │ │ │ +virtual std::string message() const; │ │ │ │ │ + │ │ │ │ │ +static const alert_category_t static_category = ; │ │ │ │ │ +virtual alert_category_t category() const { return static_category; } │ │ │ │ │ + │ │ │ │ │ +virtual char const* what() const { return ; } │ │ │ │ │ +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. │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** 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 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 save_state () const; │ │ │ │ │ + virtual void load_state (std::map 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; │ │ │ │ │ +}; │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** implemented_features() ***** │ │ │ │ │ +virtual feature_flags_t implemented_features (); │ │ │ │ │ +This function is expected to return a bitmask indicating which features this │ │ │ │ │ +plugin implements. Some callbacks on this object may not be called unless the │ │ │ │ │ +corresponding feature flag is returned here. Note that callbacks may still be │ │ │ │ │ +called even if the corresponding feature is not specified in the return value │ │ │ │ │ +here. See feature_flags_t for possible flags to return. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** new_torrent() ***** │ │ │ │ │ +virtual std::shared_ptr new_torrent (torrent_handle const&, │ │ │ │ │ +client_data_t); │ │ │ │ │ +this is called by the session every time a new torrent is added. The torrent* │ │ │ │ │ +points to the internal torrent object created for the new torrent. The │ │ │ │ │ +client_data_t is the userdata pointer as passed in via add_torrent_params. │ │ │ │ │ +If the plugin returns a torrent_plugin instance, it will be added to the new │ │ │ │ │ +torrent. Otherwise, return an empty shared_ptr to a torrent_plugin (the │ │ │ │ │ +default). │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** added() ***** │ │ │ │ │ +virtual void added (session_handle const&); │ │ │ │ │ +called when plugin is added to a session │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** abort() ***** │ │ │ │ │ +virtual void abort (); │ │ │ │ │ +called when the session is aborted the plugin should perform any cleanup │ │ │ │ │ +necessary to allow the session's destruction (e.g. cancel outstanding async │ │ │ │ │ +operations) │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** on_dht_request() ***** │ │ │ │ │ +virtual bool on_dht_request (string_view /* query */ │ │ │ │ │ + , udp::endpoint const& /* source */, bdecode_node const& /* message */ │ │ │ │ │ + , entry& /* response */); │ │ │ │ │ +called when a dht request is received. If your plugin expects this to be │ │ │ │ │ +called, make sure to include the flag dht_request_feature in the return value │ │ │ │ │ +from implemented_features(). │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** on_alert() ***** │ │ │ │ │ +virtual void on_alert (alert const*); │ │ │ │ │ +called when an alert is posted alerts that are filtered are not posted. If your │ │ │ │ │ +plugin expects this to be called, make sure to include the flag alert_feature │ │ │ │ │ +in the return value from implemented_features(). │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** on_unknown_torrent() ***** │ │ │ │ │ +virtual bool on_unknown_torrent (info_hash_t const& /* info_hash */ │ │ │ │ │ + , peer_connection_handle const& /* pc */, add_torrent_params& /* p */); │ │ │ │ │ +return true if the add_torrent_params should be added │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** on_tick() ***** │ │ │ │ │ +virtual void on_tick (); │ │ │ │ │ +called once per second. If your plugin expects this to be called, make sure to │ │ │ │ │ +include the flag tick_feature in the return value from implemented_features(). │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** get_unchoke_priority() ***** │ │ │ │ │ +virtual uint64_t get_unchoke_priority (peer_connection_handle const& /* peer */ │ │ │ │ │ +); │ │ │ │ │ +called when choosing peers to optimistically unchoke. The return value │ │ │ │ │ +indicates the peer's priority for unchoking. Lower return values correspond to │ │ │ │ │ +higher priority. Priorities above 2^63-1 are reserved. If your plugin has no │ │ │ │ │ +priority to assign a peer it should return 2^64-1. If your plugin expects this │ │ │ │ │ +to be called, make sure to include the flag optimistic_unchoke_feature in the │ │ │ │ │ +return value from implemented_features(). If multiple plugins implement this │ │ │ │ │ +function the lowest return value (i.e. the highest priority) is used. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** load_state() ***** │ │ │ │ │ +virtual void load_state (std::map const&); │ │ │ │ │ +called on startup while loading settings state from the session_params │ │ │ │ │ +[report_issue] │ │ │ │ │ + optimistic_unchoke_feature │ │ │ │ │ + include this bit if your plugin needs to alter the order of the │ │ │ │ │ + optimistic unchoke of peers. i.e. have the on_optimistic_unchoke() │ │ │ │ │ + callback be called. │ │ │ │ │ +[report_issue] │ │ │ │ │ + tick_feature │ │ │ │ │ + include this bit if your plugin needs to have on_tick() called │ │ │ │ │ +[report_issue] │ │ │ │ │ + dht_request_feature │ │ │ │ │ + include this bit if your plugin needs to have on_dht_request() called │ │ │ │ │ +[report_issue] │ │ │ │ │ + alert_feature │ │ │ │ │ + include this bit if your plugin needs to have on_alert() called │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** 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 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_pause (); │ │ │ │ │ + virtual bool on_resume (); │ │ │ │ │ + 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; │ │ │ │ │ +}; │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** new_connection() ***** │ │ │ │ │ +virtual std::shared_ptr new_connection (peer_connection_handle │ │ │ │ │ +const&); │ │ │ │ │ +This function is called each time a new peer is connected to the torrent. You │ │ │ │ │ +may choose to ignore this by just returning a default constructed shared_ptr │ │ │ │ │ +(in which case you don't need to override this member function). │ │ │ │ │ +If you need an extension to the peer connection (which most plugins do) you are │ │ │ │ │ +supposed to return an instance of your peer_plugin class. Which in turn will │ │ │ │ │ +have its hook functions called on event specific to that peer. │ │ │ │ │ +The peer_connection_handle will be valid as long as the shared_ptr is being │ │ │ │ │ +held by the torrent object. So, it is generally a good idea to not keep a │ │ │ │ │ +shared_ptr to your own peer_plugin. If you want to keep references to it, use │ │ │ │ │ +weak_ptr. │ │ │ │ │ +If this function throws an exception, the connection will be closed. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** add() remove() ***** │ │ │ │ │ -void add (socket_type_t const st, peer_class_t const peer_class); │ │ │ │ │ -void remove (socket_type_t const st, peer_class_t const peer_class); │ │ │ │ │ -add() and remove() adds and removes a peer class to be added to new peers based │ │ │ │ │ -on socket type. │ │ │ │ │ +***** on_piece_failed() on_piece_pass() ***** │ │ │ │ │ +virtual void on_piece_failed (piece_index_t); │ │ │ │ │ +virtual void on_piece_pass (piece_index_t); │ │ │ │ │ +These hooks are called when a piece passes the hash check or fails the hash │ │ │ │ │ +check, respectively. The index is the piece index that was downloaded. It is │ │ │ │ │ +possible to access the list of peers that participated in sending the piece │ │ │ │ │ +through the torrent and the piece_picker. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** tick() ***** │ │ │ │ │ +virtual void tick (); │ │ │ │ │ +This hook is called approximately once per second. It is a way of making it │ │ │ │ │ +easy for plugins to do timed events, for sending messages or whatever. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** disallow() allow() ***** │ │ │ │ │ -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); │ │ │ │ │ -disallow() and allow() adds and removes a peer class to be removed from new │ │ │ │ │ -peers based on socket type. │ │ │ │ │ -The peer_class argument cannot be greater than 31. The bitmasks representing │ │ │ │ │ -peer classes in the peer_class_type_filter are 32 bits. │ │ │ │ │ +***** on_pause() on_resume() ***** │ │ │ │ │ +virtual bool on_pause (); │ │ │ │ │ +virtual bool on_resume (); │ │ │ │ │ +These hooks are called when the torrent is paused and resumed respectively. The │ │ │ │ │ +return value indicates if the event was handled. A return value of true │ │ │ │ │ +indicates that it was handled, and no other plugin after this one will have │ │ │ │ │ +this hook function called, and the standard handler will also not be invoked. │ │ │ │ │ +So, returning true effectively overrides the standard behavior of pause or │ │ │ │ │ +resume. │ │ │ │ │ +Note that if you call pause() or resume() on the torrent from your handler it │ │ │ │ │ +will recurse back into your handler, so in order to invoke the standard │ │ │ │ │ +handler, you have to keep your own state on whether you want standard behavior │ │ │ │ │ +or overridden behavior. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** apply() ***** │ │ │ │ │ -std::uint32_t apply (socket_type_t const st, std::uint32_t peer_class_mask); │ │ │ │ │ -takes a bitmask of peer classes and returns a new bitmask of peer classes after │ │ │ │ │ -the rules have been applied, based on the socket type argument (st). │ │ │ │ │ +***** on_files_checked() ***** │ │ │ │ │ +virtual void on_files_checked (); │ │ │ │ │ +This function is called when the initial files of the torrent have been │ │ │ │ │ +checked. If there are no files to check, this function is called immediately. │ │ │ │ │ +i.e. This function is always called when the torrent is in a state where it can │ │ │ │ │ +start downloading. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** enum socket_type_t ***** │ │ │ │ │ -Declared in "libtorrent/peer_class_type_filter.hpp" │ │ │ │ │ - ________________________________________________________________________ │ │ │ │ │ -|name____________|value|description______________________________________| │ │ │ │ │ -|tcp_socket |0 |these match the socket types from socket_type.hpp| │ │ │ │ │ -|________________|_____|shifted_one_down_________________________________| │ │ │ │ │ -|utp_socket______|1____| _______________________________________________| │ │ │ │ │ -|ssl_tcp_socket__|2____| _______________________________________________| │ │ │ │ │ -|ssl_utp_socket__|3____| _______________________________________________| │ │ │ │ │ -|i2p_socket______|4____| _______________________________________________| │ │ │ │ │ -|num_socket_types|5____| _______________________________________________| │ │ │ │ │ +***** on_state() ***** │ │ │ │ │ +virtual void on_state (torrent_status::state_t); │ │ │ │ │ +called when the torrent changes state the state is one of torrent_status:: │ │ │ │ │ +state_t enum members │ │ │ │ │ [report_issue] │ │ │ │ │ -****** 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 │ │ │ │ │ +***** on_add_peer() ***** │ │ │ │ │ +virtual void on_add_peer (tcp::endpoint const&, │ │ │ │ │ + peer_source_flags_t, add_peer_flags_t); │ │ │ │ │ +called every time a new peer is added to the peer list. This is before the peer │ │ │ │ │ +is connected to. For flags, see torrent_plugin::flags_t. The source argument │ │ │ │ │ +refers to the source where we learned about this peer from. It's a bitmask, │ │ │ │ │ +because many sources may have told us about the same peer. For peer source │ │ │ │ │ +flags, see peer_info::peer_source_flags. │ │ │ │ │ +[report_issue] │ │ │ │ │ + first_time │ │ │ │ │ + this is the first time we see this peer │ │ │ │ │ +[report_issue] │ │ │ │ │ + filtered │ │ │ │ │ + this peer was not added because it was filtered by the IP filter │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** 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 │ │ │ │ │ { │ │ │ │ │ - bool ignore_unchoke_slots; │ │ │ │ │ - int connection_limit_factor; │ │ │ │ │ - std::string label; │ │ │ │ │ - int upload_limit; │ │ │ │ │ - int download_limit; │ │ │ │ │ - int upload_priority; │ │ │ │ │ - int download_priority; │ │ │ │ │ + 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); │ │ │ │ │ + virtual bool on_extension_handshake (bdecode_node const&); │ │ │ │ │ + virtual bool on_bitfield (bitfield const& /*bitfield*/); │ │ │ │ │ + virtual bool on_request (peer_request const&); │ │ │ │ │ + virtual bool on_not_interested (); │ │ │ │ │ + virtual bool on_interested (); │ │ │ │ │ + virtual bool on_have_all (); │ │ │ │ │ + virtual bool on_unchoke (); │ │ │ │ │ + virtual bool on_dont_have (piece_index_t); │ │ │ │ │ + virtual bool on_have (piece_index_t); │ │ │ │ │ + virtual bool on_have_none (); │ │ │ │ │ + virtual bool on_choke (); │ │ │ │ │ + virtual bool on_allowed_fast (piece_index_t); │ │ │ │ │ + virtual bool on_piece (peer_request const& /*piece*/ │ │ │ │ │ + , span /*buf*/); │ │ │ │ │ + virtual bool on_cancel (peer_request const&); │ │ │ │ │ + virtual bool on_reject (peer_request const&); │ │ │ │ │ + virtual bool on_suggest (piece_index_t); │ │ │ │ │ + virtual void sent_have_none (); │ │ │ │ │ + virtual void sent_have_all (); │ │ │ │ │ + virtual void sent_suggest (piece_index_t); │ │ │ │ │ + virtual void sent_reject_request (peer_request const&); │ │ │ │ │ + virtual void sent_request (peer_request const&); │ │ │ │ │ + virtual void sent_cancel (peer_request const&); │ │ │ │ │ + virtual void sent_allow_fast (piece_index_t); │ │ │ │ │ + virtual void sent_choke (); │ │ │ │ │ + virtual void sent_piece (peer_request const&); │ │ │ │ │ + virtual void sent_not_interested (); │ │ │ │ │ + virtual void sent_unchoke (); │ │ │ │ │ + virtual void sent_interested (); │ │ │ │ │ + virtual void sent_have (piece_index_t); │ │ │ │ │ + virtual void sent_payload (int /* bytes */); │ │ │ │ │ + virtual bool can_disconnect (error_code const& /*ec*/); │ │ │ │ │ + virtual bool on_extended (int /*length*/, int /*msg*/, │ │ │ │ │ + span /*body*/); │ │ │ │ │ + virtual bool on_unknown_message (int /*length*/, int /*msg*/, │ │ │ │ │ + span /*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&); │ │ │ │ │ }; │ │ │ │ │ [report_issue] │ │ │ │ │ - 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. │ │ │ │ │ +***** type() ***** │ │ │ │ │ +virtual string_view type () const; │ │ │ │ │ +This function is expected to return the name of the plugin. │ │ │ │ │ [report_issue] │ │ │ │ │ - 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. │ │ │ │ │ +***** add_handshake() ***** │ │ │ │ │ +virtual void add_handshake (entry&); │ │ │ │ │ +can add entries to the extension handshake this is not called for web seeds │ │ │ │ │ [report_issue] │ │ │ │ │ - label │ │ │ │ │ - not used by libtorrent. It's intended as a potentially user-facing │ │ │ │ │ - identifier of this peer class. │ │ │ │ │ +***** on_disconnect() ***** │ │ │ │ │ +virtual void on_disconnect (error_code const&); │ │ │ │ │ +called when the peer is being disconnected. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** on_connected() ***** │ │ │ │ │ +virtual void on_connected (); │ │ │ │ │ +called when the peer is successfully connected. Note that incoming connections │ │ │ │ │ +will have been connected by the time the peer plugin is attached to it, and │ │ │ │ │ +won't have this hook called. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** on_handshake() ***** │ │ │ │ │ +virtual bool on_handshake (span); │ │ │ │ │ +this is called when the initial bittorrent handshake is received. Returning │ │ │ │ │ +false means that the other end doesn't support this extension and will remove │ │ │ │ │ +it from the list of plugins. this is not called for web seeds │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** on_extension_handshake() ***** │ │ │ │ │ +virtual bool on_extension_handshake (bdecode_node const&); │ │ │ │ │ +called when the extension handshake from the other end is received if this │ │ │ │ │ +returns false, it means that this extension isn't supported by this peer. It │ │ │ │ │ +will result in this peer_plugin being removed from the peer_connection and │ │ │ │ │ +destructed. this is not called for web seeds │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** on_have() on_have_all() on_interested() on_request() on_bitfield() │ │ │ │ │ +on_dont_have() on_allowed_fast() on_unchoke() on_have_none() on_not_interested │ │ │ │ │ +() on_choke() ***** │ │ │ │ │ +virtual bool on_bitfield (bitfield const& /*bitfield*/); │ │ │ │ │ +virtual bool on_request (peer_request const&); │ │ │ │ │ +virtual bool on_not_interested (); │ │ │ │ │ +virtual bool on_interested (); │ │ │ │ │ +virtual bool on_have_all (); │ │ │ │ │ +virtual bool on_unchoke (); │ │ │ │ │ +virtual bool on_dont_have (piece_index_t); │ │ │ │ │ +virtual bool on_have (piece_index_t); │ │ │ │ │ +virtual bool on_have_none (); │ │ │ │ │ +virtual bool on_choke (); │ │ │ │ │ +virtual bool on_allowed_fast (piece_index_t); │ │ │ │ │ +returning true from any of the message handlers indicates that the plugin has │ │ │ │ │ +handled the message. it will break the plugin chain traversing and not let │ │ │ │ │ +anyone else handle the message, including the default handler. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** on_piece() ***** │ │ │ │ │ +virtual bool on_piece (peer_request const& /*piece*/ │ │ │ │ │ + , span /*buf*/); │ │ │ │ │ +This function is called when the peer connection is receiving a piece. buf │ │ │ │ │ +points (non-owning pointer) to the data in an internal immutable disk buffer. │ │ │ │ │ +The length of the data is specified in the length member of the piece │ │ │ │ │ +parameter. returns true to indicate that the piece is handled and the rest of │ │ │ │ │ +the logic should be ignored. │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** sent_piece() sent_unchoke() sent_interested() sent_not_interested() │ │ │ │ │ +sent_have() ***** │ │ │ │ │ +virtual void sent_piece (peer_request const&); │ │ │ │ │ +virtual void sent_not_interested (); │ │ │ │ │ +virtual void sent_unchoke (); │ │ │ │ │ +virtual void sent_interested (); │ │ │ │ │ +virtual void sent_have (piece_index_t); │ │ │ │ │ +called after a choke message has been sent to the peer │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** sent_payload() ***** │ │ │ │ │ +virtual void sent_payload (int /* bytes */); │ │ │ │ │ +called after piece data has been sent to the peer this can be used for stats │ │ │ │ │ +book keeping │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** can_disconnect() ***** │ │ │ │ │ +virtual bool can_disconnect (error_code const& /*ec*/); │ │ │ │ │ +called when libtorrent think this peer should be disconnected. if the plugin │ │ │ │ │ +returns false, the peer will not be disconnected. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** on_extended() ***** │ │ │ │ │ +virtual bool on_extended (int /*length*/, int /*msg*/, │ │ │ │ │ + span /*body*/); │ │ │ │ │ +called when an extended message is received. If returning true, the message is │ │ │ │ │ +not processed by any other plugin and if false is returned the next plugin in │ │ │ │ │ +the chain will receive it to be able to handle it. This is not called for web │ │ │ │ │ +seeds. thus function may be called more than once per incoming message, but │ │ │ │ │ +only the last of the calls will the body size equal the length. i.e. Every time │ │ │ │ │ +another fragment of the message is received, this function will be called, │ │ │ │ │ +until finally the whole message has been received. The purpose of this is to │ │ │ │ │ +allow early disconnects for invalid messages and for reporting progress of │ │ │ │ │ +receiving large messages. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** on_unknown_message() ***** │ │ │ │ │ +virtual bool on_unknown_message (int /*length*/, int /*msg*/, │ │ │ │ │ + span /*body*/); │ │ │ │ │ +this is not called for web seeds │ │ │ │ │ [report_issue] │ │ │ │ │ - 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. │ │ │ │ │ +***** on_piece_failed() on_piece_pass() ***** │ │ │ │ │ +virtual void on_piece_failed (piece_index_t); │ │ │ │ │ +virtual void on_piece_pass (piece_index_t); │ │ │ │ │ +called when a piece that this peer participated in either fails or passes the │ │ │ │ │ +hash_check │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** tick() ***** │ │ │ │ │ +virtual void tick (); │ │ │ │ │ +called approximately once every second │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** write_request() ***** │ │ │ │ │ +virtual bool write_request (peer_request const&); │ │ │ │ │ +called each time a request message is to be sent. If true is returned, the │ │ │ │ │ +original request message won't be sent and no other plugin will have this │ │ │ │ │ +function called. │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** crypto_plugin ****** │ │ │ │ │ +Declared in "libtorrent/extensions.hpp" │ │ │ │ │ +struct crypto_plugin │ │ │ │ │ +{ │ │ │ │ │ + virtual void set_outgoing_key (span key) = 0; │ │ │ │ │ + virtual void set_incoming_key (span key) = 0; │ │ │ │ │ + encrypt (span> /*send_vec*/) = 0; │ │ │ │ │ + virtual std::tuple decrypt (span> /*receive_vec*/ │ │ │ │ │ +) = 0; │ │ │ │ │ +}; │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** decrypt() ***** │ │ │ │ │ +virtual std::tuple decrypt (span> /*receive_vec*/) = │ │ │ │ │ +0; │ │ │ │ │ +decrypt the provided buffers. returns is a tuple representing the values │ │ │ │ │ +(consume, produce, packet_size) │ │ │ │ │ +consume is set to the number of bytes which should be trimmed from the head of │ │ │ │ │ +the buffers, default is 0 │ │ │ │ │ +produce is set to the number of bytes of payload which are now ready to be sent │ │ │ │ │ +to the upper layer. default is the number of bytes passed in receive_vec │ │ │ │ │ +packet_size is set to the minimum number of bytes which must be read to advance │ │ │ │ │ +the next step of decryption. default is 0 │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** 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 impl); │ │ │ │ │ + connection_type type () const; │ │ │ │ │ + void add_extension (std::shared_ptr); │ │ │ │ │ + peer_plugin const* find_plugin (string_view type) const; │ │ │ │ │ + bool is_seed () const; │ │ │ │ │ + bool upload_only () const; │ │ │ │ │ + peer_id const& pid () const; │ │ │ │ │ + bool has_piece (piece_index_t i) const; │ │ │ │ │ + bool is_interesting () const; │ │ │ │ │ + bool is_choked () const; │ │ │ │ │ + bool is_peer_interested () const; │ │ │ │ │ + bool has_peer_choked () const; │ │ │ │ │ + void maybe_unchoke_this_peer (); │ │ │ │ │ + void choke_this_peer (); │ │ │ │ │ + void get_peer_info (peer_info& p) const; │ │ │ │ │ + torrent_handle associated_torrent () const; │ │ │ │ │ + tcp::endpoint local_endpoint () const; │ │ │ │ │ + tcp::endpoint const& remote () const; │ │ │ │ │ + bool is_outgoing () const; │ │ │ │ │ + bool is_disconnecting () const; │ │ │ │ │ + bool is_connecting () const; │ │ │ │ │ + void disconnect (error_code const& ec, operation_t op │ │ │ │ │ + , disconnect_severity_t = peer_connection_interface::normal); │ │ │ │ │ + bool on_local_network () const; │ │ │ │ │ + bool ignore_unchoke_slots () const; │ │ │ │ │ + bool failed () const; │ │ │ │ │ + void peer_log (peer_log_alert::direction_t direction │ │ │ │ │ + , char const* event, char const* fmt = "", ...) const TORRENT_FORMAT │ │ │ │ │ +(4,5); │ │ │ │ │ + bool should_log (peer_log_alert::direction_t direction) const; │ │ │ │ │ + bool can_disconnect (error_code const& ec) const; │ │ │ │ │ + bool has_metadata () const; │ │ │ │ │ + bool in_handshake () const; │ │ │ │ │ + void send_buffer (char const* begin, int size); │ │ │ │ │ + time_point time_of_last_unchoke () const; │ │ │ │ │ + std::time_t last_seen_complete () 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 native_handle () const; │ │ │ │ │ +}; │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** 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); │ │ │ │ │ + void switch_recv_crypto (std::shared_ptr crypto); │ │ │ │ │ + std::shared_ptr native_handle () const; │ │ │ │ │ +}; │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** create_ut_metadata_plugin() ****** │ │ │ │ │ +Declared in "libtorrent/extensions/ut_metadata.hpp" │ │ │ │ │ +std::shared_ptr 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(). │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** create_smart_ban_plugin() ****** │ │ │ │ │ +Declared in "libtorrent/extensions/smart_ban.hpp" │ │ │ │ │ +std::shared_ptr 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(). │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** create_ut_pex_plugin() ****** │ │ │ │ │ +Declared in "libtorrent/extensions/ut_pex.hpp" │ │ │ │ │ +std::shared_ptr 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(). │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** ip_filter ****** │ │ │ │ │ +Declared in "libtorrent/ip_filter.hpp" │ │ │ │ │ +The ip_filter class is a set of rules that uniquely categorizes all ip │ │ │ │ │ +addresses as allowed or disallowed. The default constructor creates a single │ │ │ │ │ +rule that allows all addresses (0.0.0.0 - 255.255.255.255 for the IPv4 range, │ │ │ │ │ +and the equivalent range covering all addresses for the IPv6 range). │ │ │ │ │ +A default constructed ip_filter does not filter any address. │ │ │ │ │ +struct ip_filter │ │ │ │ │ +{ │ │ │ │ │ + ip_filter (); │ │ │ │ │ + ip_filter& operator= (ip_filter&&); │ │ │ │ │ + ~ip_filter (); │ │ │ │ │ + ip_filter (ip_filter&&); │ │ │ │ │ + ip_filter& operator= (ip_filter const&); │ │ │ │ │ + ip_filter (ip_filter const&); │ │ │ │ │ + bool empty () const; │ │ │ │ │ + void add_rule (address const& first, address const& last, std::uint32_t │ │ │ │ │ +flags); │ │ │ │ │ + std::uint32_t access (address const& addr) const; │ │ │ │ │ + filter_tuple_t export_filter () const; │ │ │ │ │ + │ │ │ │ │ + enum access_flags │ │ │ │ │ + { │ │ │ │ │ + blocked, │ │ │ │ │ + }; │ │ │ │ │ +}; │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** empty() ***** │ │ │ │ │ +bool empty () const; │ │ │ │ │ +returns true if the filter does not contain any rules │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** add_rule() ***** │ │ │ │ │ +void add_rule (address const& first, address const& last, std::uint32_t flags); │ │ │ │ │ +Adds a rule to the filter. first and last defines a range of ip addresses that │ │ │ │ │ +will be marked with the given flags. The flags can currently be 0, which means │ │ │ │ │ +allowed, or ip_filter::blocked, which means disallowed. │ │ │ │ │ +precondition: first.is_v4() == last.is_v4() && first.is_v6() == last.is_v6() │ │ │ │ │ +postcondition: access(x) == flags for every x in the range [first, last] │ │ │ │ │ +This means that in a case of overlapping ranges, the last one applied takes │ │ │ │ │ +precedence. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** access() ***** │ │ │ │ │ +std::uint32_t access (address const& addr) const; │ │ │ │ │ +Returns the access permissions for the given address (addr). The permission can │ │ │ │ │ +currently be 0 or ip_filter::blocked. The complexity of this operation is O(log │ │ │ │ │ +n), where n is the minimum number of non-overlapping ranges to describe the │ │ │ │ │ +current filter. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** export_filter() ***** │ │ │ │ │ +filter_tuple_t export_filter () const; │ │ │ │ │ +This function will return the current state of the filter in the minimum number │ │ │ │ │ +of ranges possible. They are sorted from ranges in low addresses to high │ │ │ │ │ +addresses. Each entry in the returned vector is a range with the access control │ │ │ │ │ +specified in its flags field. │ │ │ │ │ +The return value is a tuple containing two range-lists. One for IPv4 addresses │ │ │ │ │ +and one for IPv6 addresses. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** enum access_flags ***** │ │ │ │ │ +Declared in "libtorrent/ip_filter.hpp" │ │ │ │ │ + _____________________________________________________________________________ │ │ │ │ │ +|name___|value|description____________________________________________________| │ │ │ │ │ +|blocked|1 |indicates that IPs in this range should not be connected to nor| │ │ │ │ │ +|_______|_____|accepted_as_incoming_connections_______________________________| │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** port_filter ****** │ │ │ │ │ +Declared in "libtorrent/ip_filter.hpp" │ │ │ │ │ +the port filter maps non-overlapping port ranges to flags. This is primarily │ │ │ │ │ +used to indicate whether a range of ports should be connected to or not. The │ │ │ │ │ +default is to have the full port range (0-65535) set to flag 0. │ │ │ │ │ +class port_filter │ │ │ │ │ +{ │ │ │ │ │ + ~port_filter (); │ │ │ │ │ + port_filter (port_filter const&); │ │ │ │ │ + port_filter& operator= (port_filter const&); │ │ │ │ │ + port_filter& operator= (port_filter&&); │ │ │ │ │ + port_filter (); │ │ │ │ │ + port_filter (port_filter&&); │ │ │ │ │ + void add_rule (std::uint16_t first, std::uint16_t last, std::uint32_t │ │ │ │ │ +flags); │ │ │ │ │ + std::uint32_t access (std::uint16_t port) const; │ │ │ │ │ + │ │ │ │ │ + enum access_flags │ │ │ │ │ + { │ │ │ │ │ + blocked, │ │ │ │ │ + }; │ │ │ │ │ +}; │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** add_rule() ***** │ │ │ │ │ +void add_rule (std::uint16_t first, std::uint16_t last, std::uint32_t flags); │ │ │ │ │ +set the flags for the specified port range (first, last) to flags overwriting │ │ │ │ │ +any existing rule for those ports. The range is inclusive, i.e. the port last │ │ │ │ │ +also has the flag set on it. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** access() ***** │ │ │ │ │ +std::uint32_t access (std::uint16_t port) const; │ │ │ │ │ +test the specified port (port) for whether it is blocked or not. The returned │ │ │ │ │ +value is the flags set for this port. see access_flags. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** enum access_flags ***** │ │ │ │ │ +Declared in "libtorrent/ip_filter.hpp" │ │ │ │ │ + ____________________________________________________________________________ │ │ │ │ │ +|name___|value|description___________________________________________________| │ │ │ │ │ +|blocked|1 |this flag indicates that destination ports in the range should| │ │ │ │ │ +|_______|_____|not_be_connected_to___________________________________________| │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** bdecode_node ****** │ │ │ │ │ +Declared in "libtorrent/bdecode.hpp" │ │ │ │ │ +Sometimes it's important to get a non-owning reference to the root node ( to be │ │ │ │ │ +able to copy it as a reference for instance). For that, use the non_owning() │ │ │ │ │ +member function. │ │ │ │ │ +There are 5 different types of nodes, see type_t. │ │ │ │ │ +struct bdecode_node │ │ │ │ │ +{ │ │ │ │ │ + bdecode_node () = default; │ │ │ │ │ + bdecode_node (bdecode_node const&); │ │ │ │ │ + bdecode_node (bdecode_node&&) noexcept; │ │ │ │ │ + bdecode_node& operator= (bdecode_node&&) & = default; │ │ │ │ │ + bdecode_node& operator= (bdecode_node const&) &; │ │ │ │ │ + type_t type () const noexcept; │ │ │ │ │ + explicit operator bool () const noexcept; │ │ │ │ │ + bdecode_node non_owning () const; │ │ │ │ │ + span data_section () const noexcept; │ │ │ │ │ + std::ptrdiff_t data_offset () const noexcept; │ │ │ │ │ + std::int64_t list_int_value_at (int i │ │ │ │ │ + , std::int64_t default_val = 0) const; │ │ │ │ │ + bdecode_node list_at (int i) const; │ │ │ │ │ + string_view list_string_value_at (int i │ │ │ │ │ + , string_view default_val = string_view()) const; │ │ │ │ │ + int list_size () const; │ │ │ │ │ + std::pair dict_at (int i) const; │ │ │ │ │ + bdecode_node dict_find_dict (string_view key) const; │ │ │ │ │ + std::int64_t dict_find_int_value (string_view key │ │ │ │ │ + , std::int64_t default_val = 0) const; │ │ │ │ │ + string_view dict_find_string_value (string_view key │ │ │ │ │ + , string_view default_value = string_view()) const; │ │ │ │ │ + int dict_size () const; │ │ │ │ │ + bdecode_node dict_find_list (string_view key) const; │ │ │ │ │ + bdecode_node dict_find_string (string_view key) const; │ │ │ │ │ + bdecode_node dict_find_int (string_view key) const; │ │ │ │ │ + std::pair dict_at_node (int i) const; │ │ │ │ │ + bdecode_node dict_find (string_view key) const; │ │ │ │ │ + std::int64_t int_value () const; │ │ │ │ │ + string_view string_value () const; │ │ │ │ │ + std::ptrdiff_t string_offset () const; │ │ │ │ │ + int string_length () const; │ │ │ │ │ + char const* string_ptr () const; │ │ │ │ │ + void clear (); │ │ │ │ │ + void swap (bdecode_node& n); │ │ │ │ │ + void reserve (int tokens); │ │ │ │ │ + void switch_underlying_buffer (char const* buf) noexcept; │ │ │ │ │ + bool has_soft_error (span error) const; │ │ │ │ │ + │ │ │ │ │ + enum type_t │ │ │ │ │ + { │ │ │ │ │ + none_t, │ │ │ │ │ + dict_t, │ │ │ │ │ + list_t, │ │ │ │ │ + string_t, │ │ │ │ │ + int_t, │ │ │ │ │ + }; │ │ │ │ │ +}; │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** bdecode_node() ***** │ │ │ │ │ +bdecode_node () = default; │ │ │ │ │ +creates a default constructed node, it will have the type none_t. │ │ │ │ │ [report_issue] │ │ │ │ │ - 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. │ │ │ │ │ +***** bdecode_node() operator=() ***** │ │ │ │ │ +bdecode_node (bdecode_node const&); │ │ │ │ │ +bdecode_node (bdecode_node&&) noexcept; │ │ │ │ │ +bdecode_node& operator= (bdecode_node&&) & = default; │ │ │ │ │ +bdecode_node& operator= (bdecode_node const&) &; │ │ │ │ │ +For owning nodes, the copy will create a copy of the tree, but the underlying │ │ │ │ │ +buffer remains the same. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** type() ***** │ │ │ │ │ +type_t type () const noexcept; │ │ │ │ │ +the type of this node. See type_t. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** bool() ***** │ │ │ │ │ +explicit operator bool () const noexcept; │ │ │ │ │ +returns true if type() != none_t. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** non_owning() ***** │ │ │ │ │ +bdecode_node non_owning () const; │ │ │ │ │ +return a non-owning reference to this node. This is useful to refer to the root │ │ │ │ │ +node without copying it in assignments. │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** data_offset() data_section() ***** │ │ │ │ │ +span data_section () const noexcept; │ │ │ │ │ +std::ptrdiff_t data_offset () const noexcept; │ │ │ │ │ +returns the buffer and length of the section in the original bencoded buffer │ │ │ │ │ +where this node is defined. For a dictionary for instance, this starts with d │ │ │ │ │ +and ends with e, and has all the content of the dictionary in between. the │ │ │ │ │ +data_offset() function returns the byte-offset to this node in, starting from │ │ │ │ │ +the beginning of the buffer that was parsed. │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** list_string_value_at() list_at() list_int_value_at() list_size() ***** │ │ │ │ │ +std::int64_t list_int_value_at (int i │ │ │ │ │ + , std::int64_t default_val = 0) const; │ │ │ │ │ +bdecode_node list_at (int i) const; │ │ │ │ │ +string_view list_string_value_at (int i │ │ │ │ │ + , string_view default_val = string_view()) const; │ │ │ │ │ +int list_size () const; │ │ │ │ │ +functions with the list_ prefix operate on lists. These functions are only │ │ │ │ │ +valid if type() == list_t. list_at() returns the item in the list at index i. i │ │ │ │ │ +may not be greater than or equal to the size of the list. size() returns the │ │ │ │ │ +size of the list. │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** dict_find_string_value() dict_find_int_value() dict_find() dict_at() │ │ │ │ │ +dict_find_dict() dict_find_string() dict_find_int() dict_at_node() dict_size() │ │ │ │ │ +dict_find_list() ***** │ │ │ │ │ +std::pair dict_at (int i) const; │ │ │ │ │ +bdecode_node dict_find_dict (string_view key) const; │ │ │ │ │ +std::int64_t dict_find_int_value (string_view key │ │ │ │ │ + , std::int64_t default_val = 0) const; │ │ │ │ │ +string_view dict_find_string_value (string_view key │ │ │ │ │ + , string_view default_value = string_view()) const; │ │ │ │ │ +int dict_size () const; │ │ │ │ │ +bdecode_node dict_find_list (string_view key) const; │ │ │ │ │ +bdecode_node dict_find_string (string_view key) const; │ │ │ │ │ +bdecode_node dict_find_int (string_view key) const; │ │ │ │ │ +std::pair dict_at_node (int i) const; │ │ │ │ │ +bdecode_node dict_find (string_view key) const; │ │ │ │ │ +Functions with the dict_ prefix operates on dictionaries. They are only valid │ │ │ │ │ +if type() == dict_t. In case a key you're looking up contains a 0 byte, you │ │ │ │ │ +cannot use the 0-terminated string overloads, but have to use string_view │ │ │ │ │ +instead. dict_find_list will return a valid bdecode_node if the key is found │ │ │ │ │ +_and_ it is a list. Otherwise it will return a default-constructed │ │ │ │ │ +bdecode_node. │ │ │ │ │ +Functions with the _value suffix return the value of the node directly, rather │ │ │ │ │ +than the nodes. In case the node is not found, or it has a different type, a │ │ │ │ │ +default value is returned (which can be specified). │ │ │ │ │ +dict_at() returns the (key, value)-pair at the specified index in a dictionary. │ │ │ │ │ +Keys are only allowed to be strings. dict_at_node() also returns the (key, │ │ │ │ │ +value)-pair, but the key is returned as a bdecode_node (and it will always be a │ │ │ │ │ +string). │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** int_value() ***** │ │ │ │ │ +std::int64_t int_value () const; │ │ │ │ │ +this function is only valid if type() == int_t. It returns the value of the │ │ │ │ │ +integer. │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** string_ptr() string_offset() string_value() string_length() ***** │ │ │ │ │ +string_view string_value () const; │ │ │ │ │ +std::ptrdiff_t string_offset () const; │ │ │ │ │ +int string_length () const; │ │ │ │ │ +char const* string_ptr () const; │ │ │ │ │ +these functions are only valid if type() == string_t. They return the string │ │ │ │ │ +values. Note that string_ptr() is not 0-terminated. string_length() returns the │ │ │ │ │ +number of bytes in the string. string_offset() returns the byte offset from the │ │ │ │ │ +start of the parsed bencoded buffer this string can be found. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** clear() ***** │ │ │ │ │ +void clear (); │ │ │ │ │ +resets the bdecoded_node to a default constructed state. If this is an owning │ │ │ │ │ +node, the tree is freed and all child nodes are invalidated. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** swap() ***** │ │ │ │ │ +void swap (bdecode_node& n); │ │ │ │ │ +Swap contents. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** reserve() ***** │ │ │ │ │ +void reserve (int tokens); │ │ │ │ │ +preallocate memory for the specified numbers of tokens. This is useful if you │ │ │ │ │ +know approximately how many tokens are in the file you are about to parse. │ │ │ │ │ +Doing so will save realloc operations while parsing. You should only call this │ │ │ │ │ +on the root node, before passing it in to bdecode(). │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** switch_underlying_buffer() ***** │ │ │ │ │ +void switch_underlying_buffer (char const* buf) noexcept; │ │ │ │ │ +this buffer MUST be identical to the one originally parsed. This operation is │ │ │ │ │ +only defined on owning root nodes, i.e. the one passed in to decode(). │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** has_soft_error() ***** │ │ │ │ │ +bool has_soft_error (span error) const; │ │ │ │ │ +returns true if there is a non-fatal error in the bencoding of this node or its │ │ │ │ │ +children │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** enum type_t ***** │ │ │ │ │ +Declared in "libtorrent/bdecode.hpp" │ │ │ │ │ + _________________________________________________________________________ │ │ │ │ │ +|name____|value|description_______________________________________________| │ │ │ │ │ +|none_t |0 |uninitialized or default constructed. This is also used to| │ │ │ │ │ +|________|_____|indicate_that_a_node_was_not_found_in_some_cases._________| │ │ │ │ │ +|dict_t__|1____|a_dictionary_node._The_dict_find__functions_are_valid.____| │ │ │ │ │ +|list_t__|2____|a_list_node._The_list__functions_are_valid._______________| │ │ │ │ │ +|string_t|3____|a_string_node,_the_string__functions_are_valid.___________| │ │ │ │ │ +|int_t___|4____|an_integer_node._The_int__functions_are_valid.____________| │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** print_entry() ****** │ │ │ │ │ +Declared in "libtorrent/bdecode.hpp" │ │ │ │ │ +std::string print_entry (bdecode_node const& e │ │ │ │ │ + , bool single_line = false, int indent = 0); │ │ │ │ │ +print the bencoded structure in a human-readable format to a string that's │ │ │ │ │ +returned. │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** bdecode() ****** │ │ │ │ │ +Declared in "libtorrent/bdecode.hpp" │ │ │ │ │ +bdecode_node bdecode (span buffer │ │ │ │ │ + , error_code& ec, int* error_pos = nullptr, int depth_limit = 100 │ │ │ │ │ + , int token_limit = 2000000); │ │ │ │ │ +int bdecode (char const* start, char const* end, bdecode_node& ret │ │ │ │ │ + , error_code& ec, int* error_pos = nullptr, int depth_limit = 100 │ │ │ │ │ + , int token_limit = 2000000); │ │ │ │ │ +bdecode_node bdecode (span buffer │ │ │ │ │ + , int depth_limit = 100, int token_limit = 2000000); │ │ │ │ │ +This function decodes/parses bdecoded data (for example a .torrent file). The │ │ │ │ │ +data structure is returned in the ret argument. the buffer to parse is │ │ │ │ │ +specified by the start of the buffer as well as the end, i.e. one byte past the │ │ │ │ │ +end. If the buffer fails to parse, the function returns a non-zero value and │ │ │ │ │ +fills in ec with the error code. The optional argument error_pos, if set to │ │ │ │ │ +non-nullptr, will be set to the byte offset into the buffer where the parse │ │ │ │ │ +failure occurred. │ │ │ │ │ +depth_limit specifies the max number of nested lists or dictionaries are │ │ │ │ │ +allowed in the data structure. (This affects the stack usage of the function, │ │ │ │ │ +be careful not to set it too high). │ │ │ │ │ +token_limit is the max number of tokens allowed to be parsed from the buffer. │ │ │ │ │ +This is simply a sanity check to not have unbounded memory usage. │ │ │ │ │ +The resulting bdecode_node is an owning node. That means it will be holding the │ │ │ │ │ +whole parsed tree. When iterating lists and dictionaries, those bdecode_node │ │ │ │ │ +objects will simply have references to the root or owning bdecode_node. If the │ │ │ │ │ +root node is destructed, all other nodes that refer to anything in that tree │ │ │ │ │ +become invalid. │ │ │ │ │ +However, the underlying buffer passed in to this function (start, end) must │ │ │ │ │ +also remain valid while the bdecoded tree is used. The parsed tree produced by │ │ │ │ │ +this function does not copy any data out of the buffer, but simply produces │ │ │ │ │ +references back into it. │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** storage_params ****** │ │ │ │ │ +Declared in "libtorrent/storage_defs.hpp" │ │ │ │ │ +a parameter pack used to construct the storage for a torrent, used in │ │ │ │ │ +disk_interface │ │ │ │ │ +struct storage_params │ │ │ │ │ +{ │ │ │ │ │ + storage_params (file_storage const& f, file_storage const* mf │ │ │ │ │ + , std::string const& sp, storage_mode_t const sm │ │ │ │ │ + , aux::vector const& prio │ │ │ │ │ + , sha1_hash const& ih); │ │ │ │ │ + │ │ │ │ │ + file_storage const& files; │ │ │ │ │ + file_storage const* mapped_files = nullptr; │ │ │ │ │ + std::string const& path; │ │ │ │ │ + storage_mode_t mode {storage_mode_sparse}; │ │ │ │ │ + aux::vector const& priorities; │ │ │ │ │ + sha1_hash info_hash; │ │ │ │ │ +}; │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** file_slice ****** │ │ │ │ │ +Declared in "libtorrent/file_storage.hpp" │ │ │ │ │ +represents a window of a file in a torrent. │ │ │ │ │ +The file_index refers to the index of the file (in the torrent_info). To get │ │ │ │ │ +the path and filename, use file_path() and give the file_index as argument. The │ │ │ │ │ +offset is the byte offset in the file where the range starts, and size is the │ │ │ │ │ +number of bytes this range is. The size + offset will never be greater than the │ │ │ │ │ +file size. │ │ │ │ │ +struct file_slice │ │ │ │ │ +{ │ │ │ │ │ + file_index_t file_index; │ │ │ │ │ + std::int64_t offset; │ │ │ │ │ + std::int64_t size; │ │ │ │ │ +}; │ │ │ │ │ +[report_issue] │ │ │ │ │ + file_index │ │ │ │ │ + the index of the file │ │ │ │ │ +[report_issue] │ │ │ │ │ + offset │ │ │ │ │ + the offset from the start of the file, in bytes │ │ │ │ │ +[report_issue] │ │ │ │ │ + size │ │ │ │ │ + the size of the window, in bytes │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** file_storage ****** │ │ │ │ │ +Declared in "libtorrent/file_storage.hpp" │ │ │ │ │ +The file_storage class represents a file list and the piece size. Everything │ │ │ │ │ +necessary to interpret a regular bittorrent storage file structure. │ │ │ │ │ +class file_storage │ │ │ │ │ +{ │ │ │ │ │ + bool is_valid () const; │ │ │ │ │ + void reserve (int num_files); │ │ │ │ │ + void add_file_borrow (string_view filename │ │ │ │ │ + , std::string const& path, std::int64_t file_size │ │ │ │ │ + , file_flags_t file_flags = {}, char const* filehash = nullptr │ │ │ │ │ + , std::int64_t mtime = 0, string_view symlink_path = string_view() │ │ │ │ │ + , char const* root_hash = nullptr); │ │ │ │ │ + void add_file (std::string const& path, std::int64_t file_size │ │ │ │ │ + , file_flags_t file_flags = {} │ │ │ │ │ + , std::time_t mtime = 0, string_view symlink_path = string_view() │ │ │ │ │ + , char const* root_hash = nullptr); │ │ │ │ │ + void add_file (error_code& ec, std::string const& path, std::int64_t │ │ │ │ │ +file_size │ │ │ │ │ + , file_flags_t file_flags = {} │ │ │ │ │ + , std::time_t mtime = 0, string_view symlink_path = string_view() │ │ │ │ │ + , char const* root_hash = nullptr); │ │ │ │ │ + void add_file_borrow (error_code& ec, string_view filename │ │ │ │ │ + , std::string const& path, std::int64_t file_size │ │ │ │ │ + , file_flags_t file_flags = {}, char const* filehash = nullptr │ │ │ │ │ + , std::int64_t mtime = 0, string_view symlink_path = string_view() │ │ │ │ │ + , char const* root_hash = nullptr); │ │ │ │ │ + void rename_file (file_index_t index, std::string const& new_filename); │ │ │ │ │ + std::vector map_block (piece_index_t piece, std::int64_t offset │ │ │ │ │ + , std::int64_t size) const; │ │ │ │ │ + peer_request map_file (file_index_t file, std::int64_t offset, int size) │ │ │ │ │ +const; │ │ │ │ │ + int num_files () const noexcept; │ │ │ │ │ + file_index_t end_file () const noexcept; │ │ │ │ │ + index_range file_range () const noexcept; │ │ │ │ │ + std::int64_t total_size () const; │ │ │ │ │ + int num_pieces () const; │ │ │ │ │ + void set_num_pieces (int n); │ │ │ │ │ + piece_index_t end_piece () const; │ │ │ │ │ + piece_index_t last_piece () const; │ │ │ │ │ + index_range piece_range () const noexcept; │ │ │ │ │ + int piece_length () const; │ │ │ │ │ + void set_piece_length (int l); │ │ │ │ │ + int piece_size (piece_index_t index) const; │ │ │ │ │ + int piece_size2 (piece_index_t index) const; │ │ │ │ │ + int blocks_in_piece2 (piece_index_t index) const; │ │ │ │ │ + void set_name (std::string const& n); │ │ │ │ │ + std::string const& name () const; │ │ │ │ │ + void swap (file_storage& ti) noexcept; │ │ │ │ │ + void canonicalize (); │ │ │ │ │ + std::string symlink (file_index_t index) const; │ │ │ │ │ + std::int64_t file_size (file_index_t index) const; │ │ │ │ │ + sha256_hash root (file_index_t index) const; │ │ │ │ │ + std::int64_t file_offset (file_index_t index) const; │ │ │ │ │ + sha1_hash hash (file_index_t index) const; │ │ │ │ │ + char const* root_ptr (file_index_t const index) const; │ │ │ │ │ + std::time_t mtime (file_index_t index) const; │ │ │ │ │ + std::string file_path (file_index_t index, std::string const& save_path = │ │ │ │ │ +"") const; │ │ │ │ │ + bool pad_file_at (file_index_t index) const; │ │ │ │ │ + string_view file_name (file_index_t index) const; │ │ │ │ │ + index_range file_piece_range (file_index_t) const; │ │ │ │ │ + int file_num_pieces (file_index_t index) const; │ │ │ │ │ + int file_num_blocks (file_index_t index) const; │ │ │ │ │ + int file_first_block_node (file_index_t index) const; │ │ │ │ │ + int file_first_piece_node (file_index_t index) const; │ │ │ │ │ + std::uint32_t file_path_hash (file_index_t index, std::string const& │ │ │ │ │ +save_path) const; │ │ │ │ │ + void all_path_hashes (std::unordered_set& table) const; │ │ │ │ │ + file_flags_t file_flags (file_index_t index) const; │ │ │ │ │ + bool file_absolute_path (file_index_t index) const; │ │ │ │ │ + file_index_t file_index_at_offset (std::int64_t offset) const; │ │ │ │ │ + file_index_t file_index_at_piece (piece_index_t piece) const; │ │ │ │ │ + file_index_t file_index_for_root (sha256_hash const& root_hash) const; │ │ │ │ │ + piece_index_t piece_index_at_file (file_index_t f) const; │ │ │ │ │ + void sanitize_symlinks (); │ │ │ │ │ + bool v2 () const; │ │ │ │ │ + │ │ │ │ │ + static constexpr file_flags_t flag_pad_file = 0_bit; │ │ │ │ │ + static constexpr file_flags_t flag_hidden = 1_bit; │ │ │ │ │ + static constexpr file_flags_t flag_executable = 2_bit; │ │ │ │ │ + static constexpr file_flags_t flag_symlink = 3_bit; │ │ │ │ │ +}; │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** is_valid() ***** │ │ │ │ │ +bool is_valid () const; │ │ │ │ │ +returns true if the piece length has been initialized on the file_storage. This │ │ │ │ │ +is typically taken as a proxy of whether the file_storage as a whole is │ │ │ │ │ +initialized or not. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** reserve() ***** │ │ │ │ │ +void reserve (int num_files); │ │ │ │ │ +allocates space for num_files in the internal file list. This can be used to │ │ │ │ │ +avoid reallocating the internal file list when the number of files to be added │ │ │ │ │ +is known up-front. │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** add_file() add_file_borrow() ***** │ │ │ │ │ +void add_file_borrow (string_view filename │ │ │ │ │ + , std::string const& path, std::int64_t file_size │ │ │ │ │ + , file_flags_t file_flags = {}, char const* filehash = nullptr │ │ │ │ │ + , std::int64_t mtime = 0, string_view symlink_path = string_view() │ │ │ │ │ + , char const* root_hash = nullptr); │ │ │ │ │ +void add_file (std::string const& path, std::int64_t file_size │ │ │ │ │ + , file_flags_t file_flags = {} │ │ │ │ │ + , std::time_t mtime = 0, string_view symlink_path = string_view() │ │ │ │ │ + , char const* root_hash = nullptr); │ │ │ │ │ +void add_file (error_code& ec, std::string const& path, std::int64_t file_size │ │ │ │ │ + , file_flags_t file_flags = {} │ │ │ │ │ + , std::time_t mtime = 0, string_view symlink_path = string_view() │ │ │ │ │ + , char const* root_hash = nullptr); │ │ │ │ │ +void add_file_borrow (error_code& ec, string_view filename │ │ │ │ │ + , std::string const& path, std::int64_t file_size │ │ │ │ │ + , file_flags_t file_flags = {}, char const* filehash = nullptr │ │ │ │ │ + , std::int64_t mtime = 0, string_view symlink_path = string_view() │ │ │ │ │ + , char const* root_hash = nullptr); │ │ │ │ │ +Adds a file to the file storage. The add_file_borrow version expects that │ │ │ │ │ +filename is the file name (without a path) of the file that's being added. This │ │ │ │ │ +memory is borrowed, i.e. it is the caller's responsibility to make sure it │ │ │ │ │ +stays valid throughout the lifetime of this file_storage object or any copy of │ │ │ │ │ +it. The same thing applies to filehash, which is an optional pointer to a 20 │ │ │ │ │ +byte binary SHA-1 hash of the file. │ │ │ │ │ +if filename is empty, the filename from path is used and not borrowed. │ │ │ │ │ +The path argument is the full path (in the torrent file) to the file to add. │ │ │ │ │ +Note that this is not supposed to be an absolute path, but it is expected to │ │ │ │ │ +include the name of the torrent as the first path element. │ │ │ │ │ +file_size is the size of the file in bytes. │ │ │ │ │ +The file_flags argument sets attributes on the file. The file attributes is an │ │ │ │ │ +extension and may not work in all bittorrent clients. │ │ │ │ │ +For possible file attributes, see file_storage::flags_t. │ │ │ │ │ +The mtime argument is optional and can be set to 0. If non-zero, it is the │ │ │ │ │ +posix time of the last modification time of this file. │ │ │ │ │ +symlink_path is the path the file is a symlink to. To make this a symlink you │ │ │ │ │ +also need to set the file_storage::flag_symlink file flag. │ │ │ │ │ +root_hash is an optional pointer to a 32 byte SHA-256 hash, being the merkle │ │ │ │ │ +tree root hash for this file. This is only used for v2 torrents. If the root │ │ │ │ │ +hash is specified for one file, it has to be specified for all, otherwise this │ │ │ │ │ +function will fail. Note that the buffer root_hash points to must out-live the │ │ │ │ │ +file_storage object, it will not be copied. This parameter is only used when │ │ │ │ │ +loading torrents, that already have their file hashes computed. When creating │ │ │ │ │ +torrents, the file hashes will be computed by the piece hashes. │ │ │ │ │ +If more files than one are added, certain restrictions to their paths apply. In │ │ │ │ │ +a multi-file file storage (torrent), all files must share the same root │ │ │ │ │ +directory. │ │ │ │ │ +That is, the first path element of all files must be the same. This shared path │ │ │ │ │ +element is also set to the name of the torrent. It can be changed by calling │ │ │ │ │ +set_name. │ │ │ │ │ +The overloads that take anerror_codereference will report failures via that │ │ │ │ │ +variable, otherwisesystem_erroris thrown. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** rename_file() ***** │ │ │ │ │ +void rename_file (file_index_t index, std::string const& new_filename); │ │ │ │ │ +renames the file at index to new_filename. Keep in mind that filenames are │ │ │ │ │ +expected to be UTF-8 encoded. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** map_block() ***** │ │ │ │ │ +std::vector map_block (piece_index_t piece, std::int64_t offset │ │ │ │ │ + , std::int64_t size) const; │ │ │ │ │ +returns a list of file_slice objects representing the portions of files the │ │ │ │ │ +specified piece index, byte offset and size range overlaps. this is the inverse │ │ │ │ │ +mapping of map_file(). │ │ │ │ │ +Preconditions of this function is that the input range is within the torrents │ │ │ │ │ +address space. piece may not be negative and │ │ │ │ │ + piece * piece_size + offset + size │ │ │ │ │ +may not exceed the total size of the torrent. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** map_file() ***** │ │ │ │ │ +peer_request map_file (file_index_t file, std::int64_t offset, int size) const; │ │ │ │ │ +returns a peer_request representing the piece index, byte offset and size the │ │ │ │ │ +specified file range overlaps. This is the inverse mapping over map_block(). │ │ │ │ │ +Note that the peer_request return type is meant to hold bittorrent block │ │ │ │ │ +requests, which may not be larger than 16 kiB. Mapping a range larger than that │ │ │ │ │ +may return an overflown integer. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** num_files() ***** │ │ │ │ │ +int num_files () const noexcept; │ │ │ │ │ +returns the number of files in the file_storage │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** end_file() ***** │ │ │ │ │ +file_index_t end_file () const noexcept; │ │ │ │ │ +returns the index of the one-past-end file in the file storage │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** file_range() ***** │ │ │ │ │ +index_range file_range () const noexcept; │ │ │ │ │ +returns an implementation-defined type that can be used as the container in a │ │ │ │ │ +range-for loop. Where the values are the indices of all files in the │ │ │ │ │ +file_storage. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** total_size() ***** │ │ │ │ │ +std::int64_t total_size () const; │ │ │ │ │ +returns the total number of bytes all the files in this torrent spans │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** num_pieces() set_num_pieces() ***** │ │ │ │ │ +int num_pieces () const; │ │ │ │ │ +void set_num_pieces (int n); │ │ │ │ │ +set and get the number of pieces in the torrent │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** end_piece() ***** │ │ │ │ │ +piece_index_t end_piece () const; │ │ │ │ │ +returns the index of the one-past-end piece in the file storage │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** last_piece() ***** │ │ │ │ │ +piece_index_t last_piece () const; │ │ │ │ │ +returns the index of the last piece in the torrent. The last piece is special │ │ │ │ │ +in that it may be smaller than the other pieces (and the other pieces are all │ │ │ │ │ +the same size). │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** piece_range() ***** │ │ │ │ │ +index_range piece_range () const noexcept; │ │ │ │ │ +returns an implementation-defined type that can be used as the container in a │ │ │ │ │ +range-for loop. Where the values are the indices of all pieces in the │ │ │ │ │ +file_storage. │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** set_piece_length() piece_length() ***** │ │ │ │ │ +int piece_length () const; │ │ │ │ │ +void set_piece_length (int l); │ │ │ │ │ +set and get the size of each piece in this torrent. It must be a power of two │ │ │ │ │ +and at least 16 kiB. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** piece_size() ***** │ │ │ │ │ +int piece_size (piece_index_t index) const; │ │ │ │ │ +returns the piece size of index. This will be the same as piece_length(), │ │ │ │ │ +except for the last piece, which may be shorter. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** piece_size2() ***** │ │ │ │ │ +int piece_size2 (piece_index_t index) const; │ │ │ │ │ +Returns the size of the given piece. If the piece spans multiple files, only │ │ │ │ │ +the first file is considered part of the piece. This is used for v2 torrents, │ │ │ │ │ +where all files are piece aligned and padded. i.e. The pad files are not │ │ │ │ │ +considered part of the piece for this purpose. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** blocks_in_piece2() ***** │ │ │ │ │ +int blocks_in_piece2 (piece_index_t index) const; │ │ │ │ │ +returns the number of blocks in the specified piece, for v2 torrents. │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** set_name() name() ***** │ │ │ │ │ +void set_name (std::string const& n); │ │ │ │ │ +std::string const& name () const; │ │ │ │ │ +set and get the name of this torrent. For multi-file torrents, this is also the │ │ │ │ │ +name of the root directory all the files are stored in. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** swap() ***** │ │ │ │ │ +void swap (file_storage& ti) noexcept; │ │ │ │ │ +swap all content of this with ti. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** canonicalize() ***** │ │ │ │ │ +void canonicalize (); │ │ │ │ │ +arrange files and padding to match the canonical form required by BEP 52 │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** file_name() file_size() file_offset() mtime() root() file_path() root_ptr │ │ │ │ │ +() symlink() pad_file_at() hash() ***** │ │ │ │ │ +std::string symlink (file_index_t index) const; │ │ │ │ │ +std::int64_t file_size (file_index_t index) const; │ │ │ │ │ +sha256_hash root (file_index_t index) const; │ │ │ │ │ +std::int64_t file_offset (file_index_t index) const; │ │ │ │ │ +sha1_hash hash (file_index_t index) const; │ │ │ │ │ +char const* root_ptr (file_index_t const index) const; │ │ │ │ │ +std::time_t mtime (file_index_t index) const; │ │ │ │ │ +std::string file_path (file_index_t index, std::string const& save_path = "") │ │ │ │ │ +const; │ │ │ │ │ +bool pad_file_at (file_index_t index) const; │ │ │ │ │ +string_view file_name (file_index_t index) const; │ │ │ │ │ +These functions are used to query attributes of files at a given index. │ │ │ │ │ +The hash() is a SHA-1 hash of the file, or 0 if none was provided in the │ │ │ │ │ +torrent file. This can potentially be used to join a bittorrent network with │ │ │ │ │ +other file sharing networks. │ │ │ │ │ +root() returns the SHA-256 merkle tree root of the specified file, in case this │ │ │ │ │ +is a v2 torrent. Otherwise returns zeros. root_ptr() returns a pointer to the │ │ │ │ │ +SHA-256 merkle tree root hash for the specified file. The pointer points into │ │ │ │ │ +storage referred to when the file was added, it is not owned by this object. │ │ │ │ │ +Torrents that are not v2 torrents return nullptr. │ │ │ │ │ +The mtime() is the modification time is the posix time when a file was last │ │ │ │ │ +modified when the torrent was created, or 0 if it was not included in the │ │ │ │ │ +torrent file. │ │ │ │ │ +file_path() returns the full path to a file. │ │ │ │ │ +file_size() returns the size of a file. │ │ │ │ │ +pad_file_at() returns true if the file at the given index is a pad-file. │ │ │ │ │ +file_name() returns just the name of the file, whereas file_path() returns the │ │ │ │ │ +path (inside the torrent file) with the filename appended. │ │ │ │ │ +file_offset() returns the byte offset within the torrent file where this file │ │ │ │ │ +starts. It can be used to map the file to a piece index (given the piece size). │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** file_num_pieces() file_piece_range() file_num_blocks() ***** │ │ │ │ │ +index_range file_piece_range (file_index_t) const; │ │ │ │ │ +int file_num_pieces (file_index_t index) const; │ │ │ │ │ +int file_num_blocks (file_index_t index) const; │ │ │ │ │ +Returns the number of pieces or blocks the file atindexspans, under the │ │ │ │ │ +assumption that the file is aligned to the start of a piece. This is only │ │ │ │ │ +meaningful for v2 torrents, where files are guaranteed such alignment. These │ │ │ │ │ +numbers are used to size and navigate the merkle hash tree for each file. │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** file_first_piece_node() file_first_block_node() ***** │ │ │ │ │ +int file_first_block_node (file_index_t index) const; │ │ │ │ │ +int file_first_piece_node (file_index_t index) const; │ │ │ │ │ +index of first piece node in the merkle tree │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** file_path_hash() ***** │ │ │ │ │ +std::uint32_t file_path_hash (file_index_t index, std::string const& save_path) │ │ │ │ │ +const; │ │ │ │ │ +returns the crc32 hash of file_path(index) │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** all_path_hashes() ***** │ │ │ │ │ +void all_path_hashes (std::unordered_set& table) const; │ │ │ │ │ +this will add the CRC32 hash of all directory entries to the table. No filename │ │ │ │ │ +will be included, just directories. Every depth of directories are added │ │ │ │ │ +separately to allow test for collisions with files at all levels. i.e. if one │ │ │ │ │ +path in the torrent is foo/bar/baz, the CRC32 hashes for foo, foo/bar and foo/ │ │ │ │ │ +bar/baz will be added to the set. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** file_flags() ***** │ │ │ │ │ +file_flags_t file_flags (file_index_t index) const; │ │ │ │ │ +returns a bitmask of flags from file_flags_t that apply to file at index. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** file_absolute_path() ***** │ │ │ │ │ +bool file_absolute_path (file_index_t index) const; │ │ │ │ │ +returns true if the file at the specified index has been renamed to have an │ │ │ │ │ +absolute path, i.e. is not anchored in the save path of the torrent. │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** file_index_at_offset() file_index_at_piece() ***** │ │ │ │ │ +file_index_t file_index_at_offset (std::int64_t offset) const; │ │ │ │ │ +file_index_t file_index_at_piece (piece_index_t piece) const; │ │ │ │ │ +returns the index of the file at the given offset in the torrent │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** file_index_for_root() ***** │ │ │ │ │ +file_index_t file_index_for_root (sha256_hash const& root_hash) const; │ │ │ │ │ +finds the file with the given root hash and returns its index if there is no │ │ │ │ │ +file with the root hash, file_index_t{-1} is returned │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** piece_index_at_file() ***** │ │ │ │ │ +piece_index_t piece_index_at_file (file_index_t f) const; │ │ │ │ │ +returns the piece index the given file starts at │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** sanitize_symlinks() ***** │ │ │ │ │ +void sanitize_symlinks (); │ │ │ │ │ +validate any symlinks, to ensure they all point to other files or directories │ │ │ │ │ +inside this storage. Any invalid symlinks are updated to point to themselves. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** v2() ***** │ │ │ │ │ +bool v2 () const; │ │ │ │ │ +returns true if this torrent contains v2 metadata. │ │ │ │ │ +[report_issue] │ │ │ │ │ + flag_pad_file │ │ │ │ │ + the file is a pad file. It's required to contain zeros at it will not be │ │ │ │ │ + saved to disk. Its purpose is to make the following file start on a piece │ │ │ │ │ + boundary. │ │ │ │ │ +[report_issue] │ │ │ │ │ + flag_hidden │ │ │ │ │ + this file has the hidden attribute set. This is primarily a windows │ │ │ │ │ + attribute │ │ │ │ │ +[report_issue] │ │ │ │ │ + flag_executable │ │ │ │ │ + this file has the executable attribute set. │ │ │ │ │ +[report_issue] │ │ │ │ │ + flag_symlink │ │ │ │ │ + this file is a symbolic link. It should have a link target string │ │ │ │ │ + associated with it. │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** default_disk_io_constructor() ****** │ │ │ │ │ +Declared in "libtorrent/session.hpp" │ │ │ │ │ +std::unique_ptr default_disk_io_constructor ( │ │ │ │ │ + io_context& ios, settings_interface const&, counters& cnt); │ │ │ │ │ +the constructor function for the default storage. On systems that support │ │ │ │ │ +memory mapped files (and a 64 bit address space) the memory mapped storage will │ │ │ │ │ +be constructed, otherwise the portable posix storage. │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** posix_disk_io_constructor() ****** │ │ │ │ │ +Declared in "libtorrent/posix_disk_io.hpp" │ │ │ │ │ +std::unique_ptr posix_disk_io_constructor ( │ │ │ │ │ + io_context& ios, settings_interface const&, counters& cnt); │ │ │ │ │ +this is a simple posix disk I/O back-end, used for systems that don't have a 64 │ │ │ │ │ +bit virtual address space or don't support memory mapped files. It's │ │ │ │ │ +implemented using portable C file functions and is single-threaded. │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** mmap_disk_io_constructor() ****** │ │ │ │ │ +Declared in "libtorrent/mmap_disk_io.hpp" │ │ │ │ │ +std::unique_ptr mmap_disk_io_constructor ( │ │ │ │ │ + io_context& ios, settings_interface const&, counters& cnt); │ │ │ │ │ +constructs a memory mapped file disk I/O object. │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** disabled_disk_io_constructor() ****** │ │ │ │ │ +Declared in "libtorrent/disabled_disk_io.hpp" │ │ │ │ │ +std::unique_ptr disabled_disk_io_constructor ( │ │ │ │ │ + io_context& ios, settings_interface const&, counters& cnt); │ │ │ │ │ +creates a disk io object that discards all data written to it, and only returns │ │ │ │ │ +zero-buffers when read from. May be useful for testing and benchmarking. │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** enum storage_mode_t ****** │ │ │ │ │ +Declared in "libtorrent/storage_defs.hpp" │ │ │ │ │ + ___________________________________________________________________________ │ │ │ │ │ +|name_________________|value|description____________________________________| │ │ │ │ │ +| | |All pieces will be written to their final | │ │ │ │ │ +| | |position, all files will be allocated in full | │ │ │ │ │ +|storage_mode_allocate|0 |when the torrent is first started. This mode | │ │ │ │ │ +| | |minimizes fragmentation but could be a costly | │ │ │ │ │ +|_____________________|_____|operation._____________________________________| │ │ │ │ │ +| | |All pieces will be written to the place where | │ │ │ │ │ +|storage_mode_sparse |1 |they belong and sparse files will be used. This| │ │ │ │ │ +|_____________________|_____|is_the_recommended,_and_default_mode.__________| │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** enum status_t ****** │ │ │ │ │ +Declared in "libtorrent/storage_defs.hpp" │ │ │ │ │ + ____________________________________________________________________________ │ │ │ │ │ +|name____________|value|description__________________________________________| │ │ │ │ │ +|no_error________|0____| ___________________________________________________| │ │ │ │ │ +|fatal_disk_error|1____| ___________________________________________________| │ │ │ │ │ +|need_full_check_|2____| ___________________________________________________| │ │ │ │ │ +|file_exist______|3____| ___________________________________________________| │ │ │ │ │ +| | |this is not an enum value, but a flag that can be set| │ │ │ │ │ +| | |in the return from async_check_files, in case an | │ │ │ │ │ +|oversized_file |16 |existing file was found larger than specified in the | │ │ │ │ │ +| | |torrent. i.e. it has garbage at the end the status_t | │ │ │ │ │ +|________________|_____|field_is_used_for_this_to_preserve_ABI.______________| │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** enum move_flags_t ****** │ │ │ │ │ +Declared in "libtorrent/storage_defs.hpp" │ │ │ │ │ + ____________________________________________________________________________ │ │ │ │ │ +|name________________|value|description______________________________________| │ │ │ │ │ +|always_replace_files|0 |replace any files in the destination when copying| │ │ │ │ │ +|____________________|_____|or_moving_the_storage____________________________| │ │ │ │ │ +| | |if any files that we want to copy exist in the | │ │ │ │ │ +| | |destination exist, fail the whole operation and | │ │ │ │ │ +| | |don't perform any copy or move. There is an | │ │ │ │ │ +|fail_if_exist |1 |inherent race condition in this mode. The files | │ │ │ │ │ +| | |are checked for existence before the operation | │ │ │ │ │ +| | |starts. In between the check and performing the | │ │ │ │ │ +| | |copy, the destination files may be created, in | │ │ │ │ │ +|____________________|_____|which_case_they_are_replaced.____________________| │ │ │ │ │ +|dont_replace |2 |if any file exist in the target, take those files| │ │ │ │ │ +|____________________|_____|instead_of_the_ones_we_may_have_in_the_source.___| │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** 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; │ │ │ │ │ +}; │ │ │ │ │ +[report_issue] │ │ │ │ │ + message │ │ │ │ │ + if this tracker has returned an error or warning message that message is │ │ │ │ │ + stored here │ │ │ │ │ +[report_issue] │ │ │ │ │ + last_error │ │ │ │ │ + if this tracker failed the last time it was contacted this error code │ │ │ │ │ + specifies what error occurred │ │ │ │ │ + [report_issue] │ │ │ │ │ + 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. │ │ │ │ │ +[report_issue] │ │ │ │ │ + fails │ │ │ │ │ + the number of times in a row we have failed to announce to this tracker. │ │ │ │ │ +[report_issue] │ │ │ │ │ + updating │ │ │ │ │ + true while we're waiting for a response from the tracker. │ │ │ │ │ +[report_issue] │ │ │ │ │ + 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. │ │ │ │ │ +[report_issue] │ │ │ │ │ + complete_sent │ │ │ │ │ + set to true when we send a event=completed. │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** 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 info_hashes; │ │ │ │ │ + bool enabled = true; │ │ │ │ │ +}; │ │ │ │ │ +[report_issue] │ │ │ │ │ + local_endpoint │ │ │ │ │ + the local endpoint of the listen interface associated with this endpoint │ │ │ │ │ +[report_issue] │ │ │ │ │ + info_hashes │ │ │ │ │ + info_hashes[0] is the v1 info hash (SHA1) info_hashes[1] is the v2 info │ │ │ │ │ + hash (truncated SHA-256) │ │ │ │ │ +[report_issue] │ │ │ │ │ + enabled │ │ │ │ │ + set to false to not announce from this endpoint │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** 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 │ │ │ │ │ +{ │ │ │ │ │ + explicit announce_entry (string_view u); │ │ │ │ │ + announce_entry (announce_entry const&); │ │ │ │ │ + announce_entry& operator= (announce_entry const&) &; │ │ │ │ │ + announce_entry (); │ │ │ │ │ + ~announce_entry (); │ │ │ │ │ + │ │ │ │ │ + enum tracker_source │ │ │ │ │ + { │ │ │ │ │ + source_torrent, │ │ │ │ │ + source_client, │ │ │ │ │ + source_magnet_link, │ │ │ │ │ + source_tex, │ │ │ │ │ + }; │ │ │ │ │ + │ │ │ │ │ + std::string url; │ │ │ │ │ + std::string trackerid; │ │ │ │ │ + std::vector endpoints; │ │ │ │ │ + std::uint8_t tier = 0; │ │ │ │ │ + std::uint8_t fail_limit = 0; │ │ │ │ │ + std::uint8_t source:4; │ │ │ │ │ + bool verified:1; │ │ │ │ │ +}; │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** ~announce_entry() announce_entry() operator=() ***** │ │ │ │ │ +explicit announce_entry (string_view u); │ │ │ │ │ +announce_entry (announce_entry const&); │ │ │ │ │ +announce_entry& operator= (announce_entry const&) &; │ │ │ │ │ +announce_entry (); │ │ │ │ │ +~announce_entry (); │ │ │ │ │ +constructs a tracker announce entry with u as the URL. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** enum tracker_source ***** │ │ │ │ │ +Declared in "libtorrent/announce_entry.hpp" │ │ │ │ │ + ____________________________________________________________________________ │ │ │ │ │ +|name______________|value|description________________________________________| │ │ │ │ │ +|source_torrent____|1____|the_tracker_was_part_of_the_.torrent_file__________| │ │ │ │ │ +|source_client |2 |the tracker was added programmatically via the | │ │ │ │ │ +|__________________|_____|add_tracker()_function_____________________________| │ │ │ │ │ +|source_magnet_link|4____|the_tracker_was_part_of_a_magnet_link______________| │ │ │ │ │ +|source_tex |8 |the tracker was received from the swarm via tracker| │ │ │ │ │ +|__________________|_____|exchange___________________________________________| │ │ │ │ │ +[report_issue] │ │ │ │ │ + url │ │ │ │ │ + tracker URL as it appeared in the torrent file │ │ │ │ │ +[report_issue] │ │ │ │ │ + trackerid │ │ │ │ │ + the current &trackerid= argument passed to the tracker. this is optional │ │ │ │ │ + and is normally empty (in which case no trackerid is sent). │ │ │ │ │ +[report_issue] │ │ │ │ │ + endpoints │ │ │ │ │ + each local listen socket (endpoint) will announce to the tracker. This │ │ │ │ │ + list contains state per endpoint. │ │ │ │ │ +[report_issue] │ │ │ │ │ + tier │ │ │ │ │ + the tier this tracker belongs to │ │ │ │ │ +[report_issue] │ │ │ │ │ + fail_limit │ │ │ │ │ + the max number of failures to announce to this tracker in a row, before │ │ │ │ │ + this tracker is not used anymore. 0 means unlimited │ │ │ │ │ +[report_issue] │ │ │ │ │ + source │ │ │ │ │ + a bitmask specifying which sources we got this tracker from. │ │ │ │ │ +[report_issue] │ │ │ │ │ + verified │ │ │ │ │ + set to true the first time we receive a valid response from this tracker. │ │ │ │ │ +This section describes the functions and classes that are used to create │ │ │ │ │ +torrent files. It is a layered API with low level classes and higher level │ │ │ │ │ +convenience functions. A torrent is created in 4 steps: │ │ │ │ │ + 1. first the files that will be part of the torrent are determined. │ │ │ │ │ + 2. the torrent properties are set, such as tracker url, web seeds, DHT nodes │ │ │ │ │ + etc. │ │ │ │ │ + 3. Read through all the files in the torrent, SHA-1 all the data and set the │ │ │ │ │ + piece hashes. │ │ │ │ │ + 4. The torrent is bencoded into a file or buffer. │ │ │ │ │ +If there are a lot of files and or deep directory hierarchies to traverse, step │ │ │ │ │ +one can be time consuming. │ │ │ │ │ +Typically step 3 is by far the most time consuming step, since it requires to │ │ │ │ │ +read all the bytes from all the files in the torrent. │ │ │ │ │ +All of these classes and functions are declared by including libtorrent/ │ │ │ │ │ +create_torrent.hpp. │ │ │ │ │ +example: │ │ │ │ │ +file_storage fs; │ │ │ │ │ + │ │ │ │ │ +// recursively adds files in directories │ │ │ │ │ +add_files(fs, "./my_torrent"); │ │ │ │ │ + │ │ │ │ │ +create_torrent t(fs); │ │ │ │ │ +t.add_tracker("http://my.tracker.com/announce"); │ │ │ │ │ +t.set_creator("libtorrent example"); │ │ │ │ │ + │ │ │ │ │ +// reads the files and calculates the hashes │ │ │ │ │ +set_piece_hashes(t, "."); │ │ │ │ │ + │ │ │ │ │ +ofstream out("my_torrent.torrent", std::ios_base::binary); │ │ │ │ │ +std::vector buf = t.generate_buf(); │ │ │ │ │ +out.write(buf.data(), buf.size()); │ │ │ │ │ + │ │ │ │ │ +// alternatively, generate an entry and encode it directly to an ostream │ │ │ │ │ +// iterator │ │ │ │ │ +bencode(std::ostream_iterator(out), t.generate()); │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** create_torrent ****** │ │ │ │ │ +Declared in "libtorrent/create_torrent.hpp" │ │ │ │ │ +This class holds state for creating a torrent. After having added all │ │ │ │ │ +information to it, call create_torrent::generate() to generate the torrent. The │ │ │ │ │ +entry that's returned can then be bencoded into a .torrent file using bencode │ │ │ │ │ +(). │ │ │ │ │ +struct create_torrent │ │ │ │ │ +{ │ │ │ │ │ + explicit create_torrent (file_storage& fs, int piece_size = 0 │ │ │ │ │ + , create_flags_t flags = {}); │ │ │ │ │ + explicit create_torrent (torrent_info const& ti); │ │ │ │ │ + entry generate () const; │ │ │ │ │ + std::vector generate_buf () const; │ │ │ │ │ + file_storage const& files () const; │ │ │ │ │ + void set_comment (char const* str); │ │ │ │ │ + void set_creator (char const* str); │ │ │ │ │ + void set_creation_date (std::time_t timestamp); │ │ │ │ │ + void set_hash (piece_index_t index, sha1_hash const& h); │ │ │ │ │ + void set_hash2 (file_index_t file, piece_index_t::diff_type piece, │ │ │ │ │ +sha256_hash const& h); │ │ │ │ │ + void add_http_seed (string_view url); │ │ │ │ │ + void add_url_seed (string_view url); │ │ │ │ │ + void add_node (std::pair node); │ │ │ │ │ + void add_tracker (string_view url, int tier = 0); │ │ │ │ │ + void set_root_cert (string_view cert); │ │ │ │ │ + bool priv () const; │ │ │ │ │ + void set_priv (bool p); │ │ │ │ │ + bool is_v1_only () const; │ │ │ │ │ + bool is_v2_only () const; │ │ │ │ │ + int num_pieces () const; │ │ │ │ │ + piece_index_t end_piece () const; │ │ │ │ │ + index_range piece_range () const noexcept; │ │ │ │ │ + file_index_t end_file () const; │ │ │ │ │ + index_range file_range () const noexcept; │ │ │ │ │ + index_range file_piece_range (file_index_t f); │ │ │ │ │ + std::int64_t total_size () const; │ │ │ │ │ + int piece_length () const; │ │ │ │ │ + int piece_size (piece_index_t i) const; │ │ │ │ │ + void add_collection (string_view c); │ │ │ │ │ + void add_similar_torrent (sha1_hash ih); │ │ │ │ │ + │ │ │ │ │ + static constexpr create_flags_t modification_time = 2_bit; │ │ │ │ │ + static constexpr create_flags_t symlinks = 3_bit; │ │ │ │ │ + static constexpr create_flags_t v2_only = 5_bit; │ │ │ │ │ + static constexpr create_flags_t v1_only = 6_bit; │ │ │ │ │ + static constexpr create_flags_t canonical_files = 7_bit; │ │ │ │ │ + static constexpr create_flags_t no_attributes = 8_bit; │ │ │ │ │ + static constexpr create_flags_t canonical_files_no_tail_padding = 9_bit; │ │ │ │ │ +}; │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** create_torrent() ***** │ │ │ │ │ +explicit create_torrent (file_storage& fs, int piece_size = 0 │ │ │ │ │ + , create_flags_t flags = {}); │ │ │ │ │ +explicit create_torrent (torrent_info const& ti); │ │ │ │ │ +The piece_size is the size of each piece in bytes. It must be a power of 2 and │ │ │ │ │ +a minimum of 16 kiB. If a piece size of 0 is specified, a piece_size will be │ │ │ │ │ +set automatically. │ │ │ │ │ +The flags arguments specifies options for the torrent creation. It can be any │ │ │ │ │ +combination of the flags defined by create_flags_t. │ │ │ │ │ +The file_storage (fs) parameter defines the files, sizes and their properties │ │ │ │ │ +for the torrent to be created. Set this up first, before passing it to the │ │ │ │ │ +create_torrent constructor. │ │ │ │ │ +The overload that takes a torrent_info object will make a verbatim copy of its │ │ │ │ │ +info dictionary (to preserve the info-hash). The copy of the info dictionary │ │ │ │ │ +will be used by create_torrent::generate(). This means that none of the member │ │ │ │ │ +functions of create_torrent that affects the content of the info dictionary │ │ │ │ │ +(such as set_hash()), will have any affect. Instead of using this overload, │ │ │ │ │ +consider using write_torrent_file() instead. │ │ │ │ │ +Warning │ │ │ │ │ +The file_storage and torrent_info objects must stay alive for the entire │ │ │ │ │ +duration of the create_torrent object. │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** generate() generate_buf() ***** │ │ │ │ │ +entry generate () const; │ │ │ │ │ +std::vector generate_buf () const; │ │ │ │ │ +This function will generate the .torrent file as a bencode tree, or a bencoded │ │ │ │ │ +into a buffer. In order to encode the entry into a flat file, use the bencode() │ │ │ │ │ +function. │ │ │ │ │ +The function returning an entry may be useful to add custom entries to the │ │ │ │ │ +torrent file before bencoding it and saving it to disk. │ │ │ │ │ +Whether the resulting torrent object is v1, v2 or hybrid depends on whether any │ │ │ │ │ +of the v1_only or v2_only flags were set on the constructor. If neither were │ │ │ │ │ +set, the resulting torrent depends on which hashes were set. If both v1 and v2 │ │ │ │ │ +hashes were set, a hybrid torrent is created. │ │ │ │ │ +Any failure will cause this function to throw system_error, with an appropriate │ │ │ │ │ +error message. These are the reasons this call may throw: │ │ │ │ │ + * the file storage has 0 files │ │ │ │ │ + * the total size of the file storage is 0 bytes (i.e. it only has empty │ │ │ │ │ + files) │ │ │ │ │ + * not all v1 hashes (set_hash()) and not all v2 hashes (set_hash2()) were │ │ │ │ │ + set │ │ │ │ │ + * for v2 torrents, you may not have a directory with the same name as a │ │ │ │ │ + file. If that's encountered in the file storage, generate() fails. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** files() ***** │ │ │ │ │ +file_storage const& files () const; │ │ │ │ │ +returns an immutable reference to the file_storage used to create the torrent │ │ │ │ │ +from. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** set_comment() ***** │ │ │ │ │ +void set_comment (char const* str); │ │ │ │ │ +Sets the comment for the torrent. The string str should be utf-8 encoded. The │ │ │ │ │ +comment in a torrent file is optional. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** set_creator() ***** │ │ │ │ │ +void set_creator (char const* str); │ │ │ │ │ +Sets the creator of the torrent. The string str should be utf-8 encoded. This │ │ │ │ │ +is optional. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** set_creation_date() ***** │ │ │ │ │ +void set_creation_date (std::time_t timestamp); │ │ │ │ │ +sets the "creation time" field. Defaults to the system clock at the time of │ │ │ │ │ +construction of the create_torrent object. The timestamp is specified in │ │ │ │ │ +seconds, posix time. If the creation date is set to 0, the "creation date" │ │ │ │ │ +field will be omitted from the generated torrent. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** set_hash() ***** │ │ │ │ │ +void set_hash (piece_index_t index, sha1_hash const& h); │ │ │ │ │ +This sets the SHA-1 hash for the specified piece (index). You are required to │ │ │ │ │ +set the hash for every piece in the torrent before generating it. If you have │ │ │ │ │ +the files on disk, you can use the high level convenience function to do this. │ │ │ │ │ +See set_piece_hashes(). A SHA-1 hash of all zeros is internally used to │ │ │ │ │ +indicate a hash that has not been set. Setting such hash will not be considered │ │ │ │ │ +set when calling generate(). This function will throw std::system_error if it │ │ │ │ │ +is called on an object constructed with the v2_only flag. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** set_hash2() ***** │ │ │ │ │ +void set_hash2 (file_index_t file, piece_index_t::diff_type piece, sha256_hash │ │ │ │ │ +const& h); │ │ │ │ │ +sets the bittorrent v2 hash for filefileof the piecepiece.pieceis relative to │ │ │ │ │ +the first piece of the file, starting at 0. The first piece in the file can be │ │ │ │ │ +computed with file_storage::file_index_at_piece(). The hash,h, is the root of │ │ │ │ │ +the merkle tree formed by the piece's 16 kiB blocks. Note that piece sizes must │ │ │ │ │ +be powers-of-2, so all per-piece merkle trees are complete. A SHA-256 hash of │ │ │ │ │ +all zeros is internally used to indicate a hash that has not been set. Setting │ │ │ │ │ +such hash will not be considered set when calling generate(). This function │ │ │ │ │ +will throw std::system_error if it is called on an object constructed with the │ │ │ │ │ +v1_only flag. │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** add_http_seed() add_url_seed() ***** │ │ │ │ │ +void add_http_seed (string_view url); │ │ │ │ │ +void add_url_seed (string_view url); │ │ │ │ │ +This adds a url seed to the torrent. You can have any number of url seeds. For │ │ │ │ │ +a single file torrent, this should be an HTTP url, pointing to a file with │ │ │ │ │ +identical content as the file of the torrent. For a multi-file torrent, it │ │ │ │ │ +should point to a directory containing a directory with the same name as this │ │ │ │ │ +torrent, and all the files of the torrent in it. │ │ │ │ │ +The second function, add_http_seed() adds an HTTP seed instead. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** add_node() ***** │ │ │ │ │ +void add_node (std::pair node); │ │ │ │ │ +This adds a DHT node to the torrent. This especially useful if you're creating │ │ │ │ │ +a tracker less torrent. It can be used by clients to bootstrap their DHT node │ │ │ │ │ +from. The node is a hostname and a port number where there is a DHT node │ │ │ │ │ +running. You can have any number of DHT nodes in a torrent. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** add_tracker() ***** │ │ │ │ │ +void add_tracker (string_view url, int tier = 0); │ │ │ │ │ +Adds a tracker to the torrent. This is not strictly required, but most torrents │ │ │ │ │ +use a tracker as their main source of peers. The url should be an http:// or │ │ │ │ │ +udp:// url to a machine running a bittorrent tracker that accepts announces for │ │ │ │ │ +this torrent's info-hash. The tier is the fallback priority of the tracker. All │ │ │ │ │ +trackers with tier 0 are tried first (in any order). If all fail, trackers with │ │ │ │ │ +tier 1 are tried. If all of those fail, trackers with tier 2 are tried, and so │ │ │ │ │ +on. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** set_root_cert() ***** │ │ │ │ │ +void set_root_cert (string_view cert); │ │ │ │ │ +This function sets an X.509 certificate in PEM format to the torrent. This │ │ │ │ │ +makes the torrent an SSL torrent. An SSL torrent requires that each peer has a │ │ │ │ │ +valid certificate signed by this root certificate. For SSL torrents, all peers │ │ │ │ │ +are connecting over SSL connections. For more information, see the section on │ │ │ │ │ +ssl_torrents. │ │ │ │ │ +The string is not the path to the cert, it's the actual content of the │ │ │ │ │ +certificate. │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** priv() set_priv() ***** │ │ │ │ │ +bool priv () const; │ │ │ │ │ +void set_priv (bool p); │ │ │ │ │ +Sets and queries the private flag of the torrent. Torrents with the private │ │ │ │ │ +flag set ask the client to not use any other sources than the tracker for │ │ │ │ │ +peers, and to not use DHT to advertise itself publicly, only the tracker. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** num_pieces() ***** │ │ │ │ │ +int num_pieces () const; │ │ │ │ │ +returns the number of pieces in the associated file_storage object. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** piece_range() ***** │ │ │ │ │ +index_range piece_range () const noexcept; │ │ │ │ │ +all piece indices in the torrent to be created │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** file_range() ***** │ │ │ │ │ +index_range file_range () const noexcept; │ │ │ │ │ +all file indices in the torrent to be created │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** file_piece_range() ***** │ │ │ │ │ +index_range file_piece_range (file_index_t f); │ │ │ │ │ +for v2 and hybrid torrents only, the pieces in the specified file, specified as │ │ │ │ │ +delta from the first piece in the file. i.e. the first index is 0. │ │ │ │ │ +[report_issue] │ │ │ │ │ +***** total_size() ***** │ │ │ │ │ +std::int64_t total_size () const; │ │ │ │ │ +the total number of bytes of all files and pad files │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** piece_size() piece_length() ***** │ │ │ │ │ +int piece_length () const; │ │ │ │ │ +int piece_size (piece_index_t i) const; │ │ │ │ │ +piece_length() returns the piece size of all pieces but the last one. │ │ │ │ │ +piece_size() returns the size of the specified piece. these functions are just │ │ │ │ │ +forwarding to the associated file_storage. │ │ │ │ │ + [report_issue] │ │ │ │ │ +***** add_similar_torrent() add_collection() ***** │ │ │ │ │ +void add_collection (string_view c); │ │ │ │ │ +void add_similar_torrent (sha1_hash ih); │ │ │ │ │ +Add similar torrents (by info-hash) or collections of similar torrents. Similar │ │ │ │ │ +torrents are expected to share some files with this torrent. Torrents sharing a │ │ │ │ │ +collection name with this torrent are also expected to share files with this │ │ │ │ │ +torrent. A torrent may have more than one collection and more than one similar │ │ │ │ │ +torrents. For more information, see BEP_38. │ │ │ │ │ +[report_issue] │ │ │ │ │ + modification_time │ │ │ │ │ + This will include the file modification time as part of the torrent. This │ │ │ │ │ + is not enabled by default, as it might cause problems when you create a │ │ │ │ │ + torrent from separate files with the same content, hoping to yield the │ │ │ │ │ + same info-hash. If the files have different modification times, with this │ │ │ │ │ + option enabled, you would get different info-hashes for the files. │ │ │ │ │ +[report_issue] │ │ │ │ │ + symlinks │ │ │ │ │ + If this flag is set, files that are symlinks get a symlink attribute set │ │ │ │ │ + on them and their data will not be included in the torrent. This is │ │ │ │ │ + useful if you need to reconstruct a file hierarchy which contains │ │ │ │ │ + symlinks. │ │ │ │ │ +[report_issue] │ │ │ │ │ + v2_only │ │ │ │ │ + Do not generate v1 metadata. The resulting torrent will only be usable by │ │ │ │ │ + clients which support v2. This requires setting all v2 hashes, with │ │ │ │ │ + set_hash2() before calling generate(). Setting v1 hashes (with set_hash │ │ │ │ │ + ()) is an error with this flag set. │ │ │ │ │ +[report_issue] │ │ │ │ │ + v1_only │ │ │ │ │ + do not generate v2 metadata or enforce v2 alignment and padding rules │ │ │ │ │ + this is mainly for tests, not recommended for production use. This │ │ │ │ │ + requires setting all v1 hashes, with set_hash(), before calling generate │ │ │ │ │ + (). Setting v2 hashes (with set_hash2()) is an error with this flag set. │ │ │ │ │ +[report_issue] │ │ │ │ │ + canonical_files │ │ │ │ │ + This flag only affects v1-only torrents, and is only relevant together │ │ │ │ │ + with the v1_only_flag. This flag will force the same file order and │ │ │ │ │ + padding as a v2 (or hybrid) torrent would have. It has the effect of │ │ │ │ │ + ordering files and inserting pad files to align them with piece │ │ │ │ │ + boundaries. │ │ │ │ │ +[report_issue] │ │ │ │ │ + no_attributes │ │ │ │ │ + passing this flag to add_files() will ignore file attributes (such as │ │ │ │ │ + executable or hidden) when adding the files to the file storage. Since │ │ │ │ │ + not all filesystems and operating systems support all file attributes the │ │ │ │ │ + resulting torrent may differ depending on where it's created. If it's │ │ │ │ │ + important for torrents to be created consistently across systems, this │ │ │ │ │ + flag should be set. │ │ │ │ │ +[report_issue] │ │ │ │ │ + canonical_files_no_tail_padding │ │ │ │ │ + this flag enforces the file layout to be canonical according to the │ │ │ │ │ + bittorrent v2 specification (just like the canonical_files flag) with the │ │ │ │ │ + one exception that tail padding is not added to the last file. This │ │ │ │ │ + behavior deviates from the specification but was the way libtorrent │ │ │ │ │ + created torrents in version up to and including 2.0.7. This flag is here │ │ │ │ │ + for backwards compatibility. │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** add_files() ****** │ │ │ │ │ +Declared in "libtorrent/create_torrent.hpp" │ │ │ │ │ +void add_files (file_storage& fs, std::string const& file │ │ │ │ │ + , create_flags_t flags = {}); │ │ │ │ │ +void add_files (file_storage& fs, std::string const& file │ │ │ │ │ + , std::function p, create_flags_t flags = {}); │ │ │ │ │ +Adds the file specified by path to the file_storage object. In case path refers │ │ │ │ │ +to a directory, files will be added recursively from the directory. │ │ │ │ │ +If specified, the predicate p is called once for every file and directory that │ │ │ │ │ +is encountered. Files for which p returns true are added, and directories for │ │ │ │ │ +which p returns true are traversed. p must have the following signature: │ │ │ │ │ +bool Pred(std::string const& p); │ │ │ │ │ +The path that is passed in to the predicate is the full path of the file or │ │ │ │ │ +directory. If no predicate is specified, all files are added, and all │ │ │ │ │ +directories are traversed. │ │ │ │ │ +The ".." directory is never traversed. │ │ │ │ │ +The flags argument should be the same as the flags passed to the create_torrent │ │ │ │ │ +constructor. │ │ │ │ │ +[report_issue] │ │ │ │ │ +****** set_piece_hashes() ****** │ │ │ │ │ +Declared in "libtorrent/create_torrent.hpp" │ │ │ │ │ +void set_piece_hashes (create_torrent& t, std::string const& p │ │ │ │ │ + , settings_interface const& settings, disk_io_constructor_type disk_io │ │ │ │ │ + , std::function const& f, error_code& ec); │ │ │ │ │ +inline void set_piece_hashes (create_torrent& t, std::string const& p │ │ │ │ │ + , settings_interface const& settings │ │ │ │ │ + , std::function const& f); │ │ │ │ │ +void set_piece_hashes (create_torrent& t, std::string const& p │ │ │ │ │ + , settings_interface const& settings │ │ │ │ │ + , std::function const& f, error_code& ec); │ │ │ │ │ +void set_piece_hashes (create_torrent& t, std::string const& p │ │ │ │ │ + , std::function const& f, error_code& ec); │ │ │ │ │ +inline void set_piece_hashes (create_torrent& t, std::string const& p │ │ │ │ │ + , std::function const& f); │ │ │ │ │ +inline void set_piece_hashes (create_torrent& t, std::string const& p); │ │ │ │ │ +inline void set_piece_hashes (create_torrent& t, std::string const& p, │ │ │ │ │ +error_code& ec); │ │ │ │ │ +This function will assume that the files added to the torrent file exists at │ │ │ │ │ +path p, read those files and hash the content and set the hashes in the │ │ │ │ │ +create_torrent object. The optional function f is called in between every hash │ │ │ │ │ +that is set. f must have the following signature: │ │ │ │ │ +void Fun(piece_index_t); │ │ │ │ │ +The overloads taking a settings_pack may be used to configure the underlying │ │ │ │ │ +disk access. Such as settings_pack::aio_threads. │ │ │ │ │ +The overloads that don't take an error_code& may throw an exception in case of │ │ │ │ │ +a file error, the other overloads sets the error code to reflect the error, if │ │ │ │ │ +any. │ │ │ │ │ [report_issue] │ │ │ │ │ ****** block_info ****** │ │ │ │ │ Declared in "libtorrent/torrent_handle.hpp" │ │ │ │ │ holds the state of a block in a piece. Who we requested it from and how far │ │ │ │ │ along we are at downloading it. │ │ │ │ │ struct block_info │ │ │ │ │ { │ │ │ │ │ - void set_peer (tcp::endpoint const& ep); │ │ │ │ │ tcp::endpoint peer () const; │ │ │ │ │ + void set_peer (tcp::endpoint const& ep); │ │ │ │ │ │ │ │ │ │ enum block_state_t │ │ │ │ │ { │ │ │ │ │ none, │ │ │ │ │ requested, │ │ │ │ │ writing, │ │ │ │ │ finished, │ │ │ │ │ @@ -10722,17 +11183,17 @@ │ │ │ │ │ │ │ │ │ │ unsigned bytes_progress:15; │ │ │ │ │ unsigned block_size:15; │ │ │ │ │ unsigned state:2; │ │ │ │ │ unsigned num_peers:14; │ │ │ │ │ }; │ │ │ │ │ [report_issue] │ │ │ │ │ -***** peer() set_peer() ***** │ │ │ │ │ -void set_peer (tcp::endpoint const& ep); │ │ │ │ │ +***** set_peer() peer() ***** │ │ │ │ │ tcp::endpoint peer () const; │ │ │ │ │ +void set_peer (tcp::endpoint const& ep); │ │ │ │ │ The peer is the ip address of the peer this block was downloaded from. │ │ │ │ │ [report_issue] │ │ │ │ │ ***** enum block_state_t ***** │ │ │ │ │ Declared in "libtorrent/torrent_handle.hpp" │ │ │ │ │ ___________________________________________________________________________ │ │ │ │ │ |name_____|value|description________________________________________________| │ │ │ │ │ |none |0 |This block has not been downloaded or requested form any | │ │ │ │ │ @@ -10819,110 +11280,110 @@ │ │ │ │ │ the handle is no longer referring to a torrent. There is one exception is_valid │ │ │ │ │ () will never throw. Since the torrents are processed by a background thread, │ │ │ │ │ there is no guarantee that a handle will remain valid between two calls. │ │ │ │ │ struct torrent_handle │ │ │ │ │ { │ │ │ │ │ friend std::size_t hash_value (torrent_handle const& th); │ │ │ │ │ torrent_handle () noexcept = default; │ │ │ │ │ - void add_piece (piece_index_t piece, std::vector data, │ │ │ │ │ -add_piece_flags_t flags = {}) const; │ │ │ │ │ void add_piece (piece_index_t piece, char const* data, add_piece_flags_t │ │ │ │ │ flags = {}) const; │ │ │ │ │ + void add_piece (piece_index_t piece, std::vector data, │ │ │ │ │ +add_piece_flags_t flags = {}) const; │ │ │ │ │ void read_piece (piece_index_t piece) const; │ │ │ │ │ bool have_piece (piece_index_t piece) const; │ │ │ │ │ void get_peer_info (std::vector& v) const; │ │ │ │ │ torrent_status status (status_flags_t flags = status_flags_t::all()) const; │ │ │ │ │ - std::vector get_download_queue () const; │ │ │ │ │ void get_download_queue (std::vector& queue) const; │ │ │ │ │ - void reset_piece_deadline (piece_index_t index) const; │ │ │ │ │ - void clear_piece_deadlines () const; │ │ │ │ │ + std::vector get_download_queue () const; │ │ │ │ │ void set_piece_deadline (piece_index_t index, int deadline, deadline_flags_t │ │ │ │ │ flags = {}) const; │ │ │ │ │ - std::vector file_progress (file_progress_flags_t flags = {}) │ │ │ │ │ -const; │ │ │ │ │ + void clear_piece_deadlines () const; │ │ │ │ │ + void reset_piece_deadline (piece_index_t index) const; │ │ │ │ │ void file_progress (std::vector& progress, │ │ │ │ │ file_progress_flags_t flags = {}) const; │ │ │ │ │ + std::vector file_progress (file_progress_flags_t flags = {}) │ │ │ │ │ +const; │ │ │ │ │ std::vector file_status () const; │ │ │ │ │ void clear_error () const; │ │ │ │ │ void add_tracker (announce_entry const&) const; │ │ │ │ │ - void replace_trackers (std::vector const&) const; │ │ │ │ │ std::vector trackers () const; │ │ │ │ │ + void replace_trackers (std::vector const&) const; │ │ │ │ │ void remove_url_seed (std::string const& url) const; │ │ │ │ │ std::set url_seeds () const; │ │ │ │ │ void add_url_seed (std::string const& url) const; │ │ │ │ │ - void add_http_seed (std::string const& url) const; │ │ │ │ │ - std::set http_seeds () const; │ │ │ │ │ void remove_http_seed (std::string const& url) const; │ │ │ │ │ + std::set http_seeds () const; │ │ │ │ │ + void add_http_seed (std::string const& url) const; │ │ │ │ │ void add_extension ( │ │ │ │ │ std::function(torrent_handle const&, │ │ │ │ │ client_data_t)> const& ext │ │ │ │ │ , client_data_t userdata = client_data_t{}); │ │ │ │ │ bool set_metadata (span metadata) const; │ │ │ │ │ bool is_valid () const; │ │ │ │ │ void resume () const; │ │ │ │ │ void pause (pause_flags_t flags = {}) const; │ │ │ │ │ - void set_flags (torrent_flags_t flags) const; │ │ │ │ │ void unset_flags (torrent_flags_t flags) const; │ │ │ │ │ void set_flags (torrent_flags_t flags, torrent_flags_t mask) const; │ │ │ │ │ torrent_flags_t flags () const; │ │ │ │ │ + void set_flags (torrent_flags_t flags) const; │ │ │ │ │ void flush_cache () const; │ │ │ │ │ void force_recheck () const; │ │ │ │ │ void save_resume_data (resume_data_flags_t flags = {}) const; │ │ │ │ │ bool need_save_resume_data () const; │ │ │ │ │ - void queue_position_down () const; │ │ │ │ │ - queue_position_t queue_position () const; │ │ │ │ │ void queue_position_bottom () const; │ │ │ │ │ - void queue_position_top () const; │ │ │ │ │ void queue_position_up () const; │ │ │ │ │ + void queue_position_top () const; │ │ │ │ │ + queue_position_t queue_position () const; │ │ │ │ │ + void queue_position_down () const; │ │ │ │ │ void queue_position_set (queue_position_t p) const; │ │ │ │ │ + void set_ssl_certificate_buffer (std::string const& certificate │ │ │ │ │ + , std::string const& private_key │ │ │ │ │ + , std::string const& dh_params); │ │ │ │ │ void set_ssl_certificate (std::string const& certificate │ │ │ │ │ , std::string const& private_key │ │ │ │ │ , std::string const& dh_params │ │ │ │ │ , std::string const& passphrase = ""); │ │ │ │ │ - void set_ssl_certificate_buffer (std::string const& certificate │ │ │ │ │ - , std::string const& private_key │ │ │ │ │ - , std::string const& dh_params); │ │ │ │ │ std::shared_ptr torrent_file () const; │ │ │ │ │ std::shared_ptr torrent_file_with_hashes () const; │ │ │ │ │ std::vector> piece_layers () const; │ │ │ │ │ void piece_availability (std::vector& avail) const; │ │ │ │ │ std::vector get_piece_priorities () const; │ │ │ │ │ void piece_priority (piece_index_t index, download_priority_t priority) │ │ │ │ │ const; │ │ │ │ │ - void prioritize_pieces (std::vector> const& pieces) const; │ │ │ │ │ download_priority_t piece_priority (piece_index_t index) const; │ │ │ │ │ void prioritize_pieces (std::vector const& pieces) │ │ │ │ │ const; │ │ │ │ │ - void file_priority (file_index_t index, download_priority_t priority) const; │ │ │ │ │ + void prioritize_pieces (std::vector> const& pieces) const; │ │ │ │ │ std::vector get_file_priorities () const; │ │ │ │ │ + void file_priority (file_index_t index, download_priority_t priority) const; │ │ │ │ │ void prioritize_files (std::vector const& files) const; │ │ │ │ │ download_priority_t file_priority (file_index_t index) const; │ │ │ │ │ - void force_lsd_announce () const; │ │ │ │ │ void force_reannounce (int seconds = 0, int idx = -1, reannounce_flags_t = │ │ │ │ │ {}) const; │ │ │ │ │ void force_dht_announce () const; │ │ │ │ │ + void force_lsd_announce () const; │ │ │ │ │ void scrape_tracker (int idx = -1) const; │ │ │ │ │ - int download_limit () const; │ │ │ │ │ - void set_upload_limit (int limit) const; │ │ │ │ │ void set_download_limit (int limit) const; │ │ │ │ │ + void set_upload_limit (int limit) const; │ │ │ │ │ + int download_limit () const; │ │ │ │ │ int upload_limit () const; │ │ │ │ │ void connect_peer (tcp::endpoint const& adr, peer_source_flags_t source = {} │ │ │ │ │ , pex_flags_t flags = pex_encryption | pex_utp | pex_holepunch) const; │ │ │ │ │ void clear_peers (); │ │ │ │ │ int max_uploads () const; │ │ │ │ │ void set_max_uploads (int max_uploads) const; │ │ │ │ │ int max_connections () const; │ │ │ │ │ void set_max_connections (int max_connections) const; │ │ │ │ │ void move_storage (std::string const& save_path │ │ │ │ │ , move_flags_t flags = move_flags_t::always_replace_files │ │ │ │ │ ) const; │ │ │ │ │ void rename_file (file_index_t index, std::string const& new_name) const; │ │ │ │ │ - sha1_hash info_hash () const; │ │ │ │ │ info_hash_t info_hashes () const; │ │ │ │ │ + sha1_hash info_hash () const; │ │ │ │ │ bool operator< (const torrent_handle& h) const; │ │ │ │ │ bool operator== (const torrent_handle& h) const; │ │ │ │ │ bool operator!= (const torrent_handle& h) const; │ │ │ │ │ std::uint32_t id () const; │ │ │ │ │ std::shared_ptr native_handle () const; │ │ │ │ │ client_data_t userdata () const; │ │ │ │ │ bool in_session () const; │ │ │ │ │ @@ -10947,18 +11408,18 @@ │ │ │ │ │ [report_issue] │ │ │ │ │ ***** torrent_handle() ***** │ │ │ │ │ torrent_handle () noexcept = default; │ │ │ │ │ constructs a torrent handle that does not refer to a torrent. i.e. is_valid() │ │ │ │ │ will return false. │ │ │ │ │ [report_issue] │ │ │ │ │ ***** add_piece() ***** │ │ │ │ │ -void add_piece (piece_index_t piece, std::vector data, add_piece_flags_t │ │ │ │ │ -flags = {}) const; │ │ │ │ │ void add_piece (piece_index_t piece, char const* data, add_piece_flags_t flags │ │ │ │ │ = {}) const; │ │ │ │ │ +void add_piece (piece_index_t piece, std::vector data, add_piece_flags_t │ │ │ │ │ +flags = {}) const; │ │ │ │ │ This function will write data to the storage as piece piece, as if it had been │ │ │ │ │ downloaded from a peer. │ │ │ │ │ By default, data that's already been downloaded is not overwritten by this │ │ │ │ │ buffer. If you trust this data to be correct (and pass the piece hash check) │ │ │ │ │ you may pass the overwrite_existing flag. This will instruct libtorrent to │ │ │ │ │ overwrite any data that may already have been downloaded with this data. │ │ │ │ │ Since the data is written asynchronously, you may know that is passed or failed │ │ │ │ │ @@ -11005,25 +11466,25 @@ │ │ │ │ │ returned in the torrent_status. Some information in there is relatively │ │ │ │ │ expensive to calculate, and if you're not interested in it (and see performance │ │ │ │ │ issues), you can filter them out. │ │ │ │ │ By default everything is included. The flags you can use to decide what to │ │ │ │ │ include are defined in this class. │ │ │ │ │ [report_issue] │ │ │ │ │ ***** get_download_queue() ***** │ │ │ │ │ -std::vector get_download_queue () const; │ │ │ │ │ void get_download_queue (std::vector& queue) const; │ │ │ │ │ +std::vector get_download_queue () const; │ │ │ │ │ get_download_queue() returns a vector with information about pieces that are │ │ │ │ │ partially downloaded or not downloaded but partially requested. See │ │ │ │ │ partial_piece_info for the fields in the returned vector. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** clear_piece_deadlines() set_piece_deadline() reset_piece_deadline() ***** │ │ │ │ │ -void reset_piece_deadline (piece_index_t index) const; │ │ │ │ │ -void clear_piece_deadlines () const; │ │ │ │ │ +***** reset_piece_deadline() set_piece_deadline() clear_piece_deadlines() ***** │ │ │ │ │ void set_piece_deadline (piece_index_t index, int deadline, deadline_flags_t │ │ │ │ │ flags = {}) const; │ │ │ │ │ +void clear_piece_deadlines () const; │ │ │ │ │ +void reset_piece_deadline (piece_index_t index) const; │ │ │ │ │ This function sets or resets the deadline associated with a specific piece │ │ │ │ │ index (index). libtorrent will attempt to download this entire piece before the │ │ │ │ │ deadline expires. This is not necessarily possible, but pieces with a more │ │ │ │ │ recent deadline will always be prioritized over pieces with a deadline further │ │ │ │ │ ahead in time. The deadline (and flags) of a piece can be changed by calling │ │ │ │ │ this function again. │ │ │ │ │ If the piece is already downloaded when this call is made, nothing happens, │ │ │ │ │ @@ -11032,18 +11493,18 @@ │ │ │ │ │ deadline is the number of milliseconds until this piece should be completed. │ │ │ │ │ reset_piece_deadline removes the deadline from the piece. If it hasn't already │ │ │ │ │ been downloaded, it will no longer be considered a priority. │ │ │ │ │ clear_piece_deadlines() removes deadlines on all pieces in the torrent. As if │ │ │ │ │ reset_piece_deadline() was called on all pieces. │ │ │ │ │ [report_issue] │ │ │ │ │ ***** file_progress() ***** │ │ │ │ │ -std::vector file_progress (file_progress_flags_t flags = {}) │ │ │ │ │ -const; │ │ │ │ │ void file_progress (std::vector& progress, file_progress_flags_t │ │ │ │ │ flags = {}) const; │ │ │ │ │ +std::vector file_progress (file_progress_flags_t flags = {}) │ │ │ │ │ +const; │ │ │ │ │ This function fills in the supplied vector, or returns a vector, with the │ │ │ │ │ number of bytes downloaded of each file in this torrent. The progress values │ │ │ │ │ are ordered the same as the files in the torrent_info. │ │ │ │ │ This operation is not very cheap. Its complexity is O(n + mj). Where n is the │ │ │ │ │ number of files, m is the number of currently downloading pieces and j is the │ │ │ │ │ number of blocks in a piece. │ │ │ │ │ The flags parameter can be used to specify the granularity of the file │ │ │ │ │ @@ -11066,46 +11527,46 @@ │ │ │ │ │ ***** clear_error() ***** │ │ │ │ │ void clear_error () const; │ │ │ │ │ If the torrent is in an error state (i.e. torrent_status::error is non-empty), │ │ │ │ │ this will clear the error and start the torrent again. │ │ │ │ │ [report_issue] │ │ │ │ │ ***** trackers() replace_trackers() add_tracker() ***** │ │ │ │ │ void add_tracker (announce_entry const&) const; │ │ │ │ │ -void replace_trackers (std::vector const&) const; │ │ │ │ │ std::vector trackers () const; │ │ │ │ │ +void replace_trackers (std::vector const&) const; │ │ │ │ │ trackers() will return the list of trackers for this torrent. The announce │ │ │ │ │ entry contains both a string url which specify the announce url for the tracker │ │ │ │ │ as well as an int tier, which is specifies the order in which this tracker is │ │ │ │ │ tried. If you want libtorrent to use another list of trackers for this torrent, │ │ │ │ │ you can use replace_trackers() which takes a list of the same form as the one │ │ │ │ │ returned from trackers() and will replace it. If you want an immediate effect, │ │ │ │ │ you have to call force_reannounce(). See announce_entry. │ │ │ │ │ add_tracker() will look if the specified tracker is already in the set. If it │ │ │ │ │ is, it doesn't do anything. If it's not in the current set of trackers, it will │ │ │ │ │ insert it in the tier specified in the announce_entry. │ │ │ │ │ The updated set of trackers will be saved in the resume data, and when a │ │ │ │ │ torrent is started with resume data, the trackers from the resume data will │ │ │ │ │ replace the original ones. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** add_url_seed() url_seeds() remove_url_seed() ***** │ │ │ │ │ +***** remove_url_seed() url_seeds() add_url_seed() ***** │ │ │ │ │ void remove_url_seed (std::string const& url) const; │ │ │ │ │ std::set url_seeds () const; │ │ │ │ │ void add_url_seed (std::string const& url) const; │ │ │ │ │ add_url_seed() adds another url to the torrent's list of url seeds. If the │ │ │ │ │ given url already exists in that list, the call has no effect. The torrent will │ │ │ │ │ connect to the server and try to download pieces from it, unless it's paused, │ │ │ │ │ queued, checking or seeding. remove_url_seed() removes the given url if it │ │ │ │ │ exists already. url_seeds() return a set of the url seeds currently in this │ │ │ │ │ torrent. Note that URLs that fails may be removed automatically from the list. │ │ │ │ │ See http_seeding for more information. │ │ │ │ │ [report_issue] │ │ │ │ │ ***** http_seeds() add_http_seed() remove_http_seed() ***** │ │ │ │ │ -void add_http_seed (std::string const& url) const; │ │ │ │ │ -std::set http_seeds () const; │ │ │ │ │ void remove_http_seed (std::string const& url) const; │ │ │ │ │ +std::set http_seeds () const; │ │ │ │ │ +void add_http_seed (std::string const& url) const; │ │ │ │ │ These functions are identical as the *_url_seed() variants, but they operate on │ │ │ │ │ BEP_17 web seeds instead of BEP_19. │ │ │ │ │ See http_seeding for more information. │ │ │ │ │ [report_issue] │ │ │ │ │ ***** add_extension() ***** │ │ │ │ │ void add_extension ( │ │ │ │ │ std::function(torrent_handle const&, │ │ │ │ │ @@ -11136,15 +11597,15 @@ │ │ │ │ │ and false afterward. │ │ │ │ │ Clients should only use is_valid() to determine if the result of session:: │ │ │ │ │ find_torrent() was successful. │ │ │ │ │ Unlike other member functions which return a value, is_valid() completes │ │ │ │ │ immediately, without blocking on a result from the network thread. Also unlike │ │ │ │ │ other functions, it never throws the system_error exception. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** resume() pause() ***** │ │ │ │ │ +***** pause() resume() ***** │ │ │ │ │ void resume () const; │ │ │ │ │ void pause (pause_flags_t flags = {}) const; │ │ │ │ │ pause(), and resume() will disconnect all peers and reconnect all peers │ │ │ │ │ respectively. When a torrent is paused, it will however remember all share │ │ │ │ │ ratios to all peers and remember all potential (not connected) peers. Torrents │ │ │ │ │ may be paused automatically if there is a file error (e.g. disk full) or │ │ │ │ │ something similar. See file_error_alert. │ │ │ │ │ @@ -11153,19 +11614,19 @@ │ │ │ │ │ for the torrent_status::paused flag. │ │ │ │ │ Note │ │ │ │ │ Torrents that are auto-managed may be automatically resumed again. It does not │ │ │ │ │ make sense to pause an auto-managed torrent without making it not auto-managed │ │ │ │ │ first. Torrents are auto-managed by default when added to the session. For more │ │ │ │ │ information, see queuing. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** set_flags() unset_flags() flags() ***** │ │ │ │ │ -void set_flags (torrent_flags_t flags) const; │ │ │ │ │ +***** unset_flags() set_flags() flags() ***** │ │ │ │ │ void unset_flags (torrent_flags_t flags) const; │ │ │ │ │ void set_flags (torrent_flags_t flags, torrent_flags_t mask) const; │ │ │ │ │ torrent_flags_t flags () const; │ │ │ │ │ +void set_flags (torrent_flags_t flags) const; │ │ │ │ │ sets and gets the torrent state flags. See torrent_flags_t. The set_flags │ │ │ │ │ overload that take a mask will affect all flags part of the mask, and set their │ │ │ │ │ values to what the flags argument is set to. This allows clearing and setting │ │ │ │ │ flags in a single function call. The set_flags overload that just takes flags, │ │ │ │ │ sets all the specified flags and leave any other flags unchanged. unset_flags │ │ │ │ │ clears the specified flags, while leaving any other flags unchanged. │ │ │ │ │ Theseed_modeflag is special, it can only be cleared once the torrent has been │ │ │ │ │ @@ -11285,21 +11746,21 @@ │ │ │ │ │ saving resume data periodically, it makes sense to skip any torrent which │ │ │ │ │ hasn't downloaded anything since the last time. │ │ │ │ │ Note │ │ │ │ │ A torrent's resume data is considered saved as soon as the │ │ │ │ │ save_resume_data_alert is posted. It is important to make sure this alert is │ │ │ │ │ received and handled in order for this function to be meaningful. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** queue_position() queue_position_bottom() queue_position_up() │ │ │ │ │ -queue_position_top() queue_position_down() ***** │ │ │ │ │ -void queue_position_down () const; │ │ │ │ │ -queue_position_t queue_position () const; │ │ │ │ │ +***** queue_position_down() queue_position() queue_position_up() │ │ │ │ │ +queue_position_bottom() queue_position_top() ***** │ │ │ │ │ void queue_position_bottom () const; │ │ │ │ │ -void queue_position_top () const; │ │ │ │ │ void queue_position_up () const; │ │ │ │ │ +void queue_position_top () const; │ │ │ │ │ +queue_position_t queue_position () const; │ │ │ │ │ +void queue_position_down () const; │ │ │ │ │ Every torrent that is added is assigned a queue position exactly one greater │ │ │ │ │ than the greatest queue position of all existing torrents. Torrents that are │ │ │ │ │ being seeded have -1 as their queue position, since they're no longer in line │ │ │ │ │ to be downloaded. │ │ │ │ │ When a torrent is removed or turns into a seed, all torrents with greater queue │ │ │ │ │ positions have their positions decreased to fill in the space in the sequence. │ │ │ │ │ queue_position() returns the torrent's position in the download queue. The │ │ │ │ │ @@ -11313,22 +11774,22 @@ │ │ │ │ │ [report_issue] │ │ │ │ │ ***** queue_position_set() ***** │ │ │ │ │ void queue_position_set (queue_position_t p) const; │ │ │ │ │ updates the position in the queue for this torrent. The relative order of all │ │ │ │ │ other torrents remain intact but their numerical queue position shifts to make │ │ │ │ │ space for this torrent's new position │ │ │ │ │ [report_issue] │ │ │ │ │ -***** set_ssl_certificate_buffer() set_ssl_certificate() ***** │ │ │ │ │ +***** set_ssl_certificate() set_ssl_certificate_buffer() ***** │ │ │ │ │ +void set_ssl_certificate_buffer (std::string const& certificate │ │ │ │ │ + , std::string const& private_key │ │ │ │ │ + , std::string const& dh_params); │ │ │ │ │ void set_ssl_certificate (std::string const& certificate │ │ │ │ │ , std::string const& private_key │ │ │ │ │ , std::string const& dh_params │ │ │ │ │ , std::string const& passphrase = ""); │ │ │ │ │ -void set_ssl_certificate_buffer (std::string const& certificate │ │ │ │ │ - , std::string const& private_key │ │ │ │ │ - , std::string const& dh_params); │ │ │ │ │ For SSL torrents, use this to specify a path to a .pem file to use as this │ │ │ │ │ client's certificate. The certificate must be signed by the certificate in the │ │ │ │ │ .torrent file to be valid. │ │ │ │ │ The set_ssl_certificate_buffer() overload takes the actual certificate, private │ │ │ │ │ key and DH params as strings, rather than paths to files. │ │ │ │ │ cert is a path to the (signed) certificate in .pem format corresponding to this │ │ │ │ │ torrent. │ │ │ │ │ @@ -11342,15 +11803,15 @@ │ │ │ │ │ Note that when a torrent first starts up, and it needs a certificate, it will │ │ │ │ │ suspend connecting to any peers until it has one. It's typically desirable to │ │ │ │ │ resume the torrent after setting the SSL certificate. │ │ │ │ │ If you receive a torrent_need_cert_alert, you need to call this to provide a │ │ │ │ │ valid cert. If you don't have a cert you won't be allowed to connect to any │ │ │ │ │ peers. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** torrent_file_with_hashes() torrent_file() ***** │ │ │ │ │ +***** torrent_file() torrent_file_with_hashes() ***** │ │ │ │ │ std::shared_ptr torrent_file () const; │ │ │ │ │ std::shared_ptr torrent_file_with_hashes () const; │ │ │ │ │ torrent_file() returns a pointer to the torrent_info object associated with │ │ │ │ │ this torrent. The torrent_info object may be a copy of the internal object. If │ │ │ │ │ the torrent doesn't have metadata, the pointer will not be initialized (i.e. a │ │ │ │ │ nullptr). The torrent may be in a state without metadata only if it was started │ │ │ │ │ without a .torrent file, e.g. by being added by magnet link. │ │ │ │ │ @@ -11390,18 +11851,18 @@ │ │ │ │ │ The piece availability is the number of peers that we are connected that has │ │ │ │ │ advertised having a particular piece. This is the information that libtorrent │ │ │ │ │ uses in order to prefer picking rare pieces. │ │ │ │ │ [report_issue] │ │ │ │ │ ***** piece_priority() get_piece_priorities() prioritize_pieces() ***** │ │ │ │ │ std::vector get_piece_priorities () const; │ │ │ │ │ void piece_priority (piece_index_t index, download_priority_t priority) const; │ │ │ │ │ -void prioritize_pieces (std::vector> const& pieces) const; │ │ │ │ │ download_priority_t piece_priority (piece_index_t index) const; │ │ │ │ │ void prioritize_pieces (std::vector const& pieces) const; │ │ │ │ │ +void prioritize_pieces (std::vector> const& pieces) const; │ │ │ │ │ These functions are used to set and get the priority of individual pieces. By │ │ │ │ │ default all pieces have priority 4. That means that the random rarest first │ │ │ │ │ algorithm is effectively active for all pieces. You may however change the │ │ │ │ │ priority of individual pieces. There are 8 priority levels. 0 means not to │ │ │ │ │ download the piece at all. Otherwise, lower priority values means less likely │ │ │ │ │ to be picked. Piece priority takes precedence over piece availability. Every │ │ │ │ │ piece with priority 7 will be attempted to be picked before a priority 6 piece │ │ │ │ │ @@ -11421,17 +11882,17 @@ │ │ │ │ │ where the piece index or priority is out of range, are not allowed. │ │ │ │ │ get_piece_priorities returns a vector with one element for each piece in the │ │ │ │ │ torrent. Each element is the current priority of that piece. │ │ │ │ │ It's possible to cancel the effect of file priorities by setting the priorities │ │ │ │ │ for the affected pieces. Care has to be taken when mixing usage of file- and │ │ │ │ │ piece priorities. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** prioritize_files() file_priority() get_file_priorities() ***** │ │ │ │ │ -void file_priority (file_index_t index, download_priority_t priority) const; │ │ │ │ │ +***** file_priority() get_file_priorities() prioritize_files() ***** │ │ │ │ │ std::vector get_file_priorities () const; │ │ │ │ │ +void file_priority (file_index_t index, download_priority_t priority) const; │ │ │ │ │ void prioritize_files (std::vector const& files) const; │ │ │ │ │ download_priority_t file_priority (file_index_t index) const; │ │ │ │ │ index must be in the range [0, number_of_files). │ │ │ │ │ file_priority() queries or sets the priority of file index. │ │ │ │ │ prioritize_files() takes a vector that has at as many elements as there are │ │ │ │ │ files in the torrent. Each entry is the priority of that file. The function │ │ │ │ │ sets the priorities of all the pieces in the torrent based on the vector. │ │ │ │ │ @@ -11452,19 +11913,19 @@ │ │ │ │ │ When combining file- and piece priorities, the resume file will record both. │ │ │ │ │ When loading the resume data, the file priorities will be applied first, then │ │ │ │ │ the piece priorities. │ │ │ │ │ Moving data from a file into the part file is currently not supported. If a │ │ │ │ │ file has its priority set to 0 after it has already been created, it will not │ │ │ │ │ be moved into the partfile. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** force_dht_announce() force_reannounce() force_lsd_announce() ***** │ │ │ │ │ -void force_lsd_announce () const; │ │ │ │ │ +***** force_reannounce() force_lsd_announce() force_dht_announce() ***** │ │ │ │ │ void force_reannounce (int seconds = 0, int idx = -1, reannounce_flags_t = {}) │ │ │ │ │ const; │ │ │ │ │ void force_dht_announce () const; │ │ │ │ │ +void force_lsd_announce () const; │ │ │ │ │ force_reannounce() will force this torrent to do another tracker request, to │ │ │ │ │ receive new peers. The seconds argument specifies how many seconds from now to │ │ │ │ │ issue the tracker announces. │ │ │ │ │ If the tracker's min_interval has not passed since the last announce, the │ │ │ │ │ forced announce will be scheduled to happen immediately as the min_interval │ │ │ │ │ expires. This is to honor trackers minimum re-announce interval settings. │ │ │ │ │ The tracker_index argument specifies which tracker to re-announce. If set to - │ │ │ │ │ @@ -11482,19 +11943,19 @@ │ │ │ │ │ A scrape request queries the tracker for statistics such as total number of │ │ │ │ │ incomplete peers, complete peers, number of downloads etc. │ │ │ │ │ This request will specifically update the num_complete and num_incomplete │ │ │ │ │ fields in the torrent_status struct once it completes. When it completes, it │ │ │ │ │ will generate a scrape_reply_alert. If it fails, it will generate a │ │ │ │ │ scrape_failed_alert. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** download_limit() set_download_limit() set_upload_limit() upload_limit() │ │ │ │ │ +***** download_limit() set_upload_limit() set_download_limit() upload_limit() │ │ │ │ │ ***** │ │ │ │ │ -int download_limit () const; │ │ │ │ │ -void set_upload_limit (int limit) const; │ │ │ │ │ void set_download_limit (int limit) const; │ │ │ │ │ +void set_upload_limit (int limit) const; │ │ │ │ │ +int download_limit () const; │ │ │ │ │ int upload_limit () const; │ │ │ │ │ set_upload_limit will limit the upload bandwidth used by this particular │ │ │ │ │ torrent to the limit you set. It is given as the number of bytes per second the │ │ │ │ │ torrent is allowed to upload. set_download_limit works the same way but for │ │ │ │ │ download bandwidth instead of upload bandwidth. Note that setting a higher │ │ │ │ │ limit on a torrent then the global limit (settings_pack::upload_rate_limit) │ │ │ │ │ will not override the global rate limit. The torrent can never upload more than │ │ │ │ │ @@ -11527,15 +11988,15 @@ │ │ │ │ │ void set_max_uploads (int max_uploads) const; │ │ │ │ │ set_max_uploads() sets the maximum number of peers that's unchoked at the same │ │ │ │ │ time on this torrent. If you set this to -1, there will be no limit. This │ │ │ │ │ defaults to infinite. The primary setting controlling this is the global │ │ │ │ │ unchoke slots limit, set by unchoke_slots_limit in settings_pack. │ │ │ │ │ max_uploads() returns the current settings. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** max_connections() set_max_connections() ***** │ │ │ │ │ +***** set_max_connections() max_connections() ***** │ │ │ │ │ int max_connections () const; │ │ │ │ │ void set_max_connections (int max_connections) const; │ │ │ │ │ set_max_connections() sets the maximum number of connection this torrent will │ │ │ │ │ open. If all connections are used up, incoming connections may be refused or │ │ │ │ │ poor connections may be closed. This must be at least 2. The default is │ │ │ │ │ unlimited number of connections. If -1 is given to the function, it means │ │ │ │ │ unlimited. There is also a global limit of the number of connections, set by │ │ │ │ │ @@ -11587,17 +12048,17 @@ │ │ │ │ │ [report_issue] │ │ │ │ │ ***** rename_file() ***** │ │ │ │ │ void rename_file (file_index_t index, std::string const& new_name) const; │ │ │ │ │ Renames the file with the given index asynchronously. The rename operation is │ │ │ │ │ complete when either a file_renamed_alert or file_rename_failed_alert is │ │ │ │ │ posted. │ │ │ │ │ [report_issue] │ │ │ │ │ -***** info_hash() info_hashes() ***** │ │ │ │ │ -sha1_hash info_hash () const; │ │ │ │ │ +***** info_hashes() info_hash() ***** │ │ │ │ │ info_hash_t info_hashes () const; │ │ │ │ │ +sha1_hash info_hash () const; │ │ │ │ │ returns the info-hash(es) of the torrent. If this handle is to a torrent that │ │ │ │ │ hasn't loaded yet (for instance by being added) by a URL, the returned value is │ │ │ │ │ undefined. The info_hash() returns the SHA-1 info-hash for v1 torrents and a │ │ │ │ │ truncated hash for v2 torrents. For the full v2 info-hash, use info_hashes() │ │ │ │ │ instead. │ │ │ │ │ [report_issue] │ │ │ │ │ ***** operator!=() operator<() operator==() ***** │ │ │ │ │ @@ -11714,774 +12175,14 @@ │ │ │ │ │ is announced immediately. │ │ │ │ │ [report_issue] │ │ │ │ │ ****** hash_value() ****** │ │ │ │ │ Declared in "libtorrent/torrent_handle.hpp" │ │ │ │ │ std::size_t hash_value (torrent_handle const& h); │ │ │ │ │ for std::hash (and to support using this type in unordered_map etc.) │ │ │ │ │ [report_issue] │ │ │ │ │ -****** storage_error ****** │ │ │ │ │ -Declared in "libtorrent/error_code.hpp" │ │ │ │ │ -used by storage to return errors also includes which underlying file the error │ │ │ │ │ -happened on │ │ │ │ │ -struct storage_error │ │ │ │ │ -{ │ │ │ │ │ - explicit operator bool () const; │ │ │ │ │ - void file (file_index_t f); │ │ │ │ │ - file_index_t file () const; │ │ │ │ │ - │ │ │ │ │ - error_code ec; │ │ │ │ │ - operation_t operation; │ │ │ │ │ -}; │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** bool() ***** │ │ │ │ │ -explicit operator bool () const; │ │ │ │ │ -explicitly converts to true if this object represents an error, and false if it │ │ │ │ │ -does not. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** file() ***** │ │ │ │ │ -void file (file_index_t f); │ │ │ │ │ -file_index_t file () const; │ │ │ │ │ -set and query the index (in the torrent) of the file this error occurred on. │ │ │ │ │ -This may also have special values defined in torrent_status. │ │ │ │ │ -[report_issue] │ │ │ │ │ - ec │ │ │ │ │ - the error that occurred │ │ │ │ │ -[report_issue] │ │ │ │ │ - operation │ │ │ │ │ - A code from operation_t enum, indicating what kind of operation failed. │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** bdecode_category() ****** │ │ │ │ │ -Declared in "libtorrent/bdecode.hpp" │ │ │ │ │ -boost::system::error_category& bdecode_category (); │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** i2p_category() ****** │ │ │ │ │ -Declared in "libtorrent/i2p_stream.hpp" │ │ │ │ │ -boost::system::error_category& i2p_category (); │ │ │ │ │ -returns the error category for I2P errors │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** socks_category() ****** │ │ │ │ │ -Declared in "libtorrent/socks5_stream.hpp" │ │ │ │ │ -boost::system::error_category& socks_category (); │ │ │ │ │ -returns the error_category for SOCKS5 errors │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** pcp_category() ****** │ │ │ │ │ -Declared in "libtorrent/natpmp.hpp" │ │ │ │ │ -boost::system::error_category& pcp_category (); │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** upnp_category() ****** │ │ │ │ │ -Declared in "libtorrent/upnp.hpp" │ │ │ │ │ -boost::system::error_category& upnp_category (); │ │ │ │ │ -the boost.system error category for UPnP errors │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** libtorrent_category() ****** │ │ │ │ │ -Declared in "libtorrent/error_code.hpp" │ │ │ │ │ -boost::system::error_category& libtorrent_category (); │ │ │ │ │ -return the instance of the libtorrent_error_category which maps libtorrent │ │ │ │ │ -error codes to human readable error messages. │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** http_category() ****** │ │ │ │ │ -Declared in "libtorrent/error_code.hpp" │ │ │ │ │ -boost::system::error_category& http_category (); │ │ │ │ │ -returns the error_category for HTTP errors │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** gzip_category() ****** │ │ │ │ │ -Declared in "libtorrent/gzip.hpp" │ │ │ │ │ -boost::system::error_category& gzip_category (); │ │ │ │ │ -get the error_category for zip errors │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** enum error_code_enum ****** │ │ │ │ │ -Declared in "libtorrent/bdecode.hpp" │ │ │ │ │ - ___________________________________________________________________________ │ │ │ │ │ -|name__________|value|description___________________________________________| │ │ │ │ │ -|no_error______|0____|Not_an_error__________________________________________| │ │ │ │ │ -|expected_digit|1____|expected_digit_in_bencoded_string_____________________| │ │ │ │ │ -|expected_colon|2____|expected_colon_in_bencoded_string_____________________| │ │ │ │ │ -|unexpected_eof|3____|unexpected_end_of_file_in_bencoded_string_____________| │ │ │ │ │ -|expected_value|4 |expected value (list, dict, int or string) in bencoded| │ │ │ │ │ -|______________|_____|string________________________________________________| │ │ │ │ │ -|depth_exceeded|5____|bencoded_recursion_depth_limit_exceeded_______________| │ │ │ │ │ -|limit_exceeded|6____|bencoded_item_count_limit_exceeded____________________| │ │ │ │ │ -|overflow______|7____|integer_overflow______________________________________| │ │ │ │ │ -|error_code_max|8____|the_number_of_error_codes_____________________________| │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** enum i2p_error_code ****** │ │ │ │ │ -Declared in "libtorrent/i2p_stream.hpp" │ │ │ │ │ - _________________________________ │ │ │ │ │ -|name___________|value|description| │ │ │ │ │ -|no_error_______|0____| _________| │ │ │ │ │ -|parse_failed___|1____| _________| │ │ │ │ │ -|cant_reach_peer|2____| _________| │ │ │ │ │ -|i2p_error______|3____| _________| │ │ │ │ │ -|invalid_key____|4____| _________| │ │ │ │ │ -|invalid_id_____|5____| _________| │ │ │ │ │ -|timeout________|6____| _________| │ │ │ │ │ -|key_not_found__|7____| _________| │ │ │ │ │ -|duplicated_id__|8____| _________| │ │ │ │ │ -|num_errors_____|9____| _________| │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** enum socks_error_code ****** │ │ │ │ │ -Declared in "libtorrent/socks5_stream.hpp" │ │ │ │ │ - ____________________________________________________ │ │ │ │ │ -|name______________________________|value|description| │ │ │ │ │ -|no_error__________________________|0____| _________| │ │ │ │ │ -|unsupported_version_______________|1____| _________| │ │ │ │ │ -|unsupported_authentication_method_|2____| _________| │ │ │ │ │ -|unsupported_authentication_version|3____| _________| │ │ │ │ │ -|authentication_error______________|4____| _________| │ │ │ │ │ -|username_required_________________|5____| _________| │ │ │ │ │ -|general_failure___________________|6____| _________| │ │ │ │ │ -|command_not_supported_____________|7____| _________| │ │ │ │ │ -|no_identd_________________________|8____| _________| │ │ │ │ │ -|identd_error______________________|9____| _________| │ │ │ │ │ -|num_errors________________________|10___| _________| │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** enum pcp_errors ****** │ │ │ │ │ -Declared in "libtorrent/natpmp.hpp" │ │ │ │ │ - _____________________________________________ │ │ │ │ │ -|name_______________________|value|description| │ │ │ │ │ -|pcp_success________________|0____| _________| │ │ │ │ │ -|pcp_unsupp_version_________|1____| _________| │ │ │ │ │ -|pcp_not_authorized_________|2____| _________| │ │ │ │ │ -|pcp_malformed_request______|3____| _________| │ │ │ │ │ -|pcp_unsupp_opcode__________|4____| _________| │ │ │ │ │ -|pcp_unsupp_option__________|5____| _________| │ │ │ │ │ -|pcp_malformed_option_______|6____| _________| │ │ │ │ │ -|pcp_network_failure________|7____| _________| │ │ │ │ │ -|pcp_no_resources___________|8____| _________| │ │ │ │ │ -|pcp_unsupp_protocol________|9____| _________| │ │ │ │ │ -|pcp_user_ex_quota__________|10___| _________| │ │ │ │ │ -|pcp_cannot_provide_external|11___| _________| │ │ │ │ │ -|pcp_address_mismatch_______|12___| _________| │ │ │ │ │ -|pcp_excessive_remote_peers_|13___| _________| │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** enum error_code_enum ****** │ │ │ │ │ -Declared in "libtorrent/upnp.hpp" │ │ │ │ │ - _____________________________________________________________________________ │ │ │ │ │ -|name______________________________|value|description_________________________| │ │ │ │ │ -|no_error__________________________|0____|No_error____________________________| │ │ │ │ │ -|invalid_argument |402 |One of the arguments in the request | │ │ │ │ │ -|__________________________________|_____|is_invalid__________________________| │ │ │ │ │ -|action_failed_____________________|501__|The_request_failed__________________| │ │ │ │ │ -|value_not_in_array |714 |The specified value does not exist | │ │ │ │ │ -|__________________________________|_____|in_the_array________________________| │ │ │ │ │ -| | |The source IP address cannot be | │ │ │ │ │ -|source_ip_cannot_be_wildcarded |715 |wild-carded, but must be fully | │ │ │ │ │ -|__________________________________|_____|specified___________________________| │ │ │ │ │ -|external_port_cannot_be_wildcarded|716 |The external port cannot be a | │ │ │ │ │ -|__________________________________|_____|wildcard,_but_must_be_specified_____| │ │ │ │ │ -| | |The port mapping entry specified | │ │ │ │ │ -|port_mapping_conflict |718 |conflicts with a mapping assigned | │ │ │ │ │ -|__________________________________|_____|previously_to_another_client________| │ │ │ │ │ -|internal_port_must_match_external |724 |Internal and external port value | │ │ │ │ │ -|__________________________________|_____|must_be_the_same____________________| │ │ │ │ │ -| | |The NAT implementation only supports| │ │ │ │ │ -|only_permanent_leases_supported |725 |permanent lease times on port | │ │ │ │ │ -|__________________________________|_____|mappings____________________________| │ │ │ │ │ -| | |RemoteHost must be a wildcard and | │ │ │ │ │ -|remote_host_must_be_wildcard |726 |cannot be a specific IP address or | │ │ │ │ │ -|__________________________________|_____|DNS_name____________________________| │ │ │ │ │ -|external_port_must_be_wildcard |727 |ExternalPort must be a wildcard and | │ │ │ │ │ -|__________________________________|_____|cannot_be_a_specific_port___________| │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** enum error_code_enum ****** │ │ │ │ │ -Declared in "libtorrent/error_code.hpp" │ │ │ │ │ - _____________________________________________________________________________ │ │ │ │ │ -|name________________________________|value|description_______________________| │ │ │ │ │ -|no_error____________________________|0____|Not_an_error______________________| │ │ │ │ │ -|file_collision |1 |Two torrents has files which end | │ │ │ │ │ -|____________________________________|_____|up_overwriting_each_other_________| │ │ │ │ │ -|failed_hash_check |2 |A piece did not match its piece | │ │ │ │ │ -|____________________________________|_____|hash______________________________| │ │ │ │ │ -| | |The .torrent file does not contain| │ │ │ │ │ -|torrent_is_no_dict |3 |a bencoded dictionary at its top | │ │ │ │ │ -|____________________________________|_____|level_____________________________| │ │ │ │ │ -|torrent_missing_info |4 |The .torrent file does not have an| │ │ │ │ │ -|____________________________________|_____|info_dictionary___________________| │ │ │ │ │ -|torrent_info_no_dict |5 |The .torrent file's info entry is | │ │ │ │ │ -|____________________________________|_____|not_a_dictionary__________________| │ │ │ │ │ -|torrent_missing_piece_length |6 |The .torrent file does not have a | │ │ │ │ │ -|____________________________________|_____|piece_length_entry________________| │ │ │ │ │ -|torrent_missing_name |7 |The .torrent file does not have a | │ │ │ │ │ -|____________________________________|_____|name_entry________________________| │ │ │ │ │ -|torrent_invalid_name |8 |The .torrent file's name entry is | │ │ │ │ │ -|____________________________________|_____|invalid___________________________| │ │ │ │ │ -| | |The length of a file, or of the | │ │ │ │ │ -|torrent_invalid_length |9 |whole .torrent file is invalid. | │ │ │ │ │ -|____________________________________|_____|Either_negative_or_not_an_integer_| │ │ │ │ │ -|torrent_file_parse_failed |10 |Failed to parse a file entry in | │ │ │ │ │ -|____________________________________|_____|the_.torrent______________________| │ │ │ │ │ -|torrent_missing_pieces |11 |The pieces field is missing or | │ │ │ │ │ -|____________________________________|_____|invalid_in_the_.torrent_file______| │ │ │ │ │ -|torrent_invalid_hashes |12 |The pieces string has incorrect | │ │ │ │ │ -|____________________________________|_____|length____________________________| │ │ │ │ │ -|too_many_pieces_in_torrent |13 |The .torrent file has more pieces | │ │ │ │ │ -|____________________________________|_____|than_is_supported_by_libtorrent___| │ │ │ │ │ -| | |The metadata (.torrent file) that | │ │ │ │ │ -|invalid_swarm_metadata |14 |was received from the swarm | │ │ │ │ │ -| | |matched the info-hash, but failed | │ │ │ │ │ -|____________________________________|_____|to_be_parsed______________________| │ │ │ │ │ -|invalid_bencoding |15 |The file or buffer is not | │ │ │ │ │ -|____________________________________|_____|correctly_bencoded________________| │ │ │ │ │ -|no_files_in_torrent |16 |The .torrent file does not contain| │ │ │ │ │ -|____________________________________|_____|any_files_________________________| │ │ │ │ │ -|invalid_escaped_string |17 |The string was not properly url- | │ │ │ │ │ -|____________________________________|_____|encoded_as_expected_______________| │ │ │ │ │ -|session_is_closing |18 |Operation is not permitted since | │ │ │ │ │ -|____________________________________|_____|the_session_is_shutting_down______| │ │ │ │ │ -| | |There's already a torrent with | │ │ │ │ │ -|duplicate_torrent |19 |that info-hash added to the | │ │ │ │ │ -|____________________________________|_____|session___________________________| │ │ │ │ │ -|invalid_torrent_handle |20 |The supplied torrent_handle is not| │ │ │ │ │ -|____________________________________|_____|referring_to_a_valid_torrent______| │ │ │ │ │ -|invalid_entry_type |21 |The type requested from the entry | │ │ │ │ │ -|____________________________________|_____|did_not_match_its_type____________| │ │ │ │ │ -|missing_info_hash_in_uri |22 |The specified URI does not contain| │ │ │ │ │ -|____________________________________|_____|a_valid_info-hash_________________| │ │ │ │ │ -| | |One of the files in the torrent | │ │ │ │ │ -|file_too_short |23 |was unexpectedly small. This might| │ │ │ │ │ -| | |be caused by files being changed | │ │ │ │ │ -|____________________________________|_____|by_an_external_process____________| │ │ │ │ │ -| | |The URL used an unknown protocol. | │ │ │ │ │ -| | |Currently http and https (if built| │ │ │ │ │ -|unsupported_url_protocol |24 |with openssl support) are | │ │ │ │ │ -| | |recognized. For trackers udp is | │ │ │ │ │ -|____________________________________|_____|recognized_as_well._______________| │ │ │ │ │ -|url_parse_error |25 |The URL did not conform to URL | │ │ │ │ │ -|____________________________________|_____|syntax_and_failed_to_be_parsed____| │ │ │ │ │ -|peer_sent_empty_piece |26 |The peer sent a piece message of | │ │ │ │ │ -|____________________________________|_____|length_0__________________________| │ │ │ │ │ -|parse_failed |27 |A bencoded structure was corrupt | │ │ │ │ │ -|____________________________________|_____|and_failed_to_be_parsed___________| │ │ │ │ │ -|invalid_file_tag |28 |The fast resume file was missing | │ │ │ │ │ -|____________________________________|_____|or_had_an_invalid_file_version_tag| │ │ │ │ │ -|missing_info_hash |29 |The fast resume file was missing | │ │ │ │ │ -|____________________________________|_____|or_had_an_invalid_info-hash_______| │ │ │ │ │ -|mismatching_info_hash |30 |The info-hash did not match the | │ │ │ │ │ -|____________________________________|_____|torrent___________________________| │ │ │ │ │ -|invalid_hostname |31 |The URL contained an invalid | │ │ │ │ │ -|____________________________________|_____|hostname__________________________| │ │ │ │ │ -|invalid_port________________________|32___|The_URL_had_an_invalid_port_______| │ │ │ │ │ -| | |The port is blocked by the port- | │ │ │ │ │ -|port_blocked |33 |filter, and prevented the | │ │ │ │ │ -|____________________________________|_____|connection________________________| │ │ │ │ │ -|expected_close_bracket_in_address |34 |The IPv6 address was expected to | │ │ │ │ │ -|____________________________________|_____|end_with_"]"______________________| │ │ │ │ │ -| | |The torrent is being destructed, | │ │ │ │ │ -|destructing_torrent |35 |preventing the operation to | │ │ │ │ │ -|____________________________________|_____|succeed___________________________| │ │ │ │ │ -|timed_out___________________________|36___|The_connection_timed_out__________| │ │ │ │ │ -| | |The peer is upload only, and we | │ │ │ │ │ -|upload_upload_connection |37 |are upload only. There's no point | │ │ │ │ │ -|____________________________________|_____|in_keeping_the_connection_________| │ │ │ │ │ -| | |The peer is upload only, and we're| │ │ │ │ │ -|uninteresting_upload_peer |38 |not interested in it. There's no | │ │ │ │ │ -|____________________________________|_____|point_in_keeping_the_connection___| │ │ │ │ │ -|invalid_info_hash___________________|39___|The_peer_sent_an_unknown_info-hash| │ │ │ │ │ -|torrent_paused |40 |The torrent is paused, preventing | │ │ │ │ │ -|____________________________________|_____|the_operation_from_succeeding_____| │ │ │ │ │ -| | |The peer sent an invalid have | │ │ │ │ │ -|invalid_have |41 |message, either wrong size or | │ │ │ │ │ -| | |referring to a piece that doesn't | │ │ │ │ │ -|____________________________________|_____|exist_in_the_torrent______________| │ │ │ │ │ -|invalid_bitfield_size |42 |The bitfield message had the | │ │ │ │ │ -|____________________________________|_____|incorrect_size____________________| │ │ │ │ │ -| | |The peer kept requesting pieces | │ │ │ │ │ -|too_many_requests_when_choked |43 |after it was choked, possible | │ │ │ │ │ -|____________________________________|_____|abuse_attempt.____________________| │ │ │ │ │ -| | |The peer sent a piece message that| │ │ │ │ │ -|invalid_piece |44 |does not correspond to a piece | │ │ │ │ │ -|____________________________________|_____|request_sent_by_the_client________| │ │ │ │ │ -|no_memory___________________________|45___|memory_allocation_failed__________| │ │ │ │ │ -|torrent_aborted |46 |The torrent is aborted, preventing| │ │ │ │ │ -|____________________________________|_____|the_operation_to_succeed__________| │ │ │ │ │ -|self_connection |47 |The peer is a connection to | │ │ │ │ │ -|____________________________________|_____|ourself,_no_point_in_keeping_it___| │ │ │ │ │ -| | |The peer sent a piece message with| │ │ │ │ │ -|invalid_piece_size |48 |invalid size, either negative or | │ │ │ │ │ -|____________________________________|_____|greater_than_one_block____________| │ │ │ │ │ -| | |The peer has not been interesting | │ │ │ │ │ -|timed_out_no_interest |49 |or interested in us for too long, | │ │ │ │ │ -|____________________________________|_____|no_point_in_keeping_it_around_____| │ │ │ │ │ -|timed_out_inactivity |50 |The peer has not said anything in | │ │ │ │ │ -|____________________________________|_____|a_long_time,_possibly_dead________| │ │ │ │ │ -| | |The peer did not send a handshake | │ │ │ │ │ -|timed_out_no_handshake |51 |within a reasonable amount of | │ │ │ │ │ -| | |time, it might not be a bittorrent| │ │ │ │ │ -|____________________________________|_____|peer______________________________| │ │ │ │ │ -| | |The peer has been unchoked for too| │ │ │ │ │ -|timed_out_no_request |52 |long without requesting any data. | │ │ │ │ │ -| | |It might be lying about its | │ │ │ │ │ -|____________________________________|_____|interest_in_us____________________| │ │ │ │ │ -|invalid_choke |53 |The peer sent an invalid choke | │ │ │ │ │ -|____________________________________|_____|message___________________________| │ │ │ │ │ -|invalid_unchoke |54 |The peer send an invalid unchoke | │ │ │ │ │ -|____________________________________|_____|message___________________________| │ │ │ │ │ -|invalid_interested |55 |The peer sent an invalid | │ │ │ │ │ -|____________________________________|_____|interested_message________________| │ │ │ │ │ -|invalid_not_interested |56 |The peer sent an invalid not- | │ │ │ │ │ -|____________________________________|_____|interested_message________________| │ │ │ │ │ -|invalid_request |57 |The peer sent an invalid piece | │ │ │ │ │ -|____________________________________|_____|request_message___________________| │ │ │ │ │ -| | |The peer sent an invalid hash-list| │ │ │ │ │ -|invalid_hash_list |58 |message (this is part of the | │ │ │ │ │ -|____________________________________|_____|merkle-torrent_extension)_________| │ │ │ │ │ -| | |The peer sent an invalid hash- | │ │ │ │ │ -|invalid_hash_piece |59 |piece message (this is part of the| │ │ │ │ │ -|____________________________________|_____|merkle-torrent_extension)_________| │ │ │ │ │ -|invalid_cancel |60 |The peer sent an invalid cancel | │ │ │ │ │ -|____________________________________|_____|message___________________________| │ │ │ │ │ -|invalid_dht_port |61 |The peer sent an invalid DHT port-| │ │ │ │ │ -|____________________________________|_____|message___________________________| │ │ │ │ │ -|invalid_suggest |62 |The peer sent an invalid suggest | │ │ │ │ │ -|____________________________________|_____|piece-message_____________________| │ │ │ │ │ -|invalid_have_all |63 |The peer sent an invalid have all-| │ │ │ │ │ -|____________________________________|_____|message___________________________| │ │ │ │ │ -|invalid_have_none |64 |The peer sent an invalid have | │ │ │ │ │ -|____________________________________|_____|none-message______________________| │ │ │ │ │ -|invalid_reject |65 |The peer sent an invalid reject | │ │ │ │ │ -|____________________________________|_____|message___________________________| │ │ │ │ │ -|invalid_allow_fast |66 |The peer sent an invalid allow | │ │ │ │ │ -|____________________________________|_____|fast-message______________________| │ │ │ │ │ -|invalid_extended |67 |The peer sent an invalid extension| │ │ │ │ │ -|____________________________________|_____|message_ID________________________| │ │ │ │ │ -|invalid_message |68 |The peer sent an invalid message | │ │ │ │ │ -|____________________________________|_____|ID________________________________| │ │ │ │ │ -|sync_hash_not_found |69 |The synchronization hash was not | │ │ │ │ │ -|____________________________________|_____|found_in_the_encrypted_handshake__| │ │ │ │ │ -|invalid_encryption_constant |70 |The encryption constant in the | │ │ │ │ │ -|____________________________________|_____|handshake_is_invalid______________| │ │ │ │ │ -|no_plaintext_mode |71 |The peer does not support plain | │ │ │ │ │ -|____________________________________|_____|text,_which_is_the_selected_mode__| │ │ │ │ │ -|no_rc4_mode |72 |The peer does not support RC4, | │ │ │ │ │ -|____________________________________|_____|which_is_the_selected_mode________| │ │ │ │ │ -| | |The peer does not support any of | │ │ │ │ │ -|unsupported_encryption_mode |73 |the encryption modes that the | │ │ │ │ │ -|____________________________________|_____|client_supports___________________| │ │ │ │ │ -| | |The peer selected an encryption | │ │ │ │ │ -|unsupported_encryption_mode_selected|74 |mode that the client did not | │ │ │ │ │ -|____________________________________|_____|advertise_and_does_not_support____| │ │ │ │ │ -| | |The pad size used in the | │ │ │ │ │ -|invalid_pad_size |75 |encryption handshake is of invalid| │ │ │ │ │ -|____________________________________|_____|size______________________________| │ │ │ │ │ -|invalid_encrypt_handshake |76 |The encryption handshake is | │ │ │ │ │ -|____________________________________|_____|invalid___________________________| │ │ │ │ │ -| | |The client is set to not support | │ │ │ │ │ -|no_incoming_encrypted |77 |incoming encrypted connections and| │ │ │ │ │ -|____________________________________|_____|this_is_an_encrypted_connection___| │ │ │ │ │ -| | |The client is set to not support | │ │ │ │ │ -|no_incoming_regular |78 |incoming regular bittorrent | │ │ │ │ │ -| | |connections, and this is a regular| │ │ │ │ │ -|____________________________________|_____|connection________________________| │ │ │ │ │ -|duplicate_peer_id |79 |The client is already connected to| │ │ │ │ │ -|____________________________________|_____|this_peer-ID______________________| │ │ │ │ │ -|torrent_removed_____________________|80___|Torrent_was_removed_______________| │ │ │ │ │ -|packet_too_large |81 |The packet size exceeded the upper| │ │ │ │ │ -|____________________________________|_____|sanity_check-limit________________| │ │ │ │ │ -|reserved____________________________|82___| ________________________________| │ │ │ │ │ -|http_error |83 |The web server responded with an | │ │ │ │ │ -|____________________________________|_____|error_____________________________| │ │ │ │ │ -|missing_location |84 |The web server response is missing| │ │ │ │ │ -|____________________________________|_____|a_location_header_________________| │ │ │ │ │ -| | |The web seed redirected to a path | │ │ │ │ │ -|invalid_redirection |85 |that no longer matches the | │ │ │ │ │ -|____________________________________|_____|.torrent_directory_structure______| │ │ │ │ │ -|redirecting |86 |The connection was closed because | │ │ │ │ │ -|____________________________________|_____|it_redirected_to_a_different_URL__| │ │ │ │ │ -|invalid_range_______________________|87___|The_HTTP_range_header_is_invalid__| │ │ │ │ │ -|no_content_length |88 |The HTTP response did not have a | │ │ │ │ │ -|____________________________________|_____|content_length____________________| │ │ │ │ │ -|banned_by_ip_filter_________________|89___|The_IP_is_blocked_by_the_IP_filter| │ │ │ │ │ -|too_many_connections________________|90___|At_the_connection_limit___________| │ │ │ │ │ -|peer_banned_________________________|91___|The_peer_is_marked_as_banned______| │ │ │ │ │ -|stopping_torrent |92 |The torrent is stopping, causing | │ │ │ │ │ -|____________________________________|_____|the_operation_to_fail_____________| │ │ │ │ │ -|too_many_corrupt_pieces |93 |The peer has sent too many corrupt| │ │ │ │ │ -|____________________________________|_____|pieces_and_is_banned______________| │ │ │ │ │ -|torrent_not_ready |94 |The torrent is not ready to | │ │ │ │ │ -|____________________________________|_____|receive_peers_____________________| │ │ │ │ │ -|peer_not_constructed |95 |The peer is not completely | │ │ │ │ │ -|____________________________________|_____|constructed_yet___________________| │ │ │ │ │ -|session_closing |96 |The session is closing, causing | │ │ │ │ │ -|____________________________________|_____|the_operation_to_fail_____________| │ │ │ │ │ -| | |The peer was disconnected in order| │ │ │ │ │ -|optimistic_disconnect |97 |to leave room for a potentially | │ │ │ │ │ -|____________________________________|_____|better_peer_______________________| │ │ │ │ │ -|torrent_finished____________________|98___|The_torrent_is_finished___________| │ │ │ │ │ -|no_router___________________________|99___|No_UPnP_router_found______________| │ │ │ │ │ -|metadata_too_large |100 |The metadata message says the | │ │ │ │ │ -|____________________________________|_____|metadata_exceeds_the_limit________| │ │ │ │ │ -|invalid_metadata_request |101 |The peer sent an invalid metadata | │ │ │ │ │ -|____________________________________|_____|request_message___________________| │ │ │ │ │ -|invalid_metadata_size |102 |The peer advertised an invalid | │ │ │ │ │ -|____________________________________|_____|metadata_size_____________________| │ │ │ │ │ -|invalid_metadata_offset |103 |The peer sent a message with an | │ │ │ │ │ -|____________________________________|_____|invalid_metadata_offset___________| │ │ │ │ │ -|invalid_metadata_message |104 |The peer sent an invalid metadata | │ │ │ │ │ -|____________________________________|_____|message___________________________| │ │ │ │ │ -|pex_message_too_large |105 |The peer sent a peer exchange | │ │ │ │ │ -|____________________________________|_____|message_that_was_too_large________| │ │ │ │ │ -|invalid_pex_message |106 |The peer sent an invalid peer | │ │ │ │ │ -|____________________________________|_____|exchange_message__________________| │ │ │ │ │ -|invalid_lt_tracker_message |107 |The peer sent an invalid tracker | │ │ │ │ │ -|____________________________________|_____|exchange_message__________________| │ │ │ │ │ -| | |The peer sent an pex messages too | │ │ │ │ │ -|too_frequent_pex |108 |often. This is a possible attempt | │ │ │ │ │ -|____________________________________|_____|of_and_attack_____________________| │ │ │ │ │ -| | |The operation failed because it | │ │ │ │ │ -| | |requires the torrent to have the | │ │ │ │ │ -| | |metadata (.torrent file) and it | │ │ │ │ │ -|no_metadata |109 |doesn't have it yet. This happens | │ │ │ │ │ -| | |for magnet links before they have | │ │ │ │ │ -| | |downloaded the metadata, and also | │ │ │ │ │ -|____________________________________|_____|torrents_added_by_URL.____________| │ │ │ │ │ -| | |The peer sent an invalid dont_have| │ │ │ │ │ -| | |message. The don't have message is| │ │ │ │ │ -|invalid_dont_have |110 |an extension to allow peers to | │ │ │ │ │ -| | |advertise that the no longer has a| │ │ │ │ │ -|____________________________________|_____|piece_they_previously_had.________| │ │ │ │ │ -| | |The peer tried to connect to an | │ │ │ │ │ -|requires_ssl_connection |111 |SSL torrent without connecting | │ │ │ │ │ -|____________________________________|_____|over_SSL._________________________| │ │ │ │ │ -| | |The peer tried to connect to a | │ │ │ │ │ -|invalid_ssl_cert |112 |torrent with a certificate for a | │ │ │ │ │ -|____________________________________|_____|different_torrent.________________| │ │ │ │ │ -| | |the torrent is not an SSL torrent,| │ │ │ │ │ -|not_an_ssl_torrent |113 |and the operation requires an SSL | │ │ │ │ │ -|____________________________________|_____|torrent___________________________| │ │ │ │ │ -| | |peer was banned because its listen| │ │ │ │ │ -|banned_by_port_filter |114 |port is within a banned port | │ │ │ │ │ -| | |range, as specified by the | │ │ │ │ │ -|____________________________________|_____|port_filter.______________________| │ │ │ │ │ -|invalid_session_handle |115 |The session_handle is not | │ │ │ │ │ -|____________________________________|_____|referring_to_a_valid_session_impl_| │ │ │ │ │ -|invalid_listen_socket |116 |the listen socket associated with | │ │ │ │ │ -|____________________________________|_____|this_request_was_closed___________| │ │ │ │ │ -|invalid_hash_request________________|117__| ________________________________| │ │ │ │ │ -|invalid_hashes______________________|118__| ________________________________| │ │ │ │ │ -|invalid_hash_reject_________________|119__| ________________________________| │ │ │ │ │ -|deprecated_120______________________|120__| ________________________________| │ │ │ │ │ -|deprecated_121______________________|121__| ________________________________| │ │ │ │ │ -|deprecated_122______________________|122__| ________________________________| │ │ │ │ │ -|deprecated_123______________________|123__| ________________________________| │ │ │ │ │ -|deprecated_124______________________|124__| ________________________________| │ │ │ │ │ -|missing_file_sizes |130 |The resume data file is missing | │ │ │ │ │ -|____________________________________|_____|the_file_sizes_entry______________| │ │ │ │ │ -|no_files_in_resume_data |131 |The resume data file file sizes | │ │ │ │ │ -|____________________________________|_____|entry_is_empty____________________| │ │ │ │ │ -|missing_pieces |132 |The resume data file is missing | │ │ │ │ │ -|____________________________________|_____|the_pieces_and_slots_entry________| │ │ │ │ │ -| | |The number of files in the resume | │ │ │ │ │ -|mismatching_number_of_files |133 |data does not match the number of | │ │ │ │ │ -|____________________________________|_____|files_in_the_torrent______________| │ │ │ │ │ -| | |One of the files on disk has a | │ │ │ │ │ -|mismatching_file_size |134 |different size than in the fast | │ │ │ │ │ -|____________________________________|_____|resume_file_______________________| │ │ │ │ │ -| | |One of the files on disk has a | │ │ │ │ │ -|mismatching_file_timestamp |135 |different timestamp than in the | │ │ │ │ │ -|____________________________________|_____|fast_resume_file__________________| │ │ │ │ │ -|not_a_dictionary |136 |The resume data file is not a | │ │ │ │ │ -|____________________________________|_____|dictionary________________________| │ │ │ │ │ -|invalid_blocks_per_piece |137 |The blocks per piece entry is | │ │ │ │ │ -|____________________________________|_____|invalid_in_the_resume_data_file___| │ │ │ │ │ -| | |The resume file is missing the | │ │ │ │ │ -|missing_slots |138 |slots entry, which is required for| │ │ │ │ │ -| | |torrents with compact allocation. | │ │ │ │ │ -|____________________________________|_____|DEPRECATED________________________| │ │ │ │ │ -|too_many_slots |139 |The resume file contains more | │ │ │ │ │ -|____________________________________|_____|slots_than_the_torrent____________| │ │ │ │ │ -|invalid_slot_list |140 |The slot entry is invalid in the | │ │ │ │ │ -|____________________________________|_____|resume_data_______________________| │ │ │ │ │ -|invalid_piece_index |141 |One index in the slot list is | │ │ │ │ │ -|____________________________________|_____|invalid___________________________| │ │ │ │ │ -| | |The pieces on disk needs to be re-| │ │ │ │ │ -| | |ordered for the specified | │ │ │ │ │ -| | |allocation mode. This happens if | │ │ │ │ │ -|pieces_need_reorder |142 |you specify sparse allocation and | │ │ │ │ │ -| | |the files on disk are using | │ │ │ │ │ -| | |compact storage. The pieces needs | │ │ │ │ │ -| | |to be moved to their right | │ │ │ │ │ -|____________________________________|_____|position._DEPRECATED______________| │ │ │ │ │ -| | |this error is returned when asking| │ │ │ │ │ -| | |to save resume data and specifying| │ │ │ │ │ -|resume_data_not_modified |143 |the flag to only save when there's| │ │ │ │ │ -| | |anything new to save | │ │ │ │ │ -| | |(torrent_handle::only_if_modified)| │ │ │ │ │ -|____________________________________|_____|and_there_wasn't_anything_changed.| │ │ │ │ │ -|http_parse_error |150 |The HTTP header was not correctly | │ │ │ │ │ -|____________________________________|_____|formatted_________________________| │ │ │ │ │ -| | |The HTTP response was in the 300- | │ │ │ │ │ -|http_missing_location |151 |399 range but lacked a location | │ │ │ │ │ -|____________________________________|_____|header____________________________| │ │ │ │ │ -| | |The HTTP response was encoded with| │ │ │ │ │ -|http_failed_decompress |152 |gzip or deflate but decompressing | │ │ │ │ │ -|____________________________________|_____|it_failed_________________________| │ │ │ │ │ -|no_i2p_router |160 |The URL specified an i2p address, | │ │ │ │ │ -|____________________________________|_____|but_no_i2p_router_is_configured___| │ │ │ │ │ -|no_i2p_endpoint |161 |i2p acceptor is not available yet,| │ │ │ │ │ -|____________________________________|_____|can't_announce_without_endpoint___| │ │ │ │ │ -| | |The tracker URL doesn't support | │ │ │ │ │ -|scrape_not_available |170 |transforming it into a scrape URL.| │ │ │ │ │ -|____________________________________|_____|i.e._it_doesn't_contain_"announce.| │ │ │ │ │ -|invalid_tracker_response____________|171__|invalid_tracker_response__________| │ │ │ │ │ -|invalid_peer_dict |172 |invalid peer dictionary entry. Not| │ │ │ │ │ -|____________________________________|_____|a_dictionary______________________| │ │ │ │ │ -|tracker_failure_____________________|173__|tracker_sent_a_failure_message____| │ │ │ │ │ -|invalid_files_entry_________________|174__|missing_or_invalid_files_entry____| │ │ │ │ │ -|invalid_hash_entry__________________|175__|missing_or_invalid_hash_entry_____| │ │ │ │ │ -|invalid_peers_entry |176 |missing or invalid peers and | │ │ │ │ │ -|____________________________________|_____|peers6_entry______________________| │ │ │ │ │ -|invalid_tracker_response_length |177 |UDP tracker response packet has | │ │ │ │ │ -|____________________________________|_____|invalid_size______________________| │ │ │ │ │ -|invalid_tracker_transaction_id |178 |invalid transaction id in UDP | │ │ │ │ │ -|____________________________________|_____|tracker_response__________________| │ │ │ │ │ -|invalid_tracker_action |179 |invalid action field in UDP | │ │ │ │ │ -|____________________________________|_____|tracker_response__________________| │ │ │ │ │ -| | |skipped announce (because it's | │ │ │ │ │ -|announce_skipped |180 |assumed to be unreachable over the| │ │ │ │ │ -|____________________________________|_____|given_source_network_interface)___| │ │ │ │ │ -|no_entropy__________________________|200__|random_number_generation_failed___| │ │ │ │ │ -|ssrf_mitigation_____________________|201__|blocked_by_SSRF_mitigation________| │ │ │ │ │ -|blocked_by_idna |202 |blocked because IDNA host names | │ │ │ │ │ -|____________________________________|_____|are_banned________________________| │ │ │ │ │ -|torrent_unknown_version |210 |the torrent file has an unknown | │ │ │ │ │ -|____________________________________|_____|meta_version______________________| │ │ │ │ │ -|torrent_missing_file_tree |211 |the v2 torrent file has no file | │ │ │ │ │ -|____________________________________|_____|tree______________________________| │ │ │ │ │ -|torrent_missing_meta_version |212 |the torrent contains v2 keys but | │ │ │ │ │ -|____________________________________|_____|does_not_specify_meta_version_2___| │ │ │ │ │ -|torrent_inconsistent_files |213 |the v1 and v2 file metadata does | │ │ │ │ │ -|____________________________________|_____|not_match_________________________| │ │ │ │ │ -|torrent_missing_piece_layer |214 |one or more files are missing | │ │ │ │ │ -|____________________________________|_____|piece_layer_hashes________________| │ │ │ │ │ -|torrent_invalid_piece_layer |215 |a piece layer has the wrong size | │ │ │ │ │ -|____________________________________|_____|or_failed_hash_check______________| │ │ │ │ │ -|torrent_missing_pieces_root_________|216__|a_v2_file_entry_has_no_root_hash__| │ │ │ │ │ -|torrent_inconsistent_hashes |217 |the v1 and v2 hashes do not | │ │ │ │ │ -|____________________________________|_____|describe_the_same_data____________| │ │ │ │ │ -|torrent_invalid_pad_file |218 |a file in the v2 metadata has the | │ │ │ │ │ -|____________________________________|_____|pad_attribute_set_________________| │ │ │ │ │ -|error_code_max______________________|219__|the_number_of_error_codes_________| │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** enum http_errors ****** │ │ │ │ │ -Declared in "libtorrent/error_code.hpp" │ │ │ │ │ - _______________________________________ │ │ │ │ │ -|name_________________|value|description| │ │ │ │ │ -|cont_________________|100__| _________| │ │ │ │ │ -|ok___________________|200__| _________| │ │ │ │ │ -|created______________|201__| _________| │ │ │ │ │ -|accepted_____________|202__| _________| │ │ │ │ │ -|no_content___________|204__| _________| │ │ │ │ │ -|multiple_choices_____|300__| _________| │ │ │ │ │ -|moved_permanently____|301__| _________| │ │ │ │ │ -|moved_temporarily____|302__| _________| │ │ │ │ │ -|not_modified_________|304__| _________| │ │ │ │ │ -|bad_request__________|400__| _________| │ │ │ │ │ -|unauthorized_________|401__| _________| │ │ │ │ │ -|forbidden____________|403__| _________| │ │ │ │ │ -|not_found____________|404__| _________| │ │ │ │ │ -|internal_server_error|500__| _________| │ │ │ │ │ -|not_implemented______|501__| _________| │ │ │ │ │ -|bad_gateway__________|502__| _________| │ │ │ │ │ -|service_unavailable__|503__| _________| │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** enum error_code_enum ****** │ │ │ │ │ -Declared in "libtorrent/gzip.hpp" │ │ │ │ │ - _____________________________________________________________________________ │ │ │ │ │ -|name_______________________________|value|description________________________| │ │ │ │ │ -|no_error___________________________|0____|Not_an_error_______________________| │ │ │ │ │ -|invalid_gzip_header |1 |the supplied gzip buffer has | │ │ │ │ │ -|___________________________________|_____|invalid_header_____________________| │ │ │ │ │ -| | |the gzip buffer would inflate to | │ │ │ │ │ -|inflated_data_too_large |2 |more bytes than the specified | │ │ │ │ │ -|___________________________________|_____|maximum_size,_and_was_rejected.____| │ │ │ │ │ -|data_did_not_terminate |3 |available inflate data did not | │ │ │ │ │ -|___________________________________|_____|terminate__________________________| │ │ │ │ │ -|space_exhausted |4 |output space exhausted before | │ │ │ │ │ -|___________________________________|_____|completing_inflate_________________| │ │ │ │ │ -|invalid_block_type_________________|5____|invalid_block_type_(type_==_3)_____| │ │ │ │ │ -|invalid_stored_block_length |6 |stored block length did not match | │ │ │ │ │ -|___________________________________|_____|one's_complement___________________| │ │ │ │ │ -|too_many_length_or_distance_codes |7 |dynamic block code description: too| │ │ │ │ │ -|___________________________________|_____|many_length_or_distance_codes______| │ │ │ │ │ -|code_lengths_codes_incomplete |8 |dynamic block code description: | │ │ │ │ │ -|___________________________________|_____|code_lengths_codes_incomplete______| │ │ │ │ │ -|repeat_lengths_with_no_first_length|9 |dynamic block code description: | │ │ │ │ │ -|___________________________________|_____|repeat_lengths_with_no_first_length| │ │ │ │ │ -|repeat_more_than_specified_lengths |10 |dynamic block code description: | │ │ │ │ │ -|___________________________________|_____|repeat_more_than_specified_lengths_| │ │ │ │ │ -|invalid_literal_length_code_lengths|11 |dynamic block code description: | │ │ │ │ │ -|___________________________________|_____|invalid_literal/length_code_lengths| │ │ │ │ │ -|invalid_distance_code_lengths |12 |dynamic block code description: | │ │ │ │ │ -|___________________________________|_____|invalid_distance_code_lengths______| │ │ │ │ │ -|invalid_literal_code_in_block |13 |invalid literal/length or distance | │ │ │ │ │ -|___________________________________|_____|code_in_fixed_or_dynamic_block_____| │ │ │ │ │ -|distance_too_far_back_in_block |14 |distance is too far back in fixed | │ │ │ │ │ -|___________________________________|_____|or_dynamic_block___________________| │ │ │ │ │ -|unknown_gzip_error |15 |an unknown error occurred during | │ │ │ │ │ -|___________________________________|_____|gzip_inflation_____________________| │ │ │ │ │ -|error_code_max_____________________|16___|the_number_of_error_codes__________| │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** 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; │ │ │ │ │ -}; │ │ │ │ │ -[report_issue] │ │ │ │ │ - message │ │ │ │ │ - if this tracker has returned an error or warning message that message is │ │ │ │ │ - stored here │ │ │ │ │ -[report_issue] │ │ │ │ │ - last_error │ │ │ │ │ - if this tracker failed the last time it was contacted this error code │ │ │ │ │ - specifies what error occurred │ │ │ │ │ - [report_issue] │ │ │ │ │ - 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. │ │ │ │ │ -[report_issue] │ │ │ │ │ - fails │ │ │ │ │ - the number of times in a row we have failed to announce to this tracker. │ │ │ │ │ -[report_issue] │ │ │ │ │ - updating │ │ │ │ │ - true while we're waiting for a response from the tracker. │ │ │ │ │ -[report_issue] │ │ │ │ │ - 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. │ │ │ │ │ -[report_issue] │ │ │ │ │ - complete_sent │ │ │ │ │ - set to true when we send a event=completed. │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** 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 info_hashes; │ │ │ │ │ - bool enabled = true; │ │ │ │ │ -}; │ │ │ │ │ -[report_issue] │ │ │ │ │ - local_endpoint │ │ │ │ │ - the local endpoint of the listen interface associated with this endpoint │ │ │ │ │ -[report_issue] │ │ │ │ │ - info_hashes │ │ │ │ │ - info_hashes[0] is the v1 info hash (SHA1) info_hashes[1] is the v2 info │ │ │ │ │ - hash (truncated SHA-256) │ │ │ │ │ -[report_issue] │ │ │ │ │ - enabled │ │ │ │ │ - set to false to not announce from this endpoint │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** 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 │ │ │ │ │ -{ │ │ │ │ │ - explicit announce_entry (string_view u); │ │ │ │ │ - announce_entry (announce_entry const&); │ │ │ │ │ - announce_entry (); │ │ │ │ │ - announce_entry& operator= (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 endpoints; │ │ │ │ │ - std::uint8_t tier = 0; │ │ │ │ │ - std::uint8_t fail_limit = 0; │ │ │ │ │ - std::uint8_t source:4; │ │ │ │ │ - bool verified:1; │ │ │ │ │ -}; │ │ │ │ │ - [report_issue] │ │ │ │ │ -***** ~announce_entry() operator=() announce_entry() ***** │ │ │ │ │ -explicit announce_entry (string_view u); │ │ │ │ │ -announce_entry (announce_entry const&); │ │ │ │ │ -announce_entry (); │ │ │ │ │ -announce_entry& operator= (announce_entry const&) &; │ │ │ │ │ -~announce_entry (); │ │ │ │ │ -constructs a tracker announce entry with u as the URL. │ │ │ │ │ -[report_issue] │ │ │ │ │ -***** enum tracker_source ***** │ │ │ │ │ -Declared in "libtorrent/announce_entry.hpp" │ │ │ │ │ - ____________________________________________________________________________ │ │ │ │ │ -|name______________|value|description________________________________________| │ │ │ │ │ -|source_torrent____|1____|the_tracker_was_part_of_the_.torrent_file__________| │ │ │ │ │ -|source_client |2 |the tracker was added programmatically via the | │ │ │ │ │ -|__________________|_____|add_tracker()_function_____________________________| │ │ │ │ │ -|source_magnet_link|4____|the_tracker_was_part_of_a_magnet_link______________| │ │ │ │ │ -|source_tex |8 |the tracker was received from the swarm via tracker| │ │ │ │ │ -|__________________|_____|exchange___________________________________________| │ │ │ │ │ -[report_issue] │ │ │ │ │ - url │ │ │ │ │ - tracker URL as it appeared in the torrent file │ │ │ │ │ -[report_issue] │ │ │ │ │ - trackerid │ │ │ │ │ - the current &trackerid= argument passed to the tracker. this is optional │ │ │ │ │ - and is normally empty (in which case no trackerid is sent). │ │ │ │ │ -[report_issue] │ │ │ │ │ - endpoints │ │ │ │ │ - each local listen socket (endpoint) will announce to the tracker. This │ │ │ │ │ - list contains state per endpoint. │ │ │ │ │ -[report_issue] │ │ │ │ │ - tier │ │ │ │ │ - the tier this tracker belongs to │ │ │ │ │ -[report_issue] │ │ │ │ │ - fail_limit │ │ │ │ │ - the max number of failures to announce to this tracker in a row, before │ │ │ │ │ - this tracker is not used anymore. 0 means unlimited │ │ │ │ │ -[report_issue] │ │ │ │ │ - source │ │ │ │ │ - a bitmask specifying which sources we got this tracker from. │ │ │ │ │ -[report_issue] │ │ │ │ │ - verified │ │ │ │ │ - set to true the first time we receive a valid response from this tracker. │ │ │ │ │ -[report_issue] │ │ │ │ │ -****** dht_state ****** │ │ │ │ │ -Declared in "libtorrent/kademlia/dht_state.hpp" │ │ │ │ │ -This structure helps to store and load the state of the dht_tracker. At this │ │ │ │ │ -moment the library is only a dual stack implementation of the DHT. See BEP_32 │ │ │ │ │ -struct dht_state │ │ │ │ │ -{ │ │ │ │ │ - void clear (); │ │ │ │ │ - │ │ │ │ │ - node_ids_t nids; │ │ │ │ │ - std::vector nodes; │ │ │ │ │ - std::vector nodes6; │ │ │ │ │ -}; │ │ │ │ │ -[report_issue] │ │ │ │ │ - nodes │ │ │ │ │ - the bootstrap nodes saved from the buckets node │ │ │ │ │ -[report_issue] │ │ │ │ │ - nodes6 │ │ │ │ │ - the bootstrap nodes saved from the IPv6 buckets node │ │ │ │ │ -[report_issue] │ │ │ │ │ ****** dht_storage_counters ****** │ │ │ │ │ Declared in "libtorrent/kademlia/dht_storage.hpp" │ │ │ │ │ This structure hold the relevant counters for the storage │ │ │ │ │ struct dht_storage_counters │ │ │ │ │ { │ │ │ │ │ void reset (); │ │ │ │ │ │ │ │ │ │ @@ -12647,14 +12348,33 @@ │ │ │ │ │ For implementers: Use this functions for expire peers or items or any other │ │ │ │ │ storage cleanup. │ │ │ │ │ [report_issue] │ │ │ │ │ ***** counters() ***** │ │ │ │ │ virtual dht_storage_counters counters () const = 0; │ │ │ │ │ return stats counters for the store │ │ │ │ │ [report_issue] │ │ │ │ │ +****** dht_state ****** │ │ │ │ │ +Declared in "libtorrent/kademlia/dht_state.hpp" │ │ │ │ │ +This structure helps to store and load the state of the dht_tracker. At this │ │ │ │ │ +moment the library is only a dual stack implementation of the DHT. See BEP_32 │ │ │ │ │ +struct dht_state │ │ │ │ │ +{ │ │ │ │ │ + void clear (); │ │ │ │ │ + │ │ │ │ │ + node_ids_t nids; │ │ │ │ │ + std::vector nodes; │ │ │ │ │ + std::vector nodes6; │ │ │ │ │ +}; │ │ │ │ │ +[report_issue] │ │ │ │ │ + nodes │ │ │ │ │ + the bootstrap nodes saved from the buckets node │ │ │ │ │ +[report_issue] │ │ │ │ │ + nodes6 │ │ │ │ │ + the bootstrap nodes saved from the IPv6 buckets node │ │ │ │ │ +[report_issue] │ │ │ │ │ ****** sign_mutable_item() ****** │ │ │ │ │ Declared in "libtorrent/kademlia/item.hpp" │ │ │ │ │ signature sign_mutable_item ( │ │ │ │ │ span v │ │ │ │ │ , span salt │ │ │ │ │ , sequence_number seq │ │ │ │ │ , public_key const& pk │ │ │ │ │ @@ -12680,62 +12400,62 @@ │ │ │ │ │ implied_port │ │ │ │ │ announce to DHT with the implied-port flag set. This tells the network to │ │ │ │ │ use your source UDP port as your listen port, rather than the one │ │ │ │ │ specified in the message. This may improve the chances of traversing NATs │ │ │ │ │ when using uTP. │ │ │ │ │ ssl_torrent │ │ │ │ │ Specify the port number for the SSL listen socket in the DHT announce. │ │ │ │ │ + [report_issue] │ │ │ │ │ +****** write_resume_data_buf() write_resume_data() ****** │ │ │ │ │ +Declared in "libtorrent/write_resume_data.hpp" │ │ │ │ │ +entry write_resume_data (add_torrent_params const& atp); │ │ │ │ │ +std::vector write_resume_data_buf (add_torrent_params const& atp); │ │ │ │ │ +this function turns the resume data in an add_torrent_params object into a │ │ │ │ │ +bencoded structure │ │ │ │ │ + [report_issue] │ │ │ │ │ +****** write_torrent_file_buf() write_torrent_file() ****** │ │ │ │ │ +Declared in "libtorrent/write_resume_data.hpp" │ │ │ │ │ +std::vector write_torrent_file_buf (add_torrent_params const& atp │ │ │ │ │ + , write_torrent_flags_t flags); │ │ │ │ │ +entry write_torrent_file (add_torrent_params const& atp); │ │ │ │ │ +entry write_torrent_file (add_torrent_params const& atp, write_torrent_flags_t │ │ │ │ │ +flags); │ │ │ │ │ +writes only the fields to create a .torrent file. This function may fail with a │ │ │ │ │ +std::system_error exception if: │ │ │ │ │ + * The add_torrent_params object passed to this function does not contain │ │ │ │ │ + the info dictionary (the ti field) │ │ │ │ │ + * The piece layers are not complete for all files that need them │ │ │ │ │ +The write_torrent_file_buf() overload returns the torrent file in bencoded │ │ │ │ │ +buffer form. This overload may be faster at the expense of lost flexibility to │ │ │ │ │ +add custom fields. │ │ │ │ │ [report_issue] │ │ │ │ │ ****** read_resume_data() ****** │ │ │ │ │ Declared in "libtorrent/read_resume_data.hpp" │ │ │ │ │ add_torrent_params read_resume_data (bdecode_node const& rd │ │ │ │ │ - , int piece_limit = 0x200000); │ │ │ │ │ -add_torrent_params read_resume_data (span buffer │ │ │ │ │ - , load_torrent_limits const& cfg = {}); │ │ │ │ │ -add_torrent_params read_resume_data (bdecode_node const& rd │ │ │ │ │ , error_code& ec, int piece_limit = 0x200000); │ │ │ │ │ add_torrent_params read_resume_data (span buffer │ │ │ │ │ , error_code& ec, load_torrent_limits const& cfg = {}); │ │ │ │ │ +add_torrent_params read_resume_data (span buffer │ │ │ │ │ + , load_torrent_limits const& cfg = {}); │ │ │ │ │ +add_torrent_params read_resume_data (bdecode_node const& rd │ │ │ │ │ + , int piece_limit = 0x200000); │ │ │ │ │ these functions are used to parse resume data and populate the appropriate │ │ │ │ │ fields in an add_torrent_params object. This object can then be used to add the │ │ │ │ │ actual torrent_info object to and pass to session::add_torrent() or session:: │ │ │ │ │ async_add_torrent(). │ │ │ │ │ If the client wants to override any field that was loaded from the resume data, │ │ │ │ │ e.g. save_path, those fields must be changed after loading resume data but │ │ │ │ │ before adding the torrent. │ │ │ │ │ The piece_limit parameter determines the largest number of pieces allowed in │ │ │ │ │ the torrent that may be loaded as part of the resume data, if it contains an │ │ │ │ │ info field. The overloads that take a flat buffer are instead configured with │ │ │ │ │ limits on torrent sizes via load_torrent limits. │ │ │ │ │ In order to support large torrents, it may also be necessary to raise the │ │ │ │ │ settings_pack::max_piece_count setting and pass a higher limit to calls to │ │ │ │ │ torrent_info::parse_info_section(). │ │ │ │ │ - [report_issue] │ │ │ │ │ -****** write_resume_data() write_resume_data_buf() ****** │ │ │ │ │ -Declared in "libtorrent/write_resume_data.hpp" │ │ │ │ │ -std::vector write_resume_data_buf (add_torrent_params const& atp); │ │ │ │ │ -entry write_resume_data (add_torrent_params const& atp); │ │ │ │ │ -this function turns the resume data in an add_torrent_params object into a │ │ │ │ │ -bencoded structure │ │ │ │ │ - [report_issue] │ │ │ │ │ -****** write_torrent_file_buf() write_torrent_file() ****** │ │ │ │ │ -Declared in "libtorrent/write_resume_data.hpp" │ │ │ │ │ -entry write_torrent_file (add_torrent_params const& atp); │ │ │ │ │ -entry write_torrent_file (add_torrent_params const& atp, write_torrent_flags_t │ │ │ │ │ -flags); │ │ │ │ │ -std::vector write_torrent_file_buf (add_torrent_params const& atp │ │ │ │ │ - , write_torrent_flags_t flags); │ │ │ │ │ -writes only the fields to create a .torrent file. This function may fail with a │ │ │ │ │ -std::system_error exception if: │ │ │ │ │ - * The add_torrent_params object passed to this function does not contain │ │ │ │ │ - the info dictionary (the ti field) │ │ │ │ │ - * The piece layers are not complete for all files that need them │ │ │ │ │ -The write_torrent_file_buf() overload returns the torrent file in bencoded │ │ │ │ │ -buffer form. This overload may be faster at the expense of lost flexibility to │ │ │ │ │ -add custom fields. │ │ │ │ │ [report_issue] │ │ │ │ │ ****** write_torrent_flags_t ****** │ │ │ │ │ Declared in "libtorrent/write_resume_data.hpp" │ │ │ │ │ allow_missing_piece_layer │ │ │ │ │ this makes write_torrent_file() not fail when attempting to write a v2 │ │ │ │ │ torrent file that does not have all the piece layers │ │ │ │ │ no_http_seeds │ │ │ │ │ @@ -12774,18 +12494,18 @@ │ │ │ │ │ Declared in "libtorrent/kademlia/ed25519.hpp" │ │ │ │ │ bool ed25519_verify (signature const& sig │ │ │ │ │ , span msg, public_key const& pk); │ │ │ │ │ Verifies the signature on the given message using pk │ │ │ │ │ [report_issue] │ │ │ │ │ ****** ed25519_add_scalar() ****** │ │ │ │ │ Declared in "libtorrent/kademlia/ed25519.hpp" │ │ │ │ │ -secret_key ed25519_add_scalar (secret_key const& sk │ │ │ │ │ - , std::array const& scalar); │ │ │ │ │ public_key ed25519_add_scalar (public_key const& pk │ │ │ │ │ , std::array const& scalar); │ │ │ │ │ +secret_key ed25519_add_scalar (secret_key const& sk │ │ │ │ │ + , std::array const& scalar); │ │ │ │ │ Adds a scalar to the given key pair where scalar is a 32 byte buffer (possibly │ │ │ │ │ generated withed25519_create_seed), generating a new key pair. │ │ │ │ │ You can calculate the public key sum without knowing the private key and vice │ │ │ │ │ versa by passing in null for the key you don't know. This is useful when a │ │ │ │ │ third party (an authoritative server for example) needs to enforce randomness │ │ │ │ │ on a key pair while only knowing the public key of the other side. │ │ │ │ │ Warning: the last bit of the scalar is ignored - if comparing scalars make sure ├── python3-libtorrent_2.0.8-1_i386.deb │ ├── file list │ │ @@ -1,3 +1,3 @@ │ │ -rw-r--r-- 0 0 0 4 2022-10-23 15:10:21.000000 debian-binary │ │ -rw-r--r-- 0 0 0 1012 2022-10-23 15:10:21.000000 control.tar.xz │ │ --rw-r--r-- 0 0 0 701076 2022-10-23 15:10:21.000000 data.tar.xz │ │ +-rw-r--r-- 0 0 0 701072 2022-10-23 15:10:21.000000 data.tar.xz │ ├── control.tar.xz │ │ ├── control.tar │ │ │ ├── ./md5sums │ │ │ │ ├── ./md5sums │ │ │ │ │┄ Files differ │ ├── data.tar.xz │ │ ├── data.tar │ │ │ ├── file list │ │ │ │ @@ -1,15 +1,15 @@ │ │ │ │ drwxr-xr-x 0 root (0) root (0) 0 2022-10-23 15:10:21.000000 ./ │ │ │ │ drwxr-xr-x 0 root (0) root (0) 0 2022-10-23 15:10:21.000000 ./usr/ │ │ │ │ drwxr-xr-x 0 root (0) root (0) 0 2022-10-23 15:10:21.000000 ./usr/lib/ │ │ │ │ drwxr-xr-x 0 root (0) root (0) 0 2022-10-23 15:10:21.000000 ./usr/lib/python3/ │ │ │ │ drwxr-xr-x 0 root (0) root (0) 0 2022-10-23 15:10:21.000000 ./usr/lib/python3/dist-packages/ │ │ │ │ -rw-r--r-- 0 root (0) root (0) 4790780 2022-10-23 15:10:21.000000 ./usr/lib/python3/dist-packages/libtorrent.cpython-311-i386-linux-gnu.so │ │ │ │ drwxr-xr-x 0 root (0) root (0) 0 2022-10-23 15:10:21.000000 ./usr/lib/python3/dist-packages/libtorrent.egg-info/ │ │ │ │ --rw-r--r-- 0 root (0) root (0) 272 2022-10-23 15:10:21.000000 ./usr/lib/python3/dist-packages/libtorrent.egg-info/PKG-INFO │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 270 2022-10-23 15:10:21.000000 ./usr/lib/python3/dist-packages/libtorrent.egg-info/PKG-INFO │ │ │ │ -rw-r--r-- 0 root (0) root (0) 1 2022-10-23 15:10:21.000000 ./usr/lib/python3/dist-packages/libtorrent.egg-info/dependency_links.txt │ │ │ │ -rw-r--r-- 0 root (0) root (0) 17 2022-10-23 15:10:21.000000 ./usr/lib/python3/dist-packages/libtorrent.egg-info/top_level.txt │ │ │ │ drwxr-xr-x 0 root (0) root (0) 0 2022-10-23 15:10:21.000000 ./usr/share/ │ │ │ │ drwxr-xr-x 0 root (0) root (0) 0 2022-10-23 15:10:21.000000 ./usr/share/doc/ │ │ │ │ drwxr-xr-x 0 root (0) root (0) 0 2022-10-23 15:10:21.000000 ./usr/share/doc/python3-libtorrent/ │ │ │ │ -rw-r--r-- 0 root (0) root (0) 2045 2022-10-23 15:10:21.000000 ./usr/share/doc/python3-libtorrent/changelog.Debian.gz │ │ │ │ -rw-r--r-- 0 root (0) root (0) 32554 2022-10-23 11:28:40.000000 ./usr/share/doc/python3-libtorrent/changelog.gz │ │ │ ├── ./usr/lib/python3/dist-packages/libtorrent.egg-info/PKG-INFO │ │ │ │ @@ -2,10 +2,10 @@ │ │ │ │ Name: libtorrent │ │ │ │ Version: 2.0.8 │ │ │ │ Summary: Python bindings for libtorrent-rasterbar │ │ │ │ Home-page: http://libtorrent.org │ │ │ │ Author: Arvid Norberg │ │ │ │ Author-email: arvid@libtorrent.org │ │ │ │ License: BSD │ │ │ │ -Platform: Linux-x86_64 │ │ │ │ +Platform: Linux-i686 │ │ │ │ │ │ │ │ Python bindings for libtorrent-rasterbar