.. include:: header.rst

`home`__

__ reference.html

.. contents:: Table of contents
  :depth: 2
  :backlinks: none

.. raw:: html

	<a name="bdecode_node"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+bdecode_node&labels=documentation&body=Documentation+under+heading+%22class+bdecode_node%22+could+be+improved">report issue</a>]</span>



bdecode_node
------------

Declared in "`libtorrent/bdecode.hpp`__"


__ include/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`__.


__ reference-Bdecoding.html#non_owning()
__ reference-Torrent_Info.html#type_t


.. parsed-literal::
	

	struct bdecode_node
	{
	   **bdecode_node** () = default;
	   **bdecode_node** (bdecode\_node&&) noexcept;
	   bdecode_node& **operator=** (bdecode\_node&&) & = default;
	   bdecode_node& **operator=** (bdecode\_node const&) &;
	   **bdecode_node** (bdecode\_node const&);
	   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;
	   bdecode_node **list_at** (int i) const;
	   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 **dict_find_dict** (string\_view key) const;
	   bdecode_node **dict_find_list** (string\_view key) const;
	   bdecode_node **dict_find_string** (string\_view key) const;
	   std::pair<bdecode_node, bdecode_node> **dict_at_node** (int i) const;
	   std::int64_t **dict_find_int_value** (string\_view key
	      , std\:\:int64\_t default\_val = 0) const;
	   bdecode_node **dict_find_int** (string\_view key) const;
	   bdecode_node **dict_find** (string\_view key) const;
	   string_view **dict_find_string_value** (string\_view key
	      , string\_view default\_value = string\_view()) const;
	   int **dict_size** () const;
	   std::pair<string_view, bdecode_node> **dict_at** (int i) const;
	   std::int64_t **int_value** () const;
	   int **string_length** () const;
	   std::ptrdiff_t **string_offset** () const;
	   char const* **string_ptr** () const;
	   string_view **string_value** () 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,
	   };
	};

.. raw:: html

	<a name="bdecode_node()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:bdecode_node%3A%3A%5Bbdecode_node%28%29%5D&labels=documentation&body=Documentation+under+heading+%22bdecode_node%3A%3A%5Bbdecode_node%28%29%5D%22+could+be+improved">report issue</a>]</span>



bdecode_node()
..............

.. parsed-literal::
	
	**bdecode_node** () = default;
	

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



.. raw:: html

	<a name="operator=()"></a>
	<a name="bdecode_node()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:bdecode_node%3A%3A%5Boperator%3D%28%29+bdecode_node%28%29%5D&labels=documentation&body=Documentation+under+heading+%22bdecode_node%3A%3A%5Boperator%3D%28%29+bdecode_node%28%29%5D%22+could+be+improved">report issue</a>]</span>



operator=() bdecode_node()
..........................

.. parsed-literal::
	
	**bdecode_node** (bdecode\_node&&) noexcept;
	bdecode_node& **operator=** (bdecode\_node&&) & = default;
	bdecode_node& **operator=** (bdecode\_node const&) &;
	**bdecode_node** (bdecode\_node const&);
	

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



.. raw:: html

	<a name="type()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:bdecode_node%3A%3A%5Btype%28%29%5D&labels=documentation&body=Documentation+under+heading+%22bdecode_node%3A%3A%5Btype%28%29%5D%22+could+be+improved">report issue</a>]</span>



type()
......

.. parsed-literal::
	
	type_t **type** () const noexcept;
	

the type of this node. See `type_t`__.


__ reference-Torrent_Info.html#type_t

.. raw:: html

	<a name="bool()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:bdecode_node%3A%3A%5Bbool%28%29%5D&labels=documentation&body=Documentation+under+heading+%22bdecode_node%3A%3A%5Bbool%28%29%5D%22+could+be+improved">report issue</a>]</span>



bool()
......

.. parsed-literal::
	
	explicit operator **bool** () const noexcept;
	

returns true if `type()`__ != none_t.


__ reference-Plugins.html#type()

.. raw:: html

	<a name="non_owning()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:bdecode_node%3A%3A%5Bnon_owning%28%29%5D&labels=documentation&body=Documentation+under+heading+%22bdecode_node%3A%3A%5Bnon_owning%28%29%5D%22+could+be+improved">report issue</a>]</span>



non_owning()
............

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="data_offset()"></a>
	<a name="data_section()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:bdecode_node%3A%3A%5Bdata_offset%28%29+data_section%28%29%5D&labels=documentation&body=Documentation+under+heading+%22bdecode_node%3A%3A%5Bdata_offset%28%29+data_section%28%29%5D%22+could+be+improved">report issue</a>]</span>



data_offset() data_section()
............................

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="list_at()"></a>
	<a name="list_int_value_at()"></a>
	<a name="list_string_value_at()"></a>
	<a name="list_size()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:bdecode_node%3A%3A%5Blist_at%28%29+list_int_value_at%28%29+list_string_value_at%28%29+list_size%28%29%5D&labels=documentation&body=Documentation+under+heading+%22bdecode_node%3A%3A%5Blist_at%28%29+list_int_value_at%28%29+list_string_value_at%28%29+list_size%28%29%5D%22+could+be+improved">report issue</a>]</span>



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

.. parsed-literal::
	
	bdecode_node **list_at** (int i) const;
	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;
	

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.



.. raw:: html

	<a name="dict_at()"></a>
	<a name="dict_find_list()"></a>
	<a name="dict_find_dict()"></a>
	<a name="dict_find_string_value()"></a>
	<a name="dict_size()"></a>
	<a name="dict_find_int_value()"></a>
	<a name="dict_at_node()"></a>
	<a name="dict_find_string()"></a>
	<a name="dict_find_int()"></a>
	<a name="dict_find()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:bdecode_node%3A%3A%5Bdict_at%28%29+dict_find_list%28%29+dict_find_dict%28%29+dict_find_string_value%28%29+dict_size%28%29+dict_find_int_value%28%29+dict_at_node%28%29+dict_find_string%28%29+dict_find_int%28%29+dict_find%28%29%5D&labels=documentation&body=Documentation+under+heading+%22bdecode_node%3A%3A%5Bdict_at%28%29+dict_find_list%28%29+dict_find_dict%28%29+dict_find_string_value%28%29+dict_size%28%29+dict_find_int_value%28%29+dict_at_node%28%29+dict_find_string%28%29+dict_find_int%28%29+dict_find%28%29%5D%22+could+be+improved">report issue</a>]</span>



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

.. parsed-literal::
	
	bdecode_node **dict_find_dict** (string\_view key) const;
	bdecode_node **dict_find_list** (string\_view key) const;
	bdecode_node **dict_find_string** (string\_view key) const;
	std::pair<bdecode_node, bdecode_node> **dict_at_node** (int i) const;
	std::int64_t **dict_find_int_value** (string\_view key
	      , std\:\:int64\_t default\_val = 0) const;
	bdecode_node **dict_find_int** (string\_view key) const;
	bdecode_node **dict_find** (string\_view key) const;
	string_view **dict_find_string_value** (string\_view key
	      , string\_view default\_value = string\_view()) const;
	int **dict_size** () 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).


__ reference-Bdecoding.html#bdecode_node

.. raw:: html

	<a name="int_value()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:bdecode_node%3A%3A%5Bint_value%28%29%5D&labels=documentation&body=Documentation+under+heading+%22bdecode_node%3A%3A%5Bint_value%28%29%5D%22+could+be+improved">report issue</a>]</span>



int_value()
...........

.. parsed-literal::
	
	std::int64_t **int_value** () const;
	

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



.. raw:: html

	<a name="string_ptr()"></a>
	<a name="string_value()"></a>
	<a name="string_length()"></a>
	<a name="string_offset()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:bdecode_node%3A%3A%5Bstring_ptr%28%29+string_value%28%29+string_length%28%29+string_offset%28%29%5D&labels=documentation&body=Documentation+under+heading+%22bdecode_node%3A%3A%5Bstring_ptr%28%29+string_value%28%29+string_length%28%29+string_offset%28%29%5D%22+could+be+improved">report issue</a>]</span>



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

.. parsed-literal::
	
	int **string_length** () const;
	std::ptrdiff_t **string_offset** () const;
	char const* **string_ptr** () const;
	string_view **string_value** () 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.



.. raw:: html

	<a name="clear()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:bdecode_node%3A%3A%5Bclear%28%29%5D&labels=documentation&body=Documentation+under+heading+%22bdecode_node%3A%3A%5Bclear%28%29%5D%22+could+be+improved">report issue</a>]</span>



clear()
.......

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="swap()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:bdecode_node%3A%3A%5Bswap%28%29%5D&labels=documentation&body=Documentation+under+heading+%22bdecode_node%3A%3A%5Bswap%28%29%5D%22+could+be+improved">report issue</a>]</span>



swap()
......

.. parsed-literal::
	
	void **swap** (bdecode\_node& n);
	

Swap contents.



.. raw:: html

	<a name="reserve()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:bdecode_node%3A%3A%5Breserve%28%29%5D&labels=documentation&body=Documentation+under+heading+%22bdecode_node%3A%3A%5Breserve%28%29%5D%22+could+be+improved">report issue</a>]</span>



reserve()
.........

.. parsed-literal::
	
	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()`__.


__ reference-Bdecoding.html#bdecode()

.. raw:: html

	<a name="switch_underlying_buffer()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:bdecode_node%3A%3A%5Bswitch_underlying_buffer%28%29%5D&labels=documentation&body=Documentation+under+heading+%22bdecode_node%3A%3A%5Bswitch_underlying_buffer%28%29%5D%22+could+be+improved">report issue</a>]</span>



switch_underlying_buffer()
..........................

.. parsed-literal::
	
	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().



.. raw:: html

	<a name="has_soft_error()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:bdecode_node%3A%3A%5Bhas_soft_error%28%29%5D&labels=documentation&body=Documentation+under+heading+%22bdecode_node%3A%3A%5Bhas_soft_error%28%29%5D%22+could+be+improved">report issue</a>]</span>



has_soft_error()
................

.. parsed-literal::
	
	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



.. raw:: html

	<a name="type_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+type_t&labels=documentation&body=Documentation+under+heading+%22enum+type_t%22+could+be+improved">report issue</a>]</span>



enum type_t
...........

Declared in "`libtorrent/bdecode.hpp`__"


__ include/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.         |
|          |       |                                                            |
+----------+-------+------------------------------------------------------------+



.. raw:: html

	<a name="print_entry()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:print_entry%28%29&labels=documentation&body=Documentation+under+heading+%22print_entry%28%29%22+could+be+improved">report issue</a>]</span>



print_entry()
-------------

Declared in "`libtorrent/bdecode.hpp`__"


__ include/libtorrent/bdecode.hpp

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="bdecode()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:bdecode%28%29&labels=documentation&body=Documentation+under+heading+%22bdecode%28%29%22+could+be+improved">report issue</a>]</span>



bdecode()
---------

Declared in "`libtorrent/bdecode.hpp`__"


__ include/libtorrent/bdecode.hpp

.. parsed-literal::
	
	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.





.. _`BEP 19`: https://www.bittorrent.org/beps/bep_0019.html
.. _extensions: manual-ref.html#extensions
.. _`BEP 3`: https://www.bittorrent.org/beps/bep_0003.html
.. _`BEP 38`: https://www.bittorrent.org/beps/bep_0038.html
.. _`BEP 42`: https://www.bittorrent.org/beps/bep_0042.html
.. _`BEP 17`: https://www.bittorrent.org/beps/bep_0017.html
.. _`rate based choking`: manual-ref.html#rate-based-choking
.. raw:: html

	<a name="session_handle"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+session_handle&labels=documentation&body=Documentation+under+heading+%22class+session_handle%22+could+be+improved">report issue</a>]</span>



session_handle
--------------

Declared in "`libtorrent/session_handle.hpp`__"


__ include/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.


__ reference-Session.html#session
__ reference-Session.html#session
__ reference-Session.html#session
__ reference-Torrent_Info.html#is_valid()


.. parsed-literal::
	

	struct session_handle
	{
	   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);
	   void **async_add_torrent** (add\_torrent\_params const& params);
	   torrent_handle **add_torrent** (add\_torrent\_params const& params, error\_code& ec);
	   torrent_handle **add_torrent** (add\_torrent\_params const& params);
	   torrent_handle **add_torrent** (add\_torrent\_params&& params);
	   void **async_add_torrent** (add\_torrent\_params&& params);
	   bool **is_paused** () const;
	   void **resume** ();
	   void **pause** ();
	   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_get_peers** (sha1\_hash const& info\_hash);
	   void **dht_announce** (sha1\_hash const& info\_hash, int port = 0, dht\:\:announce\_flags\_t flags = {});
	   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);
	   ip_filter **get_ip_filter** () const;
	   void **set_ip_filter** (ip\_filter f);
	   void **set_port_filter** (port\_filter const& f);
	   unsigned short **listen_port** () const;
	   bool **is_listening** () const;
	   unsigned short **ssl_listen_port** () 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 = {});
	   settings_pack **get_settings** () const;
	   void **apply_settings** (settings\_pack&&);
	   void **apply_settings** (settings\_pack const&);
	   void **set_alert_notify** (std\:\:function<void()> const& fun);
	   alert\* **wait_for_alert** (time\_duration max\_wait);
	   void **pop_alerts** (std\:\:vector<alert\*>\* alerts);
	   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;
	};

.. raw:: html

	<a name="is_valid()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bis_valid%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bis_valid%28%29%5D%22+could+be+improved">report issue</a>]</span>



is_valid()
..........

.. parsed-literal::
	
	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.


__ reference-Session.html#session
__ reference-Session.html#session
__ reference-Session.html#session_handle

.. raw:: html

	<a name="session_state()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bsession_state%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bsession_state%28%29%5D%22+could+be+improved">report issue</a>]</span>



session_state()
...............

.. parsed-literal::
	
	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


__ reference-Session.html#session
__ reference-Session.html#write_session_params()
__ reference-Session.html#read_session_params()
__ reference-Session.html#session
__ reference-Session.html#session

.. raw:: html

	<a name="refresh_torrent_status()"></a>
	<a name="get_torrent_status()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Brefresh_torrent_status%28%29+get_torrent_status%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Brefresh_torrent_status%28%29+get_torrent_status%28%29%5D%22+could+be+improved">report issue</a>]</span>



refresh_torrent_status() get_torrent_status()
.............................................

.. parsed-literal::
	
	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.


__ reference-Torrent_Status.html#torrent_status
__ reference-Torrent_Handle.html#status()
__ reference-Torrent_Status.html#torrent_status
__ reference-Session.html#get_torrent_status()
__ reference-Torrent_Status.html#torrent_status

.. raw:: html

	<a name="post_torrent_updates()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bpost_torrent_updates%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bpost_torrent_updates%28%29%5D%22+could+be+improved">report issue</a>]</span>



post_torrent_updates()
......................

.. parsed-literal::
	
	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`__.


__ reference-Session.html#session
__ reference-Alerts.html#state_update_alert
__ reference-Add_Torrent.html#add_torrent_params
__ reference-Torrent_Handle.html#status()
__ reference-Torrent_Handle.html#torrent_handle

.. raw:: html

	<a name="post_session_stats()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bpost_session_stats%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bpost_session_stats%28%29%5D%22+could+be+improved">report issue</a>]</span>



post_session_stats()
....................

.. parsed-literal::
	
	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.


__ reference-Alerts.html#session_stats_alert
__ reference-Stats.html#counters
__ reference-Stats.html#counters
__ reference-Session.html#session
__ reference-Stats.html#session_stats_metrics()
__ manual-ref.html#session-statistics

.. raw:: html

	<a name="post_dht_stats()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bpost_dht_stats%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bpost_dht_stats%28%29%5D%22+could+be+improved">report issue</a>]</span>



post_dht_stats()
................

.. parsed-literal::
	
	void **post_dht_stats** ();
	

This will cause a `dht_stats_alert`__ to be posted.


__ reference-Alerts.html#dht_stats_alert

.. raw:: html

	<a name="set_dht_state()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bset_dht_state%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bset_dht_state%28%29%5D%22+could+be+improved">report issue</a>]</span>



set_dht_state()
...............

.. parsed-literal::
	
	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.


__ reference-Session.html#session
__ reference-Session.html#session_params

.. raw:: html

	<a name="get_torrents()"></a>
	<a name="find_torrent()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bget_torrents%28%29+find_torrent%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bget_torrents%28%29+find_torrent%28%29%5D%22+could+be+improved">report issue</a>]</span>



get_torrents() find_torrent()
.............................

.. parsed-literal::
	
	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`__.


__ reference-Session.html#session
__ reference-Torrent_Handle.html#torrent_handle
__ reference-Torrent_Handle.html#torrent_handle
__ reference-Session.html#session

.. raw:: html

	<a name="async_add_torrent()"></a>
	<a name="add_torrent()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Basync_add_torrent%28%29+add_torrent%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Basync_add_torrent%28%29+add_torrent%28%29%5D%22+could+be+improved">report issue</a>]</span>



async_add_torrent() add_torrent()
.................................

.. parsed-literal::
	
	torrent_handle **add_torrent** (add\_torrent\_params&& params, error\_code& ec);
	void **async_add_torrent** (add\_torrent\_params const& params);
	torrent_handle **add_torrent** (add\_torrent\_params const& params, error\_code& ec);
	torrent_handle **add_torrent** (add\_torrent\_params const& params);
	torrent_handle **add_torrent** (add\_torrent\_params&& params);
	void **async_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.


__ reference-Session.html#add_torrent()
__ reference-Session.html#add_torrent()
__ reference-Torrent_Handle.html#torrent_handle
__ reference-Session.html#async_add_torrent()
__ reference-Alerts.html#add_torrent_alert
__ reference-Torrent_Handle.html#torrent_handle
__ reference-Session.html#add_torrent()
__ reference-Session.html#session
__ reference-Session.html#add_torrent()
__ reference-Add_Torrent.html#add_torrent_params

.. raw:: html

	<a name="pause()"></a>
	<a name="resume()"></a>
	<a name="is_paused()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bpause%28%29+resume%28%29+is_paused%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bpause%28%29+resume%28%29+is_paused%28%29%5D%22+could+be+improved">report issue</a>]</span>



pause() resume() is_paused()
............................

.. parsed-literal::
	
	bool **is_paused** () const;
	void **resume** ();
	void **pause** ();
	

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.


__ reference-Session.html#session
__ reference-Session.html#session
__ reference-Session.html#session

.. raw:: html

	<a name="is_dht_running()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bis_dht_running%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bis_dht_running%28%29%5D%22+could+be+improved">report issue</a>]</span>



is_dht_running()
................

.. parsed-literal::
	
	bool **is_dht_running** () const;
	

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



.. raw:: html

	<a name="set_dht_storage()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bset_dht_storage%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bset_dht_storage%28%29%5D%22+could+be+improved">report issue</a>]</span>



set_dht_storage()
.................

.. parsed-literal::
	
	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.


__ reference-Session.html#session

.. raw:: html

	<a name="add_dht_node()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Badd_dht_node%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Badd_dht_node%28%29%5D%22+could+be+improved">report issue</a>]</span>



add_dht_node()
..............

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="dht_get_item()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bdht_get_item%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bdht_get_item%28%29%5D%22+could+be+improved">report issue</a>]</span>



dht_get_item()
..............

.. parsed-literal::
	
	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`__.


__ reference-Alerts.html#dht_immutable_item_alert

.. raw:: html

	<a name="dht_get_item()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bdht_get_item%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bdht_get_item%28%29%5D%22+could+be+improved">report issue</a>]</span>



dht_get_item()
..............

.. parsed-literal::
	
	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.


__ reference-Alerts.html#dht_mutable_item_alert

.. raw:: html

	<a name="dht_put_item()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bdht_put_item%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bdht_put_item%28%29%5D%22+could+be+improved">report issue</a>]</span>



dht_put_item()
..............

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="dht_put_item()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bdht_put_item%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bdht_put_item%28%29%5D%22+could+be+improved">report issue</a>]</span>



dht_put_item()
..............

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="dht_get_peers()"></a>
	<a name="dht_announce()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bdht_get_peers%28%29+dht_announce%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bdht_get_peers%28%29+dht_announce%28%29%5D%22+could+be+improved">report issue</a>]</span>



dht_get_peers() dht_announce()
..............................

.. parsed-literal::
	
	void **dht_get_peers** (sha1\_hash const& info\_hash);
	void **dht_announce** (sha1\_hash const& info\_hash, int port = 0, dht\:\:announce\_flags\_t flags = {});
	

``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`__.


__ reference-Alerts.html#dht_get_peers_reply_alert
__ reference-DHT.html#announce_flags_t

.. raw:: html

	<a name="dht_live_nodes()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bdht_live_nodes%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bdht_live_nodes%28%29%5D%22+could+be+improved">report issue</a>]</span>



dht_live_nodes()
................

.. parsed-literal::
	
	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.


__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert

.. raw:: html

	<a name="dht_sample_infohashes()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bdht_sample_infohashes%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bdht_sample_infohashes%28%29%5D%22+could+be+improved">report issue</a>]</span>



dht_sample_infohashes()
.......................

.. parsed-literal::
	
	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``.



.. raw:: html

	<a name="dht_direct_request()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bdht_direct_request%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bdht_direct_request%28%29%5D%22+could+be+improved">report issue</a>]</span>



dht_direct_request()
....................

.. parsed-literal::
	
	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.


__ reference-Alerts.html#dht_direct_response_alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert

.. raw:: html

	<a name="add_extension()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Badd_extension%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Badd_extension%28%29%5D%22+could+be+improved">report issue</a>]</span>



add_extension()
...............

.. parsed-literal::
	
	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.

.. code:: c++

	#include <libtorrent/extensions/ut_metadata.hpp>
	ses.add_extension(&lt::create_ut_metadata_plugin);

uTorrent peer exchange
	Exchanges peers between clients.

.. code:: c++

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

.. code:: c++

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


.. _`libtorrent plugins`: reference-Plugins.html


__ reference-Session.html#session
__ reference-Plugins.html#plugin
__ reference-Plugins.html#plugin

.. raw:: html

	<a name="get_ip_filter()"></a>
	<a name="set_ip_filter()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bget_ip_filter%28%29+set_ip_filter%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bget_ip_filter%28%29+set_ip_filter%28%29%5D%22+could+be+improved">report issue</a>]</span>



get_ip_filter() set_ip_filter()
...............................

.. parsed-literal::
	
	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`__.


__ reference-Filter.html#ip_filter
__ reference-Alerts.html#peer_blocked_alert
__ reference-Filter.html#ip_filter
__ reference-Session.html#session
__ reference-Filter.html#ip_filter

.. raw:: html

	<a name="set_port_filter()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bset_port_filter%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bset_port_filter%28%29%5D%22+could+be+improved">report issue</a>]</span>



set_port_filter()
.................

.. parsed-literal::
	
	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.


__ reference-Filter.html#port_filter

.. raw:: html

	<a name="is_listening()"></a>
	<a name="listen_port()"></a>
	<a name="ssl_listen_port()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bis_listening%28%29+listen_port%28%29+ssl_listen_port%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bis_listening%28%29+listen_port%28%29+ssl_listen_port%28%29%5D%22+could+be+improved">report issue</a>]</span>



is_listening() listen_port() ssl_listen_port()
..............................................

.. parsed-literal::
	
	unsigned short **listen_port** () const;
	bool **is_listening** () const;
	unsigned short **ssl_listen_port** () 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.


__ reference-Session.html#session
__ reference-Settings.html#listen_interfaces

.. raw:: html

	<a name="set_peer_class_filter()"></a>
	<a name="get_peer_class_filter()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bset_peer_class_filter%28%29+get_peer_class_filter%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bset_peer_class_filter%28%29+get_peer_class_filter%28%29%5D%22+could+be+improved">report issue</a>]</span>



set_peer_class_filter() get_peer_class_filter()
...............................................

.. parsed-literal::
	
	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:

.. code:: c++

	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`__.


__ reference-Session.html#session
__ reference-Filter.html#ip_filter
__ manual-ref.html#peer-classes

.. raw:: html

	<a name="set_peer_class_type_filter()"></a>
	<a name="get_peer_class_type_filter()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bset_peer_class_type_filter%28%29+get_peer_class_type_filter%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bset_peer_class_type_filter%28%29+get_peer_class_type_filter%28%29%5D%22+could+be+improved">report issue</a>]</span>



set_peer_class_type_filter() get_peer_class_type_filter()
.........................................................

.. parsed-literal::
	
	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`__.


__ manual-ref.html#peer-classes

.. raw:: html

	<a name="create_peer_class()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bcreate_peer_class%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bcreate_peer_class%28%29%5D%22+could+be+improved">report issue</a>]</span>



create_peer_class()
...................

.. parsed-literal::
	
	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`__.


__ manual-ref.html#peer-classes
__ reference-Session.html#set_peer_class_filter()
__ manual-ref.html#peer-classes

.. raw:: html

	<a name="delete_peer_class()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bdelete_peer_class%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bdelete_peer_class%28%29%5D%22+could+be+improved">report issue</a>]</span>



delete_peer_class()
...................

.. parsed-literal::
	
	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`__.


__ reference-Session.html#session
__ manual-ref.html#peer-classes

.. raw:: html

	<a name="get_peer_class()"></a>
	<a name="set_peer_class()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bget_peer_class%28%29+set_peer_class%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bget_peer_class%28%29+set_peer_class%28%29%5D%22+could+be+improved">report issue</a>]</span>



get_peer_class() set_peer_class()
.................................

.. parsed-literal::
	
	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`__.


__ reference-PeerClass.html#peer_class_info
__ manual-ref.html#peer-classes

.. raw:: html

	<a name="remove_torrent()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bremove_torrent%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bremove_torrent%28%29%5D%22+could+be+improved">report issue</a>]</span>



remove_torrent()
................

.. parsed-literal::
	
	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.


__ reference-Alerts.html#torrent_removed_alert
__ reference-Custom_Storage.html#remove_torrent()
__ reference-Session.html#session
__ reference-Session.html#add_torrent()
__ reference-Alerts.html#torrent_deleted_alert
__ reference-Torrent_Handle.html#torrent_handle
__ reference-Custom_Storage.html#remove_torrent()
__ reference-Torrent_Handle.html#is_valid()
__ reference-Torrent_Handle.html#status()
__ reference-Custom_Storage.html#remove_torrent()

.. raw:: html

	<a name="get_settings()"></a>
	<a name="apply_settings()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bget_settings%28%29+apply_settings%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bget_settings%28%29+apply_settings%28%29%5D%22+could+be+improved">report issue</a>]</span>



get_settings() apply_settings()
...............................

.. parsed-literal::
	
	settings_pack **get_settings** () const;
	void **apply_settings** (settings\_pack&&);
	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.


__ reference-Settings.html#settings_pack

.. raw:: html

	<a name="pop_alerts()"></a>
	<a name="set_alert_notify()"></a>
	<a name="wait_for_alert()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bpop_alerts%28%29+set_alert_notify%28%29+wait_for_alert%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bpop_alerts%28%29+set_alert_notify%28%29+wait_for_alert%28%29%5D%22+could+be+improved">report issue</a>]</span>



pop_alerts() set_alert_notify() wait_for_alert()
................................................

.. parsed-literal::
	
	void **set_alert_notify** (std\:\:function<void()> const& fun);
	alert\* **wait_for_alert** (time\_duration max\_wait);
	void **pop_alerts** (std\:\:vector<alert\*>\* 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.


__ reference-Session.html#session
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Session.html#session
__ reference-Session.html#session
__ reference-Alerts.html#alert
__ reference-Alerts.html#save_resume_data_alert
__ reference-Alerts.html#save_resume_data_failed_alert
__ reference-Alerts.html#alert
__ reference-Settings.html#alert_mask
__ reference-Alerts.html#alert
__ reference-Alerts.html#alerts_dropped_alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert

.. raw:: html

	<a name="delete_port_mapping()"></a>
	<a name="add_port_mapping()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bdelete_port_mapping%28%29+add_port_mapping%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bdelete_port_mapping%28%29+add_port_mapping%28%29%5D%22+could+be+improved">report issue</a>]</span>



delete_port_mapping() add_port_mapping()
........................................

.. parsed-literal::
	
	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.


__ reference-Session.html#session
__ reference-Session.html#delete_port_mapping()

.. raw:: html

	<a name="reopen_network_sockets()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Breopen_network_sockets%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Breopen_network_sockets%28%29%5D%22+could+be+improved">report issue</a>]</span>



reopen_network_sockets()
........................

.. parsed-literal::
	
	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.


__ reference-Session.html#session

.. raw:: html

	<a name="native_handle()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bnative_handle%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bnative_handle%28%29%5D%22+could+be+improved">report issue</a>]</span>



native_handle()
...............

.. parsed-literal::
	
	std::shared_ptr<aux::session_impl> **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.



.. raw:: html

	<a name="save_settings"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bsave_settings%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bsave_settings%5D%22+could+be+improved">report issue</a>]</span>


save_settings
	saves settings (i.e. the `settings_pack`__)
	

__ reference-Settings.html#settings_pack

.. raw:: html

	<a name="save_dht_state"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bsave_dht_state%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bsave_dht_state%5D%22+could+be+improved">report issue</a>]</span>


save_dht_state
	saves dht state such as nodes and node-id, possibly accelerating
	joining the DHT if provided at next `session`__ startup.
	

__ reference-Session.html#session

.. raw:: html

	<a name="save_extension_state"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bsave_extension_state%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bsave_extension_state%5D%22+could+be+improved">report issue</a>]</span>


save_extension_state
	load or save state from plugins
	


.. raw:: html

	<a name="save_ip_filter"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bsave_ip_filter%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bsave_ip_filter%5D%22+could+be+improved">report issue</a>]</span>


save_ip_filter
	load or save the IP filter set on the `session`__
	

__ reference-Session.html#session

.. raw:: html

	<a name="global_peer_class_id"></a>
	<a name="tcp_peer_class_id"></a>
	<a name="local_peer_class_id"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bglobal_peer_class_id+tcp_peer_class_id+local_peer_class_id%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bglobal_peer_class_id+tcp_peer_class_id+local_peer_class_id%5D%22+could+be+improved">report issue</a>]</span>


global_peer_class_id tcp_peer_class_id local_peer_class_id
	built-in peer classes
	


.. raw:: html

	<a name="delete_files"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bdelete_files%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bdelete_files%5D%22+could+be+improved">report issue</a>]</span>


delete_files
	delete the files belonging to the torrent from disk.
	including the part-file, if there is one
	


.. raw:: html

	<a name="delete_partfile"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bdelete_partfile%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bdelete_partfile%5D%22+could+be+improved">report issue</a>]</span>


delete_partfile
	delete just the part-file associated with this torrent
	


.. raw:: html

	<a name="paused"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Bpaused%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Bpaused%5D%22+could+be+improved">report issue</a>]</span>


paused
	when set, the `session`__ will start paused. Call
	`session_handle::resume()`__ to start
	

__ reference-Session.html#session
__ reference-Session.html#resume()

.. raw:: html

	<a name="udp"></a>
	<a name="tcp"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Budp+tcp%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Budp+tcp%5D%22+could+be+improved">report issue</a>]</span>


udp tcp
	protocols used by `add_port_mapping()`__
	

__ reference-Session.html#add_port_mapping()

.. raw:: html

	<a name="reopen_map_ports"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_handle%3A%3A%5Breopen_map_ports%5D&labels=documentation&body=Documentation+under+heading+%22session_handle%3A%3A%5Breopen_map_ports%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="session_proxy"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+session_proxy&labels=documentation&body=Documentation+under+heading+%22class+session_proxy%22+could+be+improved">report issue</a>]</span>



session_proxy
-------------

Declared in "`libtorrent/session.hpp`__"


__ include/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.


__ reference-Session.html#session
__ reference-Session.html#session
__ reference-Session.html#session
__ reference-Session.html#session
__ reference-Session.html#session_proxy
__ reference-Session.html#session


.. parsed-literal::
	

	struct session_proxy
	{
	   session_proxy& **operator=** (session\_proxy&&) & noexcept;
	   session_proxy& **operator=** (session\_proxy const&) &;
	   **session_proxy** (session\_proxy&&) noexcept;
	   **session_proxy** (session\_proxy const&);
	   **session_proxy** ();
	   **~session_proxy** ();
	};

.. raw:: html

	<a name="operator=()"></a>
	<a name="session_proxy()"></a>
	<a name="~session_proxy()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_proxy%3A%3A%5Boperator%3D%28%29+session_proxy%28%29+~session_proxy%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_proxy%3A%3A%5Boperator%3D%28%29+session_proxy%28%29+~session_proxy%28%29%5D%22+could+be+improved">report issue</a>]</span>



operator=() session_proxy() ~session_proxy()
............................................

.. parsed-literal::
	
	session_proxy& **operator=** (session\_proxy&&) & noexcept;
	session_proxy& **operator=** (session\_proxy const&) &;
	**session_proxy** (session\_proxy&&) noexcept;
	**session_proxy** (session\_proxy const&);
	**session_proxy** ();
	**~session_proxy** ();
	

default constructor, does not refer to any `session`__
implementation object.


__ reference-Session.html#session

.. raw:: html

	<a name="session"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+session&labels=documentation&body=Documentation+under+heading+%22class+session%22+could+be+improved">report issue</a>]</span>



session
-------

Declared in "`libtorrent/session.hpp`__"


__ include/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()`__.


__ reference-Session.html#session
__ reference-Session.html#session
__ reference-Session.html#session
__ reference-Settings.html#settings_pack
__ reference-Session.html#apply_settings()


.. parsed-literal::
	

	struct session : session_handle
	{
	   explicit **session** (session\_params&& params);
	   **session** (session\_params&& params, session\_flags\_t flags);
	   explicit **session** (session\_params const& params);
	   **session** ();
	   **session** (session\_params const& params, session\_flags\_t flags);
	   **session** (session\_params&& params, io\_context& ios, session\_flags\_t);
	   **session** (session\_params const& params, io\_context& ios);
	   **session** (session\_params&& params, io\_context& ios);
	   **session** (session\_params const& params, io\_context& ios, session\_flags\_t);
	   **~session** ();
	   session_proxy **abort** ();
	};

.. raw:: html

	<a name="session()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session%3A%3A%5Bsession%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session%3A%3A%5Bsession%28%29%5D%22+could+be+improved">report issue</a>]</span>



session()
.........

.. parsed-literal::
	
	explicit **session** (session\_params&& params);
	**session** (session\_params&& params, session\_flags\_t flags);
	explicit **session** (session\_params const& params);
	**session** ();
	**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.


__ reference-Session.html#session
__ reference-Session.html#session
__ reference-Session.html#session_params
__ reference-Session.html#session
__ reference-Session.html#session
__ reference-Session.html#session_params

.. raw:: html

	<a name="session()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session%3A%3A%5Bsession%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session%3A%3A%5Bsession%28%29%5D%22+could+be+improved">report issue</a>]</span>



session()
.........

.. parsed-literal::
	
	**session** (session\_params&& params, io\_context& ios, session\_flags\_t);
	**session** (session\_params const& params, io\_context& ios);
	**session** (session\_params&& params, io\_context& ios);
	**session** (session\_params const& params, io\_context& ios, session\_flags\_t);
	

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.


__ reference-Session.html#session
__ reference-Session.html#session
__ reference-Session.html#session
__ reference-Session.html#abort()
__ reference-Session.html#session_proxy
__ reference-Session.html#session
__ reference-Session.html#session_proxy

.. raw:: html

	<a name="~session()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session%3A%3A%5B~session%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session%3A%3A%5B~session%28%29%5D%22+could+be+improved">report issue</a>]</span>



~session()
..........

.. parsed-literal::
	
	**~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()`__.


__ reference-Session.html#session
__ reference-Session.html#session
__ reference-Session.html#session
__ reference-Session.html#apply_settings()

.. raw:: html

	<a name="abort()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session%3A%3A%5Babort%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session%3A%3A%5Babort%28%29%5D%22+could+be+improved">report issue</a>]</span>



abort()
.......

.. parsed-literal::
	
	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 {};


__ reference-Session.html#session
__ reference-Session.html#session
__ reference-Session.html#session
__ reference-Session.html#session
__ reference-Session.html#session
__ reference-Session.html#session
__ reference-Session.html#session

.. raw:: html

	<a name="session_params"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+session_params&labels=documentation&body=Documentation+under+heading+%22class+session_params%22+could+be+improved">report issue</a>]</span>



session_params
--------------

Declared in "`libtorrent/session_params.hpp`__"


__ include/libtorrent/session_params.hpp

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


__ reference-Session.html#session_params
__ reference-Session.html#session


.. parsed-literal::
	

	struct session_params
	{
	   **session_params** (settings\_pack&& sp);
	   **session_params** ();
	   **session_params** (settings\_pack const& sp);
	   **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);
	
	   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;
	};

.. raw:: html

	<a name="session_params()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_params%3A%3A%5Bsession_params%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_params%3A%3A%5Bsession_params%28%29%5D%22+could+be+improved">report issue</a>]</span>



session_params()
................

.. parsed-literal::
	
	**session_params** (settings\_pack&& sp);
	**session_params** ();
	**session_params** (settings\_pack const& 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.


__ reference-Settings.html#settings_pack
__ reference-Session.html#session

.. raw:: html

	<a name="session_params()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_params%3A%3A%5Bsession_params%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_params%3A%3A%5Bsession_params%28%29%5D%22+could+be+improved">report issue</a>]</span>



session_params()
................

.. parsed-literal::
	
	**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);
	

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


__ reference-Session.html#session

.. raw:: html

	<a name="settings"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_params%3A%3A%5Bsettings%5D&labels=documentation&body=Documentation+under+heading+%22session_params%3A%3A%5Bsettings%5D%22+could+be+improved">report issue</a>]</span>


settings
	The settings to configure the `session`__ with
	

__ reference-Session.html#session

.. raw:: html

	<a name="extensions"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_params%3A%3A%5Bextensions%5D&labels=documentation&body=Documentation+under+heading+%22session_params%3A%3A%5Bextensions%5D%22+could+be+improved">report issue</a>]</span>


extensions
	the plugins to add to the `session`__ as it is constructed
	

__ reference-Session.html#session

.. raw:: html

	<a name="dht_state"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_params%3A%3A%5Bdht_state%5D&labels=documentation&body=Documentation+under+heading+%22session_params%3A%3A%5Bdht_state%5D%22+could+be+improved">report issue</a>]</span>


dht_state
	DHT node ID and node addresses to bootstrap the DHT with.
	


.. raw:: html

	<a name="dht_storage_constructor"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_params%3A%3A%5Bdht_storage_constructor%5D&labels=documentation&body=Documentation+under+heading+%22session_params%3A%3A%5Bdht_storage_constructor%5D%22+could+be+improved">report issue</a>]</span>


dht_storage_constructor
	function object to construct the storage object for DHT items.
	


.. raw:: html

	<a name="disk_io_constructor"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_params%3A%3A%5Bdisk_io_constructor%5D&labels=documentation&body=Documentation+under+heading+%22session_params%3A%3A%5Bdisk_io_constructor%5D%22+could+be+improved">report issue</a>]</span>


disk_io_constructor
	function object to create the disk I/O subsystem. Defaults to
	default_disk_io_constructor.
	


.. raw:: html

	<a name="ext_state"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_params%3A%3A%5Bext_state%5D&labels=documentation&body=Documentation+under+heading+%22session_params%3A%3A%5Bext_state%5D%22+could+be+improved">report issue</a>]</span>


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

__ reference-Session.html#read_session_params()
__ reference-Session.html#write_session_params()

.. raw:: html

	<a name="ip_filter"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_params%3A%3A%5Bip_filter%5D&labels=documentation&body=Documentation+under+heading+%22session_params%3A%3A%5Bip_filter%5D%22+could+be+improved">report issue</a>]</span>


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

__ reference-Session.html#session
__ reference-Session.html#set_ip_filter()

.. raw:: html

	<a name="write_session_params()"></a>
	<a name="write_session_params_buf()"></a>
	<a name="read_session_params()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:write_session_params%28%29+write_session_params_buf%28%29+read_session_params%28%29&labels=documentation&body=Documentation+under+heading+%22write_session_params%28%29+write_session_params_buf%28%29+read_session_params%28%29%22+could+be+improved">report issue</a>]</span>



write_session_params() write_session_params_buf() read_session_params()
-----------------------------------------------------------------------

Declared in "`libtorrent/session_params.hpp`__"


__ include/libtorrent/session_params.hpp

.. parsed-literal::
	
	std::vector<char> **write_session_params_buf** (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());
	entry **write_session_params** (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.


__ reference-Session.html#session_params
__ reference-Session.html#session
__ reference-Session.html#session
__ reference-Session.html#session
__ reference-Session.html#session_params



.. _`BEP 19`: https://www.bittorrent.org/beps/bep_0019.html
.. _extensions: manual-ref.html#extensions
.. _`BEP 3`: https://www.bittorrent.org/beps/bep_0003.html
.. _`BEP 38`: https://www.bittorrent.org/beps/bep_0038.html
.. _`BEP 42`: https://www.bittorrent.org/beps/bep_0042.html
.. _`BEP 17`: https://www.bittorrent.org/beps/bep_0017.html
.. _`rate based choking`: manual-ref.html#rate-based-choking

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:

__ reference-Session.html#session
__ reference-Session.html#session
__ reference-Session.html#session_params
__ reference-Custom_Storage.html#disk_interface
__ reference-Session.html#session
__ reference-Session.html#session_params

.. include:: ../examples/custom_storage.cpp
	:code: c++
	:tab-width: 2
	:start-after: -- example begin
	:end-before: // -- example end

.. raw:: html

	<a name="settings_interface"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+settings_interface&labels=documentation&body=Documentation+under+heading+%22class+settings_interface%22+could+be+improved">report issue</a>]</span>



settings_interface
------------------

Declared in "`libtorrent/settings_pack.hpp`__"


__ include/libtorrent/settings_pack.hpp

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


__ reference-Settings.html#settings_pack


.. parsed-literal::
	

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

.. raw:: html

	<a name="buffer_allocator_interface"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+buffer_allocator_interface&labels=documentation&body=Documentation+under+heading+%22class+buffer_allocator_interface%22+could+be+improved">report issue</a>]</span>



buffer_allocator_interface
--------------------------

Declared in "`libtorrent/disk_buffer_holder.hpp`__"


__ include/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


__ reference-Custom_Storage.html#disk_buffer_holder
__ reference-Custom_Storage.html#disk_interface


.. parsed-literal::
	

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

.. raw:: html

	<a name="disk_buffer_holder"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+disk_buffer_holder&labels=documentation&body=Documentation+under+heading+%22class+disk_buffer_holder%22+could+be+improved">report issue</a>]</span>



disk_buffer_holder
------------------

Declared in "`libtorrent/disk_buffer_holder.hpp`__"


__ include/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.




.. parsed-literal::
	

	struct disk_buffer_holder
	{
	   disk_buffer_holder& **operator=** (disk\_buffer\_holder&&) & noexcept;
	   **disk_buffer_holder** (disk\_buffer\_holder&&) noexcept;
	   **disk_buffer_holder** (disk\_buffer\_holder const&) = delete;
	   disk_buffer_holder& **operator=** (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;
	};

.. raw:: html

	<a name="disk_buffer_holder()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:disk_buffer_holder%3A%3A%5Bdisk_buffer_holder%28%29%5D&labels=documentation&body=Documentation+under+heading+%22disk_buffer_holder%3A%3A%5Bdisk_buffer_holder%28%29%5D%22+could+be+improved">report issue</a>]</span>



disk_buffer_holder()
....................

.. parsed-literal::
	
	**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`__)


__ reference-Session.html#session

.. raw:: html

	<a name="disk_buffer_holder()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:disk_buffer_holder%3A%3A%5Bdisk_buffer_holder%28%29%5D&labels=documentation&body=Documentation+under+heading+%22disk_buffer_holder%3A%3A%5Bdisk_buffer_holder%28%29%5D%22+could+be+improved">report issue</a>]</span>



disk_buffer_holder()
....................

.. parsed-literal::
	
	**disk_buffer_holder** () noexcept = default;
	

default construct a holder that does not own any buffer



.. raw:: html

	<a name="~disk_buffer_holder()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:disk_buffer_holder%3A%3A%5B~disk_buffer_holder%28%29%5D&labels=documentation&body=Documentation+under+heading+%22disk_buffer_holder%3A%3A%5B~disk_buffer_holder%28%29%5D%22+could+be+improved">report issue</a>]</span>



~disk_buffer_holder()
.....................

.. parsed-literal::
	
	**~disk_buffer_holder** ();
	

frees disk buffer held by this object



.. raw:: html

	<a name="data()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:disk_buffer_holder%3A%3A%5Bdata%28%29%5D&labels=documentation&body=Documentation+under+heading+%22disk_buffer_holder%3A%3A%5Bdata%28%29%5D%22+could+be+improved">report issue</a>]</span>



data()
......

.. parsed-literal::
	
	char\* **data** () const noexcept;
	

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



.. raw:: html

	<a name="reset()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:disk_buffer_holder%3A%3A%5Breset%28%29%5D&labels=documentation&body=Documentation+under+heading+%22disk_buffer_holder%3A%3A%5Breset%28%29%5D%22+could+be+improved">report issue</a>]</span>



reset()
.......

.. parsed-literal::
	
	void **reset** ();
	

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



.. raw:: html

	<a name="swap()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:disk_buffer_holder%3A%3A%5Bswap%28%29%5D&labels=documentation&body=Documentation+under+heading+%22disk_buffer_holder%3A%3A%5Bswap%28%29%5D%22+could+be+improved">report issue</a>]</span>



swap()
......

.. parsed-literal::
	
	void **swap** (disk\_buffer\_holder& h) noexcept;
	

swap pointers of two disk buffer holders.



.. raw:: html

	<a name="is_mutable()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:disk_buffer_holder%3A%3A%5Bis_mutable%28%29%5D&labels=documentation&body=Documentation+under+heading+%22disk_buffer_holder%3A%3A%5Bis_mutable%28%29%5D%22+could+be+improved">report issue</a>]</span>



is_mutable()
............

.. parsed-literal::
	
	bool **is_mutable** () const noexcept;
	

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



.. raw:: html

	<a name="bool()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:disk_buffer_holder%3A%3A%5Bbool%28%29%5D&labels=documentation&body=Documentation+under+heading+%22disk_buffer_holder%3A%3A%5Bbool%28%29%5D%22+could+be+improved">report issue</a>]</span>



bool()
......

.. parsed-literal::
	
	explicit operator **bool** () const noexcept;
	

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



.. raw:: html

	<a name="disk_observer"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+disk_observer&labels=documentation&body=Documentation+under+heading+%22class+disk_observer%22+could+be+improved">report issue</a>]</span>



disk_observer
-------------

Declared in "`libtorrent/disk_observer.hpp`__"


__ include/libtorrent/disk_observer.hpp





.. parsed-literal::
	

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

.. raw:: html

	<a name="on_disk()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:disk_observer%3A%3A%5Bon_disk%28%29%5D&labels=documentation&body=Documentation+under+heading+%22disk_observer%3A%3A%5Bon_disk%28%29%5D%22+could+be+improved">report issue</a>]</span>



on_disk()
.........

.. parsed-literal::
	
	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



.. raw:: html

	<a name="open_file_state"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+open_file_state&labels=documentation&body=Documentation+under+heading+%22class+open_file_state%22+could+be+improved">report issue</a>]</span>



open_file_state
---------------

Declared in "`libtorrent/disk_interface.hpp`__"


__ include/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.




.. parsed-literal::
	

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

.. raw:: html

	<a name="file_index"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:open_file_state%3A%3A%5Bfile_index%5D&labels=documentation&body=Documentation+under+heading+%22open_file_state%3A%3A%5Bfile_index%5D%22+could+be+improved">report issue</a>]</span>


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.
	

__ reference-Bencoding.html#entry

.. raw:: html

	<a name="open_mode"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:open_file_state%3A%3A%5Bopen_mode%5D&labels=documentation&body=Documentation+under+heading+%22open_file_state%3A%3A%5Bopen_mode%5D%22+could+be+improved">report issue</a>]</span>


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.
	

__ reference-Custom_Storage.html#file_open_mode_t

.. raw:: html

	<a name="last_use"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:open_file_state%3A%3A%5Blast_use%5D&labels=documentation&body=Documentation+under+heading+%22open_file_state%3A%3A%5Blast_use%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="disk_interface"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+disk_interface&labels=documentation&body=Documentation+under+heading+%22class+disk_interface%22+could+be+improved">report issue</a>]</span>



disk_interface
--------------

Declared in "`libtorrent/disk_interface.hpp`__"


__ include/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.


__ reference-Custom_Storage.html#disk_interface
__ reference-Session.html#session
__ reference-Custom_Storage.html#disk_interface


.. parsed-literal::
	

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

.. raw:: html

	<a name="new_torrent()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:disk_interface%3A%3A%5Bnew_torrent%28%29%5D&labels=documentation&body=Documentation+under+heading+%22disk_interface%3A%3A%5Bnew_torrent%28%29%5D%22+could+be+improved">report issue</a>]</span>



new_torrent()
.............

.. parsed-literal::
	
	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


__ reference-Custom_Storage.html#storage_holder

.. raw:: html

	<a name="remove_torrent()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:disk_interface%3A%3A%5Bremove_torrent%28%29%5D&labels=documentation&body=Documentation+under+heading+%22disk_interface%3A%3A%5Bremove_torrent%28%29%5D%22+could+be+improved">report issue</a>]</span>



remove_torrent()
................

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="async_read()"></a>
	<a name="async_write()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:disk_interface%3A%3A%5Basync_read%28%29+async_write%28%29%5D&labels=documentation&body=Documentation+under+heading+%22disk_interface%3A%3A%5Basync_read%28%29+async_write%28%29%5D%22+could+be+improved">report issue</a>]</span>



async_read() async_write()
..........................

.. parsed-literal::
	
	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.


__ reference-Custom_Storage.html#disk_buffer_holder
__ reference-Custom_Storage.html#disk_observer
__ reference-Core.html#peer_request

.. raw:: html

	<a name="async_hash()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:disk_interface%3A%3A%5Basync_hash%28%29%5D&labels=documentation&body=Documentation+under+heading+%22disk_interface%3A%3A%5Basync_hash%28%29%5D%22+could+be+improved">report issue</a>]</span>



async_hash()
............

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="async_hash2()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:disk_interface%3A%3A%5Basync_hash2%28%29%5D&labels=documentation&body=Documentation+under+heading+%22disk_interface%3A%3A%5Basync_hash2%28%29%5D%22+could+be+improved">report issue</a>]</span>



async_hash2()
.............

.. parsed-literal::
	
	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``.



.. raw:: html

	<a name="async_move_storage()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:disk_interface%3A%3A%5Basync_move_storage%28%29%5D&labels=documentation&body=Documentation+under+heading+%22disk_interface%3A%3A%5Basync_move_storage%28%29%5D%22+could+be+improved">report issue</a>]</span>



async_move_storage()
....................

.. parsed-literal::
	
	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`__).


__ reference-Storage.html#move_flags_t

.. raw:: html

	<a name="async_release_files()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:disk_interface%3A%3A%5Basync_release_files%28%29%5D&labels=documentation&body=Documentation+under+heading+%22disk_interface%3A%3A%5Basync_release_files%28%29%5D%22+could+be+improved">report issue</a>]</span>



async_release_files()
.....................

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="async_check_files()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:disk_interface%3A%3A%5Basync_check_files%28%29%5D&labels=documentation&body=Documentation+under+heading+%22disk_interface%3A%3A%5Basync_check_files%28%29%5D%22+could+be+improved">report issue</a>]</span>



async_check_files()
...................

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="async_stop_torrent()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:disk_interface%3A%3A%5Basync_stop_torrent%28%29%5D&labels=documentation&body=Documentation+under+heading+%22disk_interface%3A%3A%5Basync_stop_torrent%28%29%5D%22+could+be+improved">report issue</a>]</span>



async_stop_torrent()
....................

.. parsed-literal::
	
	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()`__.


__ reference-Custom_Storage.html#async_release_files()

.. raw:: html

	<a name="async_rename_file()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:disk_interface%3A%3A%5Basync_rename_file%28%29%5D&labels=documentation&body=Documentation+under+heading+%22disk_interface%3A%3A%5Basync_rename_file%28%29%5D%22+could+be+improved">report issue</a>]</span>



async_rename_file()
...................

.. parsed-literal::
	
	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.).



.. raw:: html

	<a name="async_delete_files()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:disk_interface%3A%3A%5Basync_delete_files%28%29%5D&labels=documentation&body=Documentation+under+heading+%22disk_interface%3A%3A%5Basync_delete_files%28%29%5D%22+could+be+improved">report issue</a>]</span>



async_delete_files()
....................

.. parsed-literal::
	
	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.


__ reference-Session.html#session_handle
__ reference-Session.html#delete_files
__ reference-Session.html#delete_partfile

.. raw:: html

	<a name="async_set_file_priority()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:disk_interface%3A%3A%5Basync_set_file_priority%28%29%5D&labels=documentation&body=Documentation+under+heading+%22disk_interface%3A%3A%5Basync_set_file_priority%28%29%5D%22+could+be+improved">report issue</a>]</span>



async_set_file_priority()
.........................

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="async_clear_piece()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:disk_interface%3A%3A%5Basync_clear_piece%28%29%5D&labels=documentation&body=Documentation+under+heading+%22disk_interface%3A%3A%5Basync_clear_piece%28%29%5D%22+could+be+improved">report issue</a>]</span>



async_clear_piece()
...................

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="update_stats_counters()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:disk_interface%3A%3A%5Bupdate_stats_counters%28%29%5D&labels=documentation&body=Documentation+under+heading+%22disk_interface%3A%3A%5Bupdate_stats_counters%28%29%5D%22+could+be+improved">report issue</a>]</span>



update_stats_counters()
.......................

.. parsed-literal::
	
	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.


__ reference-Custom_Storage.html#update_stats_counters()
__ reference-Stats.html#counters
__ reference-Stats.html#counters

.. raw:: html

	<a name="get_status()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:disk_interface%3A%3A%5Bget_status%28%29%5D&labels=documentation&body=Documentation+under+heading+%22disk_interface%3A%3A%5Bget_status%28%29%5D%22+could+be+improved">report issue</a>]</span>



get_status()
............

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="abort()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:disk_interface%3A%3A%5Babort%28%29%5D&labels=documentation&body=Documentation+under+heading+%22disk_interface%3A%3A%5Babort%28%29%5D%22+could+be+improved">report issue</a>]</span>



abort()
.......

.. parsed-literal::
	
	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.


__ reference-Session.html#session

.. raw:: html

	<a name="submit_jobs()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:disk_interface%3A%3A%5Bsubmit_jobs%28%29%5D&labels=documentation&body=Documentation+under+heading+%22disk_interface%3A%3A%5Bsubmit_jobs%28%29%5D%22+could+be+improved">report issue</a>]</span>



submit_jobs()
.............

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="settings_updated()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:disk_interface%3A%3A%5Bsettings_updated%28%29%5D&labels=documentation&body=Documentation+under+heading+%22disk_interface%3A%3A%5Bsettings_updated%28%29%5D%22+could+be+improved">report issue</a>]</span>



settings_updated()
..................

.. parsed-literal::
	
	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.


__ reference-Custom_Storage.html#settings_interface

.. raw:: html

	<a name="force_copy"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:disk_interface%3A%3A%5Bforce_copy%5D&labels=documentation&body=Documentation+under+heading+%22disk_interface%3A%3A%5Bforce_copy%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="sequential_access"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:disk_interface%3A%3A%5Bsequential_access%5D&labels=documentation&body=Documentation+under+heading+%22disk_interface%3A%3A%5Bsequential_access%5D%22+could+be+improved">report issue</a>]</span>


sequential_access
	hint that there may be more disk operations with sequential access to
	the file
	


.. raw:: html

	<a name="volatile_read"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:disk_interface%3A%3A%5Bvolatile_read%5D&labels=documentation&body=Documentation+under+heading+%22disk_interface%3A%3A%5Bvolatile_read%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="v1_hash"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:disk_interface%3A%3A%5Bv1_hash%5D&labels=documentation&body=Documentation+under+heading+%22disk_interface%3A%3A%5Bv1_hash%5D%22+could+be+improved">report issue</a>]</span>


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.
	

__ reference-Custom_Storage.html#async_hash()
__ reference-Custom_Storage.html#async_hash()

.. raw:: html

	<a name="flush_piece"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:disk_interface%3A%3A%5Bflush_piece%5D&labels=documentation&body=Documentation+under+heading+%22disk_interface%3A%3A%5Bflush_piece%5D%22+could+be+improved">report issue</a>]</span>


flush_piece
	this flag instructs a hash job that we just completed this piece, and
	it should be flushed to disk
	


.. raw:: html

	<a name="storage_holder"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+storage_holder&labels=documentation&body=Documentation+under+heading+%22class+storage_holder%22+could+be+improved">report issue</a>]</span>



storage_holder
--------------

Declared in "`libtorrent/disk_interface.hpp`__"


__ include/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.


__ reference-Custom_Storage.html#disk_interface
__ reference-Session.html#session


.. parsed-literal::
	

	struct storage_holder
	{
	   **~storage_holder** ();
	   **storage_holder** (storage\_index\_t idx, disk\_interface& disk\_io);
	   **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;
	};

.. raw:: html

	<a name="file_open_mode_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_open_mode_t&labels=documentation&body=Documentation+under+heading+%22file_open_mode_t%22+could+be+improved">report issue</a>]</span>



file_open_mode_t
----------------

Declared in "`libtorrent/disk_interface.hpp`__"


__ include/libtorrent/disk_interface.hpp

.. raw:: html

	<a name="file_open_mode_t::read_only"></a>

read_only
	open the file for reading only
	


.. raw:: html

	<a name="file_open_mode_t::write_only"></a>

write_only
	open the file for writing only
	


.. raw:: html

	<a name="file_open_mode_t::read_write"></a>

read_write
	open the file for reading and writing
	


.. raw:: html

	<a name="file_open_mode_t::rw_mask"></a>

rw_mask
	the mask for the bits determining read or write mode
	


.. raw:: html

	<a name="file_open_mode_t::sparse"></a>

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


.. raw:: html

	<a name="file_open_mode_t::no_atime"></a>

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


.. raw:: html

	<a name="file_open_mode_t::random_access"></a>

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





.. _`BEP 19`: https://www.bittorrent.org/beps/bep_0019.html
.. _extensions: manual-ref.html#extensions
.. _`BEP 3`: https://www.bittorrent.org/beps/bep_0003.html
.. _`BEP 38`: https://www.bittorrent.org/beps/bep_0038.html
.. _`BEP 42`: https://www.bittorrent.org/beps/bep_0042.html
.. _`BEP 17`: https://www.bittorrent.org/beps/bep_0017.html
.. _`rate based choking`: manual-ref.html#rate-based-choking

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:

.. raw:: html

	<a name="settings_pack"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+settings_pack&labels=documentation&body=Documentation+under+heading+%22class+settings_pack%22+could+be+improved">report issue</a>]</span>



settings_pack
-------------

Declared in "`libtorrent/settings_pack.hpp`__"


__ reference-Session.html#session
__ reference-Settings.html#settings_pack
__ reference-Settings.html#settings_pack
__ reference-Session.html#session
__ reference-Settings.html#settings_pack
__ include/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.


.. include:: settings-ref.rst





.. parsed-literal::
	

	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_int** (int name, flags\:\:bitfield\_flag<Type, Tag> const val);
	   void **set_str** (int name, std\:\:string val) override;
	   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);
	   std::string const& **get_str** (int name) const override;
	   bool **get_bool** (int name) const override;
	   int **get_int** (int name) const override;
	   void **for_each** (Fun&& f) const;
	
	   enum type_bases
	   {
	      string_type_base,
	      int_type_base,
	      bool_type_base,
	      type_mask,
	      index_mask,
	   };
	
	   enum suggest_mode_t
	   {
	      no_piece_suggestions,
	      suggest_read_cache,
	   };
	
	   enum choking_algorithm_t
	   {
	      fixed_slots_choker,
	      rate_based_choker,
	      deprecated_bittyrant_choker,
	   };
	
	   enum seed_choking_algorithm_t
	   {
	      round_robin,
	      fastest_upload,
	      anti_leech,
	   };
	
	   enum io_buffer_mode_t
	   {
	      enable_os_cache,
	      deprecated_disable_os_cache_for_aligned_files,
	      disable_os_cache,
	      write_through,
	   };
	
	   enum bandwidth_mixed_algo_t
	   {
	      prefer_tcp,
	      peer_proportional,
	   };
	
	   enum enc_policy
	   {
	      pe_forced,
	      pe_enabled,
	      pe_disabled,
	   };
	
	   enum enc_level
	   {
	      pe_plaintext,
	      pe_rc4,
	      pe_both,
	   };
	
	   enum proxy_type_t
	   {
	      none,
	      socks4,
	      socks5,
	      socks5_pw,
	      http,
	      http_pw,
	      i2p_proxy,
	   };
	};

.. raw:: html

	<a name="set_int()"></a>
	<a name="set_str()"></a>
	<a name="set_bool()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:settings_pack%3A%3A%5Bset_int%28%29+set_str%28%29+set_bool%28%29%5D&labels=documentation&body=Documentation+under+heading+%22settings_pack%3A%3A%5Bset_int%28%29+set_str%28%29+set_bool%28%29%5D%22+could+be+improved">report issue</a>]</span>



set_int() set_str() set_bool()
..............................

.. parsed-literal::
	
	void **set_int** (int name, flags\:\:bitfield\_flag<Type, Tag> const val);
	void **set_str** (int name, std\:\:string val) override;
	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.


__ reference-Settings.html#settings_pack

.. raw:: html

	<a name="has_val()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:settings_pack%3A%3A%5Bhas_val%28%29%5D&labels=documentation&body=Documentation+under+heading+%22settings_pack%3A%3A%5Bhas_val%28%29%5D%22+could+be+improved">report issue</a>]</span>



has_val()
.........

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="clear()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:settings_pack%3A%3A%5Bclear%28%29%5D&labels=documentation&body=Documentation+under+heading+%22settings_pack%3A%3A%5Bclear%28%29%5D%22+could+be+improved">report issue</a>]</span>



clear()
.......

.. parsed-literal::
	
	void **clear** ();
	

clear the settings pack from all settings



.. raw:: html

	<a name="clear()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:settings_pack%3A%3A%5Bclear%28%29%5D&labels=documentation&body=Documentation+under+heading+%22settings_pack%3A%3A%5Bclear%28%29%5D%22+could+be+improved">report issue</a>]</span>



clear()
.......

.. parsed-literal::
	
	void **clear** (int name);
	

clear a specific setting from the pack



.. raw:: html

	<a name="get_bool()"></a>
	<a name="get_str()"></a>
	<a name="get_int()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:settings_pack%3A%3A%5Bget_bool%28%29+get_str%28%29+get_int%28%29%5D&labels=documentation&body=Documentation+under+heading+%22settings_pack%3A%3A%5Bget_bool%28%29+get_str%28%29+get_int%28%29%5D%22+could+be+improved">report issue</a>]</span>



get_bool() get_str() get_int()
..............................

.. parsed-literal::
	
	std::string const& **get_str** (int name) const override;
	bool **get_bool** (int name) const override;
	int **get_int** (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.


__ reference-Settings.html#settings_pack

.. raw:: html

	<a name="type_bases"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+type_bases&labels=documentation&body=Documentation+under+heading+%22enum+type_bases%22+could+be+improved">report issue</a>]</span>



enum type_bases
...............

Declared in "`libtorrent/settings_pack.hpp`__"


__ include/libtorrent/settings_pack.hpp

+------------------+-------+-------------+
| name             | value | description |
+==================+=======+=============+
| string_type_base | 0     |             |
+------------------+-------+-------------+
| int_type_base    | 16384 |             |
+------------------+-------+-------------+
| bool_type_base   | 32768 |             |
+------------------+-------+-------------+
| type_mask        | 49152 |             |
+------------------+-------+-------------+
| index_mask       | 16383 |             |
+------------------+-------+-------------+



.. raw:: html

	<a name="suggest_mode_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+suggest_mode_t&labels=documentation&body=Documentation+under+heading+%22enum+suggest_mode_t%22+could+be+improved">report issue</a>]</span>



enum suggest_mode_t
...................

Declared in "`libtorrent/settings_pack.hpp`__"


__ include/libtorrent/settings_pack.hpp

+----------------------+-------+-------------+
| name                 | value | description |
+======================+=======+=============+
| no_piece_suggestions | 0     |             |
+----------------------+-------+-------------+
| suggest_read_cache   | 1     |             |
+----------------------+-------+-------------+



.. raw:: html

	<a name="choking_algorithm_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+choking_algorithm_t&labels=documentation&body=Documentation+under+heading+%22enum+choking_algorithm_t%22+could+be+improved">report issue</a>]</span>



enum choking_algorithm_t
........................

Declared in "`libtorrent/settings_pack.hpp`__"


__ include/libtorrent/settings_pack.hpp

+-----------------------------+-------+-------------------------------------------------------------------+
| name                        | value | description                                                       |
+=============================+=======+===================================================================+
| fixed_slots_choker          | 0     | This is the traditional choker with a fixed number of unchoke     |
|                             |       | slots (as specified by `settings_pack::unchoke_slots_limit`__).   |
|                             |       |                                                                   |
+-----------------------------+-------+-------------------------------------------------------------------+
| rate_based_choker           | 2     | 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_choker | 3     |                                                                   |
+-----------------------------+-------+-------------------------------------------------------------------+


__ reference-Settings.html#unchoke_slots_limit
__ reference-Settings.html#rate_choker_initial_threshold

.. raw:: html

	<a name="seed_choking_algorithm_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+seed_choking_algorithm_t&labels=documentation&body=Documentation+under+heading+%22enum+seed_choking_algorithm_t%22+could+be+improved">report issue</a>]</span>



enum seed_choking_algorithm_t
.............................

Declared in "`libtorrent/settings_pack.hpp`__"


__ include/libtorrent/settings_pack.hpp

+----------------+-------+--------------------------------------------------------------------+
| name           | value | description                                                        |
+================+=======+====================================================================+
| round_robin    | 0     | which 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 | 1     | unchokes the peers we can send to the fastest. This might be a     |
|                |       | bit more reliable in utilizing all available capacity.             |
|                |       |                                                                    |
+----------------+-------+--------------------------------------------------------------------+
| anti_leech     | 2     | prioritizes 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.                                                             |
|                |       |                                                                    |
+----------------+-------+--------------------------------------------------------------------+



.. raw:: html

	<a name="io_buffer_mode_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+io_buffer_mode_t&labels=documentation&body=Documentation+under+heading+%22enum+io_buffer_mode_t%22+could+be+improved">report issue</a>]</span>



enum io_buffer_mode_t
.....................

Declared in "`libtorrent/settings_pack.hpp`__"


__ include/libtorrent/settings_pack.hpp

+-----------------------------------------------+-------+-------------+
| name                                          | value | description |
+===============================================+=======+=============+
| enable_os_cache                               | 0     |             |
+-----------------------------------------------+-------+-------------+
| deprecated_disable_os_cache_for_aligned_files | 1     |             |
+-----------------------------------------------+-------+-------------+
| disable_os_cache                              | 2     |             |
+-----------------------------------------------+-------+-------------+
| write_through                                 | 3     |             |
+-----------------------------------------------+-------+-------------+



.. raw:: html

	<a name="bandwidth_mixed_algo_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+bandwidth_mixed_algo_t&labels=documentation&body=Documentation+under+heading+%22enum+bandwidth_mixed_algo_t%22+could+be+improved">report issue</a>]</span>



enum bandwidth_mixed_algo_t
...........................

Declared in "`libtorrent/settings_pack.hpp`__"


__ include/libtorrent/settings_pack.hpp

+-------------------+-------+-------------------------------------------------------------+
| name              | value | description                                                 |
+===================+=======+=============================================================+
| prefer_tcp        | 0     | disables the mixed mode bandwidth balancing                 |
|                   |       |                                                             |
+-------------------+-------+-------------------------------------------------------------+
| peer_proportional | 1     | does not throttle uTP, throttles TCP to the same proportion |
|                   |       | of throughput as there are TCP connections                  |
|                   |       |                                                             |
+-------------------+-------+-------------------------------------------------------------+



.. raw:: html

	<a name="enc_policy"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+enc_policy&labels=documentation&body=Documentation+under+heading+%22enum+enc_policy%22+could+be+improved">report issue</a>]</span>



enum enc_policy
...............

Declared in "`libtorrent/settings_pack.hpp`__"


__ include/libtorrent/settings_pack.hpp

+-------------+-------+---------------------------------------------------------------------+
| name        | value | description                                                         |
+=============+=======+=====================================================================+
| pe_forced   | 0     | Only 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_enabled  | 1     | encrypted 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_disabled | 2     | only non-encrypted connections are allowed.                         |
|             |       |                                                                     |
+-------------+-------+---------------------------------------------------------------------+



.. raw:: html

	<a name="enc_level"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+enc_level&labels=documentation&body=Documentation+under+heading+%22enum+enc_level%22+could+be+improved">report issue</a>]</span>



enum enc_level
..............

Declared in "`libtorrent/settings_pack.hpp`__"


__ include/libtorrent/settings_pack.hpp

+--------------+-------+--------------------------------+
| name         | value | description                    |
+==============+=======+================================+
| pe_plaintext | 1     | use only plain text encryption |
|              |       |                                |
+--------------+-------+--------------------------------+
| pe_rc4       | 2     | use only RC4 encryption        |
|              |       |                                |
+--------------+-------+--------------------------------+
| pe_both      | 3     | allow both                     |
|              |       |                                |
+--------------+-------+--------------------------------+



.. raw:: html

	<a name="proxy_type_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+proxy_type_t&labels=documentation&body=Documentation+under+heading+%22enum+proxy_type_t%22+could+be+improved">report issue</a>]</span>



enum proxy_type_t
.................

Declared in "`libtorrent/settings_pack.hpp`__"


__ include/libtorrent/settings_pack.hpp

+-----------+-------+-------------------------------------------------------------------------------+
| name      | value | description                                                                   |
+===========+=======+===============================================================================+
| none      | 0     | No proxy server is used and all other fields are ignored.                     |
|           |       |                                                                               |
+-----------+-------+-------------------------------------------------------------------------------+
| socks4    | 1     | The server is assumed to be a `SOCKS4 server`_ that requires a                |
|           |       | username.                                                                     |
|           |       |                                                                               |
|           |       | .. _`SOCKS4 server`: http://www.ufasoft.com/doc/socks4_protocol.htm           |
|           |       |                                                                               |
+-----------+-------+-------------------------------------------------------------------------------+
| socks5    | 2     | The server is assumed to be a SOCKS5 server (`RFC 1928`_) that does           |
|           |       | not require any authentication. The username and password are                 |
|           |       | ignored.                                                                      |
|           |       |                                                                               |
|           |       | .. _`RFC 1928`: http://www.faqs.org/rfcs/rfc1928.html                         |
|           |       |                                                                               |
+-----------+-------+-------------------------------------------------------------------------------+
| socks5_pw | 3     | The 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.                                                                     |
|           |       |                                                                               |
|           |       | .. _`RFC 1929`: http://www.faqs.org/rfcs/rfc1929.html                         |
|           |       |                                                                               |
+-----------+-------+-------------------------------------------------------------------------------+
| http      | 4     | The 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.                    |
|           |       |                                                                               |
|           |       | .. _CONNECT: http://tools.ietf.org/html/draft-luotonen-web-proxy-tunneling-01 |
|           |       |                                                                               |
+-----------+-------+-------------------------------------------------------------------------------+
| http_pw   | 5     | The server is assumed to be an HTTP proxy that requires user                  |
|           |       | authorization. The username and password will be sent to the proxy.           |
|           |       |                                                                               |
+-----------+-------+-------------------------------------------------------------------------------+
| i2p_proxy | 6     | route through a i2p SAM proxy                                                 |
|           |       |                                                                               |
+-----------+-------+-------------------------------------------------------------------------------+



.. raw:: html

	<a name="name_for_setting()"></a>
	<a name="setting_by_name()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:name_for_setting%28%29+setting_by_name%28%29&labels=documentation&body=Documentation+under+heading+%22name_for_setting%28%29+setting_by_name%28%29%22+could+be+improved">report issue</a>]</span>



name_for_setting() setting_by_name()
------------------------------------

Declared in "`libtorrent/settings_pack.hpp`__"


__ include/libtorrent/settings_pack.hpp

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="default_settings()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:default_settings%28%29&labels=documentation&body=Documentation+under+heading+%22default_settings%28%29%22+could+be+improved">report issue</a>]</span>



default_settings()
------------------

Declared in "`libtorrent/settings_pack.hpp`__"


__ include/libtorrent/settings_pack.hpp

.. parsed-literal::
	
	settings_pack **default_settings** ();
	

returns a `settings_pack`__ with every setting set to its default value


__ reference-Settings.html#settings_pack

.. raw:: html

	<a name="high_performance_seed()"></a>
	<a name="min_memory_usage()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:high_performance_seed%28%29+min_memory_usage%28%29&labels=documentation&body=Documentation+under+heading+%22high_performance_seed%28%29+min_memory_usage%28%29%22+could+be+improved">report issue</a>]</span>



high_performance_seed() min_memory_usage()
------------------------------------------

Declared in "`libtorrent/session.hpp`__"


__ include/libtorrent/session.hpp

.. parsed-literal::
	
	settings_pack **high_performance_seed** ();
	settings_pack **min_memory_usage** ();
	

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.


__ reference-Session.html#session
__ reference-Session.html#session

.. raw:: html

	<a name="generate_fingerprint()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:generate_fingerprint%28%29&labels=documentation&body=Documentation+under+heading+%22generate_fingerprint%28%29%22+could+be+improved">report issue</a>]</span>



generate_fingerprint()
----------------------

Declared in "`libtorrent/fingerprint.hpp`__"


__ include/libtorrent/fingerprint.hpp

.. parsed-literal::
	
	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 chars | client                |
+==========+=======================+
| LT       | libtorrent (default)  |
+----------+-----------------------+
| UT       | uTorrent              |
+----------+-----------------------+
| UM       | uTorrent Mac          |
+----------+-----------------------+
| qB       | qBittorrent           |
+----------+-----------------------+
| BP       | BitTorrent Pro        |
+----------+-----------------------+
| BT       | BitTorrent            |
+----------+-----------------------+
| DE       | Deluge                |
+----------+-----------------------+
| AZ       | Azureus               |
+----------+-----------------------+
| TL       | Tribler               |
+----------+-----------------------+

There's an informal directory of client id's here_.

.. _here: http://wiki.theory.org/BitTorrentSpecification#peer_id

The ``major``, ``minor``, ``revision`` and ``tag`` parameters are used to
identify the version of your client.


__ reference-Settings.html#settings_pack



.. _`BEP 19`: https://www.bittorrent.org/beps/bep_0019.html
.. _extensions: manual-ref.html#extensions
.. _`BEP 3`: https://www.bittorrent.org/beps/bep_0003.html
.. _`BEP 38`: https://www.bittorrent.org/beps/bep_0038.html
.. _`BEP 42`: https://www.bittorrent.org/beps/bep_0042.html
.. _`BEP 17`: https://www.bittorrent.org/beps/bep_0017.html
.. _`rate based choking`: manual-ref.html#rate-based-choking
.. raw:: html

	<a name="announce_infohash"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+announce_infohash&labels=documentation&body=Documentation+under+heading+%22class+announce_infohash%22+could+be+improved">report issue</a>]</span>



announce_infohash
-----------------

Declared in "`libtorrent/announce_entry.hpp`__"


__ include/libtorrent/announce_entry.hpp





.. parsed-literal::
	

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

.. raw:: html

	<a name="message"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:announce_infohash%3A%3A%5Bmessage%5D&labels=documentation&body=Documentation+under+heading+%22announce_infohash%3A%3A%5Bmessage%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="last_error"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:announce_infohash%3A%3A%5Blast_error%5D&labels=documentation&body=Documentation+under+heading+%22announce_infohash%3A%3A%5Blast_error%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="scrape_incomplete"></a>
	<a name="scrape_complete"></a>
	<a name="scrape_downloaded"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:announce_infohash%3A%3A%5Bscrape_incomplete+scrape_complete+scrape_downloaded%5D&labels=documentation&body=Documentation+under+heading+%22announce_infohash%3A%3A%5Bscrape_incomplete+scrape_complete+scrape_downloaded%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="fails"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:announce_infohash%3A%3A%5Bfails%5D&labels=documentation&body=Documentation+under+heading+%22announce_infohash%3A%3A%5Bfails%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="updating"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:announce_infohash%3A%3A%5Bupdating%5D&labels=documentation&body=Documentation+under+heading+%22announce_infohash%3A%3A%5Bupdating%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="start_sent"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:announce_infohash%3A%3A%5Bstart_sent%5D&labels=documentation&body=Documentation+under+heading+%22announce_infohash%3A%3A%5Bstart_sent%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="complete_sent"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:announce_infohash%3A%3A%5Bcomplete_sent%5D&labels=documentation&body=Documentation+under+heading+%22announce_infohash%3A%3A%5Bcomplete_sent%5D%22+could+be+improved">report issue</a>]</span>


complete_sent
	set to true when we send a event=completed.
	


.. raw:: html

	<a name="announce_endpoint"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+announce_endpoint&labels=documentation&body=Documentation+under+heading+%22class+announce_endpoint%22+could+be+improved">report issue</a>]</span>



announce_endpoint
-----------------

Declared in "`libtorrent/announce_entry.hpp`__"


__ include/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




.. parsed-literal::
	

	struct announce_endpoint
	{
	   **announce_endpoint** ();
	
	   tcp::endpoint local_endpoint;
	   aux::array<announce_infohash, num_protocols, protocol_version> info_hashes;
	   bool **enabled**  = true;
	};

.. raw:: html

	<a name="local_endpoint"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:announce_endpoint%3A%3A%5Blocal_endpoint%5D&labels=documentation&body=Documentation+under+heading+%22announce_endpoint%3A%3A%5Blocal_endpoint%5D%22+could+be+improved">report issue</a>]</span>


local_endpoint
	the local endpoint of the listen interface associated with this endpoint
	


.. raw:: html

	<a name="info_hashes"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:announce_endpoint%3A%3A%5Binfo_hashes%5D&labels=documentation&body=Documentation+under+heading+%22announce_endpoint%3A%3A%5Binfo_hashes%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="enabled"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:announce_endpoint%3A%3A%5Benabled%5D&labels=documentation&body=Documentation+under+heading+%22announce_endpoint%3A%3A%5Benabled%5D%22+could+be+improved">report issue</a>]</span>


enabled
	set to false to not announce from this endpoint
	


.. raw:: html

	<a name="announce_entry"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+announce_entry&labels=documentation&body=Documentation+under+heading+%22class+announce_entry%22+could+be+improved">report issue</a>]</span>



announce_entry
--------------

Declared in "`libtorrent/announce_entry.hpp`__"


__ include/libtorrent/announce_entry.hpp

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




.. parsed-literal::
	

	struct announce_entry
	{
	   **announce_entry** ();
	   **~announce_entry** ();
	   explicit **announce_entry** (string\_view u);
	   **announce_entry** (announce\_entry const&);
	   announce_entry& **operator=** (announce\_entry const&) &;
	
	   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;
	};

.. raw:: html

	<a name="announce_entry()"></a>
	<a name="~announce_entry()"></a>
	<a name="operator=()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:announce_entry%3A%3A%5Bannounce_entry%28%29+~announce_entry%28%29+operator%3D%28%29%5D&labels=documentation&body=Documentation+under+heading+%22announce_entry%3A%3A%5Bannounce_entry%28%29+~announce_entry%28%29+operator%3D%28%29%5D%22+could+be+improved">report issue</a>]</span>



announce_entry() ~announce_entry() operator=()
..............................................

.. parsed-literal::
	
	**announce_entry** ();
	**~announce_entry** ();
	explicit **announce_entry** (string\_view u);
	**announce_entry** (announce\_entry const&);
	announce_entry& **operator=** (announce\_entry const&) &;
	

constructs a tracker announce `entry`__ with ``u`` as the URL.


__ reference-Bencoding.html#entry

.. raw:: html

	<a name="tracker_source"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+tracker_source&labels=documentation&body=Documentation+under+heading+%22enum+tracker_source%22+could+be+improved">report issue</a>]</span>



enum tracker_source
...................

Declared in "`libtorrent/announce_entry.hpp`__"


__ include/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              |
|                    |       |                                                                           |
+--------------------+-------+---------------------------------------------------------------------------+


__ reference-Torrent_Info.html#add_tracker()

.. raw:: html

	<a name="url"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:announce_entry%3A%3A%5Burl%5D&labels=documentation&body=Documentation+under+heading+%22announce_entry%3A%3A%5Burl%5D%22+could+be+improved">report issue</a>]</span>


url
	tracker URL as it appeared in the torrent file
	


.. raw:: html

	<a name="trackerid"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:announce_entry%3A%3A%5Btrackerid%5D&labels=documentation&body=Documentation+under+heading+%22announce_entry%3A%3A%5Btrackerid%5D%22+could+be+improved">report issue</a>]</span>


trackerid
	the current ``&trackerid=`` argument passed to the tracker.
	this is optional and is normally empty (in which case no
	trackerid is sent).
	


.. raw:: html

	<a name="endpoints"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:announce_entry%3A%3A%5Bendpoints%5D&labels=documentation&body=Documentation+under+heading+%22announce_entry%3A%3A%5Bendpoints%5D%22+could+be+improved">report issue</a>]</span>


endpoints
	each local listen socket (endpoint) will announce to the tracker. This
	list contains state per endpoint.
	


.. raw:: html

	<a name="tier"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:announce_entry%3A%3A%5Btier%5D&labels=documentation&body=Documentation+under+heading+%22announce_entry%3A%3A%5Btier%5D%22+could+be+improved">report issue</a>]</span>


tier
	the tier this tracker belongs to
	


.. raw:: html

	<a name="fail_limit"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:announce_entry%3A%3A%5Bfail_limit%5D&labels=documentation&body=Documentation+under+heading+%22announce_entry%3A%3A%5Bfail_limit%5D%22+could+be+improved">report issue</a>]</span>


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
	


.. raw:: html

	<a name="source"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:announce_entry%3A%3A%5Bsource%5D&labels=documentation&body=Documentation+under+heading+%22announce_entry%3A%3A%5Bsource%5D%22+could+be+improved">report issue</a>]</span>


source
	a bitmask specifying which sources we got this tracker from.
	


.. raw:: html

	<a name="verified"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:announce_entry%3A%3A%5Bverified%5D&labels=documentation&body=Documentation+under+heading+%22announce_entry%3A%3A%5Bverified%5D%22+could+be+improved">report issue</a>]</span>


verified
	set to true the first time we receive a valid response
	from this tracker.
	




.. _`BEP 19`: https://www.bittorrent.org/beps/bep_0019.html
.. _extensions: manual-ref.html#extensions
.. _`BEP 3`: https://www.bittorrent.org/beps/bep_0003.html
.. _`BEP 38`: https://www.bittorrent.org/beps/bep_0038.html
.. _`BEP 42`: https://www.bittorrent.org/beps/bep_0042.html
.. _`BEP 17`: https://www.bittorrent.org/beps/bep_0017.html
.. _`rate based choking`: manual-ref.html#rate-based-choking
.. raw:: html

	<a name="hasher"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+hasher&labels=documentation&body=Documentation+under+heading+%22class+hasher%22+could+be+improved">report issue</a>]</span>



hasher
------

Declared in "`libtorrent/hasher.hpp`__"


__ include/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``.


__ reference-Utility.html#hasher
__ reference-Utility.html#hasher
__ reference-Utility.html#hasher


.. parsed-literal::
	

	class hasher
	{
	   **hasher** ();
	   explicit **hasher** (span<char const> data);
	   **hasher** (hasher const&);
	   **hasher** (char const\* data, int len);
	   hasher& **operator=** (hasher const&) &;
	   hasher& **update** (span<char const> data);
	   hasher& **update** (char const\* data, int len);
	   sha1_hash **final** ();
	   void **reset** ();
	};

.. raw:: html

	<a name="hasher()"></a>
	<a name="operator=()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:hasher%3A%3A%5Bhasher%28%29+operator%3D%28%29%5D&labels=documentation&body=Documentation+under+heading+%22hasher%3A%3A%5Bhasher%28%29+operator%3D%28%29%5D%22+could+be+improved">report issue</a>]</span>



hasher() operator=()
....................

.. parsed-literal::
	
	explicit **hasher** (span<char const> data);
	**hasher** (hasher const&);
	**hasher** (char const\* data, int len);
	hasher& **operator=** (hasher const&) &;
	

this is the same as default constructing followed by a call to
``update(data, len)``.



.. raw:: html

	<a name="update()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:hasher%3A%3A%5Bupdate%28%29%5D&labels=documentation&body=Documentation+under+heading+%22hasher%3A%3A%5Bupdate%28%29%5D%22+could+be+improved">report issue</a>]</span>



update()
........

.. parsed-literal::
	
	hasher& **update** (span<char const> data);
	hasher& **update** (char const\* data, int len);
	

append the following bytes to what is being hashed



.. raw:: html

	<a name="final()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:hasher%3A%3A%5Bfinal%28%29%5D&labels=documentation&body=Documentation+under+heading+%22hasher%3A%3A%5Bfinal%28%29%5D%22+could+be+improved">report issue</a>]</span>



final()
.......

.. parsed-literal::
	
	sha1_hash **final** ();
	

returns the SHA-1 digest of the buffers previously passed to
`update()`__ and the `hasher`__ constructor.


__ reference-Utility.html#update()
__ reference-Utility.html#hasher

.. raw:: html

	<a name="reset()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:hasher%3A%3A%5Breset%28%29%5D&labels=documentation&body=Documentation+under+heading+%22hasher%3A%3A%5Breset%28%29%5D%22+could+be+improved">report issue</a>]</span>



reset()
.......

.. parsed-literal::
	
	void **reset** ();
	

restore the `hasher`__ state to be as if the `hasher`__ has just been
default constructed.


__ reference-Utility.html#hasher
__ reference-Utility.html#hasher

.. raw:: html

	<a name="hasher256"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+hasher256&labels=documentation&body=Documentation+under+heading+%22class+hasher256%22+could+be+improved">report issue</a>]</span>



hasher256
---------

Declared in "`libtorrent/hasher.hpp`__"


__ include/libtorrent/hasher.hpp





.. parsed-literal::
	

	class hasher256
	{
	   **hasher256** ();
	   **hasher256** (hasher256 const&);
	   explicit **hasher256** (span<char const> data);
	   **hasher256** (char const\* data, int len);
	   hasher256& **operator=** (hasher256 const&) &;
	   hasher256& **update** (span<char const> data);
	   hasher256& **update** (char const\* data, int len);
	   sha256_hash **final** ();
	   void **reset** ();
	   **~hasher256** ();
	};

.. raw:: html

	<a name="operator=()"></a>
	<a name="hasher256()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:hasher256%3A%3A%5Boperator%3D%28%29+hasher256%28%29%5D&labels=documentation&body=Documentation+under+heading+%22hasher256%3A%3A%5Boperator%3D%28%29+hasher256%28%29%5D%22+could+be+improved">report issue</a>]</span>



operator=() hasher256()
.......................

.. parsed-literal::
	
	**hasher256** (hasher256 const&);
	explicit **hasher256** (span<char const> data);
	**hasher256** (char const\* data, int len);
	hasher256& **operator=** (hasher256 const&) &;
	

this is the same as default constructing followed by a call to
``update(data, len)``.



.. raw:: html

	<a name="update()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:hasher256%3A%3A%5Bupdate%28%29%5D&labels=documentation&body=Documentation+under+heading+%22hasher256%3A%3A%5Bupdate%28%29%5D%22+could+be+improved">report issue</a>]</span>



update()
........

.. parsed-literal::
	
	hasher256& **update** (span<char const> data);
	hasher256& **update** (char const\* data, int len);
	

append the following bytes to what is being hashed



.. raw:: html

	<a name="final()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:hasher256%3A%3A%5Bfinal%28%29%5D&labels=documentation&body=Documentation+under+heading+%22hasher256%3A%3A%5Bfinal%28%29%5D%22+could+be+improved">report issue</a>]</span>



final()
.......

.. parsed-literal::
	
	sha256_hash **final** ();
	

returns the SHA-1 digest of the buffers previously passed to
`update()`__ and the `hasher`__ constructor.


__ reference-Utility.html#update()
__ reference-Utility.html#hasher

.. raw:: html

	<a name="reset()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:hasher256%3A%3A%5Breset%28%29%5D&labels=documentation&body=Documentation+under+heading+%22hasher256%3A%3A%5Breset%28%29%5D%22+could+be+improved">report issue</a>]</span>



reset()
.......

.. parsed-literal::
	
	void **reset** ();
	

restore the `hasher`__ state to be as if the `hasher`__ has just been
default constructed.


__ reference-Utility.html#hasher
__ reference-Utility.html#hasher

.. raw:: html

	<a name="bitfield"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+bitfield&labels=documentation&body=Documentation+under+heading+%22class+bitfield%22+could+be+improved">report issue</a>]</span>



bitfield
--------

Declared in "`libtorrent/bitfield.hpp`__"


__ include/libtorrent/bitfield.hpp

The `bitfield`__ type stores any number of bits as a `bitfield`__
in a heap allocated array.


__ reference-Utility.html#bitfield
__ reference-Utility.html#bitfield


.. parsed-literal::
	

	struct bitfield
	{
	   **bitfield** (bitfield const& rhs);
	   **bitfield** (bitfield&& rhs) noexcept = default;
	   **bitfield** (char const\* b, int bits);
	   **bitfield** () noexcept = default;
	   **bitfield** (int bits, bool val);
	   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 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;
	};

.. raw:: html

	<a name="bitfield()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:bitfield%3A%3A%5Bbitfield%28%29%5D&labels=documentation&body=Documentation+under+heading+%22bitfield%3A%3A%5Bbitfield%28%29%5D%22+could+be+improved">report issue</a>]</span>



bitfield()
..........

.. parsed-literal::
	
	**bitfield** (bitfield const& rhs);
	**bitfield** (bitfield&& rhs) noexcept = default;
	**bitfield** (char const\* b, int bits);
	**bitfield** () noexcept = default;
	**bitfield** (int bits, bool val);
	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).


__ reference-Utility.html#bitfield
__ reference-Utility.html#bitfield
__ reference-Utility.html#bitfield
__ reference-Utility.html#bitfield

.. raw:: html

	<a name="assign()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:bitfield%3A%3A%5Bassign%28%29%5D&labels=documentation&body=Documentation+under+heading+%22bitfield%3A%3A%5Bassign%28%29%5D%22+could+be+improved">report issue</a>]</span>



assign()
........

.. parsed-literal::
	
	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.


__ reference-Utility.html#bitfield

.. raw:: html

	<a name="operator[]()"></a>
	<a name="get_bit()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:bitfield%3A%3A%5Boperator%5B%5D%28%29+get_bit%28%29%5D&labels=documentation&body=Documentation+under+heading+%22bitfield%3A%3A%5Boperator%5B%5D%28%29+get_bit%28%29%5D%22+could+be+improved">report issue</a>]</span>



operator[]() get_bit()
......................

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="clear_bit()"></a>
	<a name="set_bit()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:bitfield%3A%3A%5Bclear_bit%28%29+set_bit%28%29%5D&labels=documentation&body=Documentation+under+heading+%22bitfield%3A%3A%5Bclear_bit%28%29+set_bit%28%29%5D%22+could+be+improved">report issue</a>]</span>



clear_bit() set_bit()
.....................

.. parsed-literal::
	
	void **clear_bit** (int index) noexcept;
	void **set_bit** (int index) noexcept;
	

set bit at ``index`` to 0 (clear_bit) or 1 (set_bit).



.. raw:: html

	<a name="all_set()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:bitfield%3A%3A%5Ball_set%28%29%5D&labels=documentation&body=Documentation+under+heading+%22bitfield%3A%3A%5Ball_set%28%29%5D%22+could+be+improved">report issue</a>]</span>



all_set()
.........

.. parsed-literal::
	
	bool **all_set** () const noexcept;
	

returns true if all bits in the `bitfield`__ are set


__ reference-Utility.html#bitfield

.. raw:: html

	<a name="none_set()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:bitfield%3A%3A%5Bnone_set%28%29%5D&labels=documentation&body=Documentation+under+heading+%22bitfield%3A%3A%5Bnone_set%28%29%5D%22+could+be+improved">report issue</a>]</span>



none_set()
..........

.. parsed-literal::
	
	bool **none_set** () const noexcept;
	

returns true if no bit in the `bitfield`__ is set


__ reference-Utility.html#bitfield

.. raw:: html

	<a name="size()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:bitfield%3A%3A%5Bsize%28%29%5D&labels=documentation&body=Documentation+under+heading+%22bitfield%3A%3A%5Bsize%28%29%5D%22+could+be+improved">report issue</a>]</span>



size()
......

.. parsed-literal::
	
	int **size** () const noexcept;
	

returns the size of the `bitfield`__ in bits.


__ reference-Utility.html#bitfield

.. raw:: html

	<a name="num_words()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:bitfield%3A%3A%5Bnum_words%28%29%5D&labels=documentation&body=Documentation+under+heading+%22bitfield%3A%3A%5Bnum_words%28%29%5D%22+could+be+improved">report issue</a>]</span>



num_words()
...........

.. parsed-literal::
	
	int **num_words** () const noexcept;
	

returns the number of 32 bit words are needed to represent all bits in
this `bitfield`__.


__ reference-Utility.html#bitfield

.. raw:: html

	<a name="empty()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:bitfield%3A%3A%5Bempty%28%29%5D&labels=documentation&body=Documentation+under+heading+%22bitfield%3A%3A%5Bempty%28%29%5D%22+could+be+improved">report issue</a>]</span>



empty()
.......

.. parsed-literal::
	
	bool **empty** () const noexcept;
	

returns true if the `bitfield`__ has zero size.


__ reference-Utility.html#bitfield

.. raw:: html

	<a name="data()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:bitfield%3A%3A%5Bdata%28%29%5D&labels=documentation&body=Documentation+under+heading+%22bitfield%3A%3A%5Bdata%28%29%5D%22+could+be+improved">report issue</a>]</span>



data()
......

.. parsed-literal::
	
	char const* **data** () const noexcept;
	char\* **data** () noexcept;
	

returns a pointer to the internal buffer of the `bitfield`__, or
``nullptr`` if it's empty.


__ reference-Utility.html#bitfield

.. raw:: html

	<a name="swap()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:bitfield%3A%3A%5Bswap%28%29%5D&labels=documentation&body=Documentation+under+heading+%22bitfield%3A%3A%5Bswap%28%29%5D%22+could+be+improved">report issue</a>]</span>



swap()
......

.. parsed-literal::
	
	void **swap** (bitfield& rhs) noexcept;
	

swaps the bit-fields two variables refer to



.. raw:: html

	<a name="count()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:bitfield%3A%3A%5Bcount%28%29%5D&labels=documentation&body=Documentation+under+heading+%22bitfield%3A%3A%5Bcount%28%29%5D%22+could+be+improved">report issue</a>]</span>



count()
.......

.. parsed-literal::
	
	int **count** () const noexcept;
	

count the number of bits in the `bitfield`__ that are set to 1.


__ reference-Utility.html#bitfield

.. raw:: html

	<a name="find_first_set()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:bitfield%3A%3A%5Bfind_first_set%28%29%5D&labels=documentation&body=Documentation+under+heading+%22bitfield%3A%3A%5Bfind_first_set%28%29%5D%22+could+be+improved">report issue</a>]</span>



find_first_set()
................

.. parsed-literal::
	
	int **find_first_set** () const noexcept;
	

returns the index of the first set bit in the `bitfield`__, i.e. 1 bit.


__ reference-Utility.html#bitfield

.. raw:: html

	<a name="find_last_clear()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:bitfield%3A%3A%5Bfind_last_clear%28%29%5D&labels=documentation&body=Documentation+under+heading+%22bitfield%3A%3A%5Bfind_last_clear%28%29%5D%22+could+be+improved">report issue</a>]</span>



find_last_clear()
.................

.. parsed-literal::
	
	int **find_last_clear** () const noexcept;
	

returns the index to the last cleared bit in the `bitfield`__, i.e. 0 bit.


__ reference-Utility.html#bitfield



.. _`BEP 19`: https://www.bittorrent.org/beps/bep_0019.html
.. _extensions: manual-ref.html#extensions
.. _`BEP 3`: https://www.bittorrent.org/beps/bep_0003.html
.. _`BEP 38`: https://www.bittorrent.org/beps/bep_0038.html
.. _`BEP 42`: https://www.bittorrent.org/beps/bep_0042.html
.. _`BEP 17`: https://www.bittorrent.org/beps/bep_0017.html
.. _`rate based choking`: manual-ref.html#rate-based-choking
.. raw:: html

	<a name="torrent_status"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+torrent_status&labels=documentation&body=Documentation+under+heading+%22class+torrent_status%22+could+be+improved">report issue</a>]</span>



torrent_status
--------------

Declared in "`libtorrent/torrent_status.hpp`__"


__ include/libtorrent/torrent_status.hpp

holds a snapshot of the status of a torrent, as queried by
`torrent_handle::status()`__.


__ reference-Torrent_Handle.html#status()


.. parsed-literal::
	

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

.. raw:: html

	<a name="operator==()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Boperator%3D%3D%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Boperator%3D%3D%28%29%5D%22+could+be+improved">report issue</a>]</span>



operator==()
............

.. parsed-literal::
	
	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.


__ reference-Torrent_Handle.html#torrent_handle

.. raw:: html

	<a name="state_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+state_t&labels=documentation&body=Documentation+under+heading+%22enum+state_t%22+could+be+improved">report issue</a>]</span>



enum state_t
............

Declared in "`libtorrent/torrent_status.hpp`__"


__ include/libtorrent/torrent_status.hpp

+----------------------------------------------------+-------+------------------------------------------------------------+
| name                                               | value | description                                                |
+====================================================+=======+============================================================+
| checking_files                                     | 1     | The torrent has not started its download yet, and is       |
|                                                    |       | currently checking existing files.                         |
|                                                    |       |                                                            |
+----------------------------------------------------+-------+------------------------------------------------------------+
| downloading_metadata                               | 2     | The torrent is trying to download metadata from peers.     |
|                                                    |       | This implies the ut_metadata extension is in use.          |
|                                                    |       |                                                            |
+----------------------------------------------------+-------+------------------------------------------------------------+
| downloading                                        | 3     | The 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.                                                |
|                                                    |       |                                                            |
+----------------------------------------------------+-------+------------------------------------------------------------+
| finished                                           | 4     | In 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.                     |
|                                                    |       |                                                            |
+----------------------------------------------------+-------+------------------------------------------------------------+
| seeding                                            | 5     | In this state the torrent has finished downloading and     |
|                                                    |       | is a pure seeder.                                          |
|                                                    |       |                                                            |
+----------------------------------------------------+-------+------------------------------------------------------------+
| unused_enum_for_backwards_compatibility_allocating | 6     | If the torrent was started in full allocation mode, this   |
|                                                    |       | indicates that the (disk) storage for the torrent is       |
|                                                    |       | allocated.                                                 |
|                                                    |       |                                                            |
+----------------------------------------------------+-------+------------------------------------------------------------+
| checking_resume_data                               | 7     | The 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.      |
|                                                    |       |                                                            |
+----------------------------------------------------+-------+------------------------------------------------------------+



.. raw:: html

	<a name="handle"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bhandle%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bhandle%5D%22+could+be+improved">report issue</a>]</span>


handle
	a handle to the torrent whose status the object represents.
	


.. raw:: html

	<a name="errc"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Berrc%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Berrc%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="error_file"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Berror_file%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Berror_file%5D%22+could+be+improved">report issue</a>]</span>


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;
	


.. raw:: html

	<a name="error_file_none"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Berror_file_none%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Berror_file_none%5D%22+could+be+improved">report issue</a>]</span>


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
	


.. raw:: html

	<a name="error_file_ssl_ctx"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Berror_file_ssl_ctx%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Berror_file_ssl_ctx%5D%22+could+be+improved">report issue</a>]</span>


error_file_ssl_ctx
	the error occurred setting up the SSL context
	


.. raw:: html

	<a name="error_file_metadata"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Berror_file_metadata%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Berror_file_metadata%5D%22+could+be+improved">report issue</a>]</span>


error_file_metadata
	the error occurred while loading the metadata for the torrent
	


.. raw:: html

	<a name="error_file_exception"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Berror_file_exception%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Berror_file_exception%5D%22+could+be+improved">report issue</a>]</span>


error_file_exception
	there was a serious error reported in this torrent. The error code
	or a torrent log `alert`__ may provide more information.
	

__ reference-Alerts.html#alert

.. raw:: html

	<a name="error_file_partfile"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Berror_file_partfile%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Berror_file_partfile%5D%22+could+be+improved">report issue</a>]</span>


error_file_partfile
	the error occurred with the partfile
	


.. raw:: html

	<a name="save_path"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bsave_path%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bsave_path%5D%22+could+be+improved">report issue</a>]</span>


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

__ reference-Session.html#async_add_torrent()
__ reference-Session.html#add_torrent()

.. raw:: html

	<a name="name"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bname%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bname%5D%22+could+be+improved">report issue</a>]</span>


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

__ reference-Session.html#session

.. raw:: html

	<a name="torrent_file"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Btorrent_file%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Btorrent_file%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="next_announce"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bnext_announce%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bnext_announce%5D%22+could+be+improved">report issue</a>]</span>


next_announce
	the time until the torrent will announce itself to the tracker.
	


.. raw:: html

	<a name="current_tracker"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bcurrent_tracker%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bcurrent_tracker%5D%22+could+be+improved">report issue</a>]</span>


current_tracker
	the URL of the last working tracker. If no tracker request has
	been successful yet, it's set to an empty string.
	


.. raw:: html

	<a name="total_download"></a>
	<a name="total_upload"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Btotal_download+total_upload%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Btotal_download+total_upload%5D%22+could+be+improved">report issue</a>]</span>


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

__ reference-Session.html#session
__ reference-Stats.html#counters

.. raw:: html

	<a name="total_payload_download"></a>
	<a name="total_payload_upload"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Btotal_payload_download+total_payload_upload%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Btotal_payload_download+total_payload_upload%5D%22+could+be+improved">report issue</a>]</span>


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.
	

__ reference-Session.html#session
__ reference-Stats.html#counters
__ reference-Session.html#session
__ reference-Stats.html#counters

.. raw:: html

	<a name="total_failed_bytes"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Btotal_failed_bytes%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Btotal_failed_bytes%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="total_redundant_bytes"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Btotal_redundant_bytes%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Btotal_redundant_bytes%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="pieces"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bpieces%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bpieces%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="verified_pieces"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bverified_pieces%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bverified_pieces%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="total_done"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Btotal_done%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Btotal_done%5D%22+could+be+improved">report issue</a>]</span>


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

__ reference-Session.html#session

.. raw:: html

	<a name="total"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Btotal%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Btotal%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="total_wanted_done"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Btotal_wanted_done%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Btotal_wanted_done%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="total_wanted"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Btotal_wanted%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Btotal_wanted%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="all_time_upload"></a>
	<a name="all_time_download"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Ball_time_upload+all_time_download%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Ball_time_upload+all_time_download%5D%22+could+be+improved">report issue</a>]</span>


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.
	

__ reference-Stats.html#counters

.. raw:: html

	<a name="added_time"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Badded_time%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Badded_time%5D%22+could+be+improved">report issue</a>]</span>


added_time
	the posix-time when this torrent was added. i.e. what ``time(nullptr)``
	returned at the time.
	


.. raw:: html

	<a name="completed_time"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bcompleted_time%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bcompleted_time%5D%22+could+be+improved">report issue</a>]</span>


completed_time
	the posix-time when this torrent was finished. If the torrent is not
	yet finished, this is 0.
	


.. raw:: html

	<a name="last_seen_complete"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Blast_seen_complete%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Blast_seen_complete%5D%22+could+be+improved">report issue</a>]</span>


last_seen_complete
	the time when we, or one of our peers, last saw a complete copy of
	this torrent.
	


.. raw:: html

	<a name="storage_mode"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bstorage_mode%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bstorage_mode%5D%22+could+be+improved">report issue</a>]</span>


storage_mode
	The allocation mode for the torrent. See `storage_mode_t`__ for the
	options. For more information, see `storage allocation`__.
	

__ reference-Storage.html#storage_mode_t
__ manual-ref.html#storage-allocation

.. raw:: html

	<a name="progress"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bprogress%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bprogress%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="progress_ppm"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bprogress_ppm%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bprogress_ppm%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="queue_position"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bqueue_position%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bqueue_position%5D%22+could+be+improved">report issue</a>]</span>


queue_position
	the position this torrent has in the download
	queue. If the torrent is a seed or finished, this is -1.
	


.. raw:: html

	<a name="download_rate"></a>
	<a name="upload_rate"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bdownload_rate+upload_rate%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bdownload_rate+upload_rate%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="download_payload_rate"></a>
	<a name="upload_payload_rate"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bdownload_payload_rate+upload_payload_rate%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bdownload_payload_rate+upload_payload_rate%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="num_seeds"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bnum_seeds%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bnum_seeds%5D%22+could+be+improved">report issue</a>]</span>


num_seeds
	the number of peers that are seeding that this client is
	currently connected to.
	


.. raw:: html

	<a name="num_peers"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bnum_peers%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bnum_peers%5D%22+could+be+improved">report issue</a>]</span>


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

__ reference-Torrent_Handle.html#get_peer_info()

.. raw:: html

	<a name="num_complete"></a>
	<a name="num_incomplete"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bnum_complete+num_incomplete%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bnum_complete+num_incomplete%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="list_seeds"></a>
	<a name="list_peers"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Blist_seeds+list_peers%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Blist_seeds+list_peers%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="connect_candidates"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bconnect_candidates%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bconnect_candidates%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="num_pieces"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bnum_pieces%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bnum_pieces%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="distributed_full_copies"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bdistributed_full_copies%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bdistributed_full_copies%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="distributed_fraction"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bdistributed_fraction%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bdistributed_fraction%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="distributed_copies"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bdistributed_copies%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bdistributed_copies%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="block_size"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bblock_size%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bblock_size%5D%22+could+be+improved">report issue</a>]</span>


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.
	

__ reference-Torrent_Handle.html#get_download_queue()

.. raw:: html

	<a name="num_uploads"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bnum_uploads%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bnum_uploads%5D%22+could+be+improved">report issue</a>]</span>


num_uploads
	the number of unchoked peers in this torrent.
	


.. raw:: html

	<a name="num_connections"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bnum_connections%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bnum_connections%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="uploads_limit"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Buploads_limit%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Buploads_limit%5D%22+could+be+improved">report issue</a>]</span>


uploads_limit
	the set limit of upload slots (unchoked peers) for this torrent.
	


.. raw:: html

	<a name="connections_limit"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bconnections_limit%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bconnections_limit%5D%22+could+be+improved">report issue</a>]</span>


connections_limit
	the set limit of number of connections for this torrent.
	


.. raw:: html

	<a name="up_bandwidth_queue"></a>
	<a name="down_bandwidth_queue"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bup_bandwidth_queue+down_bandwidth_queue%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bup_bandwidth_queue+down_bandwidth_queue%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="seed_rank"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bseed_rank%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bseed_rank%5D%22+could+be+improved">report issue</a>]</span>


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
	

__ manual-ref.html#queuing

.. raw:: html

	<a name="state"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bstate%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bstate%5D%22+could+be+improved">report issue</a>]</span>


state
	the main state the torrent is in. See `torrent_status::state_t`__.
	

__ reference-Torrent_Status.html#state_t

.. raw:: html

	<a name="need_save_resume"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bneed_save_resume%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bneed_save_resume%5D%22+could+be+improved">report issue</a>]</span>


need_save_resume
	true if this torrent has unsaved changes
	to its download state and statistics since the last resume data
	was saved.
	


.. raw:: html

	<a name="is_seeding"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bis_seeding%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bis_seeding%5D%22+could+be+improved">report issue</a>]</span>


is_seeding
	true if all pieces have been downloaded.
	


.. raw:: html

	<a name="is_finished"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bis_finished%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bis_finished%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="has_metadata"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bhas_metadata%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bhas_metadata%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="has_incoming"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bhas_incoming%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bhas_incoming%5D%22+could+be+improved">report issue</a>]</span>


has_incoming
	true if there has ever been an incoming connection attempt to this
	torrent.
	


.. raw:: html

	<a name="moving_storage"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bmoving_storage%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bmoving_storage%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="announcing_to_trackers"></a>
	<a name="announcing_to_lsd"></a>
	<a name="announcing_to_dht"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bannouncing_to_trackers+announcing_to_lsd+announcing_to_dht%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bannouncing_to_trackers+announcing_to_lsd+announcing_to_dht%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="info_hashes"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Binfo_hashes%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Binfo_hashes%5D%22+could+be+improved">report issue</a>]</span>


info_hashes
	the info-hash for this torrent
	


.. raw:: html

	<a name="last_upload"></a>
	<a name="last_download"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Blast_upload+last_download%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Blast_upload+last_download%5D%22+could+be+improved">report issue</a>]</span>


last_upload last_download
	the timestamps of the last time this torrent uploaded or downloaded
	payload to any peer.
	


.. raw:: html

	<a name="active_duration"></a>
	<a name="finished_duration"></a>
	<a name="seeding_duration"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bactive_duration+finished_duration+seeding_duration%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bactive_duration+finished_duration+seeding_duration%5D%22+could+be+improved">report issue</a>]</span>


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.
	

__ reference-Stats.html#counters
__ reference-Session.html#session

.. raw:: html

	<a name="flags"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_status%3A%3A%5Bflags%5D&labels=documentation&body=Documentation+under+heading+%22torrent_status%3A%3A%5Bflags%5D%22+could+be+improved">report issue</a>]</span>


flags
	reflects several of the torrent's flags. For more
	information, see ``torrent_handle::flags()``.
	




.. _`BEP 19`: https://www.bittorrent.org/beps/bep_0019.html
.. _extensions: manual-ref.html#extensions
.. _`BEP 3`: https://www.bittorrent.org/beps/bep_0003.html
.. _`BEP 38`: https://www.bittorrent.org/beps/bep_0038.html
.. _`BEP 42`: https://www.bittorrent.org/beps/bep_0042.html
.. _`BEP 17`: https://www.bittorrent.org/beps/bep_0017.html
.. _`rate based choking`: manual-ref.html#rate-based-choking
.. raw:: html

	<a name="peer_request"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+peer_request&labels=documentation&body=Documentation+under+heading+%22class+peer_request%22+could+be+improved">report issue</a>]</span>



peer_request
------------

Declared in "`libtorrent/peer_request.hpp`__"


__ include/libtorrent/peer_request.hpp

represents a byte range within a piece. Internally this is is used for
incoming piece requests.




.. parsed-literal::
	

	struct peer_request
	{
	   bool **operator==** (peer\_request const& r) const;
	
	   piece_index_t piece;
	   int start;
	   int length;
	};

.. raw:: html

	<a name="operator==()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_request%3A%3A%5Boperator%3D%3D%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_request%3A%3A%5Boperator%3D%3D%28%29%5D%22+could+be+improved">report issue</a>]</span>



operator==()
............

.. parsed-literal::
	
	bool **operator==** (peer\_request const& r) const;
	

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


__ reference-Core.html#peer_request

.. raw:: html

	<a name="piece"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_request%3A%3A%5Bpiece%5D&labels=documentation&body=Documentation+under+heading+%22peer_request%3A%3A%5Bpiece%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="start"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_request%3A%3A%5Bstart%5D&labels=documentation&body=Documentation+under+heading+%22peer_request%3A%3A%5Bstart%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="length"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_request%3A%3A%5Blength%5D&labels=documentation&body=Documentation+under+heading+%22peer_request%3A%3A%5Blength%5D%22+could+be+improved">report issue</a>]</span>


length
	The size of the range, in bytes.
	


.. raw:: html

	<a name="piece_block"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+piece_block&labels=documentation&body=Documentation+under+heading+%22class+piece_block%22+could+be+improved">report issue</a>]</span>



piece_block
-----------

Declared in "`libtorrent/piece_block.hpp`__"


__ include/libtorrent/piece_block.hpp





.. parsed-literal::
	

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

.. raw:: html

	<a name="info_hash_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+info_hash_t&labels=documentation&body=Documentation+under+heading+%22class+info_hash_t%22+could+be+improved">report issue</a>]</span>



info_hash_t
-----------

Declared in "`libtorrent/info_hash.hpp`__"


__ include/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




.. parsed-literal::
	

	struct info_hash_t
	{
	   explicit **info_hash_t** (sha256\_hash h2) noexcept;
	   explicit **info_hash_t** (sha1\_hash h1) noexcept;
	   **info_hash_t** () noexcept = default;
	   **info_hash_t** (sha1\_hash h1, sha256\_hash h2) noexcept;
	   bool **has_v2** () const;
	   bool **has** (protocol\_version v) const;
	   bool **has_v1** () const;
	   sha1_hash **get** (protocol\_version v) const;
	   sha1_hash **get_best** () const;
	   friend bool **operator!=** (info\_hash\_t const& lhs, info\_hash\_t const& rhs);
	   friend bool **operator==** (info\_hash\_t const& lhs, info\_hash\_t const& rhs) noexcept;
	   template <typename F> void **for_each** (F f) const;
	   bool **operator<** (info\_hash\_t const& o) const;
	   friend std::ostream& **operator<<** (std\:\:ostream& os, info\_hash\_t const& ih);
	
	   sha1_hash v1;
	   sha256_hash v2;
	};

.. raw:: html

	<a name="info_hash_t()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:info_hash_t%3A%3A%5Binfo_hash_t%28%29%5D&labels=documentation&body=Documentation+under+heading+%22info_hash_t%3A%3A%5Binfo_hash_t%28%29%5D%22+could+be+improved">report issue</a>]</span>



info_hash_t()
.............

.. parsed-literal::
	
	explicit **info_hash_t** (sha256\_hash h2) noexcept;
	explicit **info_hash_t** (sha1\_hash h1) noexcept;
	**info_hash_t** () noexcept = default;
	**info_hash_t** (sha1\_hash h1, sha256\_hash h2) noexcept;
	

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

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



.. raw:: html

	<a name="has_v1()"></a>
	<a name="has_v2()"></a>
	<a name="has()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:info_hash_t%3A%3A%5Bhas_v1%28%29+has_v2%28%29+has%28%29%5D&labels=documentation&body=Documentation+under+heading+%22info_hash_t%3A%3A%5Bhas_v1%28%29+has_v2%28%29+has%28%29%5D%22+could+be+improved">report issue</a>]</span>



has_v1() has_v2() has()
.......................

.. parsed-literal::
	
	bool **has_v2** () const;
	bool **has** (protocol\_version v) const;
	bool **has_v1** () const;
	

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



.. raw:: html

	<a name="get()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:info_hash_t%3A%3A%5Bget%28%29%5D&labels=documentation&body=Documentation+under+heading+%22info_hash_t%3A%3A%5Bget%28%29%5D%22+could+be+improved">report issue</a>]</span>



get()
.....

.. parsed-literal::
	
	sha1_hash **get** (protocol\_version v) const;
	

returns the has for the specified protocol version



.. raw:: html

	<a name="get_best()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:info_hash_t%3A%3A%5Bget_best%28%29%5D&labels=documentation&body=Documentation+under+heading+%22info_hash_t%3A%3A%5Bget_best%28%29%5D%22+could+be+improved">report issue</a>]</span>



get_best()
..........

.. parsed-literal::
	
	sha1_hash **get_best** () const;
	

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



.. raw:: html

	<a name="for_each()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:info_hash_t%3A%3A%5Bfor_each%28%29%5D&labels=documentation&body=Documentation+under+heading+%22info_hash_t%3A%3A%5Bfor_each%28%29%5D%22+could+be+improved">report issue</a>]</span>



for_each()
..........

.. parsed-literal::
	
	template <typename F> void **for_each** (F f) const;
	

calls the function object ``f`` for each hash that is available.
starting with v1. The signature of ``F`` is::

	void(sha1_hash, protocol_version);



.. raw:: html

	<a name="peer_info"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+peer_info&labels=documentation&body=Documentation+under+heading+%22class+peer_info%22+could+be+improved">report issue</a>]</span>



peer_info
---------

Declared in "`libtorrent/peer_info.hpp`__"


__ include/libtorrent/peer_info.hpp

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




.. parsed-literal::
	

	struct peer_info
	{
	   std::string client;
	   typed_bitfield<piece_index_t> pieces;
	   std::int64_t total_download;
	   std::int64_t total_upload;
	   time_duration last_request;
	   time_duration last_active;
	   time_duration download_queue_time;
	   static constexpr peer_flags_t **interesting**  = 0_bit;
	   static constexpr peer_flags_t **choked**  = 1_bit;
	   static constexpr peer_flags_t **remote_interested**  = 2_bit;
	   static constexpr peer_flags_t **remote_choked**  = 3_bit;
	   static constexpr peer_flags_t **supports_extensions**  = 4_bit;
	   static constexpr peer_flags_t **outgoing_connection**  = 5_bit;
	   static constexpr peer_flags_t **local_connection**  = 5_bit;
	   static constexpr peer_flags_t **handshake**  = 6_bit;
	   static constexpr peer_flags_t **connecting**  = 7_bit;
	   static constexpr peer_flags_t **on_parole**  = 9_bit;
	   static constexpr peer_flags_t **seed**  = 10_bit;
	   static constexpr peer_flags_t **optimistic_unchoke**  = 11_bit;
	   static constexpr peer_flags_t **snubbed**  = 12_bit;
	   static constexpr peer_flags_t **upload_only**  = 13_bit;
	   static constexpr peer_flags_t **endgame_mode**  = 14_bit;
	   static constexpr peer_flags_t **holepunched**  = 15_bit;
	   static constexpr peer_flags_t **i2p_socket**  = 16_bit;
	   static constexpr peer_flags_t **utp_socket**  = 17_bit;
	   static constexpr peer_flags_t **ssl_socket**  = 18_bit;
	   static constexpr peer_flags_t **rc4_encrypted**  = 19_bit;
	   static constexpr peer_flags_t **plaintext_encrypted**  = 20_bit;
	   peer_flags_t flags;
	   static constexpr peer_source_flags_t **tracker**  = 0_bit;
	   static constexpr peer_source_flags_t **dht**  = 1_bit;
	   static constexpr peer_source_flags_t **pex**  = 2_bit;
	   static constexpr peer_source_flags_t **lsd**  = 3_bit;
	   static constexpr peer_source_flags_t **resume_data**  = 4_bit;
	   static constexpr peer_source_flags_t **incoming**  = 5_bit;
	   peer_source_flags_t source;
	   int up_speed;
	   int down_speed;
	   int payload_up_speed;
	   int payload_down_speed;
	   peer_id pid;
	   int queue_bytes;
	   int request_timeout;
	   int send_buffer_size;
	   int used_send_buffer;
	   int receive_buffer_size;
	   int used_receive_buffer;
	   int receive_buffer_watermark;
	   int num_hashfails;
	   int download_queue_length;
	   int timed_out_requests;
	   int busy_requests;
	   int requests_in_buffer;
	   int target_dl_queue_length;
	   int upload_queue_length;
	   int failcount;
	   piece_index_t downloading_piece_index;
	   int downloading_block_index;
	   int downloading_progress;
	   int downloading_total;
	   static constexpr connection_type_t **standard_bittorrent**  = 0_bit;
	   static constexpr connection_type_t **web_seed**  = 1_bit;
	   static constexpr connection_type_t **http_seed**  = 2_bit;
	   connection_type_t connection_type;
	   int pending_disk_bytes;
	   int pending_disk_read_bytes;
	   int send_quota;
	   int receive_quota;
	   int rtt;
	   int num_pieces;
	   int download_rate_peak;
	   int upload_rate_peak;
	   float progress;
	   int progress_ppm;
	   tcp::endpoint ip;
	   tcp::endpoint local_endpoint;
	   static constexpr bandwidth_state_flags_t **bw_idle**  = 0_bit;
	   static constexpr bandwidth_state_flags_t **bw_limit**  = 1_bit;
	   static constexpr bandwidth_state_flags_t **bw_network**  = 2_bit;
	   static constexpr bandwidth_state_flags_t **bw_disk**  = 4_bit;
	   bandwidth_state_flags_t read_state;
	   bandwidth_state_flags_t write_state;
	};

.. raw:: html

	<a name="client"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bclient%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bclient%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="pieces"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bpieces%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bpieces%5D%22+could+be+improved">report issue</a>]</span>


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

__ reference-Utility.html#bitfield

.. raw:: html

	<a name="total_download"></a>
	<a name="total_upload"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Btotal_download+total_upload%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Btotal_download+total_upload%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="last_request"></a>
	<a name="last_active"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Blast_request+last_active%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Blast_request+last_active%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="download_queue_time"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bdownload_queue_time%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bdownload_queue_time%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="interesting"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Binteresting%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Binteresting%5D%22+could+be+improved">report issue</a>]</span>


interesting
	**we** are interested in pieces from this peer.
	


.. raw:: html

	<a name="choked"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bchoked%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bchoked%5D%22+could+be+improved">report issue</a>]</span>


choked
	**we** have choked this peer.
	


.. raw:: html

	<a name="remote_interested"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bremote_interested%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bremote_interested%5D%22+could+be+improved">report issue</a>]</span>


remote_interested
	the peer is interested in **us**
	


.. raw:: html

	<a name="remote_choked"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bremote_choked%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bremote_choked%5D%22+could+be+improved">report issue</a>]</span>


remote_choked
	the peer has choked **us**.
	


.. raw:: html

	<a name="supports_extensions"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bsupports_extensions%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bsupports_extensions%5D%22+could+be+improved">report issue</a>]</span>


supports_extensions
	means that this peer supports the
	`extension protocol`__.
	
	__ extension_protocol.html
	


.. raw:: html

	<a name="outgoing_connection"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Boutgoing_connection%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Boutgoing_connection%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="local_connection"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Blocal_connection%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Blocal_connection%5D%22+could+be+improved">report issue</a>]</span>


local_connection
	deprecated synonym for outgoing_connection
	


.. raw:: html

	<a name="handshake"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bhandshake%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bhandshake%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="connecting"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bconnecting%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bconnecting%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="on_parole"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bon_parole%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bon_parole%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="seed"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bseed%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bseed%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="optimistic_unchoke"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Boptimistic_unchoke%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Boptimistic_unchoke%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="snubbed"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bsnubbed%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bsnubbed%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="upload_only"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bupload_only%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bupload_only%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="endgame_mode"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bendgame_mode%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bendgame_mode%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="holepunched"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bholepunched%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bholepunched%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="i2p_socket"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bi2p_socket%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bi2p_socket%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="utp_socket"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Butp_socket%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Butp_socket%5D%22+could+be+improved">report issue</a>]</span>


utp_socket
	indicates that this socket is a uTP socket
	


.. raw:: html

	<a name="ssl_socket"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bssl_socket%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bssl_socket%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="rc4_encrypted"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Brc4_encrypted%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Brc4_encrypted%5D%22+could+be+improved">report issue</a>]</span>


rc4_encrypted
	this connection is obfuscated with RC4
	


.. raw:: html

	<a name="plaintext_encrypted"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bplaintext_encrypted%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bplaintext_encrypted%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="flags"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bflags%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bflags%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="tracker"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Btracker%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Btracker%5D%22+could+be+improved">report issue</a>]</span>


tracker
	The peer was received from the tracker.
	


.. raw:: html

	<a name="dht"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bdht%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bdht%5D%22+could+be+improved">report issue</a>]</span>


dht
	The peer was received from the kademlia DHT.
	


.. raw:: html

	<a name="pex"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bpex%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bpex%5D%22+could+be+improved">report issue</a>]</span>


pex
	The peer was received from the peer exchange
	extension.
	


.. raw:: html

	<a name="lsd"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Blsd%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Blsd%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="resume_data"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bresume_data%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bresume_data%5D%22+could+be+improved">report issue</a>]</span>


resume_data
	The peer was added from the fast resume data.
	


.. raw:: html

	<a name="incoming"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bincoming%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bincoming%5D%22+could+be+improved">report issue</a>]</span>


incoming
	we received an incoming connection from this peer
	


.. raw:: html

	<a name="source"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bsource%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bsource%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="up_speed"></a>
	<a name="down_speed"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bup_speed+down_speed%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bup_speed+down_speed%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="payload_up_speed"></a>
	<a name="payload_down_speed"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bpayload_up_speed+payload_down_speed%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bpayload_up_speed+payload_down_speed%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="pid"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bpid%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bpid%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="queue_bytes"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bqueue_bytes%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bqueue_bytes%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="request_timeout"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Brequest_timeout%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Brequest_timeout%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="send_buffer_size"></a>
	<a name="used_send_buffer"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bsend_buffer_size+used_send_buffer%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bsend_buffer_size+used_send_buffer%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="receive_buffer_size"></a>
	<a name="used_receive_buffer"></a>
	<a name="receive_buffer_watermark"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Breceive_buffer_size+used_receive_buffer+receive_buffer_watermark%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Breceive_buffer_size+used_receive_buffer+receive_buffer_watermark%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="num_hashfails"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bnum_hashfails%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bnum_hashfails%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="download_queue_length"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bdownload_queue_length%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bdownload_queue_length%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="timed_out_requests"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Btimed_out_requests%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Btimed_out_requests%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="busy_requests"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bbusy_requests%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bbusy_requests%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="requests_in_buffer"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Brequests_in_buffer%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Brequests_in_buffer%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="target_dl_queue_length"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Btarget_dl_queue_length%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Btarget_dl_queue_length%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="upload_queue_length"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bupload_queue_length%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bupload_queue_length%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="failcount"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bfailcount%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bfailcount%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="downloading_piece_index"></a>
	<a name="downloading_block_index"></a>
	<a name="downloading_progress"></a>
	<a name="downloading_total"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bdownloading_piece_index+downloading_block_index+downloading_progress+downloading_total%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bdownloading_piece_index+downloading_block_index+downloading_progress+downloading_total%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="standard_bittorrent"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bstandard_bittorrent%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bstandard_bittorrent%5D%22+could+be+improved">report issue</a>]</span>


standard_bittorrent
	Regular bittorrent connection
	


.. raw:: html

	<a name="web_seed"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bweb_seed%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bweb_seed%5D%22+could+be+improved">report issue</a>]</span>


web_seed
	HTTP connection using the `BEP 19`_ protocol
	


.. raw:: html

	<a name="http_seed"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bhttp_seed%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bhttp_seed%5D%22+could+be+improved">report issue</a>]</span>


http_seed
	HTTP connection using the `BEP 17`_ protocol
	


.. raw:: html

	<a name="connection_type"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bconnection_type%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bconnection_type%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="pending_disk_bytes"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bpending_disk_bytes%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bpending_disk_bytes%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="pending_disk_read_bytes"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bpending_disk_read_bytes%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bpending_disk_read_bytes%5D%22+could+be+improved">report issue</a>]</span>


pending_disk_read_bytes
	number of outstanding bytes to read
	from disk
	


.. raw:: html

	<a name="send_quota"></a>
	<a name="receive_quota"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bsend_quota+receive_quota%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bsend_quota+receive_quota%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="rtt"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Brtt%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Brtt%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="num_pieces"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bnum_pieces%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bnum_pieces%5D%22+could+be+improved">report issue</a>]</span>


num_pieces
	the number of pieces this peer has.
	


.. raw:: html

	<a name="download_rate_peak"></a>
	<a name="upload_rate_peak"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bdownload_rate_peak+upload_rate_peak%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bdownload_rate_peak+upload_rate_peak%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="progress"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bprogress%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bprogress%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="progress_ppm"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bprogress_ppm%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bprogress_ppm%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="ip"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bip%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bip%5D%22+could+be+improved">report issue</a>]</span>


ip
	the IP-address to this peer. The type is an asio endpoint. For
	more info, see the asio_ documentation.
	
	.. _asio: http://asio.sourceforge.net/asio-0.3.8/doc/asio/reference.html
	


.. raw:: html

	<a name="local_endpoint"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Blocal_endpoint%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Blocal_endpoint%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="bw_idle"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bbw_idle%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bbw_idle%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="bw_limit"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bbw_limit%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bbw_limit%5D%22+could+be+improved">report issue</a>]</span>


bw_limit
	The peer is waiting for the rate limiter.
	


.. raw:: html

	<a name="bw_network"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bbw_network%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bbw_network%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="bw_disk"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bbw_disk%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bbw_disk%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="read_state"></a>
	<a name="write_state"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_info%3A%3A%5Bread_state+write_state%5D&labels=documentation&body=Documentation+under+heading+%22peer_info%3A%3A%5Bread_state+write_state%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="version()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:version%28%29&labels=documentation&body=Documentation+under+heading+%22version%28%29%22+could+be+improved">report issue</a>]</span>



version()
---------

Declared in "`libtorrent/version.hpp`__"


__ include/libtorrent/version.hpp

.. parsed-literal::
	
	char const* **version** ();
	

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



.. raw:: html

	<a name="truncate_files()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:truncate_files%28%29&labels=documentation&body=Documentation+under+heading+%22truncate_files%28%29%22+could+be+improved">report issue</a>]</span>



truncate_files()
----------------

Declared in "`libtorrent/truncate.hpp`__"


__ include/libtorrent/truncate.hpp

.. parsed-literal::
	
	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.


__ reference-Storage.html#file_storage

.. raw:: html

	<a name="make_magnet_uri()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:make_magnet_uri%28%29&labels=documentation&body=Documentation+under+heading+%22make_magnet_uri%28%29%22+could+be+improved">report issue</a>]</span>



make_magnet_uri()
-----------------

Declared in "`libtorrent/magnet_uri.hpp`__"


__ include/libtorrent/magnet_uri.hpp

.. parsed-literal::
	
	std::string **make_magnet_uri** (torrent\_info const& info);
	std::string **make_magnet_uri** (torrent\_handle const& handle);
	

Generates a magnet URI from the specified torrent. If the torrent
handle is invalid, an empty string is returned.

For more information about magnet links, see `magnet links`__.



__ manual-ref.html#magnet-links

.. raw:: html

	<a name="parse_magnet_uri()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:parse_magnet_uri%28%29&labels=documentation&body=Documentation+under+heading+%22parse_magnet_uri%28%29%22+could+be+improved">report issue</a>]</span>



parse_magnet_uri()
------------------

Declared in "`libtorrent/magnet_uri.hpp`__"


__ include/libtorrent/magnet_uri.hpp

.. parsed-literal::
	
	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.


__ reference-Add_Torrent.html#add_torrent_params

.. raw:: html

	<a name="connection_type"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+connection_type&labels=documentation&body=Documentation+under+heading+%22enum+connection_type%22+could+be+improved">report issue</a>]</span>



enum connection_type
--------------------

Declared in "`libtorrent/peer_connection.hpp`__"


__ include/libtorrent/peer_connection.hpp

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



.. raw:: html

	<a name="event_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+event_t&labels=documentation&body=Documentation+under+heading+%22enum+event_t%22+could+be+improved">report issue</a>]</span>



enum event_t
------------

Declared in "`libtorrent/tracker_manager.hpp`__"


__ include/libtorrent/tracker_manager.hpp

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



.. raw:: html

	<a name="portmap_transport"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+portmap_transport&labels=documentation&body=Documentation+under+heading+%22enum+portmap_transport%22+could+be+improved">report issue</a>]</span>



enum portmap_transport
----------------------

Declared in "`libtorrent/portmap.hpp`__"


__ include/libtorrent/portmap.hpp

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



.. raw:: html

	<a name="portmap_protocol"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+portmap_protocol&labels=documentation&body=Documentation+under+heading+%22enum+portmap_protocol%22+could+be+improved">report issue</a>]</span>



enum portmap_protocol
---------------------

Declared in "`libtorrent/portmap.hpp`__"


__ include/libtorrent/portmap.hpp

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



.. raw:: html

	<a name="protocol_version"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+protocol_version&labels=documentation&body=Documentation+under+heading+%22enum+protocol_version%22+could+be+improved">report issue</a>]</span>



enum protocol_version
---------------------

Declared in "`libtorrent/info_hash.hpp`__"


__ include/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     |                                                            |
+------+-------+------------------------------------------------------------+



.. raw:: html

	<a name="socket_type_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+socket_type_t&labels=documentation&body=Documentation+under+heading+%22enum+socket_type_t%22+could+be+improved">report issue</a>]</span>



enum socket_type_t
------------------

Declared in "`libtorrent/socket_type.hpp`__"


__ include/libtorrent/socket_type.hpp

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



.. raw:: html

	<a name="torrent_flags_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_flags_t&labels=documentation&body=Documentation+under+heading+%22torrent_flags_t%22+could+be+improved">report issue</a>]</span>



torrent_flags_t
---------------

Declared in "`libtorrent/torrent_flags.hpp`__"


__ include/libtorrent/torrent_flags.hpp

.. raw:: html

	<a name="torrent_flags_t::seed_mode"></a>

seed_mode
	If ``seed_mode`` is set, libtorrent will assume that all files
	are present for this torrent and that they all match the hashes in
	the torrent file. Each time a peer requests to download a block,
	the piece is verified against the hash, unless it has been verified
	already. If a hash fails, the torrent will automatically leave the
	seed mode and recheck all the files. The use case for this mode is
	if a torrent is created and seeded, or if the user already know
	that the files are complete, this is a way to avoid the initial
	file checks, and significantly reduce the startup time.
	
	Setting ``seed_mode`` on a torrent without metadata (a
	.torrent file) is a no-op and will be ignored.
	
	It is not possible to *set* the ``seed_mode`` flag on a torrent after it has
	been added to a `session`__. It is possible to *clear* it though.
	

	__ reference-Session.html#session

.. raw:: html

	<a name="torrent_flags_t::upload_mode"></a>

upload_mode
	If ``upload_mode`` is set, the torrent will be initialized in
	upload-mode, which means it will not make any piece requests. This
	state is typically entered on disk I/O errors, and if the torrent
	is also auto managed, it will be taken out of this state
	periodically (see ``settings_pack::optimistic_disk_retry``).
	
	This mode can be used to avoid race conditions when
	adjusting priorities of pieces before allowing the torrent to start
	downloading.
	
	If the torrent is auto-managed (``auto_managed``), the torrent
	will eventually be taken out of upload-mode, regardless of how it
	got there. If it's important to manually control when the torrent
	leaves upload mode, don't make it auto managed.
	


.. raw:: html

	<a name="torrent_flags_t::share_mode"></a>

share_mode
	determines if the torrent should be added in *share mode* or not.
	Share mode indicates that we are not interested in downloading the
	torrent, but merely want to improve our share ratio (i.e. increase
	it). A torrent started in share mode will do its best to never
	download more than it uploads to the swarm. If the swarm does not
	have enough demand for upload capacity, the torrent will not
	download anything. This mode is intended to be safe to add any
	number of torrents to, without manual screening, without the risk
	of downloading more than is uploaded.
	
	A torrent in share mode sets the priority to all pieces to 0,
	except for the pieces that are downloaded, when pieces are decided
	to be downloaded. This affects the progress bar, which might be set
	to "100% finished" most of the time. Do not change file or piece
	priorities for torrents in share mode, it will make it not work.
	
	The share mode has one setting, the share ratio target, see
	``settings_pack::share_mode_target`` for more info.
	


.. raw:: html

	<a name="torrent_flags_t::apply_ip_filter"></a>

apply_ip_filter
	determines if the IP filter should apply to this torrent or not. By
	default all torrents are subject to filtering by the IP filter
	(i.e. this flag is set by default). This is useful if certain
	torrents needs to be exempt for some reason, being an auto-update
	torrent for instance.
	


.. raw:: html

	<a name="torrent_flags_t::paused"></a>

paused
	specifies whether or not the torrent is paused. i.e. it won't connect to the tracker or any of the peers
	until it's resumed. Note that a paused torrent that also has the
	auto_managed flag set can be started at any time by libtorrent's queuing
	logic. See `queuing`__.
	

	__ manual-ref.html#queuing

.. raw:: html

	<a name="torrent_flags_t::auto_managed"></a>

auto_managed
	If the torrent is auto-managed (``auto_managed``), the torrent
	may be resumed at any point, regardless of how it paused. If it's
	important to manually control when the torrent is paused and
	resumed, don't make it auto managed.
	
	If ``auto_managed`` is set, the torrent will be queued,
	started and seeded automatically by libtorrent. When this is set,
	the torrent should also be started as paused. The default queue
	order is the order the torrents were added. They are all downloaded
	in that order. For more details, see `queuing`__.
	

	__ manual-ref.html#queuing

.. raw:: html

	<a name="torrent_flags_t::duplicate_is_error"></a>

duplicate_is_error
	used in `add_torrent_params`__ to indicate that it's an error to attempt
	to add a torrent that's already in the `session`__. If it's not considered an
	error, a handle to the existing torrent is returned.
	This flag is not saved by `write_resume_data()`__, since it is only meant for
	adding torrents.
	

	__ reference-Add_Torrent.html#add_torrent_params
	__ reference-Session.html#session
	__ reference-Resume_Data.html#write_resume_data()

.. raw:: html

	<a name="torrent_flags_t::update_subscribe"></a>

update_subscribe
	on by default and means that this torrent will be part of state
	updates when calling `post_torrent_updates()`__.
	This flag is not saved by `write_resume_data()`__.
	

	__ reference-Session.html#post_torrent_updates()
	__ reference-Resume_Data.html#write_resume_data()

.. raw:: html

	<a name="torrent_flags_t::super_seeding"></a>

super_seeding
	sets the torrent into super seeding/initial seeding mode. If the torrent
	is not a seed, this flag has no effect.
	


.. raw:: html

	<a name="torrent_flags_t::sequential_download"></a>

sequential_download
	sets the sequential download state for the torrent. In this mode the
	piece picker will pick pieces with low index numbers before pieces with
	high indices. The actual pieces that are picked depend on other factors
	still, such as which pieces a peer has and whether it is in parole mode
	or "prefer whole pieces"-mode. Sequential mode is not ideal for streaming
	media. For that, see `set_piece_deadline()`__ instead.
	

	__ reference-Torrent_Handle.html#set_piece_deadline()

.. raw:: html

	<a name="torrent_flags_t::stop_when_ready"></a>

stop_when_ready
	When this flag is set, the torrent will *force stop* whenever it
	transitions from a non-data-transferring state into a data-transferring
	state (referred to as being ready to download or seed). This is useful
	for torrents that should not start downloading or seeding yet, but want
	to be made ready to do so. A torrent may need to have its files checked
	for instance, so it needs to be started and possibly queued for checking
	(auto-managed and started) but as soon as it's done, it should be
	stopped.
	
	*Force stopped* means auto-managed is set to false and it's paused. As
	if the auto_manages flag is cleared and the paused flag is set on the torrent.
	
	Note that the torrent may transition into a downloading state while
	setting this flag, and since the logic is edge triggered you may
	miss the edge. To avoid this race, if the torrent already is in a
	downloading state when this call is made, it will trigger the
	stop-when-ready immediately.
	
	When the stop-when-ready logic fires, the flag is cleared. Any
	subsequent transitions between downloading and non-downloading states
	will not be affected, until this flag is set again.
	
	The behavior is more robust when setting this flag as part of adding
	the torrent. See `add_torrent_params`__.
	
	The stop-when-ready flag fixes the inherent race condition of waiting
	for the `state_changed_alert`__ and then call `pause()`__. The download/seeding
	will most likely start in between posting the `alert`__ and receiving the
	call to pause.
	
	A downloading state is one where peers are being connected. Which means
	just downloading the metadata via the ``ut_metadata`` extension counts
	as a downloading state. In order to stop a torrent once the metadata
	has been downloaded, instead set all file priorities to dont_download
	

	__ reference-Add_Torrent.html#add_torrent_params
	__ reference-Alerts.html#state_changed_alert
	__ reference-Torrent_Handle.html#pause()
	__ reference-Alerts.html#alert

.. raw:: html

	<a name="torrent_flags_t::override_trackers"></a>

override_trackers
	when this flag is set, the tracker list in the `add_torrent_params`__
	object override any trackers from the torrent file. If the flag is
	not set, the trackers from the `add_torrent_params`__ object will be
	added to the list of trackers used by the torrent.
	This flag is set by `read_resume_data()`__ if there are trackers present in
	the resume data file. This effectively makes the trackers saved in the
	resume data take precedence over the original trackers. This includes if
	there's an empty list of trackers, to support the case where they were
	explicitly removed in the previous `session`__.
	This flag is not saved by `write_resume_data()`__
	

	__ reference-Add_Torrent.html#add_torrent_params
	__ reference-Add_Torrent.html#add_torrent_params
	__ reference-Resume_Data.html#read_resume_data()
	__ reference-Session.html#session
	__ reference-Resume_Data.html#write_resume_data()

.. raw:: html

	<a name="torrent_flags_t::override_web_seeds"></a>

override_web_seeds
	If this flag is set, the web seeds from the `add_torrent_params`__
	object will override any web seeds in the torrent file. If it's not
	set, web seeds in the `add_torrent_params`__ object will be added to the
	list of web seeds used by the torrent.
	This flag is set by `read_resume_data()`__ if there are web seeds present in
	the resume data file. This effectively makes the web seeds saved in the
	resume data take precedence over the original ones. This includes if
	there's an empty list of web seeds, to support the case where they were
	explicitly removed in the previous `session`__.
	This flag is not saved by `write_resume_data()`__
	

	__ reference-Add_Torrent.html#add_torrent_params
	__ reference-Add_Torrent.html#add_torrent_params
	__ reference-Resume_Data.html#read_resume_data()
	__ reference-Session.html#session
	__ reference-Resume_Data.html#write_resume_data()

.. raw:: html

	<a name="torrent_flags_t::need_save_resume"></a>

need_save_resume
	if this flag is set (which it is by default) the torrent will be
	considered needing to save its resume data immediately as it's
	added. New torrents that don't have any resume data should do that.
	This flag is cleared by a successful call to `save_resume_data()`__
	This flag is not saved by `write_resume_data()`__, since it represents an
	ephemeral state of a running torrent.
	

	__ reference-Torrent_Handle.html#save_resume_data()
	__ reference-Resume_Data.html#write_resume_data()

.. raw:: html

	<a name="torrent_flags_t::disable_dht"></a>

disable_dht
	set this flag to disable DHT for this torrent. This lets you have the DHT
	enabled for the whole client, and still have specific torrents not
	participating in it. i.e. not announcing to the DHT nor picking up peers
	from it.
	


.. raw:: html

	<a name="torrent_flags_t::disable_lsd"></a>

disable_lsd
	set this flag to disable local service discovery for this torrent.
	


.. raw:: html

	<a name="torrent_flags_t::disable_pex"></a>

disable_pex
	set this flag to disable peer exchange for this torrent.
	


.. raw:: html

	<a name="torrent_flags_t::no_verify_files"></a>

no_verify_files
	if this flag is set, the resume data will be assumed to be correct
	without validating it against any files on disk. This may be used when
	restoring a `session`__ by loading resume data from disk. It will save time
	and also delay any hard disk errors until files are actually needed. If
	the resume data cannot be trusted, or if a torrent is added for the first
	time to some save path that may already have some of the files, this flag
	should not be set.
	

	__ reference-Session.html#session

.. raw:: html

	<a name="torrent_flags_t::all"></a>

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



.. raw:: html

	<a name="pex_flags_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:pex_flags_t&labels=documentation&body=Documentation+under+heading+%22pex_flags_t%22+could+be+improved">report issue</a>]</span>



pex_flags_t
-----------

Declared in "`libtorrent/pex_flags.hpp`__"


__ include/libtorrent/pex_flags.hpp

.. raw:: html

	<a name="pex_flags_t::pex_encryption"></a>

pex_encryption
	the peer supports protocol encryption
	


.. raw:: html

	<a name="pex_flags_t::pex_seed"></a>

pex_seed
	the peer is a seed
	


.. raw:: html

	<a name="pex_flags_t::pex_utp"></a>

pex_utp
	the peer supports the uTP, transport protocol over UDP.
	


.. raw:: html

	<a name="pex_flags_t::pex_holepunch"></a>

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
	


.. raw:: html

	<a name="pex_flags_t::pex_lt_v2"></a>

pex_lt_v2
	protocol v2
	this is not a standard flag, it is only used internally
	



.. raw:: html

	<a name="int"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:int&labels=documentation&body=Documentation+under+heading+%22int%22+could+be+improved">report issue</a>]</span>



int
---

Declared in "`libtorrent/version.hpp`__"


__ include/libtorrent/version.hpp

.. raw:: html

	<a name="int::version_major"></a>

version_major
	the major, minor and tiny versions of libtorrent
	


.. raw:: html

	<a name="int::version_minor"></a>

version_minor
	the major, minor and tiny versions of libtorrent
	


.. raw:: html

	<a name="int::version_tiny"></a>

version_tiny
	the major, minor and tiny versions of libtorrent
	



.. raw:: html

	<a name="char const*"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:char+const%2A&labels=documentation&body=Documentation+under+heading+%22char+const%2A%22+could+be+improved">report issue</a>]</span>



char const*
-----------

Declared in "`libtorrent/version.hpp`__"


__ include/libtorrent/version.hpp

.. raw:: html

	<a name="char const*::version_str"></a>

version_str
	the libtorrent version in string form
	



.. raw:: html

	<a name="std::uint64_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:std%3A%3Auint64_t&labels=documentation&body=Documentation+under+heading+%22std%3A%3Auint64_t%22+could+be+improved">report issue</a>]</span>



std::uint64_t
-------------

Declared in "`libtorrent/version.hpp`__"


__ include/libtorrent/version.hpp

.. raw:: html

	<a name="std::uint64_t::version_revision"></a>

version_revision
	the git commit of this libtorrent version
	



.. raw:: html

	<a name="download_priority_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:download_priority_t&labels=documentation&body=Documentation+under+heading+%22download_priority_t%22+could+be+improved">report issue</a>]</span>



download_priority_t
-------------------

Declared in "`libtorrent/download_priority.hpp`__"


__ include/libtorrent/download_priority.hpp

.. raw:: html

	<a name="download_priority_t::dont_download"></a>

dont_download
	Don't download the file or piece. Partial pieces may still be downloaded when
	setting file priorities.
	


.. raw:: html

	<a name="download_priority_t::default_priority"></a>

default_priority
	The default priority for files and pieces.
	


.. raw:: html

	<a name="download_priority_t::low_priority"></a>

low_priority
	The lowest priority for files and pieces.
	


.. raw:: html

	<a name="download_priority_t::top_priority"></a>

top_priority
	The highest priority for files and pieces.
	





.. _`BEP 19`: https://www.bittorrent.org/beps/bep_0019.html
.. _extensions: manual-ref.html#extensions
.. _`BEP 3`: https://www.bittorrent.org/beps/bep_0003.html
.. _`BEP 38`: https://www.bittorrent.org/beps/bep_0038.html
.. _`BEP 42`: https://www.bittorrent.org/beps/bep_0042.html
.. _`BEP 17`: https://www.bittorrent.org/beps/bep_0017.html
.. _`rate based choking`: manual-ref.html#rate-based-choking

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:

.. code:: c++

	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);
	bencode(std::ostream_iterator<char>(out), t.generate());


.. raw:: html

	<a name="create_torrent"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+create_torrent&labels=documentation&body=Documentation+under+heading+%22class+create_torrent%22+could+be+improved">report issue</a>]</span>



create_torrent
--------------

Declared in "`libtorrent/create_torrent.hpp`__"


__ include/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()`__.


__ reference-Create_Torrents.html#generate()
__ reference-Bencoding.html#entry
__ reference-Bencoding.html#bencode()


.. parsed-literal::
	

	struct create_torrent
	{
	   explicit **create_torrent** (torrent\_info const& ti);
	   explicit **create_torrent** (file\_storage& fs, int piece\_size = 0
	      , create\_flags\_t flags = {});
	   entry **generate** () 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;
	   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;
	};

.. raw:: html

	<a name="create_torrent()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:create_torrent%3A%3A%5Bcreate_torrent%28%29%5D&labels=documentation&body=Documentation+under+heading+%22create_torrent%3A%3A%5Bcreate_torrent%28%29%5D%22+could+be+improved">report issue</a>]</span>



create_torrent()
................

.. parsed-literal::
	
	explicit **create_torrent** (torrent\_info const& ti);
	explicit **create_torrent** (file\_storage& fs, int piece\_size = 0
	      , create\_flags\_t flags = {});
	

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

.. warning::
	The `file_storage`__ and `torrent_info`__ objects must stay alive for the
	entire duration of the `create_torrent`__ object.

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


__ reference-Storage.html#file_storage
__ reference-Create_Torrents.html#create_torrent
__ reference-Create_Torrents.html#generate()
__ reference-Create_Torrents.html#create_torrent
__ reference-Create_Torrents.html#set_hash()
__ reference-Storage.html#file_storage
__ reference-Torrent_Info.html#torrent_info
__ reference-Create_Torrents.html#create_torrent

.. raw:: html

	<a name="generate()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:create_torrent%3A%3A%5Bgenerate%28%29%5D&labels=documentation&body=Documentation+under+heading+%22create_torrent%3A%3A%5Bgenerate%28%29%5D%22+could+be+improved">report issue</a>]</span>



generate()
..........

.. parsed-literal::
	
	entry **generate** () const;
	

This function will generate the .torrent file as a bencode tree. In order to
generate the flat file, use the `bencode()`__ function.

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


__ reference-Bencoding.html#bencode()
__ reference-Create_Torrents.html#set_hash()
__ reference-Create_Torrents.html#set_hash2()
__ reference-Create_Torrents.html#generate()

.. raw:: html

	<a name="files()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:create_torrent%3A%3A%5Bfiles%28%29%5D&labels=documentation&body=Documentation+under+heading+%22create_torrent%3A%3A%5Bfiles%28%29%5D%22+could+be+improved">report issue</a>]</span>



files()
.......

.. parsed-literal::
	
	file_storage const& **files** () const;
	

returns an immutable reference to the `file_storage`__ used to create
the torrent from.


__ reference-Storage.html#file_storage

.. raw:: html

	<a name="set_comment()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:create_torrent%3A%3A%5Bset_comment%28%29%5D&labels=documentation&body=Documentation+under+heading+%22create_torrent%3A%3A%5Bset_comment%28%29%5D%22+could+be+improved">report issue</a>]</span>



set_comment()
.............

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="set_creator()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:create_torrent%3A%3A%5Bset_creator%28%29%5D&labels=documentation&body=Documentation+under+heading+%22create_torrent%3A%3A%5Bset_creator%28%29%5D%22+could+be+improved">report issue</a>]</span>



set_creator()
.............

.. parsed-literal::
	
	void **set_creator** (char const\* str);
	

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



.. raw:: html

	<a name="set_creation_date()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:create_torrent%3A%3A%5Bset_creation_date%28%29%5D&labels=documentation&body=Documentation+under+heading+%22create_torrent%3A%3A%5Bset_creation_date%28%29%5D%22+could+be+improved">report issue</a>]</span>



set_creation_date()
...................

.. parsed-literal::
	
	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.


__ reference-Create_Torrents.html#create_torrent

.. raw:: html

	<a name="set_hash()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:create_torrent%3A%3A%5Bset_hash%28%29%5D&labels=documentation&body=Documentation+under+heading+%22create_torrent%3A%3A%5Bset_hash%28%29%5D%22+could+be+improved">report issue</a>]</span>



set_hash()
..........

.. parsed-literal::
	
	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.


__ reference-Create_Torrents.html#set_piece_hashes()
__ reference-Create_Torrents.html#generate()

.. raw:: html

	<a name="set_hash2()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:create_torrent%3A%3A%5Bset_hash2%28%29%5D&labels=documentation&body=Documentation+under+heading+%22create_torrent%3A%3A%5Bset_hash2%28%29%5D%22+could+be+improved">report issue</a>]</span>



set_hash2()
...........

.. parsed-literal::
	
	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.


__ reference-Storage.html#file_index_at_piece()
__ reference-Create_Torrents.html#generate()

.. raw:: html

	<a name="add_http_seed()"></a>
	<a name="add_url_seed()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:create_torrent%3A%3A%5Badd_http_seed%28%29+add_url_seed%28%29%5D&labels=documentation&body=Documentation+under+heading+%22create_torrent%3A%3A%5Badd_http_seed%28%29+add_url_seed%28%29%5D%22+could+be+improved">report issue</a>]</span>



add_http_seed() add_url_seed()
..............................

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="add_node()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:create_torrent%3A%3A%5Badd_node%28%29%5D&labels=documentation&body=Documentation+under+heading+%22create_torrent%3A%3A%5Badd_node%28%29%5D%22+could+be+improved">report issue</a>]</span>



add_node()
..........

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="add_tracker()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:create_torrent%3A%3A%5Badd_tracker%28%29%5D&labels=documentation&body=Documentation+under+heading+%22create_torrent%3A%3A%5Badd_tracker%28%29%5D%22+could+be+improved">report issue</a>]</span>



add_tracker()
.............

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="set_root_cert()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:create_torrent%3A%3A%5Bset_root_cert%28%29%5D&labels=documentation&body=Documentation+under+heading+%22create_torrent%3A%3A%5Bset_root_cert%28%29%5D%22+could+be+improved">report issue</a>]</span>



set_root_cert()
...............

.. parsed-literal::
	
	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.


__ manual-ref.html#ssl-torrents

.. raw:: html

	<a name="set_priv()"></a>
	<a name="priv()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:create_torrent%3A%3A%5Bset_priv%28%29+priv%28%29%5D&labels=documentation&body=Documentation+under+heading+%22create_torrent%3A%3A%5Bset_priv%28%29+priv%28%29%5D%22+could+be+improved">report issue</a>]</span>



set_priv() priv()
.................

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="num_pieces()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:create_torrent%3A%3A%5Bnum_pieces%28%29%5D&labels=documentation&body=Documentation+under+heading+%22create_torrent%3A%3A%5Bnum_pieces%28%29%5D%22+could+be+improved">report issue</a>]</span>



num_pieces()
............

.. parsed-literal::
	
	int **num_pieces** () const;
	

returns the number of pieces in the associated `file_storage`__ object.


__ reference-Storage.html#file_storage

.. raw:: html

	<a name="piece_size()"></a>
	<a name="piece_length()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:create_torrent%3A%3A%5Bpiece_size%28%29+piece_length%28%29%5D&labels=documentation&body=Documentation+under+heading+%22create_torrent%3A%3A%5Bpiece_size%28%29+piece_length%28%29%5D%22+could+be+improved">report issue</a>]</span>



piece_size() piece_length()
...........................

.. parsed-literal::
	
	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`__.


__ reference-Storage.html#file_storage

.. raw:: html

	<a name="add_collection()"></a>
	<a name="add_similar_torrent()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:create_torrent%3A%3A%5Badd_collection%28%29+add_similar_torrent%28%29%5D&labels=documentation&body=Documentation+under+heading+%22create_torrent%3A%3A%5Badd_collection%28%29+add_similar_torrent%28%29%5D%22+could+be+improved">report issue</a>]</span>



add_collection() add_similar_torrent()
......................................

.. parsed-literal::
	
	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`_.



.. raw:: html

	<a name="modification_time"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:create_torrent%3A%3A%5Bmodification_time%5D&labels=documentation&body=Documentation+under+heading+%22create_torrent%3A%3A%5Bmodification_time%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="symlinks"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:create_torrent%3A%3A%5Bsymlinks%5D&labels=documentation&body=Documentation+under+heading+%22create_torrent%3A%3A%5Bsymlinks%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="v2_only"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:create_torrent%3A%3A%5Bv2_only%5D&labels=documentation&body=Documentation+under+heading+%22create_torrent%3A%3A%5Bv2_only%5D%22+could+be+improved">report issue</a>]</span>


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.
	

__ reference-Create_Torrents.html#set_hash2()
__ reference-Create_Torrents.html#generate()
__ reference-Create_Torrents.html#set_hash()

.. raw:: html

	<a name="v1_only"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:create_torrent%3A%3A%5Bv1_only%5D&labels=documentation&body=Documentation+under+heading+%22create_torrent%3A%3A%5Bv1_only%5D%22+could+be+improved">report issue</a>]</span>


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.
	

__ reference-Create_Torrents.html#set_hash()
__ reference-Create_Torrents.html#generate()
__ reference-Create_Torrents.html#set_hash2()

.. raw:: html

	<a name="canonical_files"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:create_torrent%3A%3A%5Bcanonical_files%5D&labels=documentation&body=Documentation+under+heading+%22create_torrent%3A%3A%5Bcanonical_files%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="no_attributes"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:create_torrent%3A%3A%5Bno_attributes%5D&labels=documentation&body=Documentation+under+heading+%22create_torrent%3A%3A%5Bno_attributes%5D%22+could+be+improved">report issue</a>]</span>


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.
	

__ reference-Create_Torrents.html#add_files()

.. raw:: html

	<a name="add_files()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:add_files%28%29&labels=documentation&body=Documentation+under+heading+%22add_files%28%29%22+could+be+improved">report issue</a>]</span>



add_files()
-----------

Declared in "`libtorrent/create_torrent.hpp`__"


__ include/libtorrent/create_torrent.hpp

.. parsed-literal::
	
	void **add_files** (file\_storage& fs, std\:\:string const& file
	   , std\:\:function<bool(std\:\:string)> p, create\_flags\_t flags = {});
	void **add_files** (file\_storage& fs, std\:\:string const& file
	   , 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:

.. code:: c++

	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.


__ reference-Storage.html#file_storage

.. raw:: html

	<a name="set_piece_hashes()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:set_piece_hashes%28%29&labels=documentation&body=Documentation+under+heading+%22set_piece_hashes%28%29%22+could+be+improved">report issue</a>]</span>



set_piece_hashes()
------------------

Declared in "`libtorrent/create_torrent.hpp`__"


__ include/libtorrent/create_torrent.hpp

.. parsed-literal::
	
	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);
	inline void **set_piece_hashes** (create\_torrent& t, std\:\:string const& p);
	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);
	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, 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:

.. code:: c++

	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.


__ reference-Settings.html#settings_pack



.. _`BEP 19`: https://www.bittorrent.org/beps/bep_0019.html
.. _extensions: manual-ref.html#extensions
.. _`BEP 3`: https://www.bittorrent.org/beps/bep_0003.html
.. _`BEP 38`: https://www.bittorrent.org/beps/bep_0038.html
.. _`BEP 42`: https://www.bittorrent.org/beps/bep_0042.html
.. _`BEP 17`: https://www.bittorrent.org/beps/bep_0017.html
.. _`rate based choking`: manual-ref.html#rate-based-choking

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.

.. raw:: html

	<a name="entry"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+entry&labels=documentation&body=Documentation+under+heading+%22class+entry%22+could+be+improved">report issue</a>]</span>



entry
-----

Declared in "`libtorrent/entry.hpp`__"


__ reference-Alerts.html#int
__ reference-Session.html#session
__ reference-Bdecoding.html#bdecode()
__ reference-Bdecoding.html#bdecode_node
__ reference-Bdecoding.html#bdecode_node
__ reference-Bencoding.html#entry
__ reference-Bdecoding.html#bdecode_node
__ include/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.




.. parsed-literal::
	

	class entry
	{
	   data_type **type** () const;
	   **entry** (list\_type);
	   **entry** (dictionary\_type);
	   **entry** (span<char const>);
	   **entry** (preformatted\_type);
	   **entry** (integer\_type);
	   **entry** (U v);
	   **entry** (data\_type t);
	   **entry** (bdecode\_node const& n);
	   entry& **operator=** (list\_type) &;
	   entry& **operator=** (integer\_type) &;
	   entry& **operator=** (span<char const>) &;
	   entry& **operator=** (entry const&) &;
	   entry& **operator=** (preformatted\_type) &;
	   entry& **operator=** (dictionary\_type) &;
	   entry& **operator=** (entry&&) & noexcept;
	   entry& **operator=** (bdecode\_node const&) &;
	   entry& **operator=** (U v) &;
	   dictionary_type& **dict** ();
	   integer_type const& **integer** () const;
	   list_type& **list** ();
	   integer_type& **integer** ();
	   preformatted_type& **preformatted** ();
	   list_type const& **list** () const;
	   string_type const& **string** () const;
	   dictionary_type const& **dict** () const;
	   preformatted_type const& **preformatted** () const;
	   string_type& **string** ();
	   void **swap** (entry& e);
	   entry& **operator[]** (string\_view key);
	   entry const& **operator[]** (string\_view key) const;
	   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,
	   };
	};

.. raw:: html

	<a name="type()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:entry%3A%3A%5Btype%28%29%5D&labels=documentation&body=Documentation+under+heading+%22entry%3A%3A%5Btype%28%29%5D%22+could+be+improved">report issue</a>]</span>



type()
......

.. parsed-literal::
	
	data_type **type** () const;
	

returns the concrete type of the `entry`__


__ reference-Bencoding.html#entry

.. raw:: html

	<a name="entry()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:entry%3A%3A%5Bentry%28%29%5D&labels=documentation&body=Documentation+under+heading+%22entry%3A%3A%5Bentry%28%29%5D%22+could+be+improved">report issue</a>]</span>



entry()
.......

.. parsed-literal::
	
	**entry** (list\_type);
	**entry** (dictionary\_type);
	**entry** (span<char const>);
	**entry** (preformatted\_type);
	**entry** (integer\_type);
	

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


__ reference-Bencoding.html#entry

.. raw:: html

	<a name="entry()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:entry%3A%3A%5Bentry%28%29%5D&labels=documentation&body=Documentation+under+heading+%22entry%3A%3A%5Bentry%28%29%5D%22+could+be+improved">report issue</a>]</span>



entry()
.......

.. parsed-literal::
	
	**entry** (data\_type t);
	

construct an empty `entry`__ of the specified type.
see `data_type`__ enum.


__ reference-Bencoding.html#entry
__ reference-Bencoding.html#data_type

.. raw:: html

	<a name="entry()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:entry%3A%3A%5Bentry%28%29%5D&labels=documentation&body=Documentation+under+heading+%22entry%3A%3A%5Bentry%28%29%5D%22+could+be+improved">report issue</a>]</span>



entry()
.......

.. parsed-literal::
	
	**entry** (bdecode\_node const& n);
	

construct from `bdecode_node`__ parsed form (see `bdecode()`__)


__ reference-Bdecoding.html#bdecode_node
__ reference-Bdecoding.html#bdecode()

.. raw:: html

	<a name="operator=()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:entry%3A%3A%5Boperator%3D%28%29%5D&labels=documentation&body=Documentation+under+heading+%22entry%3A%3A%5Boperator%3D%28%29%5D%22+could+be+improved">report issue</a>]</span>



operator=()
...........

.. parsed-literal::
	
	entry& **operator=** (list\_type) &;
	entry& **operator=** (integer\_type) &;
	entry& **operator=** (span<char const>) &;
	entry& **operator=** (entry const&) &;
	entry& **operator=** (preformatted\_type) &;
	entry& **operator=** (dictionary\_type) &;
	entry& **operator=** (entry&&) & noexcept;
	entry& **operator=** (bdecode\_node const&) &;
	

copies the structure of the right hand side into this
`entry`__.


__ reference-Bencoding.html#entry

.. raw:: html

	<a name="integer()"></a>
	<a name="preformatted()"></a>
	<a name="string()"></a>
	<a name="list()"></a>
	<a name="dict()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:entry%3A%3A%5Binteger%28%29+preformatted%28%29+string%28%29+list%28%29+dict%28%29%5D&labels=documentation&body=Documentation+under+heading+%22entry%3A%3A%5Binteger%28%29+preformatted%28%29+string%28%29+list%28%29+dict%28%29%5D%22+could+be+improved">report issue</a>]</span>



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

.. parsed-literal::
	
	dictionary_type& **dict** ();
	integer_type const& **integer** () const;
	list_type& **list** ();
	integer_type& **integer** ();
	preformatted_type& **preformatted** ();
	list_type const& **list** () const;
	string_type const& **string** () const;
	dictionary_type const& **dict** () const;
	preformatted_type const& **preformatted** () const;
	string_type& **string** ();
	

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:

.. code:: c++

	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:

.. code:: c++

	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.


__ reference-Torrent_Info.html#torrent_info

.. raw:: html

	<a name="swap()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:entry%3A%3A%5Bswap%28%29%5D&labels=documentation&body=Documentation+under+heading+%22entry%3A%3A%5Bswap%28%29%5D%22+could+be+improved">report issue</a>]</span>



swap()
......

.. parsed-literal::
	
	void **swap** (entry& e);
	

swaps the content of *this* with ``e``.



.. raw:: html

	<a name="operator[]()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:entry%3A%3A%5Boperator%5B%5D%28%29%5D&labels=documentation&body=Documentation+under+heading+%22entry%3A%3A%5Boperator%5B%5D%28%29%5D%22+could+be+improved">report issue</a>]</span>



operator[]()
............

.. parsed-literal::
	
	entry& **operator[]** (string\_view key);
	entry const& **operator[]** (string\_view key) const;
	

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


__ reference-Bencoding.html#entry

.. raw:: html

	<a name="find_key()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:entry%3A%3A%5Bfind_key%28%29%5D&labels=documentation&body=Documentation+under+heading+%22entry%3A%3A%5Bfind_key%28%29%5D%22+could+be+improved">report issue</a>]</span>



find_key()
..........

.. parsed-literal::
	
	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.


__ reference-Bencoding.html#entry

.. raw:: html

	<a name="to_string()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:entry%3A%3A%5Bto_string%28%29%5D&labels=documentation&body=Documentation+under+heading+%22entry%3A%3A%5Bto_string%28%29%5D%22+could+be+improved">report issue</a>]</span>



to_string()
...........

.. parsed-literal::
	
	std::string **to_string** (bool single\_line = false) const;
	

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



.. raw:: html

	<a name="data_type"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+data_type&labels=documentation&body=Documentation+under+heading+%22enum+data_type%22+could+be+improved">report issue</a>]</span>



enum data_type
..............

Declared in "`libtorrent/entry.hpp`__"


__ include/libtorrent/entry.hpp

+----------------+-------+-------------+
| name           | value | description |
+================+=======+=============+
| int_t          | 0     |             |
+----------------+-------+-------------+
| string_t       | 1     |             |
+----------------+-------+-------------+
| list_t         | 2     |             |
+----------------+-------+-------------+
| dictionary_t   | 3     |             |
+----------------+-------+-------------+
| undefined_t    | 4     |             |
+----------------+-------+-------------+
| preformatted_t | 5     |             |
+----------------+-------+-------------+



.. raw:: html

	<a name="bencode()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:bencode%28%29&labels=documentation&body=Documentation+under+heading+%22bencode%28%29%22+could+be+improved">report issue</a>]</span>



bencode()
---------

Declared in "`libtorrent/bencode.hpp`__"


__ include/libtorrent/bencode.hpp

.. parsed-literal::
	
	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);

.. _OutputIterator:  https://en.cppreference.com/w/cpp/named_req/OutputIterator
.. _ostream_iterator: https://en.cppreference.com/w/cpp/iterator/ostream_iterator
.. _back_insert_iterator: https://en.cppreference.com/w/cpp/iterator/back_insert_iterator


__ reference-Bencoding.html#entry

.. raw:: html

	<a name="operator<<()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:operator%3C%3C%28%29&labels=documentation&body=Documentation+under+heading+%22operator%3C%3C%28%29%22+could+be+improved">report issue</a>]</span>



operator<<()
------------

Declared in "`libtorrent/entry.hpp`__"


__ include/libtorrent/entry.hpp

.. parsed-literal::
	
	inline std::ostream& **operator<<** (std\:\:ostream& os, const entry& e);
	

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





.. _`BEP 19`: https://www.bittorrent.org/beps/bep_0019.html
.. _extensions: manual-ref.html#extensions
.. _`BEP 3`: https://www.bittorrent.org/beps/bep_0003.html
.. _`BEP 38`: https://www.bittorrent.org/beps/bep_0038.html
.. _`BEP 42`: https://www.bittorrent.org/beps/bep_0042.html
.. _`BEP 17`: https://www.bittorrent.org/beps/bep_0017.html
.. _`rate based choking`: manual-ref.html#rate-based-choking
.. raw:: html

	<a name="peer_class_type_filter"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+peer_class_type_filter&labels=documentation&body=Documentation+under+heading+%22class+peer_class_type_filter%22+could+be+improved">report issue</a>]</span>



peer_class_type_filter
----------------------

Declared in "`libtorrent/peer_class_type_filter.hpp`__"


__ include/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).




.. parsed-literal::
	

	struct peer_class_type_filter
	{
	   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);
	
	   enum socket_type_t
	   {
	      tcp_socket,
	      utp_socket,
	      ssl_tcp_socket,
	      ssl_utp_socket,
	      i2p_socket,
	      num_socket_types,
	   };
	};

.. raw:: html

	<a name="remove()"></a>
	<a name="add()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_class_type_filter%3A%3A%5Bremove%28%29+add%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_class_type_filter%3A%3A%5Bremove%28%29+add%28%29%5D%22+could+be+improved">report issue</a>]</span>



remove() add()
..............

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="allow()"></a>
	<a name="disallow()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_class_type_filter%3A%3A%5Ballow%28%29+disallow%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_class_type_filter%3A%3A%5Ballow%28%29+disallow%28%29%5D%22+could+be+improved">report issue</a>]</span>



allow() disallow()
..................

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="apply()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_class_type_filter%3A%3A%5Bapply%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_class_type_filter%3A%3A%5Bapply%28%29%5D%22+could+be+improved">report issue</a>]</span>



apply()
.......

.. parsed-literal::
	
	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``).



.. raw:: html

	<a name="socket_type_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+socket_type_t&labels=documentation&body=Documentation+under+heading+%22enum+socket_type_t%22+could+be+improved">report issue</a>]</span>



enum socket_type_t
..................

Declared in "`libtorrent/peer_class_type_filter.hpp`__"


__ include/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     |                                                   |
+------------------+-------+---------------------------------------------------+



.. raw:: html

	<a name="peer_class_info"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+peer_class_info&labels=documentation&body=Documentation+under+heading+%22class+peer_class_info%22+could+be+improved">report issue</a>]</span>



peer_class_info
---------------

Declared in "`libtorrent/peer_class.hpp`__"


__ include/libtorrent/peer_class.hpp

holds settings for a peer class. Used in `set_peer_class()`__ and
`get_peer_class()`__ calls.


__ reference-Session.html#set_peer_class()
__ reference-Session.html#get_peer_class()


.. parsed-literal::
	

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

.. raw:: html

	<a name="ignore_unchoke_slots"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_class_info%3A%3A%5Bignore_unchoke_slots%5D&labels=documentation&body=Documentation+under+heading+%22peer_class_info%3A%3A%5Bignore_unchoke_slots%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="connection_limit_factor"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_class_info%3A%3A%5Bconnection_limit_factor%5D&labels=documentation&body=Documentation+under+heading+%22peer_class_info%3A%3A%5Bconnection_limit_factor%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="label"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_class_info%3A%3A%5Blabel%5D&labels=documentation&body=Documentation+under+heading+%22peer_class_info%3A%3A%5Blabel%5D%22+could+be+improved">report issue</a>]</span>


label
	not used by libtorrent. It's intended as a potentially user-facing
	identifier of this peer class.
	


.. raw:: html

	<a name="upload_limit"></a>
	<a name="download_limit"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_class_info%3A%3A%5Bupload_limit+download_limit%5D&labels=documentation&body=Documentation+under+heading+%22peer_class_info%3A%3A%5Bupload_limit+download_limit%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="upload_priority"></a>
	<a name="download_priority"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_class_info%3A%3A%5Bupload_priority+download_priority%5D&labels=documentation&body=Documentation+under+heading+%22peer_class_info%3A%3A%5Bupload_priority+download_priority%5D%22+could+be+improved">report issue</a>]</span>


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.
	




.. _`BEP 19`: https://www.bittorrent.org/beps/bep_0019.html
.. _extensions: manual-ref.html#extensions
.. _`BEP 3`: https://www.bittorrent.org/beps/bep_0003.html
.. _`BEP 38`: https://www.bittorrent.org/beps/bep_0038.html
.. _`BEP 42`: https://www.bittorrent.org/beps/bep_0042.html
.. _`BEP 17`: https://www.bittorrent.org/beps/bep_0017.html
.. _`rate based choking`: manual-ref.html#rate-based-choking

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
posting alerts. Only alerts that belong to an enabled category are
posted. Setting the `alert`__ bitmask to 0 will disable all alerts (except those
that are non-discardable). Alerts that are responses to API calls such as
`save_resume_data()`__ and `post_session_stats()`__ are non-discardable and will be
posted even if their category is disabled.

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.

.. raw:: html

	<a name="dht_routing_bucket"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+dht_routing_bucket&labels=documentation&body=Documentation+under+heading+%22class+dht_routing_bucket%22+could+be+improved">report issue</a>]</span>



dht_routing_bucket
------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ reference-Session.html#pop_alerts()
__ reference-Session.html#session
__ reference-Session.html#pop_alerts()
__ reference-Settings.html#alert_mask
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert_category_t
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Torrent_Handle.html#save_resume_data()
__ reference-Session.html#post_session_stats()
__ reference-Alerts.html#alert
__ reference-Alerts.html#torrent_alert
__ reference-Alerts.html#tracker_alert
__ reference-Session.html#pop_alerts()
__ reference-Session.html#pop_alerts()
__ reference-Alerts.html#alert
__ reference-Session.html#pop_alerts()
__ reference-Session.html#pop_alerts()
__ include/libtorrent/alert_types.hpp

struct to hold information about a single DHT routing table bucket




.. parsed-literal::
	

	struct dht_routing_bucket
	{
	   int num_nodes;
	   int num_replacements;
	   int last_active;
	};

.. raw:: html

	<a name="num_nodes"></a>
	<a name="num_replacements"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_routing_bucket%3A%3A%5Bnum_nodes+num_replacements%5D&labels=documentation&body=Documentation+under+heading+%22dht_routing_bucket%3A%3A%5Bnum_nodes+num_replacements%5D%22+could+be+improved">report issue</a>]</span>


num_nodes num_replacements
	the total number of nodes and replacement nodes
	in the routing table
	


.. raw:: html

	<a name="last_active"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_routing_bucket%3A%3A%5Blast_active%5D&labels=documentation&body=Documentation+under+heading+%22dht_routing_bucket%3A%3A%5Blast_active%5D%22+could+be+improved">report issue</a>]</span>


last_active
	number of seconds since last activity
	


.. raw:: html

	<a name="torrent_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+torrent_alert&labels=documentation&body=Documentation+under+heading+%22class+torrent_alert%22+could+be+improved">report issue</a>]</span>



torrent_alert
-------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This is a base class for alerts that are associated with a
specific torrent. It contains a handle to the torrent.

Note that by the time the client receives a `torrent_alert`__, its
``handle`` member may be invalid.


__ reference-Alerts.html#torrent_alert


.. parsed-literal::
	

	struct torrent_alert : alert
	{
	   std::string **message** () const override;
	   char const* **torrent_name** () const;
	
	   torrent_handle handle;
	};

.. raw:: html

	<a name="message()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_alert%3A%3A%5Bmessage%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_alert%3A%3A%5Bmessage%28%29%5D%22+could+be+improved">report issue</a>]</span>



message()
.........

.. parsed-literal::
	
	std::string **message** () const override;
	

returns the message associated with this `alert`__


__ reference-Alerts.html#alert

.. raw:: html

	<a name="handle"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_alert%3A%3A%5Bhandle%5D&labels=documentation&body=Documentation+under+heading+%22torrent_alert%3A%3A%5Bhandle%5D%22+could+be+improved">report issue</a>]</span>


handle
	The `torrent_handle`__ pointing to the torrent this
	`alert`__ is associated with.
	

__ reference-Torrent_Handle.html#torrent_handle
__ reference-Alerts.html#alert

.. raw:: html

	<a name="peer_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+peer_alert&labels=documentation&body=Documentation+under+heading+%22class+peer_alert%22+could+be+improved">report issue</a>]</span>



peer_alert
----------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

The peer `alert`__ is a base class for alerts that refer to a specific peer. It includes all
the information to identify the peer. i.e. ``ip`` and ``peer-id``.


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct peer_alert : torrent_alert
	{
	   std::string **message** () const override;
	
	   aux::noexcept_movable<tcp::endpoint> endpoint;
	   peer_id pid;
	};

.. raw:: html

	<a name="endpoint"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_alert%3A%3A%5Bendpoint%5D&labels=documentation&body=Documentation+under+heading+%22peer_alert%3A%3A%5Bendpoint%5D%22+could+be+improved">report issue</a>]</span>


endpoint
	The peer's IP address and port.
	


.. raw:: html

	<a name="pid"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_alert%3A%3A%5Bpid%5D&labels=documentation&body=Documentation+under+heading+%22peer_alert%3A%3A%5Bpid%5D%22+could+be+improved">report issue</a>]</span>


pid
	the peer ID, if known.
	


.. raw:: html

	<a name="tracker_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+tracker_alert&labels=documentation&body=Documentation+under+heading+%22class+tracker_alert%22+could+be+improved">report issue</a>]</span>



tracker_alert
-------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This is a base class used for alerts that are associated with a
specific tracker. It derives from `torrent_alert`__ since a tracker
is also associated with a specific torrent.


__ reference-Alerts.html#torrent_alert


.. parsed-literal::
	

	struct tracker_alert : torrent_alert
	{
	   std::string **message** () const override;
	   char const* **tracker_url** () const;
	
	   aux::noexcept_movable<tcp::endpoint> local_endpoint;
	};

.. raw:: html

	<a name="tracker_url()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:tracker_alert%3A%3A%5Btracker_url%28%29%5D&labels=documentation&body=Documentation+under+heading+%22tracker_alert%3A%3A%5Btracker_url%28%29%5D%22+could+be+improved">report issue</a>]</span>



tracker_url()
.............

.. parsed-literal::
	
	char const* **tracker_url** () const;
	

returns a 0-terminated string of the tracker's URL



.. raw:: html

	<a name="local_endpoint"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:tracker_alert%3A%3A%5Blocal_endpoint%5D&labels=documentation&body=Documentation+under+heading+%22tracker_alert%3A%3A%5Blocal_endpoint%5D%22+could+be+improved">report issue</a>]</span>


local_endpoint
	endpoint of the listen interface being announced
	


.. raw:: html

	<a name="torrent_removed_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+torrent_removed_alert&labels=documentation&body=Documentation+under+heading+%22class+torrent_removed_alert%22+could+be+improved">report issue</a>]</span>



torrent_removed_alert
---------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

The ``torrent_removed_alert`` is posted whenever a torrent is removed. Since
the torrent handle in its base class will usually be invalid (since the torrent
is already removed) it has the info hash as a member, to identify it.
It's posted when the ``alert_category::status`` bit is set in the alert_mask.

Note that the ``handle`` remains valid for some time after
`torrent_removed_alert`__ is posted, as long as some internal libtorrent
task (such as an I/O task) refers to it. Additionally, other alerts like
`save_resume_data_alert`__ may be posted after `torrent_removed_alert`__.
To synchronize on whether the torrent has been removed or not, call
`torrent_handle::in_session()`__. This will return true before
`torrent_removed_alert`__ is posted, and false afterward.

Even though the ``handle`` member doesn't point to an existing torrent anymore,
it is still useful for comparing to other handles, which may also no
longer point to existing torrents, but to the same non-existing torrents.

The ``torrent_handle`` acts as a ``weak_ptr``, even though its object no
longer exists, it can still compare equal to another weak pointer which
points to the same non-existent object.


__ reference-Alerts.html#torrent_removed_alert
__ reference-Alerts.html#save_resume_data_alert
__ reference-Alerts.html#torrent_removed_alert
__ reference-Torrent_Handle.html#in_session()
__ reference-Alerts.html#torrent_removed_alert


.. parsed-literal::
	

	struct torrent_removed_alert final : torrent_alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::status;
	   info_hash_t info_hashes;
	   client_data_t userdata;
	};

.. raw:: html

	<a name="userdata"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_removed_alert%3A%3A%5Buserdata%5D&labels=documentation&body=Documentation+under+heading+%22torrent_removed_alert%3A%3A%5Buserdata%5D%22+could+be+improved">report issue</a>]</span>


userdata
	'`userdata`` as set in `add_torrent_params`__ at torrent creation.
	This can be used to associate this torrent with related data
	in the client application more efficiently than info_hashes.
	

__ reference-Add_Torrent.html#add_torrent_params

.. raw:: html

	<a name="read_piece_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+read_piece_alert&labels=documentation&body=Documentation+under+heading+%22class+read_piece_alert%22+could+be+improved">report issue</a>]</span>



read_piece_alert
----------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is posted when the asynchronous read operation initiated by
a call to `torrent_handle::read_piece()`__ is completed. If the read failed, the torrent
is paused and an error state is set and the buffer member of the `alert`__
is 0. If successful, ``buffer`` points to a buffer containing all the data
of the piece. ``piece`` is the piece index that was read. ``size`` is the
number of bytes that was read.

If the operation fails, ``error`` will indicate what went wrong.


__ reference-Alerts.html#alert
__ reference-Torrent_Handle.html#read_piece()
__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct read_piece_alert final : torrent_alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::storage;
	   error_code const error;
	   boost::shared_array<char> const buffer;
	   piece_index_t const piece;
	   int const size;
	};

.. raw:: html

	<a name="file_completed_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+file_completed_alert&labels=documentation&body=Documentation+under+heading+%22class+file_completed_alert%22+could+be+improved">report issue</a>]</span>



file_completed_alert
--------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This is posted whenever an individual file completes its download. i.e.
All pieces overlapping this file have passed their hash check.




.. parsed-literal::
	

	struct file_completed_alert final : torrent_alert
	{
	   std::string **message** () const override;
	
	   file_index_t const index;
	};

.. raw:: html

	<a name="index"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_completed_alert%3A%3A%5Bindex%5D&labels=documentation&body=Documentation+under+heading+%22file_completed_alert%3A%3A%5Bindex%5D%22+could+be+improved">report issue</a>]</span>


index
	refers to the index of the file that completed.
	


.. raw:: html

	<a name="file_renamed_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+file_renamed_alert&labels=documentation&body=Documentation+under+heading+%22class+file_renamed_alert%22+could+be+improved">report issue</a>]</span>



file_renamed_alert
------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This is posted as a response to a `torrent_handle::rename_file()`__ call, if the rename
operation succeeds.


__ reference-Torrent_Handle.html#rename_file()


.. parsed-literal::
	

	struct file_renamed_alert final : torrent_alert
	{
	   std::string **message** () const override;
	   char const* **old_name** () const;
	   char const* **new_name** () const;
	
	   static constexpr alert_category_t **static_category**  = alert_category::storage;
	   file_index_t const index;
	};

.. raw:: html

	<a name="new_name()"></a>
	<a name="old_name()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_renamed_alert%3A%3A%5Bnew_name%28%29+old_name%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_renamed_alert%3A%3A%5Bnew_name%28%29+old_name%28%29%5D%22+could+be+improved">report issue</a>]</span>



new_name() old_name()
.....................

.. parsed-literal::
	
	char const* **old_name** () const;
	char const* **new_name** () const;
	

returns the new and previous file name, respectively.



.. raw:: html

	<a name="index"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_renamed_alert%3A%3A%5Bindex%5D&labels=documentation&body=Documentation+under+heading+%22file_renamed_alert%3A%3A%5Bindex%5D%22+could+be+improved">report issue</a>]</span>


index
	refers to the index of the file that was renamed,
	


.. raw:: html

	<a name="file_rename_failed_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+file_rename_failed_alert&labels=documentation&body=Documentation+under+heading+%22class+file_rename_failed_alert%22+could+be+improved">report issue</a>]</span>



file_rename_failed_alert
------------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This is posted as a response to a `torrent_handle::rename_file()`__ call, if the rename
operation failed.


__ reference-Torrent_Handle.html#rename_file()


.. parsed-literal::
	

	struct file_rename_failed_alert final : torrent_alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::storage;
	   file_index_t const index;
	   error_code const error;
	};

.. raw:: html

	<a name="index"></a>
	<a name="error"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_rename_failed_alert%3A%3A%5Bindex+error%5D&labels=documentation&body=Documentation+under+heading+%22file_rename_failed_alert%3A%3A%5Bindex+error%5D%22+could+be+improved">report issue</a>]</span>


index error
	refers to the index of the file that was supposed to be renamed,
	``error`` is the error code returned from the filesystem.
	


.. raw:: html

	<a name="performance_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+performance_alert&labels=documentation&body=Documentation+under+heading+%22class+performance_alert%22+could+be+improved">report issue</a>]</span>



performance_alert
-----------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is generated when a limit is reached that might have a negative impact on
upload or download rate performance.


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct performance_alert final : torrent_alert
	{
	   std::string **message** () const override;
	
	   enum performance_warning_t
	   {
	      outstanding_disk_buffer_limit_reached,
	      outstanding_request_limit_reached,
	      upload_limit_too_low,
	      download_limit_too_low,
	      send_buffer_watermark_too_low,
	      too_many_optimistic_unchoke_slots,
	      too_high_disk_queue_limit,
	      aio_limit_reached,
	      deprecated_bittyrant_with_no_uplimit,
	      too_few_outgoing_ports,
	      too_few_file_descriptors,
	      num_warnings,
	   };
	
	   static constexpr alert_category_t **static_category**  = alert_category::performance_warning;
	   performance_warning_t const warning_code;
	};

.. raw:: html

	<a name="performance_warning_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+performance_warning_t&labels=documentation&body=Documentation+under+heading+%22enum+performance_warning_t%22+could+be+improved">report issue</a>]</span>



enum performance_warning_t
..........................

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

+---------------------------------------+-------+-------------------------------------------------------------------------------------------------+
| name                                  | value | description                                                                                     |
+=======================================+=======+=================================================================================================+
| outstanding_disk_buffer_limit_reached | 0     | This warning means that the number of bytes queued to be written to disk                        |
|                                       |       | exceeds the max disk byte queue setting (``settings_pack::max_queued_disk_bytes``).             |
|                                       |       | This might restrict the download rate, by not queuing up enough write jobs                      |
|                                       |       | to the disk I/O thread. When this `alert`__ is posted, peer connections are                     |
|                                       |       | temporarily stopped from downloading, until the queued disk bytes have fallen                   |
|                                       |       | below the limit again. Unless your ``max_queued_disk_bytes`` setting is already                 |
|                                       |       | high, you might want to increase it to get better performance.                                  |
|                                       |       |                                                                                                 |
+---------------------------------------+-------+-------------------------------------------------------------------------------------------------+
| outstanding_request_limit_reached     | 1     | This is posted when libtorrent would like to send more requests to a peer,                      |
|                                       |       | but it's limited by ``settings_pack::max_out_request_queue``. The queue length                  |
|                                       |       | libtorrent is trying to achieve is determined by the download rate and the                      |
|                                       |       | assumed round-trip-time (``settings_pack::request_queue_time``). The assumed                    |
|                                       |       | round-trip-time is not limited to just the network RTT, but also the remote disk                |
|                                       |       | access time and message handling time. It defaults to 3 seconds. The target number              |
|                                       |       | of outstanding requests is set to fill the bandwidth-delay product (assumed RTT                 |
|                                       |       | times download rate divided by number of bytes per request). When this `alert`__                |
|                                       |       | is posted, there is a risk that the number of outstanding requests is too low                   |
|                                       |       | and limits the download rate. You might want to increase the ``max_out_request_queue``          |
|                                       |       | setting.                                                                                        |
|                                       |       |                                                                                                 |
+---------------------------------------+-------+-------------------------------------------------------------------------------------------------+
| upload_limit_too_low                  | 2     | This warning is posted when the amount of TCP/IP overhead is greater than the                   |
|                                       |       | upload rate limit. When this happens, the TCP/IP overhead is caused by a much                   |
|                                       |       | faster download rate, triggering TCP ACK packets. These packets eat into the                    |
|                                       |       | rate limit specified to libtorrent. When the overhead traffic is greater than                   |
|                                       |       | the rate limit, libtorrent will not be able to send any actual payload, such                    |
|                                       |       | as piece requests. This means the download rate will suffer, and new requests                   |
|                                       |       | can be sent again. There will be an equilibrium where the download rate, on                     |
|                                       |       | average, is about 20 times the upload rate limit. If you want to maximize the                   |
|                                       |       | download rate, increase the upload rate limit above 5% of your download capacity.               |
|                                       |       |                                                                                                 |
+---------------------------------------+-------+-------------------------------------------------------------------------------------------------+
| download_limit_too_low                | 3     | This is the same warning as ``upload_limit_too_low`` but referring to the download              |
|                                       |       | limit instead of upload. This suggests that your download rate limit is much lower              |
|                                       |       | than your upload capacity. Your upload rate will suffer. To maximize upload rate,               |
|                                       |       | make sure your download rate limit is above 5% of your upload capacity.                         |
|                                       |       |                                                                                                 |
+---------------------------------------+-------+-------------------------------------------------------------------------------------------------+
| send_buffer_watermark_too_low         | 4     | We're stalled on the disk. We want to write to the socket, and we can write                     |
|                                       |       | but our send buffer is empty, waiting to be refilled from the disk.                             |
|                                       |       | This either means the disk is slower than the network connection                                |
|                                       |       | or that our send buffer watermark is too small, because we can                                  |
|                                       |       | send it all before the disk gets back to us.                                                    |
|                                       |       | The number of bytes that we keep outstanding, requested from the disk, is calculated            |
|                                       |       | as follows:                                                                                     |
|                                       |       |                                                                                                 |
|                                       |       | .. code:: C++                                                                                   |
|                                       |       |                                                                                                 |
|                                       |       |    min(512, max(upload_rate * send_buffer_watermark_factor / 100, send_buffer_watermark))       |
|                                       |       |                                                                                                 |
|                                       |       | If you receive this `alert`__, you might want to either increase your ``send_buffer_watermark`` |
|                                       |       | or ``send_buffer_watermark_factor``.                                                            |
|                                       |       |                                                                                                 |
+---------------------------------------+-------+-------------------------------------------------------------------------------------------------+
| too_many_optimistic_unchoke_slots     | 5     | If the half (or more) of all upload slots are set as optimistic unchoke slots, this             |
|                                       |       | warning is issued. You probably want more regular (rate based) unchoke slots.                   |
|                                       |       |                                                                                                 |
+---------------------------------------+-------+-------------------------------------------------------------------------------------------------+
| too_high_disk_queue_limit             | 6     | If the disk write queue ever grows larger than half of the cache size, this warning             |
|                                       |       | is posted. The disk write queue eats into the total disk cache and leaves very little           |
|                                       |       | left for the actual cache. This causes the disk cache to oscillate in evicting large            |
|                                       |       | portions of the cache before allowing peers to download any more, onto the disk write           |
|                                       |       | queue. Either lower ``max_queued_disk_bytes`` or increase ``cache_size``.                       |
|                                       |       |                                                                                                 |
+---------------------------------------+-------+-------------------------------------------------------------------------------------------------+
| aio_limit_reached                     | 7     |                                                                                                 |
+---------------------------------------+-------+-------------------------------------------------------------------------------------------------+
| deprecated_bittyrant_with_no_uplimit  | 8     |                                                                                                 |
+---------------------------------------+-------+-------------------------------------------------------------------------------------------------+
| too_few_outgoing_ports                | 9     | This is generated if outgoing peer connections are failing because of *address in use*          |
|                                       |       | errors, indicating that ``settings_pack::outgoing_ports`` is set and is too small of            |
|                                       |       | a range. Consider not using the ``outgoing_ports`` setting at all, or widen the range to        |
|                                       |       | include more ports.                                                                             |
|                                       |       |                                                                                                 |
+---------------------------------------+-------+-------------------------------------------------------------------------------------------------+
| too_few_file_descriptors              | 10    |                                                                                                 |
+---------------------------------------+-------+-------------------------------------------------------------------------------------------------+
| num_warnings                          | 11    |                                                                                                 |
+---------------------------------------+-------+-------------------------------------------------------------------------------------------------+


__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert

.. raw:: html

	<a name="state_changed_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+state_changed_alert&labels=documentation&body=Documentation+under+heading+%22class+state_changed_alert%22+could+be+improved">report issue</a>]</span>



state_changed_alert
-------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

Generated whenever a torrent changes its state.




.. parsed-literal::
	

	struct state_changed_alert final : torrent_alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::status;
	   torrent_status::state_t const state;
	   torrent_status::state_t const prev_state;
	};

.. raw:: html

	<a name="state"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:state_changed_alert%3A%3A%5Bstate%5D&labels=documentation&body=Documentation+under+heading+%22state_changed_alert%3A%3A%5Bstate%5D%22+could+be+improved">report issue</a>]</span>


state
	the new state of the torrent.
	


.. raw:: html

	<a name="prev_state"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:state_changed_alert%3A%3A%5Bprev_state%5D&labels=documentation&body=Documentation+under+heading+%22state_changed_alert%3A%3A%5Bprev_state%5D%22+could+be+improved">report issue</a>]</span>


prev_state
	the previous state.
	


.. raw:: html

	<a name="tracker_error_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+tracker_error_alert&labels=documentation&body=Documentation+under+heading+%22class+tracker_error_alert%22+could+be+improved">report issue</a>]</span>



tracker_error_alert
-------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is generated on tracker time outs, premature disconnects,
invalid response or a HTTP response other than "200 OK". From the `alert`__
you can get the handle to the torrent the tracker belongs to.


__ reference-Alerts.html#alert
__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct tracker_error_alert final : tracker_alert
	{
	   std::string **message** () const override;
	   char const* **failure_reason** () const;
	
	   static constexpr alert_category_t **static_category**  = alert_category::tracker | alert_category::error;
	   int const times_in_row;
	   error_code const error;
	   operation_t op;
	};

.. raw:: html

	<a name="failure_reason()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:tracker_error_alert%3A%3A%5Bfailure_reason%28%29%5D&labels=documentation&body=Documentation+under+heading+%22tracker_error_alert%3A%3A%5Bfailure_reason%28%29%5D%22+could+be+improved">report issue</a>]</span>



failure_reason()
................

.. parsed-literal::
	
	char const* **failure_reason** () const;
	

if the tracker sent a "failure reason" string, it will be returned
here.



.. raw:: html

	<a name="times_in_row"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:tracker_error_alert%3A%3A%5Btimes_in_row%5D&labels=documentation&body=Documentation+under+heading+%22tracker_error_alert%3A%3A%5Btimes_in_row%5D%22+could+be+improved">report issue</a>]</span>


times_in_row
	This member says how many times in a row this tracker has failed.
	


.. raw:: html

	<a name="error"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:tracker_error_alert%3A%3A%5Berror%5D&labels=documentation&body=Documentation+under+heading+%22tracker_error_alert%3A%3A%5Berror%5D%22+could+be+improved">report issue</a>]</span>


error
	the error code indicating why the tracker announce failed. If it is
	is ``lt::errors::tracker_failure`` the `failure_reason()`__ might contain
	a more detailed description of why the tracker rejected the request.
	HTTP status codes indicating errors are also set in this field.
	

__ reference-Alerts.html#failure_reason()

.. raw:: html

	<a name="tracker_warning_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+tracker_warning_alert&labels=documentation&body=Documentation+under+heading+%22class+tracker_warning_alert%22+could+be+improved">report issue</a>]</span>



tracker_warning_alert
---------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is triggered if the tracker reply contains a warning field.
Usually this means that the tracker announce was successful, but the
tracker has a message to the client.


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct tracker_warning_alert final : tracker_alert
	{
	   std::string **message** () const override;
	   char const* **warning_message** () const;
	
	   static constexpr alert_category_t **static_category**  = alert_category::tracker | alert_category::error;
	};

.. raw:: html

	<a name="warning_message()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:tracker_warning_alert%3A%3A%5Bwarning_message%28%29%5D&labels=documentation&body=Documentation+under+heading+%22tracker_warning_alert%3A%3A%5Bwarning_message%28%29%5D%22+could+be+improved">report issue</a>]</span>



warning_message()
.................

.. parsed-literal::
	
	char const* **warning_message** () const;
	

the message associated with this warning



.. raw:: html

	<a name="scrape_reply_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+scrape_reply_alert&labels=documentation&body=Documentation+under+heading+%22class+scrape_reply_alert%22+could+be+improved">report issue</a>]</span>



scrape_reply_alert
------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is generated when a scrape request succeeds.


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct scrape_reply_alert final : tracker_alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::tracker;
	   int const incomplete;
	   int const complete;
	};

.. raw:: html

	<a name="incomplete"></a>
	<a name="complete"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:scrape_reply_alert%3A%3A%5Bincomplete+complete%5D&labels=documentation&body=Documentation+under+heading+%22scrape_reply_alert%3A%3A%5Bincomplete+complete%5D%22+could+be+improved">report issue</a>]</span>


incomplete complete
	the data returned in the scrape response. These numbers
	may be -1 if the response was malformed.
	


.. raw:: html

	<a name="scrape_failed_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+scrape_failed_alert&labels=documentation&body=Documentation+under+heading+%22class+scrape_failed_alert%22+could+be+improved">report issue</a>]</span>



scrape_failed_alert
-------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

If a scrape request fails, this `alert`__ is generated. This might be due
to the tracker timing out, refusing connection or returning an http response
code indicating an error.


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct scrape_failed_alert final : tracker_alert
	{
	   std::string **message** () const override;
	   char const* **error_message** () const;
	
	   static constexpr alert_category_t **static_category**  = alert_category::tracker | alert_category::error;
	   error_code const error;
	};

.. raw:: html

	<a name="error_message()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:scrape_failed_alert%3A%3A%5Berror_message%28%29%5D&labels=documentation&body=Documentation+under+heading+%22scrape_failed_alert%3A%3A%5Berror_message%28%29%5D%22+could+be+improved">report issue</a>]</span>



error_message()
...............

.. parsed-literal::
	
	char const* **error_message** () const;
	

if the error indicates there is an associated message, this returns
that message. Otherwise and empty string.



.. raw:: html

	<a name="error"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:scrape_failed_alert%3A%3A%5Berror%5D&labels=documentation&body=Documentation+under+heading+%22scrape_failed_alert%3A%3A%5Berror%5D%22+could+be+improved">report issue</a>]</span>


error
	the error itself. This may indicate that the tracker sent an error
	message (``error::tracker_failure``), in which case it can be
	retrieved by calling ``error_message()``.
	


.. raw:: html

	<a name="tracker_reply_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+tracker_reply_alert&labels=documentation&body=Documentation+under+heading+%22class+tracker_reply_alert%22+could+be+improved">report issue</a>]</span>



tracker_reply_alert
-------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is only for informational purpose. It is generated when a tracker announce
succeeds. It is generated regardless what kind of tracker was used, be it UDP, HTTP or
the DHT.


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct tracker_reply_alert final : tracker_alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::tracker;
	   int const num_peers;
	};

.. raw:: html

	<a name="num_peers"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:tracker_reply_alert%3A%3A%5Bnum_peers%5D&labels=documentation&body=Documentation+under+heading+%22tracker_reply_alert%3A%3A%5Bnum_peers%5D%22+could+be+improved">report issue</a>]</span>


num_peers
	tells how many peers the tracker returned in this response. This is
	not expected to be greater than the ``num_want`` settings. These are not necessarily
	all new peers, some of them may already be connected.
	


.. raw:: html

	<a name="dht_reply_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+dht_reply_alert&labels=documentation&body=Documentation+under+heading+%22class+dht_reply_alert%22+could+be+improved">report issue</a>]</span>



dht_reply_alert
---------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is generated each time the DHT receives peers from a node. ``num_peers``
is the number of peers we received in this packet. Typically these packets are
received from multiple DHT nodes, and so the alerts are typically generated
a few at a time.


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct dht_reply_alert final : tracker_alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::dht | alert_category::tracker;
	   int const num_peers;
	};

.. raw:: html

	<a name="tracker_announce_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+tracker_announce_alert&labels=documentation&body=Documentation+under+heading+%22class+tracker_announce_alert%22+could+be+improved">report issue</a>]</span>



tracker_announce_alert
----------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is generated each time a tracker announce is sent (or attempted to be sent).
There are no extra data members in this `alert`__. The url can be found in the base class
however.


__ reference-Alerts.html#alert
__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct tracker_announce_alert final : tracker_alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::tracker;
	   event_t const event;
	};

.. raw:: html

	<a name="event"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:tracker_announce_alert%3A%3A%5Bevent%5D&labels=documentation&body=Documentation+under+heading+%22tracker_announce_alert%3A%3A%5Bevent%5D%22+could+be+improved">report issue</a>]</span>


event
	specifies what event was sent to the tracker. See `event_t`__.
	

__ reference-Core.html#event_t

.. raw:: html

	<a name="hash_failed_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+hash_failed_alert&labels=documentation&body=Documentation+under+heading+%22class+hash_failed_alert%22+could+be+improved">report issue</a>]</span>



hash_failed_alert
-----------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is generated when a finished piece fails its hash check. You can get the handle
to the torrent which got the failed piece and the index of the piece itself from the `alert`__.


__ reference-Alerts.html#alert
__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct hash_failed_alert final : torrent_alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::status;
	   piece_index_t const piece_index;
	};

.. raw:: html

	<a name="peer_ban_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+peer_ban_alert&labels=documentation&body=Documentation+under+heading+%22class+peer_ban_alert%22+could+be+improved">report issue</a>]</span>



peer_ban_alert
--------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is generated when a peer is banned because it has sent too many corrupt pieces
to us. ``ip`` is the endpoint to the peer that was banned.


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct peer_ban_alert final : peer_alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::peer;
	};

.. raw:: html

	<a name="peer_unsnubbed_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+peer_unsnubbed_alert&labels=documentation&body=Documentation+under+heading+%22class+peer_unsnubbed_alert%22+could+be+improved">report issue</a>]</span>



peer_unsnubbed_alert
--------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is generated when a peer is un-snubbed. Essentially when it was snubbed for stalling
sending data, and now it started sending data again.


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct peer_unsnubbed_alert final : peer_alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::peer;
	};

.. raw:: html

	<a name="peer_snubbed_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+peer_snubbed_alert&labels=documentation&body=Documentation+under+heading+%22class+peer_snubbed_alert%22+could+be+improved">report issue</a>]</span>



peer_snubbed_alert
------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is generated when a peer is snubbed, when it stops sending data when we request
it.


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct peer_snubbed_alert final : peer_alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::peer;
	};

.. raw:: html

	<a name="peer_error_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+peer_error_alert&labels=documentation&body=Documentation+under+heading+%22class+peer_error_alert%22+could+be+improved">report issue</a>]</span>



peer_error_alert
----------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is generated when a peer sends invalid data over the peer-peer protocol. The peer
will be disconnected, but you get its ip address from the `alert`__, to identify it.


__ reference-Alerts.html#alert
__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct peer_error_alert final : peer_alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::peer;
	   operation_t op;
	   error_code const error;
	};

.. raw:: html

	<a name="op"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_error_alert%3A%3A%5Bop%5D&labels=documentation&body=Documentation+under+heading+%22peer_error_alert%3A%3A%5Bop%5D%22+could+be+improved">report issue</a>]</span>


op
	a 0-terminated string of the low-level operation that failed, or nullptr if
	there was no low level disk operation.
	


.. raw:: html

	<a name="error"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_error_alert%3A%3A%5Berror%5D&labels=documentation&body=Documentation+under+heading+%22peer_error_alert%3A%3A%5Berror%5D%22+could+be+improved">report issue</a>]</span>


error
	tells you what error caused this `alert`__.
	

__ reference-Alerts.html#alert

.. raw:: html

	<a name="peer_connect_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+peer_connect_alert&labels=documentation&body=Documentation+under+heading+%22class+peer_connect_alert%22+could+be+improved">report issue</a>]</span>



peer_connect_alert
------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is posted every time an incoming peer connection both
successfully passes the protocol handshake and is associated with a
torrent, or an outgoing peer connection attempt succeeds. For arbitrary
incoming connections, see `incoming_connection_alert`__.


__ reference-Alerts.html#alert
__ reference-Alerts.html#incoming_connection_alert


.. parsed-literal::
	

	struct peer_connect_alert final : peer_alert
	{
	   std::string **message** () const override;
	
	   enum direction_t
	   {
	      in,
	      out,
	   };
	
	   static constexpr alert_category_t **static_category**  = alert_category::connect;
	   direction_t direction;
	   socket_type_t socket_type;
	};

.. raw:: html

	<a name="direction_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+direction_t&labels=documentation&body=Documentation+under+heading+%22enum+direction_t%22+could+be+improved">report issue</a>]</span>



enum direction_t
................

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

+------+-------+-------------+
| name | value | description |
+======+=======+=============+
| in   | 0     |             |
+------+-------+-------------+
| out  | 1     |             |
+------+-------+-------------+



.. raw:: html

	<a name="direction"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_connect_alert%3A%3A%5Bdirection%5D&labels=documentation&body=Documentation+under+heading+%22peer_connect_alert%3A%3A%5Bdirection%5D%22+could+be+improved">report issue</a>]</span>


direction
	Tells you if the peer was incoming or outgoing
	


.. raw:: html

	<a name="peer_disconnected_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+peer_disconnected_alert&labels=documentation&body=Documentation+under+heading+%22class+peer_disconnected_alert%22+could+be+improved">report issue</a>]</span>



peer_disconnected_alert
-----------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is generated when a peer is disconnected for any reason (other than the ones
covered by `peer_error_alert`__ ).


__ reference-Alerts.html#alert
__ reference-Alerts.html#peer_error_alert


.. parsed-literal::
	

	struct peer_disconnected_alert final : peer_alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::connect;
	   socket_type_t const socket_type;
	   operation_t const op;
	   error_code const error;
	   close_reason_t const reason;
	};

.. raw:: html

	<a name="socket_type"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_disconnected_alert%3A%3A%5Bsocket_type%5D&labels=documentation&body=Documentation+under+heading+%22peer_disconnected_alert%3A%3A%5Bsocket_type%5D%22+could+be+improved">report issue</a>]</span>


socket_type
	the kind of socket this peer was connected over
	


.. raw:: html

	<a name="op"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_disconnected_alert%3A%3A%5Bop%5D&labels=documentation&body=Documentation+under+heading+%22peer_disconnected_alert%3A%3A%5Bop%5D%22+could+be+improved">report issue</a>]</span>


op
	the operation or level where the error occurred. Specified as an
	value from the `operation_t`__ enum. Defined in operations.hpp.
	

__ reference-Alerts.html#operation_t

.. raw:: html

	<a name="error"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_disconnected_alert%3A%3A%5Berror%5D&labels=documentation&body=Documentation+under+heading+%22peer_disconnected_alert%3A%3A%5Berror%5D%22+could+be+improved">report issue</a>]</span>


error
	tells you what error caused peer to disconnect.
	


.. raw:: html

	<a name="reason"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_disconnected_alert%3A%3A%5Breason%5D&labels=documentation&body=Documentation+under+heading+%22peer_disconnected_alert%3A%3A%5Breason%5D%22+could+be+improved">report issue</a>]</span>


reason
	the reason the peer disconnected (if specified)
	


.. raw:: html

	<a name="invalid_request_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+invalid_request_alert&labels=documentation&body=Documentation+under+heading+%22class+invalid_request_alert%22+could+be+improved">report issue</a>]</span>



invalid_request_alert
---------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This is a debug `alert`__ that is generated by an incoming invalid piece request.
``ip`` is the address of the peer and the ``request`` is the actual incoming
request from the peer. See `peer_request`__ for more info.


__ reference-Alerts.html#alert
__ reference-Core.html#peer_request


.. parsed-literal::
	

	struct invalid_request_alert final : peer_alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::peer;
	   peer_request const request;
	   bool const we_have;
	   bool const peer_interested;
	   bool const withheld;
	};

.. raw:: html

	<a name="request"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:invalid_request_alert%3A%3A%5Brequest%5D&labels=documentation&body=Documentation+under+heading+%22invalid_request_alert%3A%3A%5Brequest%5D%22+could+be+improved">report issue</a>]</span>


request
	the request we received from the peer
	


.. raw:: html

	<a name="we_have"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:invalid_request_alert%3A%3A%5Bwe_have%5D&labels=documentation&body=Documentation+under+heading+%22invalid_request_alert%3A%3A%5Bwe_have%5D%22+could+be+improved">report issue</a>]</span>


we_have
	true if we have this piece
	


.. raw:: html

	<a name="peer_interested"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:invalid_request_alert%3A%3A%5Bpeer_interested%5D&labels=documentation&body=Documentation+under+heading+%22invalid_request_alert%3A%3A%5Bpeer_interested%5D%22+could+be+improved">report issue</a>]</span>


peer_interested
	true if the peer indicated that it was interested to download before
	sending the request
	


.. raw:: html

	<a name="withheld"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:invalid_request_alert%3A%3A%5Bwithheld%5D&labels=documentation&body=Documentation+under+heading+%22invalid_request_alert%3A%3A%5Bwithheld%5D%22+could+be+improved">report issue</a>]</span>


withheld
	if this is true, the peer is not allowed to download this piece because
	of super-seeding rules.
	


.. raw:: html

	<a name="torrent_finished_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+torrent_finished_alert&labels=documentation&body=Documentation+under+heading+%22class+torrent_finished_alert%22+could+be+improved">report issue</a>]</span>



torrent_finished_alert
----------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is generated when a torrent switches from being a downloader to a seed.
It will only be generated once per torrent. It contains a `torrent_handle`__ to the
torrent in question.


__ reference-Alerts.html#alert
__ reference-Torrent_Handle.html#torrent_handle


.. parsed-literal::
	

	struct torrent_finished_alert final : torrent_alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::status;
	};

.. raw:: html

	<a name="piece_finished_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+piece_finished_alert&labels=documentation&body=Documentation+under+heading+%22class+piece_finished_alert%22+could+be+improved">report issue</a>]</span>



piece_finished_alert
--------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

this `alert`__ is posted every time a piece completes downloading
and passes the hash check. This `alert`__ derives from `torrent_alert`__
which contains the `torrent_handle`__ to the torrent the piece belongs to.
Note that being downloaded and passing the hash check may happen before
the piece is also fully flushed to disk. So `torrent_handle::have_piece()`__
may still return false


__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#torrent_alert
__ reference-Torrent_Handle.html#torrent_handle
__ reference-Torrent_Handle.html#have_piece()


.. parsed-literal::
	

	struct piece_finished_alert final : torrent_alert
	{
	   std::string **message** () const override;
	
	   piece_index_t const piece_index;
	};

.. raw:: html

	<a name="piece_index"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:piece_finished_alert%3A%3A%5Bpiece_index%5D&labels=documentation&body=Documentation+under+heading+%22piece_finished_alert%3A%3A%5Bpiece_index%5D%22+could+be+improved">report issue</a>]</span>


piece_index
	the index of the piece that finished
	


.. raw:: html

	<a name="request_dropped_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+request_dropped_alert&labels=documentation&body=Documentation+under+heading+%22class+request_dropped_alert%22+could+be+improved">report issue</a>]</span>



request_dropped_alert
---------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is generated when a peer rejects or ignores a piece request.


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct request_dropped_alert final : peer_alert
	{
	   std::string **message** () const override;
	
	   int const block_index;
	   piece_index_t const piece_index;
	};

.. raw:: html

	<a name="block_timeout_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+block_timeout_alert&labels=documentation&body=Documentation+under+heading+%22class+block_timeout_alert%22+could+be+improved">report issue</a>]</span>



block_timeout_alert
-------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is generated when a block request times out.


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct block_timeout_alert final : peer_alert
	{
	   std::string **message** () const override;
	
	   int const block_index;
	   piece_index_t const piece_index;
	};

.. raw:: html

	<a name="block_finished_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+block_finished_alert&labels=documentation&body=Documentation+under+heading+%22class+block_finished_alert%22+could+be+improved">report issue</a>]</span>



block_finished_alert
--------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is generated when a block request receives a response.


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct block_finished_alert final : peer_alert
	{
	   std::string **message** () const override;
	
	   int const block_index;
	   piece_index_t const piece_index;
	};

.. raw:: html

	<a name="block_downloading_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+block_downloading_alert&labels=documentation&body=Documentation+under+heading+%22class+block_downloading_alert%22+could+be+improved">report issue</a>]</span>



block_downloading_alert
-----------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is generated when a block request is sent to a peer.


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct block_downloading_alert final : peer_alert
	{
	   std::string **message** () const override;
	
	   int const block_index;
	   piece_index_t const piece_index;
	};

.. raw:: html

	<a name="unwanted_block_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+unwanted_block_alert&labels=documentation&body=Documentation+under+heading+%22class+unwanted_block_alert%22+could+be+improved">report issue</a>]</span>



unwanted_block_alert
--------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is generated when a block is received that was not requested or
whose request timed out.


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct unwanted_block_alert final : peer_alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::peer;
	   int const block_index;
	   piece_index_t const piece_index;
	};

.. raw:: html

	<a name="storage_moved_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+storage_moved_alert&labels=documentation&body=Documentation+under+heading+%22class+storage_moved_alert%22+could+be+improved">report issue</a>]</span>



storage_moved_alert
-------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

The ``storage_moved_alert`` is generated when all the disk IO has
completed and the files have been moved, as an effect of a call to
``torrent_handle::move_storage``. This is useful to synchronize with the
actual disk. The ``storage_path()`` member return the new path of the
storage.




.. parsed-literal::
	

	struct storage_moved_alert final : torrent_alert
	{
	   std::string **message** () const override;
	   char const* **old_path** () const;
	   char const* **storage_path** () const;
	
	   static constexpr alert_category_t **static_category**  = alert_category::storage;
	};

.. raw:: html

	<a name="old_path()"></a>
	<a name="storage_path()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:storage_moved_alert%3A%3A%5Bold_path%28%29+storage_path%28%29%5D&labels=documentation&body=Documentation+under+heading+%22storage_moved_alert%3A%3A%5Bold_path%28%29+storage_path%28%29%5D%22+could+be+improved">report issue</a>]</span>



old_path() storage_path()
.........................

.. parsed-literal::
	
	char const* **old_path** () const;
	char const* **storage_path** () const;
	

the path the torrent was moved to and from, respectively.



.. raw:: html

	<a name="storage_moved_failed_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+storage_moved_failed_alert&labels=documentation&body=Documentation+under+heading+%22class+storage_moved_failed_alert%22+could+be+improved">report issue</a>]</span>



storage_moved_failed_alert
--------------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

The ``storage_moved_failed_alert`` is generated when an attempt to move the storage,
via `torrent_handle::move_storage()`__, fails.


__ reference-Torrent_Handle.html#move_storage()


.. parsed-literal::
	

	struct storage_moved_failed_alert final : torrent_alert
	{
	   std::string **message** () const override;
	   char const* **file_path** () const;
	
	   static constexpr alert_category_t **static_category**  = alert_category::storage;
	   error_code const error;
	   operation_t op;
	};

.. raw:: html

	<a name="file_path()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:storage_moved_failed_alert%3A%3A%5Bfile_path%28%29%5D&labels=documentation&body=Documentation+under+heading+%22storage_moved_failed_alert%3A%3A%5Bfile_path%28%29%5D%22+could+be+improved">report issue</a>]</span>



file_path()
...........

.. parsed-literal::
	
	char const* **file_path** () const;
	

If the error happened for a specific file, this returns its path.



.. raw:: html

	<a name="op"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:storage_moved_failed_alert%3A%3A%5Bop%5D&labels=documentation&body=Documentation+under+heading+%22storage_moved_failed_alert%3A%3A%5Bop%5D%22+could+be+improved">report issue</a>]</span>


op
	this indicates what underlying operation caused the error
	


.. raw:: html

	<a name="torrent_deleted_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+torrent_deleted_alert&labels=documentation&body=Documentation+under+heading+%22class+torrent_deleted_alert%22+could+be+improved">report issue</a>]</span>



torrent_deleted_alert
---------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is generated when a request to delete the files of a torrent complete.

This `alert`__ is posted in the ``alert_category::storage`` category, and that bit
needs to be set in the alert_mask.


__ reference-Alerts.html#alert
__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct torrent_deleted_alert final : torrent_alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::storage;
	   info_hash_t info_hashes;
	};

.. raw:: html

	<a name="info_hashes"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_deleted_alert%3A%3A%5Binfo_hashes%5D&labels=documentation&body=Documentation+under+heading+%22torrent_deleted_alert%3A%3A%5Binfo_hashes%5D%22+could+be+improved">report issue</a>]</span>


info_hashes
	The info-hash of the torrent that was just deleted. Most of
	the time the `torrent_handle`__ in the ``torrent_alert`` will be invalid by the time
	this `alert`__ arrives, since the torrent is being deleted. The ``info_hashes`` member
	is hence the main way of identifying which torrent just completed the delete.
	

__ reference-Torrent_Handle.html#torrent_handle
__ reference-Alerts.html#alert

.. raw:: html

	<a name="torrent_delete_failed_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+torrent_delete_failed_alert&labels=documentation&body=Documentation+under+heading+%22class+torrent_delete_failed_alert%22+could+be+improved">report issue</a>]</span>



torrent_delete_failed_alert
---------------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is generated when a request to delete the files of a torrent fails.
Just removing a torrent from the `session`__ cannot fail


__ reference-Alerts.html#alert
__ reference-Session.html#session


.. parsed-literal::
	

	struct torrent_delete_failed_alert final : torrent_alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::storage
	   | alert_category::error;
	   error_code const error;
	   info_hash_t info_hashes;
	};

.. raw:: html

	<a name="error"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_delete_failed_alert%3A%3A%5Berror%5D&labels=documentation&body=Documentation+under+heading+%22torrent_delete_failed_alert%3A%3A%5Berror%5D%22+could+be+improved">report issue</a>]</span>


error
	tells you why it failed.
	


.. raw:: html

	<a name="info_hashes"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_delete_failed_alert%3A%3A%5Binfo_hashes%5D&labels=documentation&body=Documentation+under+heading+%22torrent_delete_failed_alert%3A%3A%5Binfo_hashes%5D%22+could+be+improved">report issue</a>]</span>


info_hashes
	the info hash of the torrent whose files failed to be deleted
	


.. raw:: html

	<a name="save_resume_data_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+save_resume_data_alert&labels=documentation&body=Documentation+under+heading+%22class+save_resume_data_alert%22+could+be+improved">report issue</a>]</span>



save_resume_data_alert
----------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is generated as a response to a ``torrent_handle::save_resume_data`` request.
It is generated once the disk IO thread is done writing the state for this torrent.


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct save_resume_data_alert final : torrent_alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::storage;
	   add_torrent_params params;
	};

.. raw:: html

	<a name="params"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:save_resume_data_alert%3A%3A%5Bparams%5D&labels=documentation&body=Documentation+under+heading+%22save_resume_data_alert%3A%3A%5Bparams%5D%22+could+be+improved">report issue</a>]</span>


params
	the ``params`` structure is populated with the fields to be passed to
	`add_torrent()`__ or `async_add_torrent()`__ to resume the torrent. To
	save the state to disk, you may pass it on to `write_resume_data()`__.
	

__ reference-Session.html#add_torrent()
__ reference-Session.html#async_add_torrent()
__ reference-Resume_Data.html#write_resume_data()

.. raw:: html

	<a name="save_resume_data_failed_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+save_resume_data_failed_alert&labels=documentation&body=Documentation+under+heading+%22class+save_resume_data_failed_alert%22+could+be+improved">report issue</a>]</span>



save_resume_data_failed_alert
-----------------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is generated instead of ``save_resume_data_alert`` if there was an error
generating the resume data. ``error`` describes what went wrong.


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct save_resume_data_failed_alert final : torrent_alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::storage
	   | alert_category::error;
	   error_code const error;
	};

.. raw:: html

	<a name="error"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:save_resume_data_failed_alert%3A%3A%5Berror%5D&labels=documentation&body=Documentation+under+heading+%22save_resume_data_failed_alert%3A%3A%5Berror%5D%22+could+be+improved">report issue</a>]</span>


error
	the error code from the resume_data failure
	


.. raw:: html

	<a name="torrent_paused_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+torrent_paused_alert&labels=documentation&body=Documentation+under+heading+%22class+torrent_paused_alert%22+could+be+improved">report issue</a>]</span>



torrent_paused_alert
--------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is generated as a response to a ``torrent_handle::pause`` request. It is
generated once all disk IO is complete and the files in the torrent have been closed.
This is useful for synchronizing with the disk.


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct torrent_paused_alert final : torrent_alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::status;
	};

.. raw:: html

	<a name="torrent_resumed_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+torrent_resumed_alert&labels=documentation&body=Documentation+under+heading+%22class+torrent_resumed_alert%22+could+be+improved">report issue</a>]</span>



torrent_resumed_alert
---------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is generated as a response to a `torrent_handle::resume()`__ request. It is
generated when a torrent goes from a paused state to an active state.


__ reference-Alerts.html#alert
__ reference-Torrent_Handle.html#resume()


.. parsed-literal::
	

	struct torrent_resumed_alert final : torrent_alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::status;
	};

.. raw:: html

	<a name="torrent_checked_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+torrent_checked_alert&labels=documentation&body=Documentation+under+heading+%22class+torrent_checked_alert%22+could+be+improved">report issue</a>]</span>



torrent_checked_alert
---------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is posted when a torrent completes checking. i.e. when it transitions
out of the ``checking files`` state into a state where it is ready to start downloading


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct torrent_checked_alert final : torrent_alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::status;
	};

.. raw:: html

	<a name="url_seed_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+url_seed_alert&labels=documentation&body=Documentation+under+heading+%22class+url_seed_alert%22+could+be+improved">report issue</a>]</span>



url_seed_alert
--------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is generated when a HTTP seed name lookup fails.


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct url_seed_alert final : torrent_alert
	{
	   std::string **message** () const override;
	   char const* **server_url** () const;
	   char const* **error_message** () const;
	
	   static constexpr alert_category_t **static_category**  = alert_category::peer | alert_category::error;
	   error_code const error;
	};

.. raw:: html

	<a name="server_url()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:url_seed_alert%3A%3A%5Bserver_url%28%29%5D&labels=documentation&body=Documentation+under+heading+%22url_seed_alert%3A%3A%5Bserver_url%28%29%5D%22+could+be+improved">report issue</a>]</span>



server_url()
............

.. parsed-literal::
	
	char const* **server_url** () const;
	

the URL the error is associated with



.. raw:: html

	<a name="error_message()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:url_seed_alert%3A%3A%5Berror_message%28%29%5D&labels=documentation&body=Documentation+under+heading+%22url_seed_alert%3A%3A%5Berror_message%28%29%5D%22+could+be+improved">report issue</a>]</span>



error_message()
...............

.. parsed-literal::
	
	char const* **error_message** () const;
	

in case the web server sent an error message, this function returns
it.



.. raw:: html

	<a name="error"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:url_seed_alert%3A%3A%5Berror%5D&labels=documentation&body=Documentation+under+heading+%22url_seed_alert%3A%3A%5Berror%5D%22+could+be+improved">report issue</a>]</span>


error
	the error the web seed encountered. If this is not set, the server
	sent an error message, call ``error_message()``.
	


.. raw:: html

	<a name="file_error_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+file_error_alert&labels=documentation&body=Documentation+under+heading+%22class+file_error_alert%22+could+be+improved">report issue</a>]</span>



file_error_alert
----------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

If the storage fails to read or write files that it needs access to, this `alert`__ is
generated and the torrent is paused.


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct file_error_alert final : torrent_alert
	{
	   std::string **message** () const override;
	   char const* **filename** () const;
	
	   static constexpr alert_category_t **static_category**  = alert_category::status
	   | alert_category::storage;
	   error_code const error;
	   operation_t op;
	};

.. raw:: html

	<a name="filename()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_error_alert%3A%3A%5Bfilename%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_error_alert%3A%3A%5Bfilename%28%29%5D%22+could+be+improved">report issue</a>]</span>



filename()
..........

.. parsed-literal::
	
	char const* **filename** () const;
	

the file that experienced the error



.. raw:: html

	<a name="error"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_error_alert%3A%3A%5Berror%5D&labels=documentation&body=Documentation+under+heading+%22file_error_alert%3A%3A%5Berror%5D%22+could+be+improved">report issue</a>]</span>


error
	the error code describing the error.
	


.. raw:: html

	<a name="op"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_error_alert%3A%3A%5Bop%5D&labels=documentation&body=Documentation+under+heading+%22file_error_alert%3A%3A%5Bop%5D%22+could+be+improved">report issue</a>]</span>


op
	indicates which underlying operation caused the error
	


.. raw:: html

	<a name="metadata_failed_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+metadata_failed_alert&labels=documentation&body=Documentation+under+heading+%22class+metadata_failed_alert%22+could+be+improved">report issue</a>]</span>



metadata_failed_alert
---------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is generated when the metadata has been completely received and the info-hash
failed to match it. i.e. the metadata that was received was corrupt. libtorrent will
automatically retry to fetch it in this case. This is only relevant when running a
torrent-less download, with the metadata extension provided by libtorrent.


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct metadata_failed_alert final : torrent_alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::error;
	   error_code const error;
	};

.. raw:: html

	<a name="error"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:metadata_failed_alert%3A%3A%5Berror%5D&labels=documentation&body=Documentation+under+heading+%22metadata_failed_alert%3A%3A%5Berror%5D%22+could+be+improved">report issue</a>]</span>


error
	indicates what failed when parsing the metadata. This error is
	what's returned from lazy_bdecode().
	


.. raw:: html

	<a name="metadata_received_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+metadata_received_alert&labels=documentation&body=Documentation+under+heading+%22class+metadata_received_alert%22+could+be+improved">report issue</a>]</span>



metadata_received_alert
-----------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is generated when the metadata has been completely received and the torrent
can start downloading. It is not generated on torrents that are started with metadata, but
only those that needs to download it from peers (when utilizing the libtorrent extension).

There are no additional data members in this `alert`__.

Typically, when receiving this `alert`__, you would want to save the torrent file in order
to load it back up again when the `session`__ is restarted. Here's an example snippet of
code to do that:

.. code:: c++

	torrent_handle h = alert->handle();
	std::shared_ptr<torrent_info const> ti = h.torrent_file();
	create_torrent ct(*ti);
	entry te = ct.generate();
	std::vector<char> buffer;
	bencode(std::back_inserter(buffer), te);
	FILE* f = fopen((to_hex(ti->info_hashes().get_best().to_string()) + ".torrent").c_str(), "wb+");
	if (f) {
		fwrite(&buffer[0], 1, buffer.size(), f);
		fclose(f);
	}



__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Session.html#session


.. parsed-literal::
	

	struct metadata_received_alert final : torrent_alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::status;
	};

.. raw:: html

	<a name="udp_error_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+udp_error_alert&labels=documentation&body=Documentation+under+heading+%22class+udp_error_alert%22+could+be+improved">report issue</a>]</span>



udp_error_alert
---------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is posted when there is an error on a UDP socket. The
UDP sockets are used for all uTP, DHT and UDP tracker traffic. They are
global to the `session`__.


__ reference-Alerts.html#alert
__ reference-Session.html#session


.. parsed-literal::
	

	struct udp_error_alert final : alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::error;
	   aux::noexcept_movable<udp::endpoint> endpoint;
	   operation_t operation;
	   error_code const error;
	};

.. raw:: html

	<a name="endpoint"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:udp_error_alert%3A%3A%5Bendpoint%5D&labels=documentation&body=Documentation+under+heading+%22udp_error_alert%3A%3A%5Bendpoint%5D%22+could+be+improved">report issue</a>]</span>


endpoint
	the source address associated with the error (if any)
	


.. raw:: html

	<a name="operation"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:udp_error_alert%3A%3A%5Boperation%5D&labels=documentation&body=Documentation+under+heading+%22udp_error_alert%3A%3A%5Boperation%5D%22+could+be+improved">report issue</a>]</span>


operation
	the operation that failed
	


.. raw:: html

	<a name="error"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:udp_error_alert%3A%3A%5Berror%5D&labels=documentation&body=Documentation+under+heading+%22udp_error_alert%3A%3A%5Berror%5D%22+could+be+improved">report issue</a>]</span>


error
	the error code describing the error
	


.. raw:: html

	<a name="external_ip_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+external_ip_alert&labels=documentation&body=Documentation+under+heading+%22class+external_ip_alert%22+could+be+improved">report issue</a>]</span>



external_ip_alert
-----------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

Whenever libtorrent learns about the machines external IP, this `alert`__ is
generated. The external IP address can be acquired from the tracker (if it
supports that) or from peers that supports the extension protocol.
The address can be accessed through the ``external_address`` member.


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct external_ip_alert final : alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::status;
	   aux::noexcept_movable<address> external_address;
	};

.. raw:: html

	<a name="external_address"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:external_ip_alert%3A%3A%5Bexternal_address%5D&labels=documentation&body=Documentation+under+heading+%22external_ip_alert%3A%3A%5Bexternal_address%5D%22+could+be+improved">report issue</a>]</span>


external_address
	the IP address that is believed to be our external IP
	


.. raw:: html

	<a name="listen_failed_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+listen_failed_alert&labels=documentation&body=Documentation+under+heading+%22class+listen_failed_alert%22+could+be+improved">report issue</a>]</span>



listen_failed_alert
-------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is generated when none of the ports, given in the port range, to
`session`__ can be opened for listening. The ``listen_interface`` member is the
interface that failed, ``error`` is the error code describing the failure.

In the case an endpoint was created before generating the `alert`__, it is
represented by ``address`` and ``port``. The combinations of socket type
and operation in which such address and port are not valid are:
accept  - i2p
accept  - socks5
enum_if - tcp

libtorrent may sometimes try to listen on port 0, if all other ports failed.
Port 0 asks the operating system to pick a port that's free). If that fails
you may see a `listen_failed_alert`__ with port 0 even if you didn't ask to
listen on it.


__ reference-Alerts.html#alert
__ reference-Session.html#session
__ reference-Alerts.html#alert
__ reference-Alerts.html#listen_failed_alert


.. parsed-literal::
	

	struct listen_failed_alert final : alert
	{
	   std::string **message** () const override;
	   char const* **listen_interface** () const;
	
	   static constexpr alert_category_t **static_category**  = alert_category::status | alert_category::error;
	   error_code const error;
	   operation_t op;
	   lt::socket_type_t const socket_type;
	   aux::noexcept_movable<lt::address> address;
	   int const port;
	};

.. raw:: html

	<a name="listen_interface()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:listen_failed_alert%3A%3A%5Blisten_interface%28%29%5D&labels=documentation&body=Documentation+under+heading+%22listen_failed_alert%3A%3A%5Blisten_interface%28%29%5D%22+could+be+improved">report issue</a>]</span>



listen_interface()
..................

.. parsed-literal::
	
	char const* **listen_interface** () const;
	

the network device libtorrent attempted to listen on, or the IP address



.. raw:: html

	<a name="error"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:listen_failed_alert%3A%3A%5Berror%5D&labels=documentation&body=Documentation+under+heading+%22listen_failed_alert%3A%3A%5Berror%5D%22+could+be+improved">report issue</a>]</span>


error
	the error the system returned
	


.. raw:: html

	<a name="op"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:listen_failed_alert%3A%3A%5Bop%5D&labels=documentation&body=Documentation+under+heading+%22listen_failed_alert%3A%3A%5Bop%5D%22+could+be+improved">report issue</a>]</span>


op
	the underlying operation that failed
	


.. raw:: html

	<a name="socket_type"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:listen_failed_alert%3A%3A%5Bsocket_type%5D&labels=documentation&body=Documentation+under+heading+%22listen_failed_alert%3A%3A%5Bsocket_type%5D%22+could+be+improved">report issue</a>]</span>


socket_type
	the type of listen socket this `alert`__ refers to.
	

__ reference-Alerts.html#alert

.. raw:: html

	<a name="address"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:listen_failed_alert%3A%3A%5Baddress%5D&labels=documentation&body=Documentation+under+heading+%22listen_failed_alert%3A%3A%5Baddress%5D%22+could+be+improved">report issue</a>]</span>


address
	the address libtorrent attempted to listen on
	see `alert`__ documentation for validity of this value
	

__ reference-Alerts.html#alert

.. raw:: html

	<a name="port"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:listen_failed_alert%3A%3A%5Bport%5D&labels=documentation&body=Documentation+under+heading+%22listen_failed_alert%3A%3A%5Bport%5D%22+could+be+improved">report issue</a>]</span>


port
	the port libtorrent attempted to listen on
	see `alert`__ documentation for validity of this value
	

__ reference-Alerts.html#alert

.. raw:: html

	<a name="listen_succeeded_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+listen_succeeded_alert&labels=documentation&body=Documentation+under+heading+%22class+listen_succeeded_alert%22+could+be+improved">report issue</a>]</span>



listen_succeeded_alert
----------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is posted when the listen port succeeds to be opened on a
particular interface. ``address`` and ``port`` is the endpoint that
successfully was opened for listening.


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct listen_succeeded_alert final : alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::status;
	   aux::noexcept_movable<lt::address> address;
	   int const port;
	   lt::socket_type_t const socket_type;
	};

.. raw:: html

	<a name="address"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:listen_succeeded_alert%3A%3A%5Baddress%5D&labels=documentation&body=Documentation+under+heading+%22listen_succeeded_alert%3A%3A%5Baddress%5D%22+could+be+improved">report issue</a>]</span>


address
	the address libtorrent ended up listening on. This address
	refers to the local interface.
	


.. raw:: html

	<a name="port"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:listen_succeeded_alert%3A%3A%5Bport%5D&labels=documentation&body=Documentation+under+heading+%22listen_succeeded_alert%3A%3A%5Bport%5D%22+could+be+improved">report issue</a>]</span>


port
	the port libtorrent ended up listening on.
	


.. raw:: html

	<a name="socket_type"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:listen_succeeded_alert%3A%3A%5Bsocket_type%5D&labels=documentation&body=Documentation+under+heading+%22listen_succeeded_alert%3A%3A%5Bsocket_type%5D%22+could+be+improved">report issue</a>]</span>


socket_type
	the type of listen socket this `alert`__ refers to.
	

__ reference-Alerts.html#alert

.. raw:: html

	<a name="portmap_error_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+portmap_error_alert&labels=documentation&body=Documentation+under+heading+%22class+portmap_error_alert%22+could+be+improved">report issue</a>]</span>



portmap_error_alert
-------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is generated when a NAT router was successfully found but some
part of the port mapping request failed. It contains a text message that
may help the user figure out what is wrong. This `alert`__ is not generated in
case it appears the client is not running on a NAT:ed network or if it
appears there is no NAT router that can be remote controlled to add port
mappings.


__ reference-Alerts.html#alert
__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct portmap_error_alert final : alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::port_mapping
	   | alert_category::error;
	   port_mapping_t const mapping;
	   portmap_transport map_transport;
	   aux::noexcept_movable<address> local_address;
	   error_code const error;
	};

.. raw:: html

	<a name="mapping"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:portmap_error_alert%3A%3A%5Bmapping%5D&labels=documentation&body=Documentation+under+heading+%22portmap_error_alert%3A%3A%5Bmapping%5D%22+could+be+improved">report issue</a>]</span>


mapping
	refers to the mapping index of the port map that failed, i.e.
	the index returned from add_mapping().
	


.. raw:: html

	<a name="map_transport"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:portmap_error_alert%3A%3A%5Bmap_transport%5D&labels=documentation&body=Documentation+under+heading+%22portmap_error_alert%3A%3A%5Bmap_transport%5D%22+could+be+improved">report issue</a>]</span>


map_transport
	UPnP or NAT-PMP
	


.. raw:: html

	<a name="local_address"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:portmap_error_alert%3A%3A%5Blocal_address%5D&labels=documentation&body=Documentation+under+heading+%22portmap_error_alert%3A%3A%5Blocal_address%5D%22+could+be+improved">report issue</a>]</span>


local_address
	the local network the port mapper is running on
	


.. raw:: html

	<a name="error"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:portmap_error_alert%3A%3A%5Berror%5D&labels=documentation&body=Documentation+under+heading+%22portmap_error_alert%3A%3A%5Berror%5D%22+could+be+improved">report issue</a>]</span>


error
	tells you what failed.
	


.. raw:: html

	<a name="portmap_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+portmap_alert&labels=documentation&body=Documentation+under+heading+%22class+portmap_alert%22+could+be+improved">report issue</a>]</span>



portmap_alert
-------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is generated when a NAT router was successfully found and
a port was successfully mapped on it. On a NAT:ed network with a NAT-PMP
capable router, this is typically generated once when mapping the TCP
port and, if DHT is enabled, when the UDP port is mapped.


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct portmap_alert final : alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::port_mapping;
	   port_mapping_t const mapping;
	   int const external_port;
	   portmap_protocol const map_protocol;
	   portmap_transport const map_transport;
	   aux::noexcept_movable<address> local_address;
	};

.. raw:: html

	<a name="mapping"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:portmap_alert%3A%3A%5Bmapping%5D&labels=documentation&body=Documentation+under+heading+%22portmap_alert%3A%3A%5Bmapping%5D%22+could+be+improved">report issue</a>]</span>


mapping
	refers to the mapping index of the port map that failed, i.e.
	the index returned from add_mapping().
	


.. raw:: html

	<a name="external_port"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:portmap_alert%3A%3A%5Bexternal_port%5D&labels=documentation&body=Documentation+under+heading+%22portmap_alert%3A%3A%5Bexternal_port%5D%22+could+be+improved">report issue</a>]</span>


external_port
	the external port allocated for the mapping.
	


.. raw:: html

	<a name="local_address"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:portmap_alert%3A%3A%5Blocal_address%5D&labels=documentation&body=Documentation+under+heading+%22portmap_alert%3A%3A%5Blocal_address%5D%22+could+be+improved">report issue</a>]</span>


local_address
	the local network the port mapper is running on
	


.. raw:: html

	<a name="portmap_log_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+portmap_log_alert&labels=documentation&body=Documentation+under+heading+%22class+portmap_log_alert%22+could+be+improved">report issue</a>]</span>



portmap_log_alert
-----------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is generated to log informational events related to either
UPnP or NAT-PMP. They contain a log line and the type (0 = NAT-PMP
and 1 = UPnP). Displaying these messages to an end user is only useful
for debugging the UPnP or NAT-PMP implementation. This `alert`__ is only
posted if the alert_category::port_mapping_log flag is enabled in
the `alert`__ mask.


__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct portmap_log_alert final : alert
	{
	   std::string **message** () const override;
	   char const* **log_message** () const;
	
	   static constexpr alert_category_t **static_category**  = alert_category::port_mapping_log;
	   portmap_transport const map_transport;
	   aux::noexcept_movable<address> local_address;
	};

.. raw:: html

	<a name="log_message()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:portmap_log_alert%3A%3A%5Blog_message%28%29%5D&labels=documentation&body=Documentation+under+heading+%22portmap_log_alert%3A%3A%5Blog_message%28%29%5D%22+could+be+improved">report issue</a>]</span>



log_message()
.............

.. parsed-literal::
	
	char const* **log_message** () const;
	

the message associated with this log line



.. raw:: html

	<a name="local_address"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:portmap_log_alert%3A%3A%5Blocal_address%5D&labels=documentation&body=Documentation+under+heading+%22portmap_log_alert%3A%3A%5Blocal_address%5D%22+could+be+improved">report issue</a>]</span>


local_address
	the local network the port mapper is running on
	


.. raw:: html

	<a name="fastresume_rejected_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+fastresume_rejected_alert&labels=documentation&body=Documentation+under+heading+%22class+fastresume_rejected_alert%22+could+be+improved">report issue</a>]</span>



fastresume_rejected_alert
-------------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is generated when a fast resume file has been passed to
`add_torrent()`__ but the files on disk did not match the fast resume file.
The error_code explains the reason why the resume file was rejected.


__ reference-Alerts.html#alert
__ reference-Session.html#add_torrent()


.. parsed-literal::
	

	struct fastresume_rejected_alert final : torrent_alert
	{
	   std::string **message** () const override;
	   char const* **file_path** () const;
	
	   static constexpr alert_category_t **static_category**  = alert_category::status
	   | alert_category::error;
	   error_code error;
	   operation_t op;
	};

.. raw:: html

	<a name="file_path()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:fastresume_rejected_alert%3A%3A%5Bfile_path%28%29%5D&labels=documentation&body=Documentation+under+heading+%22fastresume_rejected_alert%3A%3A%5Bfile_path%28%29%5D%22+could+be+improved">report issue</a>]</span>



file_path()
...........

.. parsed-literal::
	
	char const* **file_path** () const;
	

If the error happened to a specific file, this returns the path to it.



.. raw:: html

	<a name="op"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:fastresume_rejected_alert%3A%3A%5Bop%5D&labels=documentation&body=Documentation+under+heading+%22fastresume_rejected_alert%3A%3A%5Bop%5D%22+could+be+improved">report issue</a>]</span>


op
	the underlying operation that failed
	


.. raw:: html

	<a name="peer_blocked_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+peer_blocked_alert&labels=documentation&body=Documentation+under+heading+%22class+peer_blocked_alert%22+could+be+improved">report issue</a>]</span>



peer_blocked_alert
------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is posted when an incoming peer connection, or a peer that's about to be added
to our peer list, is blocked for some reason. This could be any of:

* the IP filter
* i2p mixed mode restrictions (a normal peer is not allowed on an i2p swarm)
* the port filter
* the peer has a low port and ``no_connect_privileged_ports`` is enabled
* the protocol of the peer is blocked (uTP/TCP blocking)


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct peer_blocked_alert final : peer_alert
	{
	   std::string **message** () const override;
	
	   enum reason_t
	   {
	      ip_filter,
	      port_filter,
	      i2p_mixed,
	      privileged_ports,
	      utp_disabled,
	      tcp_disabled,
	      invalid_local_interface,
	      ssrf_mitigation,
	   };
	
	   static constexpr alert_category_t **static_category**  = alert_category::ip_block;
	   int const reason;
	};

.. raw:: html

	<a name="reason_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+reason_t&labels=documentation&body=Documentation+under+heading+%22enum+reason_t%22+could+be+improved">report issue</a>]</span>



enum reason_t
.............

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

+-------------------------+-------+-------------+
| name                    | value | description |
+=========================+=======+=============+
| ip_filter               | 0     |             |
+-------------------------+-------+-------------+
| port_filter             | 1     |             |
+-------------------------+-------+-------------+
| i2p_mixed               | 2     |             |
+-------------------------+-------+-------------+
| privileged_ports        | 3     |             |
+-------------------------+-------+-------------+
| utp_disabled            | 4     |             |
+-------------------------+-------+-------------+
| tcp_disabled            | 5     |             |
+-------------------------+-------+-------------+
| invalid_local_interface | 6     |             |
+-------------------------+-------+-------------+
| ssrf_mitigation         | 7     |             |
+-------------------------+-------+-------------+



.. raw:: html

	<a name="reason"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_blocked_alert%3A%3A%5Breason%5D&labels=documentation&body=Documentation+under+heading+%22peer_blocked_alert%3A%3A%5Breason%5D%22+could+be+improved">report issue</a>]</span>


reason
	the reason for the peer being blocked. Is one of the values from the
	`reason_t`__ enum.
	

__ reference-Alerts.html#reason_t

.. raw:: html

	<a name="dht_announce_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+dht_announce_alert&labels=documentation&body=Documentation+under+heading+%22class+dht_announce_alert%22+could+be+improved">report issue</a>]</span>



dht_announce_alert
------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is generated when a DHT node announces to an info-hash on our
DHT node. It belongs to the ``alert_category::dht`` category.


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct dht_announce_alert final : alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::dht;
	   aux::noexcept_movable<address> ip;
	   int port;
	   sha1_hash info_hash;
	};

.. raw:: html

	<a name="dht_get_peers_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+dht_get_peers_alert&labels=documentation&body=Documentation+under+heading+%22class+dht_get_peers_alert%22+could+be+improved">report issue</a>]</span>



dht_get_peers_alert
-------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is generated when a DHT node sends a ``get_peers`` message to
our DHT node. It belongs to the ``alert_category::dht`` category.


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct dht_get_peers_alert final : alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::dht;
	   sha1_hash info_hash;
	};

.. raw:: html

	<a name="cache_flushed_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+cache_flushed_alert&labels=documentation&body=Documentation+under+heading+%22class+cache_flushed_alert%22+could+be+improved">report issue</a>]</span>



cache_flushed_alert
-------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is posted when the disk cache has been flushed for a specific
torrent as a result of a call to `torrent_handle::flush_cache()`__. This
`alert`__ belongs to the ``alert_category::storage`` category, which must be
enabled to let this `alert`__ through. The `alert`__ is also posted when removing
a torrent from the `session`__, once the outstanding cache flush is complete
and the torrent does no longer have any files open.


__ reference-Alerts.html#alert
__ reference-Torrent_Handle.html#flush_cache()
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Session.html#session


.. parsed-literal::
	

	struct cache_flushed_alert final : torrent_alert
	{
	   static constexpr alert_category_t **static_category**  = alert_category::storage;
	};

.. raw:: html

	<a name="lsd_peer_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+lsd_peer_alert&labels=documentation&body=Documentation+under+heading+%22class+lsd_peer_alert%22+could+be+improved">report issue</a>]</span>



lsd_peer_alert
--------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is generated when we receive a local service discovery message
from a peer for a torrent we're currently participating in.


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct lsd_peer_alert final : peer_alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::peer;
	};

.. raw:: html

	<a name="trackerid_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+trackerid_alert&labels=documentation&body=Documentation+under+heading+%22class+trackerid_alert%22+could+be+improved">report issue</a>]</span>



trackerid_alert
---------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is posted whenever a tracker responds with a ``trackerid``.
The tracker ID is like a cookie. libtorrent will store the tracker ID
for this tracker and repeat it in subsequent announces.


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct trackerid_alert final : tracker_alert
	{
	   std::string **message** () const override;
	   char const* **tracker_id** () const;
	
	   static constexpr alert_category_t **static_category**  = alert_category::status;
	};

.. raw:: html

	<a name="tracker_id()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:trackerid_alert%3A%3A%5Btracker_id%28%29%5D&labels=documentation&body=Documentation+under+heading+%22trackerid_alert%3A%3A%5Btracker_id%28%29%5D%22+could+be+improved">report issue</a>]</span>



tracker_id()
............

.. parsed-literal::
	
	char const* **tracker_id** () const;
	

The tracker ID returned by the tracker



.. raw:: html

	<a name="dht_bootstrap_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+dht_bootstrap_alert&labels=documentation&body=Documentation+under+heading+%22class+dht_bootstrap_alert%22+could+be+improved">report issue</a>]</span>



dht_bootstrap_alert
-------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is posted when the initial DHT bootstrap is done.


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct dht_bootstrap_alert final : alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::dht;
	};

.. raw:: html

	<a name="torrent_error_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+torrent_error_alert&labels=documentation&body=Documentation+under+heading+%22class+torrent_error_alert%22+could+be+improved">report issue</a>]</span>



torrent_error_alert
-------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This is posted whenever a torrent is transitioned into the error state.




.. parsed-literal::
	

	struct torrent_error_alert final : torrent_alert
	{
	   std::string **message** () const override;
	   char const* **filename** () const;
	
	   static constexpr alert_category_t **static_category**  = alert_category::error | alert_category::status;
	   error_code const error;
	};

.. raw:: html

	<a name="filename()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_error_alert%3A%3A%5Bfilename%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_error_alert%3A%3A%5Bfilename%28%29%5D%22+could+be+improved">report issue</a>]</span>



filename()
..........

.. parsed-literal::
	
	char const* **filename** () const;
	

the filename (or object) the error occurred on.



.. raw:: html

	<a name="error"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_error_alert%3A%3A%5Berror%5D&labels=documentation&body=Documentation+under+heading+%22torrent_error_alert%3A%3A%5Berror%5D%22+could+be+improved">report issue</a>]</span>


error
	specifies which error the torrent encountered.
	


.. raw:: html

	<a name="torrent_need_cert_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+torrent_need_cert_alert&labels=documentation&body=Documentation+under+heading+%22class+torrent_need_cert_alert%22+could+be+improved">report issue</a>]</span>



torrent_need_cert_alert
-----------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This is always posted for SSL torrents. This is a reminder to the client that
the torrent won't work unless `torrent_handle::set_ssl_certificate()`__ is called with
a valid certificate. Valid certificates MUST be signed by the SSL certificate
in the .torrent file.


__ reference-Torrent_Handle.html#set_ssl_certificate()


.. parsed-literal::
	

	struct torrent_need_cert_alert final : torrent_alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::status;
	};

.. raw:: html

	<a name="incoming_connection_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+incoming_connection_alert&labels=documentation&body=Documentation+under+heading+%22class+incoming_connection_alert%22+could+be+improved">report issue</a>]</span>



incoming_connection_alert
-------------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

The incoming connection `alert`__ is posted every time we successfully accept
an incoming connection, through any mean. The most straight-forward ways
of accepting incoming connections are through the TCP listen socket and
the UDP listen socket for uTP sockets. However, connections may also be
accepted through a Socks5 or i2p listen socket, or via an SSL listen
socket.


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct incoming_connection_alert final : alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::peer;
	   socket_type_t socket_type;
	   aux::noexcept_movable<tcp::endpoint> endpoint;
	};

.. raw:: html

	<a name="socket_type"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:incoming_connection_alert%3A%3A%5Bsocket_type%5D&labels=documentation&body=Documentation+under+heading+%22incoming_connection_alert%3A%3A%5Bsocket_type%5D%22+could+be+improved">report issue</a>]</span>


socket_type
	tells you what kind of socket the connection was accepted
	


.. raw:: html

	<a name="endpoint"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:incoming_connection_alert%3A%3A%5Bendpoint%5D&labels=documentation&body=Documentation+under+heading+%22incoming_connection_alert%3A%3A%5Bendpoint%5D%22+could+be+improved">report issue</a>]</span>


endpoint
	is the IP address and port the connection came from.
	


.. raw:: html

	<a name="add_torrent_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+add_torrent_alert&labels=documentation&body=Documentation+under+heading+%22class+add_torrent_alert%22+could+be+improved">report issue</a>]</span>



add_torrent_alert
-----------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is always posted when a torrent was attempted to be added
and contains the return status of the add operation. The torrent handle of the new
torrent can be found as the ``handle`` member in the base class. If adding
the torrent failed, ``error`` contains the error code.


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct add_torrent_alert final : torrent_alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::status;
	   add_torrent_params params;
	   error_code error;
	};

.. raw:: html

	<a name="params"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:add_torrent_alert%3A%3A%5Bparams%5D&labels=documentation&body=Documentation+under+heading+%22add_torrent_alert%3A%3A%5Bparams%5D%22+could+be+improved">report issue</a>]</span>


params
	This contains copies of the most important fields from the original
	`add_torrent_params`__ object, passed to `add_torrent()`__ or
	`async_add_torrent()`__. Specifically, these fields are copied:
	
	* version
	* ti
	* name
	* save_path
	* userdata
	* tracker_id
	* flags
	* info_hash
	
	the info_hash field will be updated with the info-hash of the torrent
	specified by ``ti``.
	

__ reference-Add_Torrent.html#add_torrent_params
__ reference-Session.html#add_torrent()
__ reference-Session.html#async_add_torrent()

.. raw:: html

	<a name="error"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:add_torrent_alert%3A%3A%5Berror%5D&labels=documentation&body=Documentation+under+heading+%22add_torrent_alert%3A%3A%5Berror%5D%22+could+be+improved">report issue</a>]</span>


error
	set to the error, if one occurred while adding the torrent.
	


.. raw:: html

	<a name="state_update_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+state_update_alert&labels=documentation&body=Documentation+under+heading+%22class+state_update_alert%22+could+be+improved">report issue</a>]</span>



state_update_alert
------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is only posted when requested by the user, by calling
session::post_torrent_updates() on the `session`__. It contains the torrent
status of all torrents that changed since last time this message was
posted. Its category is ``alert_category::status``, but it's not subject to
filtering, since it's only manually posted anyway.


__ reference-Alerts.html#alert
__ reference-Session.html#session


.. parsed-literal::
	

	struct state_update_alert final : alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::status;
	   std::vector<torrent_status> status;
	};

.. raw:: html

	<a name="status"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:state_update_alert%3A%3A%5Bstatus%5D&labels=documentation&body=Documentation+under+heading+%22state_update_alert%3A%3A%5Bstatus%5D%22+could+be+improved">report issue</a>]</span>


status
	contains the torrent status of all torrents that changed since last
	time this message was posted. Note that you can map a torrent status
	to a specific torrent via its ``handle`` member. The receiving end is
	suggested to have all torrents sorted by the `torrent_handle`__ or hashed
	by it, for efficient updates.
	

__ reference-Torrent_Handle.html#torrent_handle

.. raw:: html

	<a name="session_stats_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+session_stats_alert&labels=documentation&body=Documentation+under+heading+%22class+session_stats_alert%22+could+be+improved">report issue</a>]</span>



session_stats_alert
-------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

The `session_stats_alert`__ is posted when the user requests `session`__ statistics by
calling `post_session_stats()`__ on the `session`__ object. This `alert`__ does not
have a category, since it's only posted in response to an API call. It
is not subject to the alert_mask filter.

the ``message()`` member function returns a string representation of the values that
properly match the line returned in ``session_stats_header_alert::message()``.

this specific output is parsed by tools/parse_session_stats.py
if this is changed, that parser should also be changed


__ reference-Alerts.html#session_stats_alert
__ reference-Session.html#session
__ reference-Session.html#post_session_stats()
__ reference-Session.html#session
__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct session_stats_alert final : alert
	{
	   std::string **message** () const override;
	   span<std::int64_t const> **counters** () const;
	
	   static constexpr alert_category_t **static_category**  = {};
	};

.. raw:: html

	<a name="counters()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_stats_alert%3A%3A%5Bcounters%28%29%5D&labels=documentation&body=Documentation+under+heading+%22session_stats_alert%3A%3A%5Bcounters%28%29%5D%22+could+be+improved">report issue</a>]</span>



counters()
..........

.. parsed-literal::
	
	span<std::int64_t const> **counters** () const;
	

An array are a mix of *counters* and *gauges*, which meanings can be
queries via the `session_stats_metrics()`__ function on the `session`__. The
mapping from a specific metric to an index into this array is constant
for a specific version of libtorrent, but may differ for other
versions. The intended usage is to request the mapping, i.e. call
`session_stats_metrics()`__, once on startup, and then use that mapping to
interpret these values throughout the process' runtime.

For more information, see the `session statistics`__ section.


__ reference-Stats.html#session_stats_metrics()
__ reference-Session.html#session
__ reference-Stats.html#session_stats_metrics()
__ manual-ref.html#session-statistics

.. raw:: html

	<a name="dht_error_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+dht_error_alert&labels=documentation&body=Documentation+under+heading+%22class+dht_error_alert%22+could+be+improved">report issue</a>]</span>



dht_error_alert
---------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

posted when something fails in the DHT. This is not necessarily a fatal
error, but it could prevent proper operation




.. parsed-literal::
	

	struct dht_error_alert final : alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::error | alert_category::dht;
	   error_code error;
	   operation_t op;
	};

.. raw:: html

	<a name="error"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_error_alert%3A%3A%5Berror%5D&labels=documentation&body=Documentation+under+heading+%22dht_error_alert%3A%3A%5Berror%5D%22+could+be+improved">report issue</a>]</span>


error
	the error code
	


.. raw:: html

	<a name="op"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_error_alert%3A%3A%5Bop%5D&labels=documentation&body=Documentation+under+heading+%22dht_error_alert%3A%3A%5Bop%5D%22+could+be+improved">report issue</a>]</span>


op
	the operation that failed
	


.. raw:: html

	<a name="dht_immutable_item_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+dht_immutable_item_alert&labels=documentation&body=Documentation+under+heading+%22class+dht_immutable_item_alert%22+could+be+improved">report issue</a>]</span>



dht_immutable_item_alert
------------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

this `alert`__ is posted as a response to a call to session::get_item(),
specifically the overload for looking up immutable items in the DHT.


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct dht_immutable_item_alert final : alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::dht;
	   sha1_hash target;
	   entry item;
	};

.. raw:: html

	<a name="target"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_immutable_item_alert%3A%3A%5Btarget%5D&labels=documentation&body=Documentation+under+heading+%22dht_immutable_item_alert%3A%3A%5Btarget%5D%22+could+be+improved">report issue</a>]</span>


target
	the target hash of the immutable item. This must
	match the SHA-1 hash of the bencoded form of ``item``.
	


.. raw:: html

	<a name="item"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_immutable_item_alert%3A%3A%5Bitem%5D&labels=documentation&body=Documentation+under+heading+%22dht_immutable_item_alert%3A%3A%5Bitem%5D%22+could+be+improved">report issue</a>]</span>


item
	the data for this item
	


.. raw:: html

	<a name="dht_mutable_item_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+dht_mutable_item_alert&labels=documentation&body=Documentation+under+heading+%22class+dht_mutable_item_alert%22+could+be+improved">report issue</a>]</span>



dht_mutable_item_alert
----------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

this `alert`__ is posted as a response to a call to session::get_item(),
specifically the overload for looking up mutable items in the DHT.


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct dht_mutable_item_alert final : alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::dht;
	   std::array<char, 32> key;
	   std::array<char, 64> signature;
	   std::int64_t seq;
	   std::string salt;
	   entry item;
	   bool authoritative;
	};

.. raw:: html

	<a name="key"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_mutable_item_alert%3A%3A%5Bkey%5D&labels=documentation&body=Documentation+under+heading+%22dht_mutable_item_alert%3A%3A%5Bkey%5D%22+could+be+improved">report issue</a>]</span>


key
	the public key that was looked up
	


.. raw:: html

	<a name="signature"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_mutable_item_alert%3A%3A%5Bsignature%5D&labels=documentation&body=Documentation+under+heading+%22dht_mutable_item_alert%3A%3A%5Bsignature%5D%22+could+be+improved">report issue</a>]</span>


signature
	the signature of the data. This is not the signature of the
	plain encoded form of the item, but it includes the sequence number
	and possibly the hash as well. See the dht_store document for more
	information. This is primarily useful for echoing back in a store
	request.
	


.. raw:: html

	<a name="seq"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_mutable_item_alert%3A%3A%5Bseq%5D&labels=documentation&body=Documentation+under+heading+%22dht_mutable_item_alert%3A%3A%5Bseq%5D%22+could+be+improved">report issue</a>]</span>


seq
	the sequence number of this item
	


.. raw:: html

	<a name="salt"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_mutable_item_alert%3A%3A%5Bsalt%5D&labels=documentation&body=Documentation+under+heading+%22dht_mutable_item_alert%3A%3A%5Bsalt%5D%22+could+be+improved">report issue</a>]</span>


salt
	the salt, if any, used to lookup and store this item. If no
	salt was used, this is an empty string
	


.. raw:: html

	<a name="item"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_mutable_item_alert%3A%3A%5Bitem%5D&labels=documentation&body=Documentation+under+heading+%22dht_mutable_item_alert%3A%3A%5Bitem%5D%22+could+be+improved">report issue</a>]</span>


item
	the data for this item
	


.. raw:: html

	<a name="authoritative"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_mutable_item_alert%3A%3A%5Bauthoritative%5D&labels=documentation&body=Documentation+under+heading+%22dht_mutable_item_alert%3A%3A%5Bauthoritative%5D%22+could+be+improved">report issue</a>]</span>


authoritative
	the last response for mutable data is authoritative.
	


.. raw:: html

	<a name="dht_put_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+dht_put_alert&labels=documentation&body=Documentation+under+heading+%22class+dht_put_alert%22+could+be+improved">report issue</a>]</span>



dht_put_alert
-------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

this is posted when a DHT put operation completes. This is useful if the
client is waiting for a put to complete before shutting down for instance.




.. parsed-literal::
	

	struct dht_put_alert final : alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::dht;
	   sha1_hash target;
	   std::array<char, 32> public_key;
	   std::array<char, 64> signature;
	   std::string salt;
	   std::int64_t seq;
	   int num_success;
	};

.. raw:: html

	<a name="target"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_put_alert%3A%3A%5Btarget%5D&labels=documentation&body=Documentation+under+heading+%22dht_put_alert%3A%3A%5Btarget%5D%22+could+be+improved">report issue</a>]</span>


target
	the target hash the item was stored under if this was an *immutable*
	item.
	


.. raw:: html

	<a name="public_key"></a>
	<a name="signature"></a>
	<a name="salt"></a>
	<a name="seq"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_put_alert%3A%3A%5Bpublic_key+signature+salt+seq%5D&labels=documentation&body=Documentation+under+heading+%22dht_put_alert%3A%3A%5Bpublic_key+signature+salt+seq%5D%22+could+be+improved">report issue</a>]</span>


public_key signature salt seq
	if a mutable item was stored, these are the public key, signature,
	salt and sequence number the item was stored under.
	


.. raw:: html

	<a name="num_success"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_put_alert%3A%3A%5Bnum_success%5D&labels=documentation&body=Documentation+under+heading+%22dht_put_alert%3A%3A%5Bnum_success%5D%22+could+be+improved">report issue</a>]</span>


num_success
	DHT put operation usually writes item to k nodes, maybe the node
	is stale so no response, or the node doesn't support 'put', or the
	token for write is out of date, etc. num_success is the number of
	successful responses we got from the puts.
	


.. raw:: html

	<a name="i2p_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+i2p_alert&labels=documentation&body=Documentation+under+heading+%22class+i2p_alert%22+could+be+improved">report issue</a>]</span>



i2p_alert
---------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

this `alert`__ is used to report errors in the i2p SAM connection


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct i2p_alert final : alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::error;
	   error_code error;
	};

.. raw:: html

	<a name="error"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:i2p_alert%3A%3A%5Berror%5D&labels=documentation&body=Documentation+under+heading+%22i2p_alert%3A%3A%5Berror%5D%22+could+be+improved">report issue</a>]</span>


error
	the error that occurred in the i2p SAM connection
	


.. raw:: html

	<a name="dht_outgoing_get_peers_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+dht_outgoing_get_peers_alert&labels=documentation&body=Documentation+under+heading+%22class+dht_outgoing_get_peers_alert%22+could+be+improved">report issue</a>]</span>



dht_outgoing_get_peers_alert
----------------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is generated when we send a get_peers request
It belongs to the ``alert_category::dht`` category.


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct dht_outgoing_get_peers_alert final : alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::dht;
	   sha1_hash info_hash;
	   sha1_hash obfuscated_info_hash;
	   aux::noexcept_movable<udp::endpoint> endpoint;
	};

.. raw:: html

	<a name="info_hash"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_outgoing_get_peers_alert%3A%3A%5Binfo_hash%5D&labels=documentation&body=Documentation+under+heading+%22dht_outgoing_get_peers_alert%3A%3A%5Binfo_hash%5D%22+could+be+improved">report issue</a>]</span>


info_hash
	the info_hash of the torrent we're looking for peers for.
	


.. raw:: html

	<a name="obfuscated_info_hash"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_outgoing_get_peers_alert%3A%3A%5Bobfuscated_info_hash%5D&labels=documentation&body=Documentation+under+heading+%22dht_outgoing_get_peers_alert%3A%3A%5Bobfuscated_info_hash%5D%22+could+be+improved">report issue</a>]</span>


obfuscated_info_hash
	if this was an obfuscated lookup, this is the info-hash target
	actually sent to the node.
	


.. raw:: html

	<a name="endpoint"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_outgoing_get_peers_alert%3A%3A%5Bendpoint%5D&labels=documentation&body=Documentation+under+heading+%22dht_outgoing_get_peers_alert%3A%3A%5Bendpoint%5D%22+could+be+improved">report issue</a>]</span>


endpoint
	the endpoint we're sending this query to
	


.. raw:: html

	<a name="log_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+log_alert&labels=documentation&body=Documentation+under+heading+%22class+log_alert%22+could+be+improved">report issue</a>]</span>



log_alert
---------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is posted by some `session`__ wide event. Its main purpose is
trouble shooting and debugging. It's not enabled by the default `alert`__
mask and is enabled by the ``alert_category::session_log`` bit.
Furthermore, it's by default disabled as a build configuration.


__ reference-Alerts.html#alert
__ reference-Session.html#session
__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct log_alert final : alert
	{
	   std::string **message** () const override;
	   char const* **log_message** () const;
	
	   static constexpr alert_category_t **static_category**  = alert_category::session_log;
	};

.. raw:: html

	<a name="log_message()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:log_alert%3A%3A%5Blog_message%28%29%5D&labels=documentation&body=Documentation+under+heading+%22log_alert%3A%3A%5Blog_message%28%29%5D%22+could+be+improved">report issue</a>]</span>



log_message()
.............

.. parsed-literal::
	
	char const* **log_message** () const;
	

returns the log message



.. raw:: html

	<a name="torrent_log_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+torrent_log_alert&labels=documentation&body=Documentation+under+heading+%22class+torrent_log_alert%22+could+be+improved">report issue</a>]</span>



torrent_log_alert
-----------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is posted by torrent wide events. It's meant to be used for
trouble shooting and debugging. It's not enabled by the default `alert`__
mask and is enabled by the ``alert_category::torrent_log`` bit. By
default it is disabled as a build configuration.


__ reference-Alerts.html#alert
__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct torrent_log_alert final : torrent_alert
	{
	   std::string **message** () const override;
	   char const* **log_message** () const;
	
	   static constexpr alert_category_t **static_category**  = alert_category::torrent_log;
	};

.. raw:: html

	<a name="log_message()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_log_alert%3A%3A%5Blog_message%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_log_alert%3A%3A%5Blog_message%28%29%5D%22+could+be+improved">report issue</a>]</span>



log_message()
.............

.. parsed-literal::
	
	char const* **log_message** () const;
	

returns the log message



.. raw:: html

	<a name="peer_log_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+peer_log_alert&labels=documentation&body=Documentation+under+heading+%22class+peer_log_alert%22+could+be+improved">report issue</a>]</span>



peer_log_alert
--------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is posted by events specific to a peer. It's meant to be used
for trouble shooting and debugging. It's not enabled by the default `alert`__
mask and is enabled by the ``alert_category::peer_log`` bit. By
default it is disabled as a build configuration.


__ reference-Alerts.html#alert
__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct peer_log_alert final : peer_alert
	{
	   std::string **message** () const override;
	   char const* **log_message** () const;
	
	   enum direction_t
	   {
	      incoming_message,
	      outgoing_message,
	      incoming,
	      outgoing,
	      info,
	   };
	
	   static constexpr alert_category_t **static_category**  = alert_category::peer_log;
	   char const* event_type;
	   direction_t direction;
	};

.. raw:: html

	<a name="log_message()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_log_alert%3A%3A%5Blog_message%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_log_alert%3A%3A%5Blog_message%28%29%5D%22+could+be+improved">report issue</a>]</span>



log_message()
.............

.. parsed-literal::
	
	char const* **log_message** () const;
	

returns the log message



.. raw:: html

	<a name="direction_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+direction_t&labels=documentation&body=Documentation+under+heading+%22enum+direction_t%22+could+be+improved">report issue</a>]</span>



enum direction_t
................

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

+------------------+-------+-------------+
| name             | value | description |
+==================+=======+=============+
| incoming_message | 0     |             |
+------------------+-------+-------------+
| outgoing_message | 1     |             |
+------------------+-------+-------------+
| incoming         | 2     |             |
+------------------+-------+-------------+
| outgoing         | 3     |             |
+------------------+-------+-------------+
| info             | 4     |             |
+------------------+-------+-------------+



.. raw:: html

	<a name="event_type"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_log_alert%3A%3A%5Bevent_type%5D&labels=documentation&body=Documentation+under+heading+%22peer_log_alert%3A%3A%5Bevent_type%5D%22+could+be+improved">report issue</a>]</span>


event_type
	string literal indicating the kind of event. For messages, this is the
	message name.
	


.. raw:: html

	<a name="lsd_error_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+lsd_error_alert&labels=documentation&body=Documentation+under+heading+%22class+lsd_error_alert%22+could+be+improved">report issue</a>]</span>



lsd_error_alert
---------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

posted if the local service discovery socket fails to start properly.
it's categorized as ``alert_category::error``.




.. parsed-literal::
	

	struct lsd_error_alert final : alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::error;
	   aux::noexcept_movable<address> local_address;
	   error_code error;
	};

.. raw:: html

	<a name="local_address"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:lsd_error_alert%3A%3A%5Blocal_address%5D&labels=documentation&body=Documentation+under+heading+%22lsd_error_alert%3A%3A%5Blocal_address%5D%22+could+be+improved">report issue</a>]</span>


local_address
	the local network the corresponding local service discovery is running
	on
	


.. raw:: html

	<a name="error"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:lsd_error_alert%3A%3A%5Berror%5D&labels=documentation&body=Documentation+under+heading+%22lsd_error_alert%3A%3A%5Berror%5D%22+could+be+improved">report issue</a>]</span>


error
	The error code
	


.. raw:: html

	<a name="dht_lookup"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+dht_lookup&labels=documentation&body=Documentation+under+heading+%22class+dht_lookup%22+could+be+improved">report issue</a>]</span>



dht_lookup
----------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

holds statistics about a current `dht_lookup`__ operation.
a DHT lookup is the traversal of nodes, looking up a
set of target nodes in the DHT for retrieving and possibly
storing information in the DHT


__ reference-Alerts.html#dht_lookup


.. parsed-literal::
	

	struct dht_lookup
	{
	   char const* type;
	   int outstanding_requests;
	   int timeouts;
	   int responses;
	   int branch_factor;
	   int nodes_left;
	   int last_sent;
	   int first_timeout;
	   sha1_hash target;
	};

.. raw:: html

	<a name="type"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_lookup%3A%3A%5Btype%5D&labels=documentation&body=Documentation+under+heading+%22dht_lookup%3A%3A%5Btype%5D%22+could+be+improved">report issue</a>]</span>


type
	string literal indicating which kind of lookup this is
	


.. raw:: html

	<a name="outstanding_requests"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_lookup%3A%3A%5Boutstanding_requests%5D&labels=documentation&body=Documentation+under+heading+%22dht_lookup%3A%3A%5Boutstanding_requests%5D%22+could+be+improved">report issue</a>]</span>


outstanding_requests
	the number of outstanding request to individual nodes
	this lookup has right now
	


.. raw:: html

	<a name="timeouts"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_lookup%3A%3A%5Btimeouts%5D&labels=documentation&body=Documentation+under+heading+%22dht_lookup%3A%3A%5Btimeouts%5D%22+could+be+improved">report issue</a>]</span>


timeouts
	the total number of requests that have timed out so far
	for this lookup
	


.. raw:: html

	<a name="responses"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_lookup%3A%3A%5Bresponses%5D&labels=documentation&body=Documentation+under+heading+%22dht_lookup%3A%3A%5Bresponses%5D%22+could+be+improved">report issue</a>]</span>


responses
	the total number of responses we have received for this
	lookup so far for this lookup
	


.. raw:: html

	<a name="branch_factor"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_lookup%3A%3A%5Bbranch_factor%5D&labels=documentation&body=Documentation+under+heading+%22dht_lookup%3A%3A%5Bbranch_factor%5D%22+could+be+improved">report issue</a>]</span>


branch_factor
	the branch factor for this lookup. This is the number of
	nodes we keep outstanding requests to in parallel by default.
	when nodes time out we may increase this.
	


.. raw:: html

	<a name="nodes_left"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_lookup%3A%3A%5Bnodes_left%5D&labels=documentation&body=Documentation+under+heading+%22dht_lookup%3A%3A%5Bnodes_left%5D%22+could+be+improved">report issue</a>]</span>


nodes_left
	the number of nodes left that could be queries for this
	lookup. Many of these are likely to be part of the trail
	while performing the lookup and would never end up actually
	being queried.
	


.. raw:: html

	<a name="last_sent"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_lookup%3A%3A%5Blast_sent%5D&labels=documentation&body=Documentation+under+heading+%22dht_lookup%3A%3A%5Blast_sent%5D%22+could+be+improved">report issue</a>]</span>


last_sent
	the number of seconds ago the
	last message was sent that's still
	outstanding
	


.. raw:: html

	<a name="first_timeout"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_lookup%3A%3A%5Bfirst_timeout%5D&labels=documentation&body=Documentation+under+heading+%22dht_lookup%3A%3A%5Bfirst_timeout%5D%22+could+be+improved">report issue</a>]</span>


first_timeout
	the number of outstanding requests
	that have exceeded the short timeout
	and are considered timed out in the
	sense that they increased the branch
	factor
	


.. raw:: html

	<a name="target"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_lookup%3A%3A%5Btarget%5D&labels=documentation&body=Documentation+under+heading+%22dht_lookup%3A%3A%5Btarget%5D%22+could+be+improved">report issue</a>]</span>


target
	the node-id or info-hash target for this lookup
	


.. raw:: html

	<a name="dht_stats_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+dht_stats_alert&labels=documentation&body=Documentation+under+heading+%22class+dht_stats_alert%22+could+be+improved">report issue</a>]</span>



dht_stats_alert
---------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

contains current DHT state. Posted in response to session::post_dht_stats().




.. parsed-literal::
	

	struct dht_stats_alert final : alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = {};
	   std::vector<dht_lookup> active_requests;
	   std::vector<dht_routing_bucket> routing_table;
	   sha1_hash nid;
	   aux::noexcept_movable<udp::endpoint> local_endpoint;
	};

.. raw:: html

	<a name="active_requests"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_stats_alert%3A%3A%5Bactive_requests%5D&labels=documentation&body=Documentation+under+heading+%22dht_stats_alert%3A%3A%5Bactive_requests%5D%22+could+be+improved">report issue</a>]</span>


active_requests
	a vector of the currently running DHT lookups.
	


.. raw:: html

	<a name="routing_table"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_stats_alert%3A%3A%5Brouting_table%5D&labels=documentation&body=Documentation+under+heading+%22dht_stats_alert%3A%3A%5Brouting_table%5D%22+could+be+improved">report issue</a>]</span>


routing_table
	contains information about every bucket in the DHT routing
	table.
	


.. raw:: html

	<a name="nid"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_stats_alert%3A%3A%5Bnid%5D&labels=documentation&body=Documentation+under+heading+%22dht_stats_alert%3A%3A%5Bnid%5D%22+could+be+improved">report issue</a>]</span>


nid
	the node ID of the DHT node instance
	


.. raw:: html

	<a name="local_endpoint"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_stats_alert%3A%3A%5Blocal_endpoint%5D&labels=documentation&body=Documentation+under+heading+%22dht_stats_alert%3A%3A%5Blocal_endpoint%5D%22+could+be+improved">report issue</a>]</span>


local_endpoint
	the local socket this DHT node is running on
	


.. raw:: html

	<a name="incoming_request_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+incoming_request_alert&labels=documentation&body=Documentation+under+heading+%22class+incoming_request_alert%22+could+be+improved">report issue</a>]</span>



incoming_request_alert
----------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

posted every time an incoming request from a peer is accepted and queued
up for being serviced. This `alert`__ is only posted if
the alert_category::incoming_request flag is enabled in the `alert`__
mask.


__ reference-Alerts.html#alert
__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct incoming_request_alert final : peer_alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::incoming_request;
	   peer_request req;
	};

.. raw:: html

	<a name="req"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:incoming_request_alert%3A%3A%5Breq%5D&labels=documentation&body=Documentation+under+heading+%22incoming_request_alert%3A%3A%5Breq%5D%22+could+be+improved">report issue</a>]</span>


req
	the request this peer sent to us
	


.. raw:: html

	<a name="dht_log_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+dht_log_alert&labels=documentation&body=Documentation+under+heading+%22class+dht_log_alert%22+could+be+improved">report issue</a>]</span>



dht_log_alert
-------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

debug logging of the DHT when alert_category::dht_log is set in the `alert`__
mask.


__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct dht_log_alert final : alert
	{
	   std::string **message** () const override;
	   char const* **log_message** () const;
	
	   enum dht_module_t
	   {
	      tracker,
	      node,
	      routing_table,
	      rpc_manager,
	      traversal,
	   };
	
	   static constexpr alert_category_t **static_category**  = alert_category::dht_log;
	   dht_module_t module;
	};

.. raw:: html

	<a name="log_message()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_log_alert%3A%3A%5Blog_message%28%29%5D&labels=documentation&body=Documentation+under+heading+%22dht_log_alert%3A%3A%5Blog_message%28%29%5D%22+could+be+improved">report issue</a>]</span>



log_message()
.............

.. parsed-literal::
	
	char const* **log_message** () const;
	

the log message



.. raw:: html

	<a name="dht_module_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+dht_module_t&labels=documentation&body=Documentation+under+heading+%22enum+dht_module_t%22+could+be+improved">report issue</a>]</span>



enum dht_module_t
.................

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

+---------------+-------+-------------+
| name          | value | description |
+===============+=======+=============+
| tracker       | 0     |             |
+---------------+-------+-------------+
| node          | 1     |             |
+---------------+-------+-------------+
| routing_table | 2     |             |
+---------------+-------+-------------+
| rpc_manager   | 3     |             |
+---------------+-------+-------------+
| traversal     | 4     |             |
+---------------+-------+-------------+



.. raw:: html

	<a name="module"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_log_alert%3A%3A%5Bmodule%5D&labels=documentation&body=Documentation+under+heading+%22dht_log_alert%3A%3A%5Bmodule%5D%22+could+be+improved">report issue</a>]</span>


module
	the module, or part, of the DHT that produced this log message.
	


.. raw:: html

	<a name="dht_pkt_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+dht_pkt_alert&labels=documentation&body=Documentation+under+heading+%22class+dht_pkt_alert%22+could+be+improved">report issue</a>]</span>



dht_pkt_alert
-------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is posted every time a DHT message is sent or received. It is
only posted if the ``alert_category::dht_log`` `alert`__ category is
enabled. It contains a verbatim copy of the message.


__ reference-Alerts.html#alert
__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct dht_pkt_alert final : alert
	{
	   std::string **message** () const override;
	   span<char const> **pkt_buf** () const;
	
	   enum direction_t
	   {
	      incoming,
	      outgoing,
	   };
	
	   static constexpr alert_category_t **static_category**  = alert_category::dht_log;
	   direction_t direction;
	   aux::noexcept_movable<udp::endpoint> node;
	};

.. raw:: html

	<a name="pkt_buf()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_pkt_alert%3A%3A%5Bpkt_buf%28%29%5D&labels=documentation&body=Documentation+under+heading+%22dht_pkt_alert%3A%3A%5Bpkt_buf%28%29%5D%22+could+be+improved">report issue</a>]</span>



pkt_buf()
.........

.. parsed-literal::
	
	span<char const> **pkt_buf** () const;
	

returns a pointer to the packet buffer and size of the packet,
respectively. This buffer is only valid for as long as the `alert`__ itself
is valid, which is owned by libtorrent and reclaimed whenever
`pop_alerts()`__ is called on the `session`__.


__ reference-Alerts.html#alert
__ reference-Session.html#pop_alerts()
__ reference-Session.html#session

.. raw:: html

	<a name="direction_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+direction_t&labels=documentation&body=Documentation+under+heading+%22enum+direction_t%22+could+be+improved">report issue</a>]</span>



enum direction_t
................

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

+----------+-------+-------------+
| name     | value | description |
+==========+=======+=============+
| incoming | 0     |             |
+----------+-------+-------------+
| outgoing | 1     |             |
+----------+-------+-------------+



.. raw:: html

	<a name="direction"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_pkt_alert%3A%3A%5Bdirection%5D&labels=documentation&body=Documentation+under+heading+%22dht_pkt_alert%3A%3A%5Bdirection%5D%22+could+be+improved">report issue</a>]</span>


direction
	whether this is an incoming or outgoing packet.
	


.. raw:: html

	<a name="node"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_pkt_alert%3A%3A%5Bnode%5D&labels=documentation&body=Documentation+under+heading+%22dht_pkt_alert%3A%3A%5Bnode%5D%22+could+be+improved">report issue</a>]</span>


node
	the DHT node we received this packet from, or sent this packet to
	(depending on ``direction``).
	


.. raw:: html

	<a name="dht_get_peers_reply_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+dht_get_peers_reply_alert&labels=documentation&body=Documentation+under+heading+%22class+dht_get_peers_reply_alert%22+could+be+improved">report issue</a>]</span>



dht_get_peers_reply_alert
-------------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

Posted when we receive a response to a DHT get_peers request.




.. parsed-literal::
	

	struct dht_get_peers_reply_alert final : alert
	{
	   std::string **message** () const override;
	   int **num_peers** () const;
	   std::vector<tcp::endpoint> **peers** () const;
	
	   static constexpr alert_category_t **static_category**  = alert_category::dht_operation;
	   sha1_hash info_hash;
	};

.. raw:: html

	<a name="dht_direct_response_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+dht_direct_response_alert&labels=documentation&body=Documentation+under+heading+%22class+dht_direct_response_alert%22+could+be+improved">report issue</a>]</span>



dht_direct_response_alert
-------------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This is posted exactly once for every call to session_handle::dht_direct_request.
If the request failed, `response()`__ will return a default constructed `bdecode_node`__.


__ reference-Alerts.html#response()
__ reference-Bdecoding.html#bdecode_node


.. parsed-literal::
	

	struct dht_direct_response_alert final : alert
	{
	   std::string **message** () const override;
	   bdecode_node **response** () const;
	
	   static constexpr alert_category_t **static_category**  = alert_category::dht;
	   client_data_t userdata;
	   aux::noexcept_movable<udp::endpoint> endpoint;
	};

.. raw:: html

	<a name="picker_log_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+picker_log_alert&labels=documentation&body=Documentation+under+heading+%22class+picker_log_alert%22+could+be+improved">report issue</a>]</span>



picker_log_alert
----------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

this is posted when one or more blocks are picked by the piece picker,
assuming the verbose piece picker logging is enabled (see
alert_category::picker_log).




.. parsed-literal::
	

	struct picker_log_alert final : peer_alert
	{
	   std::string **message** () const override;
	   std::vector<piece_block> **blocks** () const;
	
	   static constexpr alert_category_t **static_category**  = alert_category::picker_log;
	   static constexpr picker_flags_t **partial_ratio**  = 0_bit;
	   static constexpr picker_flags_t **prioritize_partials**  = 1_bit;
	   static constexpr picker_flags_t **rarest_first_partials**  = 2_bit;
	   static constexpr picker_flags_t **rarest_first**  = 3_bit;
	   static constexpr picker_flags_t **reverse_rarest_first**  = 4_bit;
	   static constexpr picker_flags_t **suggested_pieces**  = 5_bit;
	   static constexpr picker_flags_t **prio_sequential_pieces**  = 6_bit;
	   static constexpr picker_flags_t **sequential_pieces**  = 7_bit;
	   static constexpr picker_flags_t **reverse_pieces**  = 8_bit;
	   static constexpr picker_flags_t **time_critical**  = 9_bit;
	   static constexpr picker_flags_t **random_pieces**  = 10_bit;
	   static constexpr picker_flags_t **prefer_contiguous**  = 11_bit;
	   static constexpr picker_flags_t **reverse_sequential**  = 12_bit;
	   static constexpr picker_flags_t **backup1**  = 13_bit;
	   static constexpr picker_flags_t **backup2**  = 14_bit;
	   static constexpr picker_flags_t **end_game**  = 15_bit;
	   static constexpr picker_flags_t **extent_affinity**  = 16_bit;
	   picker_flags_t const picker_flags;
	};

.. raw:: html

	<a name="picker_flags"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:picker_log_alert%3A%3A%5Bpicker_flags%5D&labels=documentation&body=Documentation+under+heading+%22picker_log_alert%3A%3A%5Bpicker_flags%5D%22+could+be+improved">report issue</a>]</span>


picker_flags
	this is a bitmask of which features were enabled for this particular
	pick. The bits are defined in the picker_flags_t enum.
	


.. raw:: html

	<a name="session_error_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+session_error_alert&labels=documentation&body=Documentation+under+heading+%22class+session_error_alert%22+could+be+improved">report issue</a>]</span>



session_error_alert
-------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

this `alert`__ is posted when the `session`__ encounters a serious error,
potentially fatal


__ reference-Alerts.html#alert
__ reference-Session.html#session


.. parsed-literal::
	

	struct session_error_alert final : alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::error;
	   error_code const error;
	};

.. raw:: html

	<a name="error"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_error_alert%3A%3A%5Berror%5D&labels=documentation&body=Documentation+under+heading+%22session_error_alert%3A%3A%5Berror%5D%22+could+be+improved">report issue</a>]</span>


error
	The error code, if one is associated with this error
	


.. raw:: html

	<a name="dht_live_nodes_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+dht_live_nodes_alert&labels=documentation&body=Documentation+under+heading+%22class+dht_live_nodes_alert%22+could+be+improved">report issue</a>]</span>



dht_live_nodes_alert
--------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/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.




.. parsed-literal::
	

	struct dht_live_nodes_alert final : alert
	{
	   std::string **message** () const override;
	   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;
	};

.. raw:: html

	<a name="num_nodes()"></a>
	<a name="nodes()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_live_nodes_alert%3A%3A%5Bnum_nodes%28%29+nodes%28%29%5D&labels=documentation&body=Documentation+under+heading+%22dht_live_nodes_alert%3A%3A%5Bnum_nodes%28%29+nodes%28%29%5D%22+could+be+improved">report issue</a>]</span>



num_nodes() nodes()
...................

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="node_id"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_live_nodes_alert%3A%3A%5Bnode_id%5D&labels=documentation&body=Documentation+under+heading+%22dht_live_nodes_alert%3A%3A%5Bnode_id%5D%22+could+be+improved">report issue</a>]</span>


node_id
	the local DHT node's node-ID this routing table belongs to
	


.. raw:: html

	<a name="session_stats_header_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+session_stats_header_alert&labels=documentation&body=Documentation+under+heading+%22class+session_stats_header_alert%22+could+be+improved">report issue</a>]</span>



session_stats_header_alert
--------------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

The session_stats_header `alert`__ is posted the first time
`post_session_stats()`__ is called

the ``message()`` member function returns a string representation of the
header that properly match the stats values string returned in
``session_stats_alert::message()``.

this specific output is parsed by tools/parse_session_stats.py
if this is changed, that parser should also be changed


__ reference-Alerts.html#alert
__ reference-Session.html#post_session_stats()


.. parsed-literal::
	

	struct session_stats_header_alert final : alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = {};
	};

.. raw:: html

	<a name="dht_sample_infohashes_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+dht_sample_infohashes_alert&labels=documentation&body=Documentation+under+heading+%22class+dht_sample_infohashes_alert%22+could+be+improved">report issue</a>]</span>



dht_sample_infohashes_alert
---------------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

posted as a response to a call to session::dht_sample_infohashes() with
the information from the DHT response message.




.. parsed-literal::
	

	struct dht_sample_infohashes_alert final : alert
	{
	   std::string **message** () const override;
	   std::vector<sha1_hash> **samples** () const;
	   int **num_samples** () 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_operation;
	   sha1_hash node_id;
	   aux::noexcept_movable<udp::endpoint> endpoint;
	   time_duration const interval;
	   int const num_infohashes;
	};

.. raw:: html

	<a name="num_samples()"></a>
	<a name="samples()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_sample_infohashes_alert%3A%3A%5Bnum_samples%28%29+samples%28%29%5D&labels=documentation&body=Documentation+under+heading+%22dht_sample_infohashes_alert%3A%3A%5Bnum_samples%28%29+samples%28%29%5D%22+could+be+improved">report issue</a>]</span>



num_samples() samples()
.......................

.. parsed-literal::
	
	std::vector<sha1_hash> **samples** () const;
	int **num_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()``.



.. raw:: html

	<a name="num_nodes()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_sample_infohashes_alert%3A%3A%5Bnum_nodes%28%29%5D&labels=documentation&body=Documentation+under+heading+%22dht_sample_infohashes_alert%3A%3A%5Bnum_nodes%28%29%5D%22+could+be+improved">report issue</a>]</span>



num_nodes()
...........

.. parsed-literal::
	
	int **num_nodes** () const;
	

The total number of nodes returned by ``nodes()``.



.. raw:: html

	<a name="nodes()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_sample_infohashes_alert%3A%3A%5Bnodes%28%29%5D&labels=documentation&body=Documentation+under+heading+%22dht_sample_infohashes_alert%3A%3A%5Bnodes%28%29%5D%22+could+be+improved">report issue</a>]</span>



nodes()
.......

.. parsed-literal::
	
	std::vector<std::pair<sha1_hash, udp::endpoint>> **nodes** () const;
	

This is the set of more DHT nodes returned by the request.

The information is included so that indexing nodes can perform a key
space traversal with a single RPC per node by adjusting the target
value for each RPC.



.. raw:: html

	<a name="node_id"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_sample_infohashes_alert%3A%3A%5Bnode_id%5D&labels=documentation&body=Documentation+under+heading+%22dht_sample_infohashes_alert%3A%3A%5Bnode_id%5D%22+could+be+improved">report issue</a>]</span>


node_id
	id of the node the request was sent to (and this response was received from)
	


.. raw:: html

	<a name="endpoint"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_sample_infohashes_alert%3A%3A%5Bendpoint%5D&labels=documentation&body=Documentation+under+heading+%22dht_sample_infohashes_alert%3A%3A%5Bendpoint%5D%22+could+be+improved">report issue</a>]</span>


endpoint
	the node the request was sent to (and this response was received from)
	


.. raw:: html

	<a name="interval"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_sample_infohashes_alert%3A%3A%5Binterval%5D&labels=documentation&body=Documentation+under+heading+%22dht_sample_infohashes_alert%3A%3A%5Binterval%5D%22+could+be+improved">report issue</a>]</span>


interval
	the interval to wait before making another request to this node
	


.. raw:: html

	<a name="num_infohashes"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_sample_infohashes_alert%3A%3A%5Bnum_infohashes%5D&labels=documentation&body=Documentation+under+heading+%22dht_sample_infohashes_alert%3A%3A%5Bnum_infohashes%5D%22+could+be+improved">report issue</a>]</span>


num_infohashes
	This field indicates how many info-hash keys are currently in the node's storage.
	If the value is larger than the number of returned samples it indicates that the
	indexer may obtain additional samples after waiting out the interval.
	


.. raw:: html

	<a name="block_uploaded_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+block_uploaded_alert&labels=documentation&body=Documentation+under+heading+%22class+block_uploaded_alert%22+could+be+improved">report issue</a>]</span>



block_uploaded_alert
--------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

This `alert`__ is posted when a block intended to be sent to a peer is placed in the
send buffer. Note that if the connection is closed before the send buffer is sent,
the `alert`__ may be posted without the bytes having been sent to the peer.
It belongs to the ``alert_category::upload`` category.


__ reference-Alerts.html#alert
__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct block_uploaded_alert final : peer_alert
	{
	   std::string **message** () const override;
	
	   int const block_index;
	   piece_index_t const piece_index;
	};

.. raw:: html

	<a name="alerts_dropped_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+alerts_dropped_alert&labels=documentation&body=Documentation+under+heading+%22class+alerts_dropped_alert%22+could+be+improved">report issue</a>]</span>



alerts_dropped_alert
--------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/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).


__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert


.. parsed-literal::
	

	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");
	
	   static constexpr alert_category_t **static_category**  = alert_category::error;
	   std::bitset<abi_alert_count> dropped_alerts;
	};

.. raw:: html

	<a name="dropped_alerts"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:alerts_dropped_alert%3A%3A%5Bdropped_alerts%5D&labels=documentation&body=Documentation+under+heading+%22alerts_dropped_alert%3A%3A%5Bdropped_alerts%5D%22+could+be+improved">report issue</a>]</span>


dropped_alerts
	a bitmask indicating which alerts were dropped. Each bit represents the
	`alert`__ type ID, where bit 0 represents whether any `alert`__ of type 0 has
	been dropped, and so on.
	

__ reference-Alerts.html#alert
__ reference-Alerts.html#alert

.. raw:: html

	<a name="socks5_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+socks5_alert&labels=documentation&body=Documentation+under+heading+%22class+socks5_alert%22+could+be+improved">report issue</a>]</span>



socks5_alert
------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

this `alert`__ is posted with SOCKS5 related errors, when a SOCKS5 proxy is
configured. It's enabled with the alert_category::error `alert`__ category.


__ reference-Alerts.html#alert
__ reference-Alerts.html#alert


.. parsed-literal::
	

	struct socks5_alert final : alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::error;
	   error_code error;
	   operation_t op;
	   aux::noexcept_movable<tcp::endpoint> ip;
	};

.. raw:: html

	<a name="error"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:socks5_alert%3A%3A%5Berror%5D&labels=documentation&body=Documentation+under+heading+%22socks5_alert%3A%3A%5Berror%5D%22+could+be+improved">report issue</a>]</span>


error
	the error
	


.. raw:: html

	<a name="op"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:socks5_alert%3A%3A%5Bop%5D&labels=documentation&body=Documentation+under+heading+%22socks5_alert%3A%3A%5Bop%5D%22+could+be+improved">report issue</a>]</span>


op
	the operation that failed
	


.. raw:: html

	<a name="ip"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:socks5_alert%3A%3A%5Bip%5D&labels=documentation&body=Documentation+under+heading+%22socks5_alert%3A%3A%5Bip%5D%22+could+be+improved">report issue</a>]</span>


ip
	the endpoint configured as the proxy
	


.. raw:: html

	<a name="file_prio_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+file_prio_alert&labels=documentation&body=Documentation+under+heading+%22class+file_prio_alert%22+could+be+improved">report issue</a>]</span>



file_prio_alert
---------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

posted when a `prioritize_files()`__ or `file_priority()`__ update of the file
priorities complete, which requires a round-trip to the disk thread.

If the disk operation fails this `alert`__ won't be posted, but a
`file_error_alert`__ is posted instead, and the torrent is stopped.


__ reference-Torrent_Handle.html#prioritize_files()
__ reference-Torrent_Handle.html#file_priority()
__ reference-Alerts.html#alert
__ reference-Alerts.html#file_error_alert


.. parsed-literal::
	

	struct file_prio_alert final : torrent_alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::storage;
	   error_code error;
	   operation_t op;
	};

.. raw:: html

	<a name="error"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_prio_alert%3A%3A%5Berror%5D&labels=documentation&body=Documentation+under+heading+%22file_prio_alert%3A%3A%5Berror%5D%22+could+be+improved">report issue</a>]</span>


error
	the error
	


.. raw:: html

	<a name="op"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_prio_alert%3A%3A%5Bop%5D&labels=documentation&body=Documentation+under+heading+%22file_prio_alert%3A%3A%5Bop%5D%22+could+be+improved">report issue</a>]</span>


op
	the operation that failed
	


.. raw:: html

	<a name="oversized_file_alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+oversized_file_alert&labels=documentation&body=Documentation+under+heading+%22class+oversized_file_alert%22+could+be+improved">report issue</a>]</span>



oversized_file_alert
--------------------

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

this `alert`__ may be posted when the initial checking of resume data and files
on disk (just existence, not piece hashes) completes. If a file belonging
to the torrent is found on disk, but is larger than the file in the
torrent, that's when this `alert`__ is posted.
the client may want to call `truncate_files()`__ in that case, or perhaps
interpret it as a sign that some other file is in the way, that shouldn't
be overwritten.


__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Core.html#truncate_files()


.. parsed-literal::
	

	struct oversized_file_alert final : torrent_alert
	{
	   std::string **message** () const override;
	
	   static constexpr alert_category_t **static_category**  = alert_category::storage;
	};

.. raw:: html

	<a name="alert"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+alert&labels=documentation&body=Documentation+under+heading+%22class+alert%22+could+be+improved">report issue</a>]</span>



alert
-----

Declared in "`libtorrent/alert.hpp`__"


__ include/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()`__)


__ reference-Alerts.html#alert
__ reference-Session.html#pop_alerts()


.. parsed-literal::
	

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

.. raw:: html

	<a name="timestamp()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:alert%3A%3A%5Btimestamp%28%29%5D&labels=documentation&body=Documentation+under+heading+%22alert%3A%3A%5Btimestamp%28%29%5D%22+could+be+improved">report issue</a>]</span>



timestamp()
...........

.. parsed-literal::
	
	time_point **timestamp** () const;
	

a timestamp is automatically created in the constructor



.. raw:: html

	<a name="type()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:alert%3A%3A%5Btype%28%29%5D&labels=documentation&body=Documentation+under+heading+%22alert%3A%3A%5Btype%28%29%5D%22+could+be+improved">report issue</a>]</span>



type()
......

.. parsed-literal::
	
	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:

.. code:: c++

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


__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert

.. raw:: html

	<a name="what()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:alert%3A%3A%5Bwhat%28%29%5D&labels=documentation&body=Documentation+under+heading+%22alert%3A%3A%5Bwhat%28%29%5D%22+could+be+improved">report issue</a>]</span>



what()
......

.. parsed-literal::
	
	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`__.


__ reference-Alerts.html#alert
__ reference-Alerts.html#alert

.. raw:: html

	<a name="message()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:alert%3A%3A%5Bmessage%28%29%5D&labels=documentation&body=Documentation+under+heading+%22alert%3A%3A%5Bmessage%28%29%5D%22+could+be+improved">report issue</a>]</span>



message()
.........

.. parsed-literal::
	
	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.


__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert

.. raw:: html

	<a name="category()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:alert%3A%3A%5Bcategory%28%29%5D&labels=documentation&body=Documentation+under+heading+%22alert%3A%3A%5Bcategory%28%29%5D%22+could+be+improved">report issue</a>]</span>



category()
..........

.. parsed-literal::
	
	virtual alert_category_t **category** () const noexcept = 0;
	

returns a bitmask specifying which categories this `alert`__ belong to.


__ reference-Alerts.html#alert

.. raw:: html

	<a name="operation_name()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:operation_name%28%29&labels=documentation&body=Documentation+under+heading+%22operation_name%28%29%22+could+be+improved">report issue</a>]</span>



operation_name()
----------------

Declared in "`libtorrent/operations.hpp`__"


__ include/libtorrent/operations.hpp

.. parsed-literal::
	
	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


__ reference-Alerts.html#peer_error_alert
__ reference-Alerts.html#peer_disconnected_alert
__ reference-Alerts.html#operation_t

.. raw:: html

	<a name="alert_cast()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:alert_cast%28%29&labels=documentation&body=Documentation+under+heading+%22alert_cast%28%29%22+could+be+improved">report issue</a>]</span>



alert_cast()
------------

Declared in "`libtorrent/alert.hpp`__"


__ include/libtorrent/alert.hpp

.. parsed-literal::
	
	template <typename T> T const* **alert_cast** (alert const\* a);
	template <typename T> T* **alert_cast** (alert\* 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


__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert

.. raw:: html

	<a name="operation_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+operation_t&labels=documentation&body=Documentation+under+heading+%22enum+operation_t%22+could+be+improved">report issue</a>]</span>



enum operation_t
----------------

Declared in "`libtorrent/operations.hpp`__"


__ include/libtorrent/operations.hpp

+---------------------+-------+-------------------------------------------------------------------------+
| name                | value | description                                                             |
+=====================+=======+=========================================================================+
| unknown             | 0     | the error was unexpected and it is unknown which operation caused it    |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| bittorrent          | 1     | this is used when the bittorrent logic                                  |
|                     |       | determines to disconnect                                                |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| iocontrol           | 2     | a call to iocontrol failed                                              |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| getpeername         | 3     | a call to ``getpeername()`` failed (querying the remote IP of a         |
|                     |       | connection)                                                             |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| getname             | 4     | a call to getname failed (querying the local IP of a                    |
|                     |       | connection)                                                             |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| alloc_recvbuf       | 5     | an attempt to allocate a receive buffer failed                          |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| alloc_sndbuf        | 6     | an attempt to allocate a send buffer failed                             |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| file_write          | 7     | writing to a file failed                                                |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| file_read           | 8     | reading from a file failed                                              |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| file                | 9     | a non-read and non-write file operation failed                          |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| sock_write          | 10    | a socket write operation failed                                         |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| sock_read           | 11    | a socket read operation failed                                          |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| sock_open           | 12    | a call to open(), to create a socket socket failed                      |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| sock_bind           | 13    | a call to bind() on a socket failed                                     |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| available           | 14    | an attempt to query the number of bytes available to read from a socket |
|                     |       | failed                                                                  |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| encryption          | 15    | a call related to bittorrent protocol encryption failed                 |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| connect             | 16    | an attempt to connect a socket failed                                   |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| ssl_handshake       | 17    | establishing an SSL connection failed                                   |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| get_interface       | 18    | a connection failed to satisfy the bind interface setting               |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| sock_listen         | 19    | a call to listen() on a socket                                          |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| sock_bind_to_device | 20    | a call to the ioctl to bind a socket to a specific network device or    |
|                     |       | adapter                                                                 |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| sock_accept         | 21    | a call to accept() on a socket                                          |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| parse_address       | 22    | convert a string into a valid network address                           |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| enum_if             | 23    | enumeration network devices or adapters                                 |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| file_stat           | 24    | invoking stat() on a file                                               |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| file_copy           | 25    | copying a file                                                          |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| file_fallocate      | 26    | allocating storage for a file                                           |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| file_hard_link      | 27    | creating a hard link                                                    |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| file_remove         | 28    | removing a file                                                         |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| file_rename         | 29    | renaming a file                                                         |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| file_open           | 30    | opening a file                                                          |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| mkdir               | 31    | creating a directory                                                    |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| check_resume        | 32    | check fast resume data against files on disk                            |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| exception           | 33    | an unknown exception                                                    |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| alloc_cache_piece   | 34    | allocate space for a piece in the cache                                 |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| partfile_move       | 35    | move a part-file                                                        |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| partfile_read       | 36    | read from a part file                                                   |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| partfile_write      | 37    | write to a part-file                                                    |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| hostname_lookup     | 38    | a hostname lookup                                                       |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| symlink             | 39    | create or read a symlink                                                |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| handshake           | 40    | handshake with a peer or server                                         |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| sock_option         | 41    | set socket option                                                       |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+
| 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)                      |
|                     |       |                                                                         |
+---------------------+-------+-------------------------------------------------------------------------+


__ reference-Alerts.html#hostname_lookup

.. raw:: html

	<a name="int"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:int&labels=documentation&body=Documentation+under+heading+%22int%22+could+be+improved">report issue</a>]</span>



int
---

Declared in "`libtorrent/alert_types.hpp`__"


__ include/libtorrent/alert_types.hpp

.. raw:: html

	<a name="int::user_alert_id"></a>

user_alert_id
	user defined alerts should use IDs greater than this
	


.. raw:: html

	<a name="int::num_alert_types"></a>

num_alert_types
	this constant represents "max_alert_index" + 1
	



.. raw:: html

	<a name="alert_category_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:alert_category_t&labels=documentation&body=Documentation+under+heading+%22alert_category_t%22+could+be+improved">report issue</a>]</span>



alert_category_t
----------------

Declared in "`libtorrent/alert.hpp`__"


__ include/libtorrent/alert.hpp

.. raw:: html

	<a name="alert_category_t::error"></a>

error
	Enables alerts that report an error. This includes:
	
	* tracker errors
	* tracker warnings
	* file errors
	* resume data failures
	* web seed errors
	* .torrent files errors
	* listen socket errors
	* port mapping errors
	


.. raw:: html

	<a name="alert_category_t::peer"></a>

peer
	Enables alerts when peers send invalid requests, get banned or
	snubbed.
	


.. raw:: html

	<a name="alert_category_t::port_mapping"></a>

port_mapping
	Enables alerts for port mapping events. For NAT-PMP and UPnP.
	


.. raw:: html

	<a name="alert_category_t::storage"></a>

storage
	Enables alerts for events related to the storage. File errors and
	synchronization events for moving the storage, renaming files etc.
	


.. raw:: html

	<a name="alert_category_t::tracker"></a>

tracker
	Enables all tracker events. Includes announcing to trackers,
	receiving responses, warnings and errors.
	


.. raw:: html

	<a name="alert_category_t::connect"></a>

connect
	Low level alerts for when peers are connected and disconnected.
	


.. raw:: html

	<a name="alert_category_t::status"></a>

status
	Enables alerts for when a torrent or the `session`__ changes state.
	

	__ reference-Session.html#session

.. raw:: html

	<a name="alert_category_t::ip_block"></a>

ip_block
	Alerts when a peer is blocked by the ip blocker or port blocker.
	


.. raw:: html

	<a name="alert_category_t::performance_warning"></a>

performance_warning
	Alerts when some limit is reached that might limit the download
	or upload rate.
	


.. raw:: html

	<a name="alert_category_t::dht"></a>

dht
	Alerts on events in the DHT node. For incoming searches or
	bootstrapping being done etc.
	


.. raw:: html

	<a name="alert_category_t::stats"></a>

stats
	If you enable these alerts, you will receive a stats_alert
	approximately once every second, for every active torrent.
	These alerts contain all statistics `counters`__ for the interval since
	the lasts stats `alert`__.
	

	__ reference-Stats.html#counters
	__ reference-Alerts.html#alert

.. raw:: html

	<a name="alert_category_t::session_log"></a>

session_log
	Enables debug logging alerts. These are available unless libtorrent
	was built with logging disabled (``TORRENT_DISABLE_LOGGING``). The
	alerts being posted are `log_alert`__ and are `session`__ wide.
	

	__ reference-Alerts.html#log_alert
	__ reference-Session.html#session

.. raw:: html

	<a name="alert_category_t::torrent_log"></a>

torrent_log
	Enables debug logging alerts for torrents. These are available
	unless libtorrent was built with logging disabled
	(``TORRENT_DISABLE_LOGGING``). The alerts being posted are
	`torrent_log_alert`__ and are torrent wide debug events.
	

	__ reference-Alerts.html#torrent_log_alert

.. raw:: html

	<a name="alert_category_t::peer_log"></a>

peer_log
	Enables debug logging alerts for peers. These are available unless
	libtorrent was built with logging disabled
	(``TORRENT_DISABLE_LOGGING``). The alerts being posted are
	`peer_log_alert`__ and low-level peer events and messages.
	

	__ reference-Alerts.html#peer_log_alert

.. raw:: html

	<a name="alert_category_t::incoming_request"></a>

incoming_request
	enables the `incoming_request_alert`__.
	

	__ reference-Alerts.html#incoming_request_alert

.. raw:: html

	<a name="alert_category_t::dht_log"></a>

dht_log
	enables `dht_log_alert`__, debug logging for the DHT
	

	__ reference-Alerts.html#dht_log_alert

.. raw:: html

	<a name="alert_category_t::dht_operation"></a>

dht_operation
	enable events from pure dht operations not related to torrents
	


.. raw:: html

	<a name="alert_category_t::port_mapping_log"></a>

port_mapping_log
	enables port mapping log events. This log is useful
	for debugging the UPnP or NAT-PMP implementation
	


.. raw:: html

	<a name="alert_category_t::picker_log"></a>

picker_log
	enables verbose logging from the piece picker.
	


.. raw:: html

	<a name="alert_category_t::file_progress"></a>

file_progress
	alerts when files complete downloading
	


.. raw:: html

	<a name="alert_category_t::piece_progress"></a>

piece_progress
	alerts when pieces complete downloading or fail hash check
	


.. raw:: html

	<a name="alert_category_t::upload"></a>

upload
	alerts when we upload blocks to other peers
	


.. raw:: html

	<a name="alert_category_t::block_progress"></a>

block_progress
	alerts on individual blocks being requested, downloading, finished,
	rejected, time-out and cancelled. This is likely to post alerts at a
	high rate.
	


.. raw:: html

	<a name="alert_category_t::all"></a>

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.
	





.. _`BEP 19`: https://www.bittorrent.org/beps/bep_0019.html
.. _extensions: manual-ref.html#extensions
.. _`BEP 3`: https://www.bittorrent.org/beps/bep_0003.html
.. _`BEP 38`: https://www.bittorrent.org/beps/bep_0038.html
.. _`BEP 42`: https://www.bittorrent.org/beps/bep_0042.html
.. _`BEP 17`: https://www.bittorrent.org/beps/bep_0017.html
.. _`rate based choking`: manual-ref.html#rate-based-choking
.. raw:: html

	<a name="stats_metric"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+stats_metric&labels=documentation&body=Documentation+under+heading+%22class+stats_metric%22+could+be+improved">report issue</a>]</span>



stats_metric
------------

Declared in "`libtorrent/session_stats.hpp`__"


__ include/libtorrent/session_stats.hpp

describes one statistics metric from the `session`__. For more information,
see the `session statistics`__ section.


__ reference-Session.html#session
__ manual-ref.html#session-statistics


.. parsed-literal::
	

	struct stats_metric
	{
	   char const* name;
	   int value_index;
	   metric_type_t type;
	};

.. raw:: html

	<a name="name"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:stats_metric%3A%3A%5Bname%5D&labels=documentation&body=Documentation+under+heading+%22stats_metric%3A%3A%5Bname%5D%22+could+be+improved">report issue</a>]</span>


name
	the name of the counter or gauge
	


.. raw:: html

	<a name="value_index"></a>
	<a name="type"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:stats_metric%3A%3A%5Bvalue_index+type%5D&labels=documentation&body=Documentation+under+heading+%22stats_metric%3A%3A%5Bvalue_index+type%5D%22+could+be+improved">report issue</a>]</span>


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.
	

__ reference-Session.html#session
__ reference-Session.html#session
__ reference-Alerts.html#session_stats_alert

.. raw:: html

	<a name="counters"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+counters&labels=documentation&body=Documentation+under+heading+%22class+counters%22+could+be+improved">report issue</a>]</span>



counters
--------

Declared in "`libtorrent/performance_counters.hpp`__"


__ include/libtorrent/performance_counters.hpp





.. parsed-literal::
	

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

.. raw:: html

	<a name="inc_stats_counter()"></a>
	<a name="operator[]()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:counters%3A%3A%5Binc_stats_counter%28%29+operator%5B%5D%28%29%5D&labels=documentation&body=Documentation+under+heading+%22counters%3A%3A%5Binc_stats_counter%28%29+operator%5B%5D%28%29%5D%22+could+be+improved">report issue</a>]</span>



inc_stats_counter() operator[]()
................................

.. parsed-literal::
	
	std::int64_t **inc_stats_counter** (int c, std\:\:int64\_t value = 1) ;
	std::int64_t **operator[]** (int i) const ;
	

returns the new value



.. raw:: html

	<a name="session_stats_metrics()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:session_stats_metrics%28%29&labels=documentation&body=Documentation+under+heading+%22session_stats_metrics%28%29%22+could+be+improved">report issue</a>]</span>



session_stats_metrics()
-----------------------

Declared in "`libtorrent/session_stats.hpp`__"


__ include/libtorrent/session_stats.hpp

.. parsed-literal::
	
	std::vector<stats_metric> **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()`__).


__ reference-Alerts.html#session_stats_alert
__ reference-Session.html#session
__ reference-Session.html#post_session_stats()

.. raw:: html

	<a name="find_metric_idx()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:find_metric_idx%28%29&labels=documentation&body=Documentation+under+heading+%22find_metric_idx%28%29%22+could+be+improved">report issue</a>]</span>



find_metric_idx()
-----------------

Declared in "`libtorrent/session_stats.hpp`__"


__ include/libtorrent/session_stats.hpp

.. parsed-literal::
	
	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`__.


__ reference-Alerts.html#session_stats_alert

.. raw:: html

	<a name="metric_type_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+metric_type_t&labels=documentation&body=Documentation+under+heading+%22enum+metric_type_t%22+could+be+improved">report issue</a>]</span>



enum metric_type_t
------------------

Declared in "`libtorrent/session_stats.hpp`__"


__ include/libtorrent/session_stats.hpp

+---------+-------+-------------+
| name    | value | description |
+=========+=======+=============+
| counter | 0     |             |
+---------+-------+-------------+
| gauge   | 1     |             |
+---------+-------+-------------+





.. _`BEP 19`: https://www.bittorrent.org/beps/bep_0019.html
.. _extensions: manual-ref.html#extensions
.. _`BEP 3`: https://www.bittorrent.org/beps/bep_0003.html
.. _`BEP 38`: https://www.bittorrent.org/beps/bep_0038.html
.. _`BEP 42`: https://www.bittorrent.org/beps/bep_0042.html
.. _`BEP 17`: https://www.bittorrent.org/beps/bep_0017.html
.. _`rate based choking`: manual-ref.html#rate-based-choking
.. raw:: html

	<a name="ip_filter"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+ip_filter&labels=documentation&body=Documentation+under+heading+%22class+ip_filter%22+could+be+improved">report issue</a>]</span>



ip_filter
---------

Declared in "`libtorrent/ip_filter.hpp`__"


__ include/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.


__ reference-Filter.html#ip_filter


.. parsed-literal::
	

	struct ip_filter
	{
	   **ip_filter** ();
	   **~ip_filter** ();
	   **ip_filter** (ip\_filter&&);
	   ip_filter& **operator=** (ip\_filter const&);
	   **ip_filter** (ip\_filter const&);
	   ip_filter& **operator=** (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;
	
	   enum access_flags
	   {
	      blocked,
	   };
	};

.. raw:: html

	<a name="empty()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:ip_filter%3A%3A%5Bempty%28%29%5D&labels=documentation&body=Documentation+under+heading+%22ip_filter%3A%3A%5Bempty%28%29%5D%22+could+be+improved">report issue</a>]</span>



empty()
.......

.. parsed-literal::
	
	bool **empty** () const;
	

returns true if the filter does not contain any rules



.. raw:: html

	<a name="add_rule()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:ip_filter%3A%3A%5Badd_rule%28%29%5D&labels=documentation&body=Documentation+under+heading+%22ip_filter%3A%3A%5Badd_rule%28%29%5D%22+could+be+improved">report issue</a>]</span>



add_rule()
..........

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="access()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:ip_filter%3A%3A%5Baccess%28%29%5D&labels=documentation&body=Documentation+under+heading+%22ip_filter%3A%3A%5Baccess%28%29%5D%22+could+be+improved">report issue</a>]</span>



access()
........

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="export_filter()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:ip_filter%3A%3A%5Bexport_filter%28%29%5D&labels=documentation&body=Documentation+under+heading+%22ip_filter%3A%3A%5Bexport_filter%28%29%5D%22+could+be+improved">report issue</a>]</span>



export_filter()
...............

.. parsed-literal::
	
	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.


__ reference-Bencoding.html#entry

.. raw:: html

	<a name="access_flags"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+access_flags&labels=documentation&body=Documentation+under+heading+%22enum+access_flags%22+could+be+improved">report issue</a>]</span>



enum access_flags
.................

Declared in "`libtorrent/ip_filter.hpp`__"


__ include/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                  |
|         |       |                                                          |
+---------+-------+----------------------------------------------------------+



.. raw:: html

	<a name="port_filter"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+port_filter&labels=documentation&body=Documentation+under+heading+%22class+port_filter%22+could+be+improved">report issue</a>]</span>



port_filter
-----------

Declared in "`libtorrent/ip_filter.hpp`__"


__ include/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.




.. parsed-literal::
	

	class port_filter
	{
	   **port_filter** ();
	   port_filter& **operator=** (port\_filter const&);
	   **port_filter** (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,
	   };
	};

.. raw:: html

	<a name="add_rule()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:port_filter%3A%3A%5Badd_rule%28%29%5D&labels=documentation&body=Documentation+under+heading+%22port_filter%3A%3A%5Badd_rule%28%29%5D%22+could+be+improved">report issue</a>]</span>



add_rule()
..........

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="access()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:port_filter%3A%3A%5Baccess%28%29%5D&labels=documentation&body=Documentation+under+heading+%22port_filter%3A%3A%5Baccess%28%29%5D%22+could+be+improved">report issue</a>]</span>



access()
........

.. parsed-literal::
	
	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`__.


__ reference-Filter.html#access_flags

.. raw:: html

	<a name="access_flags"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+access_flags&labels=documentation&body=Documentation+under+heading+%22enum+access_flags%22+could+be+improved">report issue</a>]</span>



enum access_flags
.................

Declared in "`libtorrent/ip_filter.hpp`__"


__ include/libtorrent/ip_filter.hpp

+---------+-------+---------------------------------------------------+
| name    | value | description                                       |
+=========+=======+===================================================+
| blocked | 1     | this flag indicates that destination ports in the |
|         |       | range should not be connected to                  |
|         |       |                                                   |
+---------+-------+---------------------------------------------------+





.. _`BEP 19`: https://www.bittorrent.org/beps/bep_0019.html
.. _extensions: manual-ref.html#extensions
.. _`BEP 3`: https://www.bittorrent.org/beps/bep_0003.html
.. _`BEP 38`: https://www.bittorrent.org/beps/bep_0038.html
.. _`BEP 42`: https://www.bittorrent.org/beps/bep_0042.html
.. _`BEP 17`: https://www.bittorrent.org/beps/bep_0017.html
.. _`rate based choking`: manual-ref.html#rate-based-choking
.. raw:: html

	<a name="storage_params"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+storage_params&labels=documentation&body=Documentation+under+heading+%22class+storage_params%22+could+be+improved">report issue</a>]</span>



storage_params
--------------

Declared in "`libtorrent/storage_defs.hpp`__"


__ include/libtorrent/storage_defs.hpp

a parameter pack used to construct the storage for a torrent, used in
`disk_interface`__


__ reference-Custom_Storage.html#disk_interface


.. parsed-literal::
	

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

.. raw:: html

	<a name="file_slice"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+file_slice&labels=documentation&body=Documentation+under+heading+%22class+file_slice%22+could+be+improved">report issue</a>]</span>



file_slice
----------

Declared in "`libtorrent/file_storage.hpp`__"


__ include/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.


__ reference-Torrent_Info.html#torrent_info


.. parsed-literal::
	

	struct file_slice
	{
	   file_index_t file_index;
	   std::int64_t offset;
	   std::int64_t size;
	};

.. raw:: html

	<a name="file_index"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_slice%3A%3A%5Bfile_index%5D&labels=documentation&body=Documentation+under+heading+%22file_slice%3A%3A%5Bfile_index%5D%22+could+be+improved">report issue</a>]</span>


file_index
	the index of the file
	


.. raw:: html

	<a name="offset"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_slice%3A%3A%5Boffset%5D&labels=documentation&body=Documentation+under+heading+%22file_slice%3A%3A%5Boffset%5D%22+could+be+improved">report issue</a>]</span>


offset
	the offset from the start of the file, in bytes
	


.. raw:: html

	<a name="size"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_slice%3A%3A%5Bsize%5D&labels=documentation&body=Documentation+under+heading+%22file_slice%3A%3A%5Bsize%5D%22+could+be+improved">report issue</a>]</span>


size
	the size of the window, in bytes
	


.. raw:: html

	<a name="file_storage"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+file_storage&labels=documentation&body=Documentation+under+heading+%22class+file_storage%22+could+be+improved">report issue</a>]</span>



file_storage
------------

Declared in "`libtorrent/file_storage.hpp`__"


__ include/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.




.. parsed-literal::
	

	class file_storage
	{
	   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_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** (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** (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 **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;
	   void **set_num_pieces** (int n);
	   int **num_pieces** () const;
	   piece_index_t **end_piece** () const;
	   piece_index_t **last_piece** () const;
	   index_range<piece_index_t> **piece_range** () const noexcept;
	   void **set_piece_length** (int l);
	   int **piece_length** () const;
	   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::time_t **mtime** (file\_index\_t index) const;
	   sha256_hash **root** (file\_index\_t index) const;
	   char const* **root_ptr** (file\_index\_t const index) const;
	   bool **pad_file_at** (file\_index\_t index) const;
	   string_view **file_name** (file\_index\_t index) const;
	   sha1_hash **hash** (file\_index\_t index) const;
	   std::string **file_path** (file\_index\_t index, std\:\:string const& save\_path = "") const;
	   std::int64_t **file_size** (file\_index\_t index) const;
	   std::string **symlink** (file\_index\_t index) const;
	   std::int64_t **file_offset** (file\_index\_t 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_piece** (piece\_index\_t piece) const;
	   file_index_t **file_index_at_offset** (std\:\:int64\_t offset) 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;
	};

.. raw:: html

	<a name="is_valid()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bis_valid%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bis_valid%28%29%5D%22+could+be+improved">report issue</a>]</span>



is_valid()
..........

.. parsed-literal::
	
	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.


__ reference-Storage.html#file_storage
__ reference-Storage.html#file_storage

.. raw:: html

	<a name="reserve()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Breserve%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Breserve%28%29%5D%22+could+be+improved">report issue</a>]</span>



reserve()
.........

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="add_file()"></a>
	<a name="add_file_borrow()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Badd_file%28%29+add_file_borrow%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Badd_file%28%29+add_file_borrow%28%29%5D%22+could+be+improved">report issue</a>]</span>



add_file() add_file_borrow()
............................

.. parsed-literal::
	
	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_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** (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** (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);
	

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.


__ reference-Storage.html#file_storage
__ reference-Storage.html#flag_symlink
__ reference-Storage.html#file_storage

.. raw:: html

	<a name="rename_file()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Brename_file%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Brename_file%28%29%5D%22+could+be+improved">report issue</a>]</span>



rename_file()
.............

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="map_block()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bmap_block%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bmap_block%28%29%5D%22+could+be+improved">report issue</a>]</span>



map_block()
...........

.. parsed-literal::
	
	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.


__ reference-Storage.html#file_slice
__ reference-Torrent_Info.html#map_file()

.. raw:: html

	<a name="map_file()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bmap_file%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bmap_file%28%29%5D%22+could+be+improved">report issue</a>]</span>



map_file()
..........

.. parsed-literal::
	
	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.


__ reference-Core.html#peer_request
__ reference-Torrent_Info.html#map_block()

.. raw:: html

	<a name="num_files()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bnum_files%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bnum_files%28%29%5D%22+could+be+improved">report issue</a>]</span>



num_files()
...........

.. parsed-literal::
	
	int **num_files** () const noexcept;
	

returns the number of files in the `file_storage`__


__ reference-Storage.html#file_storage

.. raw:: html

	<a name="end_file()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bend_file%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bend_file%28%29%5D%22+could+be+improved">report issue</a>]</span>



end_file()
..........

.. parsed-literal::
	
	file_index_t **end_file** () const noexcept;
	

returns the index of the one-past-end file in the file storage



.. raw:: html

	<a name="file_range()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bfile_range%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bfile_range%28%29%5D%22+could+be+improved">report issue</a>]</span>



file_range()
............

.. parsed-literal::
	
	index_range<file_index_t> **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`__.


__ reference-Storage.html#file_storage

.. raw:: html

	<a name="total_size()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Btotal_size%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Btotal_size%28%29%5D%22+could+be+improved">report issue</a>]</span>



total_size()
............

.. parsed-literal::
	
	std::int64_t **total_size** () const;
	

returns the total number of bytes all the files in this torrent spans



.. raw:: html

	<a name="num_pieces()"></a>
	<a name="set_num_pieces()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bnum_pieces%28%29+set_num_pieces%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bnum_pieces%28%29+set_num_pieces%28%29%5D%22+could+be+improved">report issue</a>]</span>



num_pieces() set_num_pieces()
.............................

.. parsed-literal::
	
	void **set_num_pieces** (int n);
	int **num_pieces** () const;
	

set and get the number of pieces in the torrent



.. raw:: html

	<a name="end_piece()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bend_piece%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bend_piece%28%29%5D%22+could+be+improved">report issue</a>]</span>



end_piece()
...........

.. parsed-literal::
	
	piece_index_t **end_piece** () const;
	

returns the index of the one-past-end piece in the file storage



.. raw:: html

	<a name="last_piece()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Blast_piece%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Blast_piece%28%29%5D%22+could+be+improved">report issue</a>]</span>



last_piece()
............

.. parsed-literal::
	
	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).



.. raw:: html

	<a name="piece_range()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bpiece_range%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bpiece_range%28%29%5D%22+could+be+improved">report issue</a>]</span>



piece_range()
.............

.. parsed-literal::
	
	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`__.


__ reference-Storage.html#file_storage

.. raw:: html

	<a name="set_piece_length()"></a>
	<a name="piece_length()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bset_piece_length%28%29+piece_length%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bset_piece_length%28%29+piece_length%28%29%5D%22+could+be+improved">report issue</a>]</span>



set_piece_length() piece_length()
.................................

.. parsed-literal::
	
	void **set_piece_length** (int l);
	int **piece_length** () const;
	

set and get the size of each piece in this torrent. It must be a power of two
and at least 16 kiB.



.. raw:: html

	<a name="piece_size()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bpiece_size%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bpiece_size%28%29%5D%22+could+be+improved">report issue</a>]</span>



piece_size()
............

.. parsed-literal::
	
	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.


__ reference-Torrent_Info.html#piece_length()

.. raw:: html

	<a name="piece_size2()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bpiece_size2%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bpiece_size2%28%29%5D%22+could+be+improved">report issue</a>]</span>



piece_size2()
.............

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="blocks_in_piece2()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bblocks_in_piece2%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bblocks_in_piece2%28%29%5D%22+could+be+improved">report issue</a>]</span>



blocks_in_piece2()
..................

.. parsed-literal::
	
	int **blocks_in_piece2** (piece\_index\_t index) const;
	

returns the number of blocks in the specified piece, for v2 torrents.



.. raw:: html

	<a name="name()"></a>
	<a name="set_name()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bname%28%29+set_name%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bname%28%29+set_name%28%29%5D%22+could+be+improved">report issue</a>]</span>



name() set_name()
.................

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="swap()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bswap%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bswap%28%29%5D%22+could+be+improved">report issue</a>]</span>



swap()
......

.. parsed-literal::
	
	void **swap** (file\_storage& ti) noexcept;
	

swap all content of *this* with *ti*.



.. raw:: html

	<a name="canonicalize()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bcanonicalize%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bcanonicalize%28%29%5D%22+could+be+improved">report issue</a>]</span>



canonicalize()
..............

.. parsed-literal::
	
	void **canonicalize** ();
	

arrange files and padding to match the canonical form required
by BEP 52



.. raw:: html

	<a name="root()"></a>
	<a name="file_name()"></a>
	<a name="mtime()"></a>
	<a name="symlink()"></a>
	<a name="file_size()"></a>
	<a name="hash()"></a>
	<a name="file_offset()"></a>
	<a name="root_ptr()"></a>
	<a name="pad_file_at()"></a>
	<a name="file_path()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Broot%28%29+file_name%28%29+mtime%28%29+symlink%28%29+file_size%28%29+hash%28%29+file_offset%28%29+root_ptr%28%29+pad_file_at%28%29+file_path%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Broot%28%29+file_name%28%29+mtime%28%29+symlink%28%29+file_size%28%29+hash%28%29+file_offset%28%29+root_ptr%28%29+pad_file_at%28%29+file_path%28%29%5D%22+could+be+improved">report issue</a>]</span>



root() file_name() mtime() symlink() file_size() hash() file_offset() root_ptr() pad_file_at() file_path()
..........................................................................................................

.. parsed-literal::
	
	std::time_t **mtime** (file\_index\_t index) const;
	sha256_hash **root** (file\_index\_t index) const;
	char const* **root_ptr** (file\_index\_t const index) const;
	bool **pad_file_at** (file\_index\_t index) const;
	string_view **file_name** (file\_index\_t index) const;
	sha1_hash **hash** (file\_index\_t index) const;
	std::string **file_path** (file\_index\_t index, std\:\:string const& save\_path = "") const;
	std::int64_t **file_size** (file\_index\_t index) const;
	std::string **symlink** (file\_index\_t index) const;
	std::int64_t **file_offset** (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).



.. raw:: html

	<a name="file_piece_range()"></a>
	<a name="file_num_blocks()"></a>
	<a name="file_num_pieces()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bfile_piece_range%28%29+file_num_blocks%28%29+file_num_pieces%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bfile_piece_range%28%29+file_num_blocks%28%29+file_num_pieces%28%29%5D%22+could+be+improved">report issue</a>]</span>



file_piece_range() file_num_blocks() file_num_pieces()
......................................................

.. parsed-literal::
	
	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;
	

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.



.. raw:: html

	<a name="file_first_block_node()"></a>
	<a name="file_first_piece_node()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bfile_first_block_node%28%29+file_first_piece_node%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bfile_first_block_node%28%29+file_first_piece_node%28%29%5D%22+could+be+improved">report issue</a>]</span>



file_first_block_node() file_first_piece_node()
...............................................

.. parsed-literal::
	
	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



.. raw:: html

	<a name="file_path_hash()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bfile_path_hash%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bfile_path_hash%28%29%5D%22+could+be+improved">report issue</a>]</span>



file_path_hash()
................

.. parsed-literal::
	
	std::uint32_t **file_path_hash** (file\_index\_t index, std\:\:string const& save\_path) const;
	

returns the crc32 hash of file_path(index)



.. raw:: html

	<a name="all_path_hashes()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Ball_path_hashes%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Ball_path_hashes%28%29%5D%22+could+be+improved">report issue</a>]</span>



all_path_hashes()
.................

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="file_flags()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bfile_flags%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bfile_flags%28%29%5D%22+could+be+improved">report issue</a>]</span>



file_flags()
............

.. parsed-literal::
	
	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``.



.. raw:: html

	<a name="file_absolute_path()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bfile_absolute_path%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bfile_absolute_path%28%29%5D%22+could+be+improved">report issue</a>]</span>



file_absolute_path()
....................

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="file_index_at_offset()"></a>
	<a name="file_index_at_piece()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bfile_index_at_offset%28%29+file_index_at_piece%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bfile_index_at_offset%28%29+file_index_at_piece%28%29%5D%22+could+be+improved">report issue</a>]</span>



file_index_at_offset() file_index_at_piece()
............................................

.. parsed-literal::
	
	file_index_t **file_index_at_piece** (piece\_index\_t piece) const;
	file_index_t **file_index_at_offset** (std\:\:int64\_t offset) const;
	

returns the index of the file at the given offset in the torrent



.. raw:: html

	<a name="file_index_for_root()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bfile_index_for_root%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bfile_index_for_root%28%29%5D%22+could+be+improved">report issue</a>]</span>



file_index_for_root()
.....................

.. parsed-literal::
	
	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



.. raw:: html

	<a name="piece_index_at_file()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bpiece_index_at_file%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bpiece_index_at_file%28%29%5D%22+could+be+improved">report issue</a>]</span>



piece_index_at_file()
.....................

.. parsed-literal::
	
	piece_index_t **piece_index_at_file** (file\_index\_t f) const;
	

returns the piece index the given file starts at



.. raw:: html

	<a name="sanitize_symlinks()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bsanitize_symlinks%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bsanitize_symlinks%28%29%5D%22+could+be+improved">report issue</a>]</span>



sanitize_symlinks()
...................

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="v2()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bv2%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bv2%28%29%5D%22+could+be+improved">report issue</a>]</span>



v2()
....

.. parsed-literal::
	
	bool **v2** () const;
	

returns true if this torrent contains v2 metadata.



.. raw:: html

	<a name="flag_pad_file"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bflag_pad_file%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bflag_pad_file%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="flag_hidden"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bflag_hidden%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bflag_hidden%5D%22+could+be+improved">report issue</a>]</span>


flag_hidden
	this file has the hidden attribute set. This is primarily
	a windows attribute
	


.. raw:: html

	<a name="flag_executable"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bflag_executable%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bflag_executable%5D%22+could+be+improved">report issue</a>]</span>


flag_executable
	this file has the executable attribute set.
	


.. raw:: html

	<a name="flag_symlink"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bflag_symlink%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bflag_symlink%5D%22+could+be+improved">report issue</a>]</span>


flag_symlink
	this file is a symbolic link. It should have a link
	target string associated with it.
	


.. raw:: html

	<a name="default_disk_io_constructor()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:default_disk_io_constructor%28%29&labels=documentation&body=Documentation+under+heading+%22default_disk_io_constructor%28%29%22+could+be+improved">report issue</a>]</span>



default_disk_io_constructor()
-----------------------------

Declared in "`libtorrent/session.hpp`__"


__ include/libtorrent/session.hpp

.. parsed-literal::
	
	std::unique_ptr<disk_interface> **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.



.. raw:: html

	<a name="posix_disk_io_constructor()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:posix_disk_io_constructor%28%29&labels=documentation&body=Documentation+under+heading+%22posix_disk_io_constructor%28%29%22+could+be+improved">report issue</a>]</span>



posix_disk_io_constructor()
---------------------------

Declared in "`libtorrent/posix_disk_io.hpp`__"


__ include/libtorrent/posix_disk_io.hpp

.. parsed-literal::
	
	std::unique_ptr<disk_interface> **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.



.. raw:: html

	<a name="mmap_disk_io_constructor()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:mmap_disk_io_constructor%28%29&labels=documentation&body=Documentation+under+heading+%22mmap_disk_io_constructor%28%29%22+could+be+improved">report issue</a>]</span>



mmap_disk_io_constructor()
--------------------------

Declared in "`libtorrent/mmap_disk_io.hpp`__"


__ include/libtorrent/mmap_disk_io.hpp

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="disabled_disk_io_constructor()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:disabled_disk_io_constructor%28%29&labels=documentation&body=Documentation+under+heading+%22disabled_disk_io_constructor%28%29%22+could+be+improved">report issue</a>]</span>



disabled_disk_io_constructor()
------------------------------

Declared in "`libtorrent/disabled_disk_io.hpp`__"


__ include/libtorrent/disabled_disk_io.hpp

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="storage_mode_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+storage_mode_t&labels=documentation&body=Documentation+under+heading+%22enum+storage_mode_t%22+could+be+improved">report issue</a>]</span>



enum storage_mode_t
-------------------

Declared in "`libtorrent/storage_defs.hpp`__"


__ include/libtorrent/storage_defs.hpp

+-----------------------+-------+----------------------------------------------------------------------------+
| name                  | value | description                                                                |
+=======================+=======+============================================================================+
| storage_mode_allocate | 0     | All 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_sparse   | 1     | All pieces will be written to the place where they belong and sparse files |
|                       |       | will be used. This is the recommended, and default mode.                   |
|                       |       |                                                                            |
+-----------------------+-------+----------------------------------------------------------------------------+



.. raw:: html

	<a name="status_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+status_t&labels=documentation&body=Documentation+under+heading+%22enum+status_t%22+could+be+improved">report issue</a>]</span>



enum status_t
-------------

Declared in "`libtorrent/storage_defs.hpp`__"


__ include/libtorrent/storage_defs.hpp

+------------------+-------+------------------------------------------------------------------------+
| name             | value | description                                                            |
+==================+=======+========================================================================+
| no_error         | 0     |                                                                        |
+------------------+-------+------------------------------------------------------------------------+
| fatal_disk_error | 1     |                                                                        |
+------------------+-------+------------------------------------------------------------------------+
| need_full_check  | 2     |                                                                        |
+------------------+-------+------------------------------------------------------------------------+
| file_exist       | 3     |                                                                        |
+------------------+-------+------------------------------------------------------------------------+
| oversized_file   | 16    | this 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.               |
|                  |       |                                                                        |
+------------------+-------+------------------------------------------------------------------------+


__ reference-Storage.html#status_t

.. raw:: html

	<a name="move_flags_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+move_flags_t&labels=documentation&body=Documentation+under+heading+%22enum+move_flags_t%22+could+be+improved">report issue</a>]</span>



enum move_flags_t
-----------------

Declared in "`libtorrent/storage_defs.hpp`__"


__ include/libtorrent/storage_defs.hpp

+----------------------+-------+------------------------------------------------------------+
| name                 | value | description                                                |
+======================+=======+============================================================+
| always_replace_files | 0     | replace any files in the destination when copying          |
|                      |       | or moving the storage                                      |
|                      |       |                                                            |
+----------------------+-------+------------------------------------------------------------+
| fail_if_exist        | 1     | 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 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.                     |
|                      |       |                                                            |
+----------------------+-------+------------------------------------------------------------+





.. _`BEP 19`: https://www.bittorrent.org/beps/bep_0019.html
.. _extensions: manual-ref.html#extensions
.. _`BEP 3`: https://www.bittorrent.org/beps/bep_0003.html
.. _`BEP 38`: https://www.bittorrent.org/beps/bep_0038.html
.. _`BEP 42`: https://www.bittorrent.org/beps/bep_0042.html
.. _`BEP 17`: https://www.bittorrent.org/beps/bep_0017.html
.. _`rate based choking`: manual-ref.html#rate-based-choking

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:

.. code:: c++

	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:

.. parsed-literal::

	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`_.

.. _`alert section`: reference-Alerts.html

.. raw:: html

	<a name="peer_connection_handle"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+peer_connection_handle&labels=documentation&body=Documentation+under+heading+%22class+peer_connection_handle%22+could+be+improved">report issue</a>]</span>



peer_connection_handle
----------------------

Declared in "`libtorrent/peer_connection_handle.hpp`__"


__ reference-Plugins.html#plugin
__ reference-Plugins.html#plugin
__ reference-Session.html#session
__ reference-Plugins.html#plugin
__ reference-Plugins.html#plugin
__ reference-Plugins.html#plugin
__ reference-Plugins.html#plugin
__ reference-Plugins.html#plugin
__ reference-Plugins.html#plugin
__ reference-Plugins.html#plugin
__ reference-Plugins.html#plugin
__ reference-Plugins.html#torrent_plugin
__ reference-Plugins.html#peer_plugin
__ reference-Session.html#session
__ reference-Session.html#session
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ include/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


__ reference-Plugins.html#peer_connection_handle


.. parsed-literal::
	

	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_choked** () const;
	   bool **is_interesting** () const;
	   bool **has_peer_choked** () const;
	   bool **is_peer_interested** () 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_disconnecting** () const;
	   bool **is_connecting** () const;
	   void **disconnect** (error\_code const& ec, operation\_t op
	      , disconnect\_severity\_t = peer\_connection\_interface\:\:normal);
	   bool **is_outgoing** () const;
	   bool **on_local_network** () const;
	   bool **ignore_unchoke_slots** () const;
	   bool **failed** () const;
	   bool **should_log** (peer\_log\_alert\:\:direction\_t direction) const;
	   void **peer_log** (peer\_log\_alert\:\:direction\_t direction
	      , char const\* event, char const\* fmt = "", ...) const TORRENT\_FORMAT(4,5);
	   bool **can_disconnect** (error\_code const& ec) const;
	   bool **has_metadata** () const;
	   bool **in_handshake** () const;
	   void **send_buffer** (char const\* begin, int size);
	   std::time_t **last_seen_complete** () const;
	   time_point **time_of_last_unchoke** () const;
	   bool **operator<** (peer\_connection\_handle const& o) const;
	   bool **operator!=** (peer\_connection\_handle const& o) const;
	   bool **operator==** (peer\_connection\_handle const& o) const;
	   std::shared_ptr<peer_connection> **native_handle** () const;
	};

.. raw:: html

	<a name="bt_peer_connection_handle"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+bt_peer_connection_handle&labels=documentation&body=Documentation+under+heading+%22class+bt_peer_connection_handle%22+could+be+improved">report issue</a>]</span>



bt_peer_connection_handle
-------------------------

Declared in "`libtorrent/peer_connection_handle.hpp`__"


__ include/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.


__ reference-Plugins.html#bt_peer_connection_handle


.. parsed-literal::
	

	struct bt_peer_connection_handle : peer_connection_handle
	{
	   explicit **bt_peer_connection_handle** (peer\_connection\_handle pc);
	   bool **support_extensions** () const;
	   bool **packet_finished** () const;
	   bool **supports_encryption** () const;
	   void **switch_recv_crypto** (std\:\:shared\_ptr<crypto\_plugin> crypto);
	   void **switch_send_crypto** (std\:\:shared\_ptr<crypto\_plugin> crypto);
	   std::shared_ptr<bt_peer_connection> **native_handle** () const;
	};

.. raw:: html

	<a name="plugin"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+plugin&labels=documentation&body=Documentation+under+heading+%22class+plugin%22+could+be+improved">report issue</a>]</span>



plugin
------

Declared in "`libtorrent/extensions.hpp`__"


__ include/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.


__ reference-Session.html#session
__ reference-Plugins.html#plugin
__ reference-Session.html#session


.. parsed-literal::
	

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

.. raw:: html

	<a name="implemented_features()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Bimplemented_features%28%29%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Bimplemented_features%28%29%5D%22+could+be+improved">report issue</a>]</span>



implemented_features()
......................

.. parsed-literal::
	
	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.


__ reference-Plugins.html#plugin

.. raw:: html

	<a name="new_torrent()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Bnew_torrent%28%29%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Bnew_torrent%28%29%5D%22+could+be+improved">report issue</a>]</span>



new_torrent()
.............

.. parsed-literal::
	
	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).


__ reference-Session.html#session
__ reference-Add_Torrent.html#client_data_t
__ reference-Add_Torrent.html#add_torrent_params
__ reference-Plugins.html#plugin
__ reference-Plugins.html#torrent_plugin
__ reference-Plugins.html#torrent_plugin

.. raw:: html

	<a name="added()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Badded%28%29%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Badded%28%29%5D%22+could+be+improved">report issue</a>]</span>



added()
.......

.. parsed-literal::
	
	virtual void **added** (session\_handle const&);
	

called when `plugin`__ is added to a `session`__


__ reference-Plugins.html#plugin
__ reference-Session.html#session

.. raw:: html

	<a name="abort()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Babort%28%29%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Babort%28%29%5D%22+could+be+improved">report issue</a>]</span>



abort()
.......

.. parsed-literal::
	
	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)


__ reference-Session.html#session
__ reference-Plugins.html#plugin

.. raw:: html

	<a name="on_dht_request()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Bon_dht_request%28%29%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Bon_dht_request%28%29%5D%22+could+be+improved">report issue</a>]</span>



on_dht_request()
................

.. parsed-literal::
	
	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()`__.


__ reference-Plugins.html#plugin
__ reference-Plugins.html#implemented_features()

.. raw:: html

	<a name="on_alert()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Bon_alert%28%29%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Bon_alert%28%29%5D%22+could+be+improved">report issue</a>]</span>



on_alert()
..........

.. parsed-literal::
	
	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()`__.


__ reference-Alerts.html#alert
__ reference-Plugins.html#plugin
__ reference-Plugins.html#implemented_features()

.. raw:: html

	<a name="on_unknown_torrent()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Bon_unknown_torrent%28%29%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Bon_unknown_torrent%28%29%5D%22+could+be+improved">report issue</a>]</span>



on_unknown_torrent()
....................

.. parsed-literal::
	
	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


__ reference-Add_Torrent.html#add_torrent_params

.. raw:: html

	<a name="on_tick()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Bon_tick%28%29%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Bon_tick%28%29%5D%22+could+be+improved">report issue</a>]</span>



on_tick()
.........

.. parsed-literal::
	
	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()`__.


__ reference-Plugins.html#plugin
__ reference-Plugins.html#implemented_features()

.. raw:: html

	<a name="get_unchoke_priority()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Bget_unchoke_priority%28%29%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Bget_unchoke_priority%28%29%5D%22+could+be+improved">report issue</a>]</span>



get_unchoke_priority()
......................

.. parsed-literal::
	
	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.


__ reference-Plugins.html#plugin
__ reference-Plugins.html#plugin
__ reference-Plugins.html#implemented_features()

.. raw:: html

	<a name="load_state()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Bload_state%28%29%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Bload_state%28%29%5D%22+could+be+improved">report issue</a>]</span>



load_state()
............

.. parsed-literal::
	
	virtual void **load_state** (std\:\:map<std\:\:string, std\:\:string> const&);
	

called on startup while loading settings state from the `session_params`__


__ reference-Session.html#session_params

.. raw:: html

	<a name="optimistic_unchoke_feature"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Boptimistic_unchoke_feature%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Boptimistic_unchoke_feature%5D%22+could+be+improved">report issue</a>]</span>


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.
	

__ reference-Plugins.html#plugin

.. raw:: html

	<a name="tick_feature"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Btick_feature%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Btick_feature%5D%22+could+be+improved">report issue</a>]</span>


tick_feature
	include this bit if your `plugin`__ needs to have `on_tick()`__ called
	

__ reference-Plugins.html#plugin
__ reference-Plugins.html#on_tick()

.. raw:: html

	<a name="dht_request_feature"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Bdht_request_feature%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Bdht_request_feature%5D%22+could+be+improved">report issue</a>]</span>


dht_request_feature
	include this bit if your `plugin`__ needs to have `on_dht_request()`__
	called
	

__ reference-Plugins.html#plugin
__ reference-Plugins.html#on_dht_request()

.. raw:: html

	<a name="alert_feature"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Balert_feature%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Balert_feature%5D%22+could+be+improved">report issue</a>]</span>


alert_feature
	include this bit if your `plugin`__ needs to have `on_alert()`__
	called
	

__ reference-Plugins.html#plugin
__ reference-Plugins.html#on_alert()

.. raw:: html

	<a name="torrent_plugin"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+torrent_plugin&labels=documentation&body=Documentation+under+heading+%22class+torrent_plugin%22+could+be+improved">report issue</a>]</span>



torrent_plugin
--------------

Declared in "`libtorrent/extensions.hpp`__"


__ include/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.




.. parsed-literal::
	

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

.. raw:: html

	<a name="new_connection()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_plugin%3A%3A%5Bnew_connection%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_plugin%3A%3A%5Bnew_connection%28%29%5D%22+could+be+improved">report issue</a>]</span>



new_connection()
................

.. parsed-literal::
	
	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.


__ reference-Plugins.html#peer_plugin
__ reference-Plugins.html#peer_plugin

.. raw:: html

	<a name="on_piece_failed()"></a>
	<a name="on_piece_pass()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_plugin%3A%3A%5Bon_piece_failed%28%29+on_piece_pass%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_plugin%3A%3A%5Bon_piece_failed%28%29+on_piece_pass%28%29%5D%22+could+be+improved">report issue</a>]</span>



on_piece_failed() on_piece_pass()
.................................

.. parsed-literal::
	
	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``.



.. raw:: html

	<a name="tick()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_plugin%3A%3A%5Btick%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_plugin%3A%3A%5Btick%28%29%5D%22+could+be+improved">report issue</a>]</span>



tick()
......

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="on_pause()"></a>
	<a name="on_resume()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_plugin%3A%3A%5Bon_pause%28%29+on_resume%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_plugin%3A%3A%5Bon_pause%28%29+on_resume%28%29%5D%22+could+be+improved">report issue</a>]</span>



on_pause() on_resume()
......................

.. parsed-literal::
	
	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.


__ reference-Plugins.html#plugin

.. raw:: html

	<a name="on_files_checked()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_plugin%3A%3A%5Bon_files_checked%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_plugin%3A%3A%5Bon_files_checked%28%29%5D%22+could+be+improved">report issue</a>]</span>



on_files_checked()
..................

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="on_state()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_plugin%3A%3A%5Bon_state%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_plugin%3A%3A%5Bon_state%28%29%5D%22+could+be+improved">report issue</a>]</span>



on_state()
..........

.. parsed-literal::
	
	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


__ reference-Torrent_Status.html#state_t

.. raw:: html

	<a name="on_add_peer()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_plugin%3A%3A%5Bon_add_peer%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_plugin%3A%3A%5Bon_add_peer%28%29%5D%22+could+be+improved">report issue</a>]</span>



on_add_peer()
.............

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="first_time"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_plugin%3A%3A%5Bfirst_time%5D&labels=documentation&body=Documentation+under+heading+%22torrent_plugin%3A%3A%5Bfirst_time%5D%22+could+be+improved">report issue</a>]</span>


first_time
	this is the first time we see this peer
	


.. raw:: html

	<a name="filtered"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_plugin%3A%3A%5Bfiltered%5D&labels=documentation&body=Documentation+under+heading+%22torrent_plugin%3A%3A%5Bfiltered%5D%22+could+be+improved">report issue</a>]</span>


filtered
	this peer was not added because it was
	filtered by the IP filter
	


.. raw:: html

	<a name="peer_plugin"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+peer_plugin&labels=documentation&body=Documentation+under+heading+%22class+peer_plugin%22+could+be+improved">report issue</a>]</span>



peer_plugin
-----------

Declared in "`libtorrent/extensions.hpp`__"


__ include/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


__ reference-Plugins.html#plugin


.. parsed-literal::
	

	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_not_interested** ();
	   virtual bool **on_request** (peer\_request const&);
	   virtual bool **on_choke** ();
	   virtual bool **on_have** (piece\_index\_t);
	   virtual bool **on_dont_have** (piece\_index\_t);
	   virtual bool **on_unchoke** ();
	   virtual bool **on_interested** ();
	   virtual bool **on_have_none** ();
	   virtual bool **on_have_all** ();
	   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_suggest** (piece\_index\_t);
	   virtual void **sent_reject_request** (peer\_request const&);
	   virtual void **sent_request** (peer\_request const&);
	   virtual void **sent_choke** ();
	   virtual void **sent_allow_fast** (piece\_index\_t);
	   virtual void **sent_cancel** (peer\_request const&);
	   virtual void **sent_have_none** ();
	   virtual void **sent_have_all** ();
	   virtual void **sent_have** (piece\_index\_t);
	   virtual void **sent_unchoke** ();
	   virtual void **sent_piece** (peer\_request const&);
	   virtual void **sent_interested** ();
	   virtual void **sent_not_interested** ();
	   virtual void **sent_payload** (int */\* bytes \*/*);
	   virtual bool **can_disconnect** (error\_code const& */\*ec\*/*);
	   virtual bool **on_extended** (int */\*length\*/*, int */\*msg\*/*,
	      span<char const> */\*body\*/*);
	   virtual bool **on_unknown_message** (int */\*length\*/*, int */\*msg\*/*,
	      span<char const> */\*body\*/*);
	   virtual void **on_piece_failed** (piece\_index\_t);
	   virtual void **on_piece_pass** (piece\_index\_t);
	   virtual void **tick** ();
	   virtual bool **write_request** (peer\_request const&);
	};

.. raw:: html

	<a name="type()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Btype%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Btype%28%29%5D%22+could+be+improved">report issue</a>]</span>



type()
......

.. parsed-literal::
	
	virtual string_view **type** () const;
	

This function is expected to return the name of
the `plugin`__.


__ reference-Plugins.html#plugin

.. raw:: html

	<a name="add_handshake()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Badd_handshake%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Badd_handshake%28%29%5D%22+could+be+improved">report issue</a>]</span>



add_handshake()
...............

.. parsed-literal::
	
	virtual void **add_handshake** (entry&);
	

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



.. raw:: html

	<a name="on_disconnect()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bon_disconnect%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bon_disconnect%28%29%5D%22+could+be+improved">report issue</a>]</span>



on_disconnect()
...............

.. parsed-literal::
	
	virtual void **on_disconnect** (error\_code const&);
	

called when the peer is being disconnected.



.. raw:: html

	<a name="on_connected()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bon_connected%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bon_connected%28%29%5D%22+could+be+improved">report issue</a>]</span>



on_connected()
..............

.. parsed-literal::
	
	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.


__ reference-Plugins.html#plugin

.. raw:: html

	<a name="on_handshake()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bon_handshake%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bon_handshake%28%29%5D%22+could+be+improved">report issue</a>]</span>



on_handshake()
..............

.. parsed-literal::
	
	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



.. raw:: html

	<a name="on_extension_handshake()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bon_extension_handshake%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bon_extension_handshake%28%29%5D%22+could+be+improved">report issue</a>]</span>



on_extension_handshake()
........................

.. parsed-literal::
	
	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


__ reference-Plugins.html#peer_plugin

.. raw:: html

	<a name="on_allowed_fast()"></a>
	<a name="on_choke()"></a>
	<a name="on_interested()"></a>
	<a name="on_bitfield()"></a>
	<a name="on_have()"></a>
	<a name="on_request()"></a>
	<a name="on_have_all()"></a>
	<a name="on_have_none()"></a>
	<a name="on_unchoke()"></a>
	<a name="on_dont_have()"></a>
	<a name="on_not_interested()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bon_allowed_fast%28%29+on_choke%28%29+on_interested%28%29+on_bitfield%28%29+on_have%28%29+on_request%28%29+on_have_all%28%29+on_have_none%28%29+on_unchoke%28%29+on_dont_have%28%29+on_not_interested%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bon_allowed_fast%28%29+on_choke%28%29+on_interested%28%29+on_bitfield%28%29+on_have%28%29+on_request%28%29+on_have_all%28%29+on_have_none%28%29+on_unchoke%28%29+on_dont_have%28%29+on_not_interested%28%29%5D%22+could+be+improved">report issue</a>]</span>



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

.. parsed-literal::
	
	virtual bool **on_bitfield** (bitfield const& */\*bitfield\*/*);
	virtual bool **on_not_interested** ();
	virtual bool **on_request** (peer\_request const&);
	virtual bool **on_choke** ();
	virtual bool **on_have** (piece\_index\_t);
	virtual bool **on_dont_have** (piece\_index\_t);
	virtual bool **on_unchoke** ();
	virtual bool **on_interested** ();
	virtual bool **on_have_none** ();
	virtual bool **on_have_all** ();
	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.


__ reference-Plugins.html#plugin
__ reference-Plugins.html#plugin

.. raw:: html

	<a name="on_piece()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bon_piece%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bon_piece%28%29%5D%22+could+be+improved">report issue</a>]</span>



on_piece()
..........

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="sent_not_interested()"></a>
	<a name="sent_piece()"></a>
	<a name="sent_unchoke()"></a>
	<a name="sent_interested()"></a>
	<a name="sent_have()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bsent_not_interested%28%29+sent_piece%28%29+sent_unchoke%28%29+sent_interested%28%29+sent_have%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bsent_not_interested%28%29+sent_piece%28%29+sent_unchoke%28%29+sent_interested%28%29+sent_have%28%29%5D%22+could+be+improved">report issue</a>]</span>



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

.. parsed-literal::
	
	virtual void **sent_have** (piece\_index\_t);
	virtual void **sent_unchoke** ();
	virtual void **sent_piece** (peer\_request const&);
	virtual void **sent_interested** ();
	virtual void **sent_not_interested** ();
	

called after a choke message has been sent to the peer



.. raw:: html

	<a name="sent_payload()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bsent_payload%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bsent_payload%28%29%5D%22+could+be+improved">report issue</a>]</span>



sent_payload()
..............

.. parsed-literal::
	
	virtual void **sent_payload** (int */\* bytes \*/*);
	

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



.. raw:: html

	<a name="can_disconnect()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bcan_disconnect%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bcan_disconnect%28%29%5D%22+could+be+improved">report issue</a>]</span>



can_disconnect()
................

.. parsed-literal::
	
	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.


__ reference-Plugins.html#plugin

.. raw:: html

	<a name="on_extended()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bon_extended%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bon_extended%28%29%5D%22+could+be+improved">report issue</a>]</span>



on_extended()
.............

.. parsed-literal::
	
	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.


__ reference-Plugins.html#plugin
__ reference-Plugins.html#plugin

.. raw:: html

	<a name="on_unknown_message()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bon_unknown_message%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bon_unknown_message%28%29%5D%22+could+be+improved">report issue</a>]</span>



on_unknown_message()
....................

.. parsed-literal::
	
	virtual bool **on_unknown_message** (int */\*length\*/*, int */\*msg\*/*,
	      span<char const> */\*body\*/*);
	

this is not called for web seeds



.. raw:: html

	<a name="on_piece_failed()"></a>
	<a name="on_piece_pass()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bon_piece_failed%28%29+on_piece_pass%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bon_piece_failed%28%29+on_piece_pass%28%29%5D%22+could+be+improved">report issue</a>]</span>



on_piece_failed() on_piece_pass()
.................................

.. parsed-literal::
	
	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



.. raw:: html

	<a name="tick()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Btick%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Btick%28%29%5D%22+could+be+improved">report issue</a>]</span>



tick()
......

.. parsed-literal::
	
	virtual void **tick** ();
	

called approximately once every second



.. raw:: html

	<a name="write_request()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bwrite_request%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bwrite_request%28%29%5D%22+could+be+improved">report issue</a>]</span>



write_request()
...............

.. parsed-literal::
	
	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.


__ reference-Plugins.html#plugin

.. raw:: html

	<a name="crypto_plugin"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+crypto_plugin&labels=documentation&body=Documentation+under+heading+%22class+crypto_plugin%22+could+be+improved">report issue</a>]</span>



crypto_plugin
-------------

Declared in "`libtorrent/extensions.hpp`__"


__ include/libtorrent/extensions.hpp





.. parsed-literal::
	

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

.. raw:: html

	<a name="decrypt()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:crypto_plugin%3A%3A%5Bdecrypt%28%29%5D&labels=documentation&body=Documentation+under+heading+%22crypto_plugin%3A%3A%5Bdecrypt%28%29%5D%22+could+be+improved">report issue</a>]</span>



decrypt()
.........

.. parsed-literal::
	
	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



.. raw:: html

	<a name="create_ut_metadata_plugin()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:create_ut_metadata_plugin%28%29&labels=documentation&body=Documentation+under+heading+%22create_ut_metadata_plugin%28%29%22+could+be+improved">report issue</a>]</span>



create_ut_metadata_plugin()
---------------------------

Declared in "`libtorrent/extensions/ut_metadata.hpp`__"


__ include/libtorrent/extensions/ut_metadata.hpp

.. parsed-literal::
	
	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()`__.


__ reference-Session.html#session
__ reference-Torrent_Handle.html#add_extension()

.. raw:: html

	<a name="create_smart_ban_plugin()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:create_smart_ban_plugin%28%29&labels=documentation&body=Documentation+under+heading+%22create_smart_ban_plugin%28%29%22+could+be+improved">report issue</a>]</span>



create_smart_ban_plugin()
-------------------------

Declared in "`libtorrent/extensions/smart_ban.hpp`__"


__ include/libtorrent/extensions/smart_ban.hpp

.. parsed-literal::
	
	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()`__.


__ reference-Torrent_Handle.html#add_extension()

.. raw:: html

	<a name="create_ut_pex_plugin()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:create_ut_pex_plugin%28%29&labels=documentation&body=Documentation+under+heading+%22create_ut_pex_plugin%28%29%22+could+be+improved">report issue</a>]</span>



create_ut_pex_plugin()
----------------------

Declared in "`libtorrent/extensions/ut_pex.hpp`__"


__ include/libtorrent/extensions/ut_pex.hpp

.. parsed-literal::
	
	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()`__.


__ reference-Session.html#session
__ reference-Torrent_Handle.html#add_extension()



.. _`BEP 19`: https://www.bittorrent.org/beps/bep_0019.html
.. _extensions: manual-ref.html#extensions
.. _`BEP 3`: https://www.bittorrent.org/beps/bep_0003.html
.. _`BEP 38`: https://www.bittorrent.org/beps/bep_0038.html
.. _`BEP 42`: https://www.bittorrent.org/beps/bep_0042.html
.. _`BEP 17`: https://www.bittorrent.org/beps/bep_0017.html
.. _`rate based choking`: manual-ref.html#rate-based-choking
.. raw:: html

	<a name="block_info"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+block_info&labels=documentation&body=Documentation+under+heading+%22class+block_info%22+could+be+improved">report issue</a>]</span>



block_info
----------

Declared in "`libtorrent/torrent_handle.hpp`__"


__ include/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.




.. parsed-literal::
	

	struct block_info
	{
	   tcp::endpoint **peer** () const;
	   void **set_peer** (tcp\:\:endpoint const& ep);
	
	   enum block_state_t
	   {
	      none,
	      requested,
	      writing,
	      finished,
	   };
	
	   unsigned bytes_progress:15;
	   unsigned block_size:15;
	   unsigned state:2;
	   unsigned num_peers:14;
	};

.. raw:: html

	<a name="set_peer()"></a>
	<a name="peer()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:block_info%3A%3A%5Bset_peer%28%29+peer%28%29%5D&labels=documentation&body=Documentation+under+heading+%22block_info%3A%3A%5Bset_peer%28%29+peer%28%29%5D%22+could+be+improved">report issue</a>]</span>



set_peer() peer()
.................

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="block_state_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+block_state_t&labels=documentation&body=Documentation+under+heading+%22enum+block_state_t%22+could+be+improved">report issue</a>]</span>



enum block_state_t
..................

Declared in "`libtorrent/torrent_handle.hpp`__"


__ include/libtorrent/torrent_handle.hpp

+-----------+-------+------------------------------------------------------------------+
| name      | value | description                                                      |
+===========+=======+==================================================================+
| none      | 0     | This block has not been downloaded or requested form any peer.   |
|           |       |                                                                  |
+-----------+-------+------------------------------------------------------------------+
| requested | 1     | The block has been requested, but not completely downloaded yet. |
|           |       |                                                                  |
+-----------+-------+------------------------------------------------------------------+
| writing   | 2     | The block has been downloaded and is currently queued for being  |
|           |       | written to disk.                                                 |
|           |       |                                                                  |
+-----------+-------+------------------------------------------------------------------+
| finished  | 3     | The block has been written to disk.                              |
|           |       |                                                                  |
+-----------+-------+------------------------------------------------------------------+



.. raw:: html

	<a name="bytes_progress"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:block_info%3A%3A%5Bbytes_progress%5D&labels=documentation&body=Documentation+under+heading+%22block_info%3A%3A%5Bbytes_progress%5D%22+could+be+improved">report issue</a>]</span>


bytes_progress
	the number of bytes that have been received for this block
	


.. raw:: html

	<a name="block_size"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:block_info%3A%3A%5Bblock_size%5D&labels=documentation&body=Documentation+under+heading+%22block_info%3A%3A%5Bblock_size%5D%22+could+be+improved">report issue</a>]</span>


block_size
	the total number of bytes in this block.
	


.. raw:: html

	<a name="state"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:block_info%3A%3A%5Bstate%5D&labels=documentation&body=Documentation+under+heading+%22block_info%3A%3A%5Bstate%5D%22+could+be+improved">report issue</a>]</span>


state
	the state this block is in (see `block_state_t`__)
	

__ reference-Torrent_Handle.html#block_state_t

.. raw:: html

	<a name="num_peers"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:block_info%3A%3A%5Bnum_peers%5D&labels=documentation&body=Documentation+under+heading+%22block_info%3A%3A%5Bnum_peers%5D%22+could+be+improved">report issue</a>]</span>


num_peers
	the number of peers that is currently requesting this block. Typically
	this is 0 or 1, but at the end of the torrent blocks may be requested
	by more peers in parallel to speed things up.
	


.. raw:: html

	<a name="partial_piece_info"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+partial_piece_info&labels=documentation&body=Documentation+under+heading+%22class+partial_piece_info%22+could+be+improved">report issue</a>]</span>



partial_piece_info
------------------

Declared in "`libtorrent/torrent_handle.hpp`__"


__ include/libtorrent/torrent_handle.hpp

This class holds information about pieces that have outstanding requests
or outstanding writes




.. parsed-literal::
	

	struct partial_piece_info
	{
	   piece_index_t piece_index;
	   int blocks_in_piece;
	   int finished;
	   int writing;
	   int requested;
	   block_info const* blocks;
	};

.. raw:: html

	<a name="piece_index"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:partial_piece_info%3A%3A%5Bpiece_index%5D&labels=documentation&body=Documentation+under+heading+%22partial_piece_info%3A%3A%5Bpiece_index%5D%22+could+be+improved">report issue</a>]</span>


piece_index
	the index of the piece in question. ``blocks_in_piece`` is the number
	of blocks in this particular piece. This number will be the same for
	most pieces, but
	the last piece may have fewer blocks than the standard pieces.
	


.. raw:: html

	<a name="blocks_in_piece"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:partial_piece_info%3A%3A%5Bblocks_in_piece%5D&labels=documentation&body=Documentation+under+heading+%22partial_piece_info%3A%3A%5Bblocks_in_piece%5D%22+could+be+improved">report issue</a>]</span>


blocks_in_piece
	the number of blocks in this piece
	


.. raw:: html

	<a name="finished"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:partial_piece_info%3A%3A%5Bfinished%5D&labels=documentation&body=Documentation+under+heading+%22partial_piece_info%3A%3A%5Bfinished%5D%22+could+be+improved">report issue</a>]</span>


finished
	the number of blocks that are in the finished state
	


.. raw:: html

	<a name="writing"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:partial_piece_info%3A%3A%5Bwriting%5D&labels=documentation&body=Documentation+under+heading+%22partial_piece_info%3A%3A%5Bwriting%5D%22+could+be+improved">report issue</a>]</span>


writing
	the number of blocks that are in the writing state
	


.. raw:: html

	<a name="requested"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:partial_piece_info%3A%3A%5Brequested%5D&labels=documentation&body=Documentation+under+heading+%22partial_piece_info%3A%3A%5Brequested%5D%22+could+be+improved">report issue</a>]</span>


requested
	the number of blocks that are in the requested state
	


.. raw:: html

	<a name="blocks"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:partial_piece_info%3A%3A%5Bblocks%5D&labels=documentation&body=Documentation+under+heading+%22partial_piece_info%3A%3A%5Bblocks%5D%22+could+be+improved">report issue</a>]</span>


blocks
	this is an array of ``blocks_in_piece`` number of
	items. One for each block in the piece.
	
	.. warning:: This is a pointer that points to an array
		that's owned by the `session`__ object. The next time
		`get_download_queue()`__ is called, it will be invalidated.
	

__ reference-Session.html#session
__ reference-Torrent_Handle.html#get_download_queue()

.. raw:: html

	<a name="torrent_handle"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+torrent_handle&labels=documentation&body=Documentation+under+heading+%22class+torrent_handle%22+could+be+improved">report issue</a>]</span>



torrent_handle
--------------

Declared in "`libtorrent/torrent_handle.hpp`__"


__ include/libtorrent/torrent_handle.hpp

You will usually have to store your torrent handles somewhere, since it's
the object through which you retrieve information about the torrent and
aborts the torrent.

.. warning::
	Any member function that returns a value or fills in a value has to be
	made synchronously. This means it has to wait for the main thread to
	complete the query before it can return. This might potentially be
	expensive if done from within a GUI thread that needs to stay
	responsive. Try to avoid querying for information you don't need, and
	try to do it in as few calls as possible. You can get most of the
	interesting information about a torrent from the
	`torrent_handle::status()`__ call.

The default constructor will initialize the handle to an invalid state.
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
	are processed by a background thread, there is no guarantee that a
	handle will remain valid between two calls.



__ reference-Torrent_Handle.html#status()
__ reference-Torrent_Handle.html#torrent_handle
__ reference-Torrent_Info.html#is_valid()


.. parsed-literal::
	

	struct torrent_handle
	{
	   friend std::size_t **hash_value** (torrent\_handle const& th);
	   **torrent_handle** () noexcept = default;
	   void **add_piece** (piece\_index\_t piece, char const\* 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;
	   void **get_download_queue** (std\:\:vector<partial\_piece\_info>& queue) const;
	   std::vector<partial_piece_info> **get_download_queue** () const;
	   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 **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 **remove_url_seed** (std\:\:string const& url) const;
	   void **add_url_seed** (std\:\:string const& url) const;
	   std::set<std::string> **url_seeds** () const;
	   std::set<std::string> **http_seeds** () const;
	   void **add_http_seed** (std\:\:string const& url) const;
	   void **remove_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;
	   torrent_flags_t **flags** () const;
	   void **set_flags** (torrent\_flags\_t flags, torrent\_flags\_t mask) const;
	   void **unset_flags** (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;
	   void **queue_position_up** () const;
	   void **queue_position_top** () const;
	   void **queue_position_bottom** () const;
	   queue_position_t **queue_position** () 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 = "");
	   std::shared_ptr<torrent_info> **torrent_file_with_hashes** () const;
	   std::shared_ptr<const torrent_info> **torrent_file** () const;
	   std::vector<std::vector<sha256_hash>> **piece_layers** () const;
	   void **piece_availability** (std\:\:vector<int>& avail) 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;
	   std::vector<download_priority_t> **get_piece_priorities** () const;
	   void **prioritize_pieces** (std\:\:vector<download\_priority\_t> const& pieces) const;
	   void **piece_priority** (piece\_index\_t index, download\_priority\_t priority) const;
	   download_priority_t **file_priority** (file\_index\_t index) const;
	   void **prioritize_files** (std\:\:vector<download\_priority\_t> const& files) const;
	   void **file_priority** (file\_index\_t index, download\_priority\_t priority) const;
	   std::vector<download_priority_t> **get_file_priorities** () const;
	   void **force_dht_announce** () const;
	   void **force_lsd_announce** () const;
	   void **force_reannounce** (int seconds = 0, int idx = -1, reannounce\_flags\_t = {}) const;
	   void **scrape_tracker** (int idx = -1) const;
	   void **set_download_limit** (int limit) const;
	   int **download_limit** () const;
	   int **upload_limit** () const;
	   void **set_upload_limit** (int 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;
	   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;
	
	   static constexpr add_piece_flags_t **overwrite_existing**  = 0_bit;
	   static constexpr status_flags_t **query_distributed_copies**  = 0_bit;
	   static constexpr status_flags_t **query_accurate_download_counters**  = 1_bit;
	   static constexpr status_flags_t **query_last_seen_complete**  = 2_bit;
	   static constexpr status_flags_t **query_pieces**  = 3_bit;
	   static constexpr status_flags_t **query_verified_pieces**  = 4_bit;
	   static constexpr status_flags_t **query_torrent_file**  = 5_bit;
	   static constexpr status_flags_t **query_name**  = 6_bit;
	   static constexpr status_flags_t **query_save_path**  = 7_bit;
	   static constexpr deadline_flags_t **alert_when_available**  = 0_bit;
	   static constexpr file_progress_flags_t **piece_granularity**  = 0_bit;
	   static constexpr pause_flags_t **graceful_pause**  = 0_bit;
	   static constexpr pause_flags_t **clear_disk_cache**  = 1_bit;
	   static constexpr resume_data_flags_t **flush_disk_cache**  = 0_bit;
	   static constexpr resume_data_flags_t **save_info_dict**  = 1_bit;
	   static constexpr resume_data_flags_t **only_if_modified**  = 2_bit;
	   static constexpr reannounce_flags_t **ignore_min_interval**  = 0_bit;
	};

.. raw:: html

	<a name="torrent_handle()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Btorrent_handle%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Btorrent_handle%28%29%5D%22+could+be+improved">report issue</a>]</span>



torrent_handle()
................

.. parsed-literal::
	
	**torrent_handle** () noexcept = default;
	

constructs a torrent handle that does not refer to a torrent.
i.e. `is_valid()`__ will return false.


__ reference-Torrent_Info.html#is_valid()

.. raw:: html

	<a name="add_piece()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Badd_piece%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Badd_piece%28%29%5D%22+could+be+improved">report issue</a>]</span>



add_piece()
...........

.. parsed-literal::
	
	void **add_piece** (piece\_index\_t piece, char const\* 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. ``data`` is expected to
point to a buffer of as many bytes as the size of the specified piece.
The data in the buffer is copied and passed on to the disk IO thread
to be written at a later point.

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 the hash check by waiting for `piece_finished_alert`__ or
`hash_failed_alert`__.

Adding pieces while the torrent is being checked (i.e. in
`torrent_status::checking_files`__ state) is not supported.


__ reference-Alerts.html#piece_finished_alert
__ reference-Alerts.html#hash_failed_alert
__ reference-Torrent_Status.html#checking_files

.. raw:: html

	<a name="read_piece()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bread_piece%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bread_piece%28%29%5D%22+could+be+improved">report issue</a>]</span>



read_piece()
............

.. parsed-literal::
	
	void **read_piece** (piece\_index\_t piece) const;
	

This function starts an asynchronous read operation of the specified
piece from this torrent. You must have completed the download of the
specified piece before calling this function.

When the read operation is completed, it is passed back through an
`alert`__, `read_piece_alert`__. Since this `alert`__ is a response to an explicit
call, it will always be posted, regardless of the `alert`__ mask.

Note that if you read multiple pieces, the read operations are not
guaranteed to finish in the same order as you initiated them.


__ reference-Alerts.html#alert
__ reference-Alerts.html#read_piece_alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert

.. raw:: html

	<a name="have_piece()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bhave_piece%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bhave_piece%28%29%5D%22+could+be+improved">report issue</a>]</span>



have_piece()
............

.. parsed-literal::
	
	bool **have_piece** (piece\_index\_t piece) const;
	

Returns true if this piece has been completely downloaded and written
to disk, and false otherwise.



.. raw:: html

	<a name="get_peer_info()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bget_peer_info%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bget_peer_info%28%29%5D%22+could+be+improved">report issue</a>]</span>



get_peer_info()
...............

.. parsed-literal::
	
	void **get_peer_info** (std\:\:vector<peer\_info>& v) const;
	

takes a reference to a vector that will be cleared and filled with one
`entry`__ for each peer connected to this torrent, given the handle is
valid. If the `torrent_handle`__ is invalid, it will throw
system_error exception. Each `entry`__ in the vector contains
information about that particular peer. See `peer_info`__.


__ reference-Bencoding.html#entry
__ reference-Torrent_Handle.html#torrent_handle
__ reference-Bencoding.html#entry
__ reference-Core.html#peer_info

.. raw:: html

	<a name="status()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bstatus%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bstatus%28%29%5D%22+could+be+improved">report issue</a>]</span>



status()
........

.. parsed-literal::
	
	torrent_status **status** (status\_flags\_t flags = status\_flags\_t\:\:all()) const;
	

``status()`` will return a structure with information about the status
of this torrent. If the `torrent_handle`__ is invalid, it will throw
system_error exception. See `torrent_status`__. The ``flags``
argument filters what information is 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.


__ reference-Torrent_Handle.html#torrent_handle
__ reference-Torrent_Status.html#torrent_status
__ reference-Torrent_Status.html#torrent_status

.. raw:: html

	<a name="get_download_queue()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bget_download_queue%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bget_download_queue%28%29%5D%22+could+be+improved">report issue</a>]</span>



get_download_queue()
....................

.. parsed-literal::
	
	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.


__ reference-Torrent_Handle.html#partial_piece_info

.. raw:: html

	<a name="clear_piece_deadlines()"></a>
	<a name="set_piece_deadline()"></a>
	<a name="reset_piece_deadline()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bclear_piece_deadlines%28%29+set_piece_deadline%28%29+reset_piece_deadline%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bclear_piece_deadlines%28%29+set_piece_deadline%28%29+reset_piece_deadline%28%29%5D%22+could+be+improved">report issue</a>]</span>



clear_piece_deadlines() set_piece_deadline() reset_piece_deadline()
...................................................................

.. parsed-literal::
	
	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;
	

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, unless the alert_when_available flag is set, in which case it
will have the same effect as calling `read_piece()`__ for ``index``.

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


__ reference-Torrent_Handle.html#read_piece()
__ reference-Torrent_Handle.html#reset_piece_deadline()

.. raw:: html

	<a name="file_progress()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bfile_progress%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bfile_progress%28%29%5D%22+could+be+improved">report issue</a>]</span>



file_progress()
...............

.. parsed-literal::
	
	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
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 progress. If left at the default value of 0, the progress will be
as accurate as possible, but also more expensive to calculate. If
``torrent_handle::piece_granularity`` is specified, the progress will
be specified in piece granularity. i.e. only pieces that have been
fully downloaded and passed the hash check count. When specifying
piece granularity, the operation is a lot cheaper, since libtorrent
already keeps track of this internally and no calculation is required.


__ reference-Torrent_Info.html#torrent_info

.. raw:: html

	<a name="file_status()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bfile_status%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bfile_status%28%29%5D%22+could+be+improved">report issue</a>]</span>



file_status()
.............

.. parsed-literal::
	
	std::vector<open_file_state> **file_status** () const;
	

This function returns a vector with status about files
that are open for this torrent. Any file that is not open
will not be reported in the vector, i.e. it's possible that
the vector is empty when returning, if none of the files in the
torrent are currently open.

See `open_file_state`__


__ reference-Custom_Storage.html#open_file_state

.. raw:: html

	<a name="clear_error()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bclear_error%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bclear_error%28%29%5D%22+could+be+improved">report issue</a>]</span>



clear_error()
.............

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="add_tracker()"></a>
	<a name="replace_trackers()"></a>
	<a name="trackers()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Badd_tracker%28%29+replace_trackers%28%29+trackers%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Badd_tracker%28%29+replace_trackers%28%29+trackers%28%29%5D%22+could+be+improved">report issue</a>]</span>



add_tracker() replace_trackers() trackers()
...........................................

.. parsed-literal::
	
	void **add_tracker** (announce\_entry const&) const;
	void **replace_trackers** (std\:\:vector<announce\_entry> const&) const;
	std::vector<announce_entry> **trackers** () 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.


__ reference-Bencoding.html#entry
__ reference-Alerts.html#int
__ reference-Torrent_Handle.html#force_reannounce()
__ reference-Trackers.html#announce_entry
__ reference-Trackers.html#announce_entry

.. raw:: html

	<a name="url_seeds()"></a>
	<a name="add_url_seed()"></a>
	<a name="remove_url_seed()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Burl_seeds%28%29+add_url_seed%28%29+remove_url_seed%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Burl_seeds%28%29+add_url_seed%28%29+remove_url_seed%28%29%5D%22+could+be+improved">report issue</a>]</span>



url_seeds() add_url_seed() remove_url_seed()
............................................

.. parsed-literal::
	
	void **remove_url_seed** (std\:\:string const& url) const;
	void **add_url_seed** (std\:\:string const& url) const;
	std::set<std::string> **url_seeds** () 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.


__ manual-ref.html#http-seeding

.. raw:: html

	<a name="add_http_seed()"></a>
	<a name="remove_http_seed()"></a>
	<a name="http_seeds()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Badd_http_seed%28%29+remove_http_seed%28%29+http_seeds%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Badd_http_seed%28%29+remove_http_seed%28%29+http_seeds%28%29%5D%22+could+be+improved">report issue</a>]</span>



add_http_seed() remove_http_seed() http_seeds()
...............................................

.. parsed-literal::
	
	std::set<std::string> **http_seeds** () const;
	void **add_http_seed** (std\:\:string const& url) const;
	void **remove_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.


__ manual-ref.html#http-seeding

.. raw:: html

	<a name="add_extension()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Badd_extension%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Badd_extension%28%29%5D%22+could+be+improved">report issue</a>]</span>



add_extension()
...............

.. parsed-literal::
	
	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{});
	

add the specified extension to this torrent. The ``ext`` argument is
a function that will be called from within libtorrent's context
passing in the internal torrent object and the specified userdata
pointer. The function is expected to return a shared pointer to
a `torrent_plugin`__ instance.


__ reference-Plugins.html#torrent_plugin

.. raw:: html

	<a name="set_metadata()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bset_metadata%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bset_metadata%28%29%5D%22+could+be+improved">report issue</a>]</span>



set_metadata()
..............

.. parsed-literal::
	
	bool **set_metadata** (span<char const> metadata) const;
	

``set_metadata`` expects the *info* section of metadata. i.e. The
buffer passed in will be hashed and verified against the info-hash. If
it fails, a ``metadata_failed_alert`` will be generated. If it passes,
a ``metadata_received_alert`` is generated. The function returns true
if the metadata is successfully set on the torrent, and false
otherwise. If the torrent already has metadata, this function will not
affect the torrent, and false will be returned.



.. raw:: html

	<a name="is_valid()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bis_valid%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bis_valid%28%29%5D%22+could+be+improved">report issue</a>]</span>



is_valid()
..........

.. parsed-literal::
	
	bool **is_valid** () const;
	

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


__ reference-Session.html#session
__ reference-Torrent_Handle.html#torrent_handle
__ reference-Session.html#session
__ reference-Torrent_Handle.html#in_session()
__ reference-Session.html#remove_torrent()
__ reference-Torrent_Info.html#is_valid()
__ reference-Torrent_Info.html#is_valid()

.. raw:: html

	<a name="pause()"></a>
	<a name="resume()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bpause%28%29+resume%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bpause%28%29+resume%28%29%5D%22+could+be+improved">report issue</a>]</span>



pause() resume()
................

.. parsed-literal::
	
	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`__.

For possible values of the ``flags`` parameter, see pause_flags_t.

To know if a torrent is paused or not, call
``torrent_handle::flags()`` and check 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`__.



__ reference-Alerts.html#file_error_alert
__ reference-Session.html#session
__ manual-ref.html#queuing

.. raw:: html

	<a name="unset_flags()"></a>
	<a name="set_flags()"></a>
	<a name="flags()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bunset_flags%28%29+set_flags%28%29+flags%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bunset_flags%28%29+set_flags%28%29+flags%28%29%5D%22+could+be+improved">report issue</a>]</span>



unset_flags() set_flags() flags()
.................................

.. parsed-literal::
	
	torrent_flags_t **flags** () const;
	void **set_flags** (torrent\_flags\_t flags, torrent\_flags\_t mask) const;
	void **unset_flags** (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.

The `seed_mode` flag is special, it can only be cleared once the
torrent has been added, and it can only be set as part of the
`add_torrent_params`__ flags, when adding the torrent.


__ reference-Core.html#torrent_flags_t
__ reference-Add_Torrent.html#add_torrent_params

.. raw:: html

	<a name="flush_cache()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bflush_cache%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bflush_cache%28%29%5D%22+could+be+improved">report issue</a>]</span>



flush_cache()
.............

.. parsed-literal::
	
	void **flush_cache** () const;
	

Instructs libtorrent to flush all the disk caches for this torrent and
close all file handles. This is done asynchronously and you will be
notified that it's complete through `cache_flushed_alert`__.

Note that by the time you get the `alert`__, libtorrent may have cached
more data for the torrent, but you are guaranteed that whatever cached
data libtorrent had by the time you called
``torrent_handle::flush_cache()`` has been written to disk.


__ reference-Alerts.html#cache_flushed_alert
__ reference-Alerts.html#alert

.. raw:: html

	<a name="force_recheck()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bforce_recheck%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bforce_recheck%28%29%5D%22+could+be+improved">report issue</a>]</span>



force_recheck()
...............

.. parsed-literal::
	
	void **force_recheck** () const;
	

``force_recheck`` puts the torrent back in a state where it assumes to
have no resume data. All peers will be disconnected and the torrent
will stop announcing to the tracker. The torrent will be added to the
checking queue, and will be checked (all the files will be read and
compared to the piece hashes). Once the check is complete, the torrent
will start connecting to peers again, as normal.
The torrent will be placed last in queue, i.e. its queue position
will be the highest of all torrents in the `session`__.


__ reference-Session.html#session

.. raw:: html

	<a name="save_resume_data()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bsave_resume_data%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bsave_resume_data%28%29%5D%22+could+be+improved">report issue</a>]</span>



save_resume_data()
..................

.. parsed-literal::
	
	void **save_resume_data** (resume\_data\_flags\_t flags = {}) const;
	

``save_resume_data()`` asks libtorrent to generate fast-resume data for
this torrent.

This operation is asynchronous, ``save_resume_data`` will return
immediately. The resume data is delivered when it's done through an
`save_resume_data_alert`__.

The fast resume data will be empty in the following cases:

	1. The torrent handle is invalid.
	2. The torrent hasn't received valid metadata and was started without
	   metadata (see libtorrent's `metadata from peers`__ extension)

Note that by the time you receive the fast resume data, it may already
be invalid if the torrent is still downloading! The recommended
practice is to first pause the `session`__, then generate the fast resume
data, and then close it down. Make sure to not `remove_torrent()`__ before
you receive the `save_resume_data_alert`__ though. There's no need to
pause when saving intermittent resume data.

.. warning::
  If you pause every torrent individually instead of pausing the
  `session`__, every torrent will have its paused state saved in the
  resume data!

.. note::
  It is typically a good idea to save resume data whenever a torrent
  is completed or paused. In those cases you don't need to pause the
  torrent or the `session`__, since the torrent will do no more writing to
  its files. If you save resume data for torrents when they are
  paused, you can accelerate the shutdown process by not saving resume
  data again for paused torrents. Completed torrents should have their
  resume data saved when they complete and on exit, since their
  statistics might be updated.

	In full allocation mode the resume data is never invalidated by
	subsequent writes to the files, since pieces won't move around. This
	means that you don't need to pause before writing resume data in full
	or sparse mode. If you don't, however, any data written to disk after
	you saved resume data and before the `session`__ closed is lost.

It also means that if the resume data is out dated, libtorrent will
not re-check the files, but assume that it is fairly recent. The
assumption is that it's better to loose a little bit than to re-check
the entire file.

It is still a good idea to save resume data periodically during
download as well as when closing down.

Example code to pause and save resume data for all torrents and wait
for the alerts:

.. code:: c++

	extern int outstanding_resume_data; // global counter of outstanding resume data
	std::vector<torrent_handle> handles = ses.get_torrents();
	ses.pause();
	for (torrent_handle const& h : handles) try
	{
		torrent_status s = h.status();
		if (!s.has_metadata || !s.need_save_resume_data()) continue;

		h.save_resume_data();
		++outstanding_resume_data;
	}
	catch (lt::system_error const& e)
	{
		// the handle was invalid, ignore this one and move to the next
	}

	while (outstanding_resume_data > 0)
	{
		alert const* a = ses.wait_for_alert(seconds(10));

		// if we don't get an alert within 10 seconds, abort
		if (a == nullptr) break;

		std::vector<alert*> alerts;
		ses.pop_alerts(&alerts);

		for (alert* i : alerts)
		{
			if (alert_cast<save_resume_data_failed_alert>(i))
			{
				process_alert(i);
				--outstanding_resume_data;
				continue;
			}

			save_resume_data_alert const* rd = alert_cast<save_resume_data_alert>(i);
			if (rd == nullptr)
			{
				process_alert(i);
				continue;
			}

			torrent_handle h = rd->handle;
			torrent_status st = h.status(torrent_handle::query_save_path
				| torrent_handle::query_name);
			std::ofstream out((st.save_path
				+ "/" + st.name + ".fastresume").c_str()
				, std::ios_base::binary);
			std::vector<char> buf = write_resume_data_buf(rd->params);
			out.write(buf.data(), buf.size());
			--outstanding_resume_data;
		}
	}

.. note::
	Note how ``outstanding_resume_data`` is a global counter in this
	example. This is deliberate, otherwise there is a race condition for
	torrents that was just asked to save their resume data, they posted
	the `alert`__, but it has not been received yet. Those torrents would
	report that they don't need to save resume data again, and skipped by
	the initial loop, and thwart the counter otherwise.


__ reference-Alerts.html#save_resume_data_alert
__ manual-ref.html#metadata-from-peers
__ reference-Session.html#session
__ reference-Custom_Storage.html#remove_torrent()
__ reference-Alerts.html#save_resume_data_alert
__ reference-Session.html#session
__ reference-Session.html#session
__ reference-Session.html#session
__ reference-Alerts.html#alert

.. raw:: html

	<a name="need_save_resume_data()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bneed_save_resume_data%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bneed_save_resume_data%28%29%5D%22+could+be+improved">report issue</a>]</span>



need_save_resume_data()
.......................

.. parsed-literal::
	
	bool **need_save_resume_data** () const;
	

This function returns true if any whole chunk has been downloaded
since the torrent was first loaded or since the last time the resume
data was saved. When 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.


__ reference-Alerts.html#save_resume_data_alert
__ reference-Alerts.html#alert

.. raw:: html

	<a name="queue_position()"></a>
	<a name="queue_position_down()"></a>
	<a name="queue_position_up()"></a>
	<a name="queue_position_bottom()"></a>
	<a name="queue_position_top()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bqueue_position%28%29+queue_position_down%28%29+queue_position_up%28%29+queue_position_bottom%28%29+queue_position_top%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bqueue_position%28%29+queue_position_down%28%29+queue_position_up%28%29+queue_position_bottom%28%29+queue_position_top%28%29%5D%22+could+be+improved">report issue</a>]</span>



queue_position() queue_position_down() queue_position_up() queue_position_bottom() queue_position_top()
.......................................................................................................

.. parsed-literal::
	
	void **queue_position_down** () const;
	void **queue_position_up** () const;
	void **queue_position_top** () const;
	void **queue_position_bottom** () const;
	queue_position_t **queue_position** () 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 torrents with the smallest numbers are the ones that are
being downloaded. The smaller number, the closer the torrent is to the
front of the line to be started.

The queue position is also available in the `torrent_status`__.

The ``queue_position_*()`` functions adjust the torrents position in
the queue. Up means closer to the front and down means closer to the
back of the queue. Top and bottom refers to the front and the back of
the queue respectively.


__ reference-Torrent_Status.html#torrent_status

.. raw:: html

	<a name="queue_position_set()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bqueue_position_set%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bqueue_position_set%28%29%5D%22+could+be+improved">report issue</a>]</span>



queue_position_set()
....................

.. parsed-literal::
	
	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



.. raw:: html

	<a name="set_ssl_certificate_buffer()"></a>
	<a name="set_ssl_certificate()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bset_ssl_certificate_buffer%28%29+set_ssl_certificate%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bset_ssl_certificate_buffer%28%29+set_ssl_certificate%28%29%5D%22+could+be+improved">report issue</a>]</span>



set_ssl_certificate_buffer() set_ssl_certificate()
..................................................

.. parsed-literal::
	
	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 = "");
	

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.

``private_key`` is a path to the private key for the specified
certificate. This must be in .pem format.

``dh_params`` is a path to the Diffie-Hellman parameter file, which
needs to be in .pem format. You can generate this file using the
openssl command like this: ``openssl dhparam -outform PEM -out
dhparams.pem 512``.

``passphrase`` may be specified if the private key is encrypted and
requires a passphrase to be decrypted.

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.


__ reference-Torrent_Handle.html#set_ssl_certificate_buffer()
__ reference-Alerts.html#torrent_need_cert_alert

.. raw:: html

	<a name="torrent_file()"></a>
	<a name="torrent_file_with_hashes()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Btorrent_file%28%29+torrent_file_with_hashes%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Btorrent_file%28%29+torrent_file_with_hashes%28%29%5D%22+could+be+improved">report issue</a>]</span>



torrent_file() torrent_file_with_hashes()
.........................................

.. parsed-literal::
	
	std::shared_ptr<torrent_info> **torrent_file_with_hashes** () const;
	std::shared_ptr<const torrent_info> **torrent_file** () 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.

Note that the `torrent_info`__ object returned here may be a different
instance than the one added to the `session`__, with different attributes
like piece layers, dht nodes and trackers. A `torrent_info`__ object does
not round-trip cleanly when added to a `session`__.

This means if you want to create a .torrent file by passing the
`torrent_info`__ object into `create_torrent`__, you need to use
`torrent_file_with_hashes()`__ instead.

`torrent_file_with_hashes()`__ returns a *copy* of the internal
`torrent_info`__ and piece layer hashes (if it's a v2 torrent). The piece
layers will only be included if they are available. If this torrent
was added from a .torrent file with piece layers or if it's seeding,
the piece layers are available. This function is more expensive than
`torrent_file()`__ since it needs to make copies of this information.

When constructing a `create_torrent`__ object from a `torrent_info`__ that's
in a `session`__, you need to use this function.

Note that a torrent added from a magnet link may not have the full
merkle trees for all files, and hence not have the complete piece
layers. In that state, you cannot create a .torrent file even from
the `torrent_info`__ returned from `torrent_file_with_hashes()`__. Once the
torrent completes downloading all files, becoming a seed, you can
make a .torrent file from it.


__ reference-Torrent_Handle.html#torrent_file()
__ reference-Torrent_Info.html#torrent_info
__ reference-Torrent_Info.html#torrent_info
__ reference-Torrent_Info.html#torrent_info
__ reference-Session.html#session
__ reference-Torrent_Info.html#torrent_info
__ reference-Session.html#session
__ reference-Torrent_Info.html#torrent_info
__ reference-Create_Torrents.html#create_torrent
__ reference-Torrent_Handle.html#torrent_file_with_hashes()
__ reference-Torrent_Handle.html#torrent_file_with_hashes()
__ reference-Torrent_Info.html#torrent_info
__ reference-Torrent_Handle.html#torrent_file()
__ reference-Create_Torrents.html#create_torrent
__ reference-Torrent_Info.html#torrent_info
__ reference-Session.html#session
__ reference-Torrent_Info.html#torrent_info
__ reference-Torrent_Handle.html#torrent_file_with_hashes()

.. raw:: html

	<a name="piece_layers()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bpiece_layers%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bpiece_layers%28%29%5D%22+could+be+improved">report issue</a>]</span>



piece_layers()
..............

.. parsed-literal::
	
	std::vector<std::vector<sha256_hash>> **piece_layers** () const;
	

returns the piece layers for all files in the torrent. If this is a
v1 torrent (and doesn't have any piece layers) it returns an empty
vector. This is a blocking call that will synchronize with the
libtorrent network thread.



.. raw:: html

	<a name="piece_availability()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bpiece_availability%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bpiece_availability%28%29%5D%22+could+be+improved">report issue</a>]</span>



piece_availability()
....................

.. parsed-literal::
	
	void **piece_availability** (std\:\:vector<int>& avail) const;
	

Fills the specified ``std::vector<int>`` with the availability for
each piece in this torrent. libtorrent does not keep track of
availability for seeds, so if the torrent is seeding the availability
for all pieces is reported as 0.

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.



.. raw:: html

	<a name="get_piece_priorities()"></a>
	<a name="piece_priority()"></a>
	<a name="prioritize_pieces()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bget_piece_priorities%28%29+piece_priority%28%29+prioritize_pieces%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bget_piece_priorities%28%29+piece_priority%28%29+prioritize_pieces%28%29%5D%22+could+be+improved">report issue</a>]</span>



get_piece_priorities() piece_priority() prioritize_pieces()
...........................................................

.. parsed-literal::
	
	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;
	std::vector<download_priority_t> **get_piece_priorities** () const;
	void **prioritize_pieces** (std\:\:vector<download\_priority\_t> const& pieces) const;
	void **piece_priority** (piece\_index\_t index, download\_priority\_t priority) 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 and so on.

The default priority of pieces is 4.

Piece priorities can not be changed for torrents that have not
downloaded the metadata yet. Magnet links won't have metadata
immediately. see the `metadata_received_alert`__.

``piece_priority`` sets or gets the priority for an individual piece,
specified by ``index``.

``prioritize_pieces`` takes a vector of integers, one integer per
piece in the torrent. All the piece priorities will be updated with
the priorities in the vector.
The second overload of ``prioritize_pieces`` that takes a vector of pairs
will update the priorities of only select pieces, and leave all other
unaffected. Each pair is (piece, priority). That is, the first item is
the piece index and the second item is the priority of that piece.
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.


__ reference-Alerts.html#metadata_received_alert

.. raw:: html

	<a name="file_priority()"></a>
	<a name="prioritize_files()"></a>
	<a name="get_file_priorities()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bfile_priority%28%29+prioritize_files%28%29+get_file_priorities%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bfile_priority%28%29+prioritize_files%28%29+get_file_priorities%28%29%5D%22+could+be+improved">report issue</a>]</span>



file_priority() prioritize_files() get_file_priorities()
........................................................

.. parsed-literal::
	
	download_priority_t **file_priority** (file\_index\_t index) const;
	void **prioritize_files** (std\:\:vector<download\_priority\_t> const& files) const;
	void **file_priority** (file\_index\_t index, download\_priority\_t priority) const;
	std::vector<download_priority_t> **get_file_priorities** () 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.

``get_file_priorities()`` returns a vector with the priorities of all
files.

The priority values are the same as for `piece_priority()`__. See
`download_priority_t`__.

Whenever a file priority is changed, all other piece priorities are
reset to match the file priorities. In order to maintain special
priorities for particular pieces, `piece_priority()`__ has to be called
again for those pieces.

You cannot set the file priorities on a torrent that does not yet have
metadata or a torrent that is a seed. ``file_priority(int, int)`` and
`prioritize_files()`__ are both no-ops for such torrents.

Since changing file priorities may involve disk operations (of moving
files in- and out of the part file), the internal accounting of file
priorities happen asynchronously. i.e. setting file priorities and then
immediately querying them may not yield the same priorities just set.
To synchronize with the priorities taking effect, wait for the
`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.


__ reference-Bencoding.html#entry
__ reference-Torrent_Handle.html#piece_priority()
__ reference-Core.html#download_priority_t
__ reference-Torrent_Handle.html#piece_priority()
__ reference-Torrent_Handle.html#prioritize_files()
__ reference-Alerts.html#file_prio_alert

.. raw:: html

	<a name="force_dht_announce()"></a>
	<a name="force_reannounce()"></a>
	<a name="force_lsd_announce()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bforce_dht_announce%28%29+force_reannounce%28%29+force_lsd_announce%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bforce_dht_announce%28%29+force_reannounce%28%29+force_lsd_announce%28%29%5D%22+could+be+improved">report issue</a>]</span>



force_dht_announce() force_reannounce() force_lsd_announce()
............................................................

.. parsed-literal::
	
	void **force_dht_announce** () const;
	void **force_lsd_announce** () const;
	void **force_reannounce** (int seconds = 0, int idx = -1, reannounce\_flags\_t = {}) 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 -1 (which is the default), all trackers are re-announce.

The ``flags`` argument can be used to affect the re-announce. See
ignore_min_interval.

``force_dht_announce`` will announce the torrent to the DHT
immediately.

``force_lsd_announce`` will announce the torrent on LSD
immediately.



.. raw:: html

	<a name="scrape_tracker()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bscrape_tracker%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bscrape_tracker%28%29%5D%22+could+be+improved">report issue</a>]</span>



scrape_tracker()
................

.. parsed-literal::
	
	void **scrape_tracker** (int idx = -1) const;
	

``scrape_tracker()`` will send a scrape request to a tracker. By
default (``idx`` = -1) it will scrape the last working tracker. If
``idx`` is >= 0, the tracker with the specified index will scraped.

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`__.


__ reference-Torrent_Status.html#torrent_status
__ reference-Alerts.html#scrape_reply_alert
__ reference-Alerts.html#scrape_failed_alert

.. raw:: html

	<a name="upload_limit()"></a>
	<a name="download_limit()"></a>
	<a name="set_upload_limit()"></a>
	<a name="set_download_limit()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bupload_limit%28%29+download_limit%28%29+set_upload_limit%28%29+set_download_limit%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bupload_limit%28%29+download_limit%28%29+set_upload_limit%28%29+set_download_limit%28%29%5D%22+could+be+improved">report issue</a>]</span>



upload_limit() download_limit() set_upload_limit() set_download_limit()
.......................................................................

.. parsed-literal::
	
	void **set_download_limit** (int limit) const;
	int **download_limit** () const;
	int **upload_limit** () const;
	void **set_upload_limit** (int 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 the global rate
limit.

``upload_limit`` and ``download_limit`` will return the current limit
setting, for upload and download, respectively.

Local peers are not rate limited by default. see `peer classes`__.


__ manual-ref.html#peer-classes

.. raw:: html

	<a name="connect_peer()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bconnect_peer%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bconnect_peer%28%29%5D%22+could+be+improved">report issue</a>]</span>



connect_peer()
..............

.. parsed-literal::
	
	void **connect_peer** (tcp\:\:endpoint const& adr, peer\_source\_flags\_t source = {}
	      , pex\_flags\_t flags = pex\_encryption | pex\_utp | pex\_holepunch) const;
	

``connect_peer()`` is a way to manually connect to peers that one
believe is a part of the torrent. If the peer does not respond, or is
not a member of this torrent, it will simply be disconnected. No harm
can be done by using this other than an unnecessary connection attempt
is made. If the torrent is uninitialized or in queued or checking
mode, this will throw system_error. The second (optional)
argument will be bitwise ORed into the source mask of this peer.
Typically this is one of the source flags in `peer_info`__. i.e.
``tracker``, ``pex``, ``dht`` etc.

For possible values of ``flags``, see `pex_flags_t`__.


__ reference-Core.html#peer_info
__ reference-Core.html#pex_flags_t

.. raw:: html

	<a name="clear_peers()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bclear_peers%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bclear_peers%28%29%5D%22+could+be+improved">report issue</a>]</span>



clear_peers()
.............

.. parsed-literal::
	
	void **clear_peers** ();
	

This will disconnect all peers and clear the peer list for this
torrent. New peers will have to be acquired before resuming, from
trackers, DHT or local service discovery, for example.



.. raw:: html

	<a name="set_max_uploads()"></a>
	<a name="max_uploads()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bset_max_uploads%28%29+max_uploads%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bset_max_uploads%28%29+max_uploads%28%29%5D%22+could+be+improved">report issue</a>]</span>



set_max_uploads() max_uploads()
...............................

.. parsed-literal::
	
	int **max_uploads** () const;
	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.


__ reference-Settings.html#settings_pack

.. raw:: html

	<a name="set_max_connections()"></a>
	<a name="max_connections()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bset_max_connections%28%29+max_connections%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bset_max_connections%28%29+max_connections%28%29%5D%22+could+be+improved">report issue</a>]</span>



set_max_connections() max_connections()
.......................................

.. parsed-literal::
	
	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
``connections_limit`` in `settings_pack`__.

``max_connections()`` returns the current settings.


__ reference-Settings.html#settings_pack

.. raw:: html

	<a name="move_storage()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bmove_storage%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bmove_storage%28%29%5D%22+could+be+improved">report issue</a>]</span>



move_storage()
..............

.. parsed-literal::
	
	void **move_storage** (std\:\:string const& save\_path
	      , move\_flags\_t flags = move\_flags\_t\:\:always\_replace\_files
	      ) const;
	

Moves the file(s) that this torrent are currently seeding from or
downloading to. If the given ``save_path`` is not located on the same
drive as the original save path, the files will be copied to the new
drive and removed from their original location. This will block all
other disk IO, and other torrents download and upload rates may drop
while copying the file.

Since disk IO is performed in a separate thread, this operation is
also asynchronous. Once the operation completes, the
``storage_moved_alert`` is generated, with the new path as the
message. If the move fails for some reason,
``storage_moved_failed_alert`` is generated instead, containing the
error message.

The ``flags`` argument determines the behavior of the copying/moving
of the files in the torrent. see `move_flags_t`__.

``always_replace_files`` is the default and replaces any file that
exist in both the source directory and the target directory.

``fail_if_exist`` first check to see that none of the copy operations
would cause an overwrite. If it would, it will fail. Otherwise it will
proceed as if it was in ``always_replace_files`` mode. Note that there
is an inherent race condition here. If the files in the target
directory appear after the check but before the copy or move
completes, they will be overwritten. When failing because of files
already existing in the target path, the ``error`` of
``move_storage_failed_alert`` is set to
``boost::system::errc::file_exists``.

The intention is that a client may use this as a probe, and if it
fails, ask the user which mode to use. The client may then re-issue
the ``move_storage`` call with one of the other modes.

``dont_replace`` always keeps the existing file in the target
directory, if there is one. The source files will still be removed in
that case. Note that it won't automatically re-check files. If an
incomplete torrent is moved into a directory with the complete files,
pause, move, force-recheck and resume. Without the re-checking, the
torrent will keep downloading and files in the new download directory
will be overwritten.

Files that have been renamed to have absolute paths are not moved by
this function. Keep in mind that files that don't belong to the
torrent but are stored in the torrent's directory may be moved as
well. This goes for files that have been renamed to absolute paths
that still end up inside the save path.

When copying files, sparse regions are not likely to be preserved.
This makes it proportionally more expensive to move a large torrent
when only few pieces have been downloaded, since the files are then
allocated with zeros in the destination directory.


__ reference-Storage.html#move_flags_t

.. raw:: html

	<a name="rename_file()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Brename_file%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Brename_file%28%29%5D%22+could+be+improved">report issue</a>]</span>



rename_file()
.............

.. parsed-literal::
	
	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.


__ reference-Alerts.html#file_renamed_alert
__ reference-Alerts.html#file_rename_failed_alert

.. raw:: html

	<a name="info_hash()"></a>
	<a name="info_hashes()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Binfo_hash%28%29+info_hashes%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Binfo_hash%28%29+info_hashes%28%29%5D%22+could+be+improved">report issue</a>]</span>



info_hash() info_hashes()
.........................

.. parsed-literal::
	
	sha1_hash **info_hash** () const;
	info_hash_t **info_hashes** () 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.



.. raw:: html

	<a name="operator<()"></a>
	<a name="operator!=()"></a>
	<a name="operator==()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Boperator%3C%28%29+operator%21%3D%28%29+operator%3D%3D%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Boperator%3C%28%29+operator%21%3D%28%29+operator%3D%3D%28%29%5D%22+could+be+improved">report issue</a>]</span>



operator<() operator!=() operator==()
.....................................

.. parsed-literal::
	
	bool **operator!=** (const torrent\_handle& h) const;
	bool **operator<** (const torrent\_handle& h) const;
	bool **operator==** (const torrent\_handle& h) const;
	

comparison operators. The order of the torrents is unspecified
but stable.



.. raw:: html

	<a name="id()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bid%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bid%28%29%5D%22+could+be+improved">report issue</a>]</span>



id()
....

.. parsed-literal::
	
	std::uint32_t **id** () const;
	

returns a unique identifier for this torrent. It's not a dense index.
It's not preserved across sessions.



.. raw:: html

	<a name="native_handle()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bnative_handle%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bnative_handle%28%29%5D%22+could+be+improved">report issue</a>]</span>



native_handle()
...............

.. parsed-literal::
	
	std::shared_ptr<torrent> **native_handle** () const;
	

This function is intended only for use by plugins and the `alert`__
dispatch function. This type does not have a stable ABI and should
be relied on as little as possible. Accessing the handle returned by
this function is not thread safe outside of libtorrent's internal
thread (which is used to invoke `plugin`__ callbacks).
The ``torrent`` class is not only eligible for changing ABI across
minor versions of libtorrent, its layout is also dependent on build
configuration. This adds additional requirements on a client to be
built with the exact same build configuration as libtorrent itself.
i.e. the ``TORRENT_`` macros must match between libtorrent and the
client builds.


__ reference-Alerts.html#alert
__ reference-Plugins.html#plugin

.. raw:: html

	<a name="userdata()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Buserdata%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Buserdata%28%29%5D%22+could+be+improved">report issue</a>]</span>



userdata()
..........

.. parsed-literal::
	
	client_data_t **userdata** () const;
	

returns the userdata pointer as set in `add_torrent_params`__


__ reference-Add_Torrent.html#add_torrent_params

.. raw:: html

	<a name="in_session()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bin_session%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bin_session%28%29%5D%22+could+be+improved">report issue</a>]</span>



in_session()
............

.. parsed-literal::
	
	bool **in_session** () const;
	

Returns true if the torrent is in the `session`__. It returns true before
session::remove_torrent() is called, and false afterward.

Note that this is a blocking function, unlike `torrent_handle::is_valid()`__
which returns immediately.


__ reference-Session.html#session
__ reference-Torrent_Handle.html#is_valid()

.. raw:: html

	<a name="overwrite_existing"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Boverwrite_existing%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Boverwrite_existing%5D%22+could+be+improved">report issue</a>]</span>


overwrite_existing
	instruct libtorrent to overwrite any data that may already have been
	downloaded with the data of the new piece being added. Using this
	flag when adding a piece that is actively being downloaded from other
	peers may have some unexpected consequences, as blocks currently
	being downloaded from peers may not be replaced.
	


.. raw:: html

	<a name="query_distributed_copies"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bquery_distributed_copies%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bquery_distributed_copies%5D%22+could+be+improved">report issue</a>]</span>


query_distributed_copies
	calculates ``distributed_copies``, ``distributed_full_copies`` and
	``distributed_fraction``.
	


.. raw:: html

	<a name="query_accurate_download_counters"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bquery_accurate_download_counters%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bquery_accurate_download_counters%5D%22+could+be+improved">report issue</a>]</span>


query_accurate_download_counters
	includes partial downloaded blocks in ``total_done`` and
	``total_wanted_done``.
	


.. raw:: html

	<a name="query_last_seen_complete"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bquery_last_seen_complete%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bquery_last_seen_complete%5D%22+could+be+improved">report issue</a>]</span>


query_last_seen_complete
	includes ``last_seen_complete``.
	


.. raw:: html

	<a name="query_pieces"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bquery_pieces%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bquery_pieces%5D%22+could+be+improved">report issue</a>]</span>


query_pieces
	populate the ``pieces`` field in `torrent_status`__.
	

__ reference-Torrent_Status.html#torrent_status

.. raw:: html

	<a name="query_verified_pieces"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bquery_verified_pieces%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bquery_verified_pieces%5D%22+could+be+improved">report issue</a>]</span>


query_verified_pieces
	includes ``verified_pieces`` (only applies to torrents in *seed
	mode*).
	


.. raw:: html

	<a name="query_torrent_file"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bquery_torrent_file%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bquery_torrent_file%5D%22+could+be+improved">report issue</a>]</span>


query_torrent_file
	includes ``torrent_file``, which is all the static information from
	the .torrent file.
	


.. raw:: html

	<a name="query_name"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bquery_name%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bquery_name%5D%22+could+be+improved">report issue</a>]</span>


query_name
	includes ``name``, the name of the torrent. This is either derived
	from the .torrent file, or from the ``&dn=`` magnet link argument
	or possibly some other source. If the name of the torrent is not
	known, this is an empty string.
	


.. raw:: html

	<a name="query_save_path"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bquery_save_path%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bquery_save_path%5D%22+could+be+improved">report issue</a>]</span>


query_save_path
	includes ``save_path``, the path to the directory the files of the
	torrent are saved to.
	


.. raw:: html

	<a name="alert_when_available"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Balert_when_available%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Balert_when_available%5D%22+could+be+improved">report issue</a>]</span>


alert_when_available
	used to ask libtorrent to send an `alert`__ once the piece has been
	downloaded, by passing alert_when_available. When set, the
	`read_piece_alert`__ `alert`__ will be delivered, with the piece data, when
	it's downloaded.
	

__ reference-Alerts.html#alert
__ reference-Alerts.html#read_piece_alert
__ reference-Alerts.html#alert

.. raw:: html

	<a name="piece_granularity"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bpiece_granularity%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bpiece_granularity%5D%22+could+be+improved">report issue</a>]</span>


piece_granularity
	only calculate file progress at piece granularity. This makes
	the `file_progress()`__ call cheaper and also only takes bytes that
	have passed the hash check into account, so progress cannot
	regress in this mode.
	

__ reference-Torrent_Handle.html#file_progress()

.. raw:: html

	<a name="graceful_pause"></a>
	<a name="clear_disk_cache"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bgraceful_pause+clear_disk_cache%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bgraceful_pause+clear_disk_cache%5D%22+could+be+improved">report issue</a>]</span>


graceful_pause clear_disk_cache
	will delay the disconnect of peers that we're still downloading
	outstanding requests from. The torrent will not accept any more
	requests and will disconnect all idle peers. As soon as a peer is done
	transferring the blocks that were requested from it, it is
	disconnected. This is a graceful shut down of the torrent in the sense
	that no downloaded bytes are wasted.
	


.. raw:: html

	<a name="flush_disk_cache"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bflush_disk_cache%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bflush_disk_cache%5D%22+could+be+improved">report issue</a>]</span>


flush_disk_cache
	the disk cache will be flushed before creating the resume data.
	This avoids a problem with file timestamps in the resume data in
	case the cache hasn't been flushed yet.
	


.. raw:: html

	<a name="save_info_dict"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bsave_info_dict%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bsave_info_dict%5D%22+could+be+improved">report issue</a>]</span>


save_info_dict
	the resume data will contain the metadata from the torrent file as
	well. This is default for any torrent that's added without a
	torrent file (such as a magnet link or a URL).
	


.. raw:: html

	<a name="only_if_modified"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bonly_if_modified%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bonly_if_modified%5D%22+could+be+improved">report issue</a>]</span>


only_if_modified
	if nothing significant has changed in the torrent since the last
	time resume data was saved, fail this attempt. Significant changes
	primarily include more data having been downloaded, file or piece
	priorities having changed etc. If the resume data doesn't need
	saving, a `save_resume_data_failed_alert`__ is posted with the error
	resume_data_not_modified.
	

__ reference-Alerts.html#save_resume_data_failed_alert

.. raw:: html

	<a name="ignore_min_interval"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_handle%3A%3A%5Bignore_min_interval%5D&labels=documentation&body=Documentation+under+heading+%22torrent_handle%3A%3A%5Bignore_min_interval%5D%22+could+be+improved">report issue</a>]</span>


ignore_min_interval
	by default, force-reannounce will still honor the min-interval
	published by the tracker. If this flag is set, it will be ignored
	and the tracker is announced immediately.
	


.. raw:: html

	<a name="hash_value()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:hash_value%28%29&labels=documentation&body=Documentation+under+heading+%22hash_value%28%29%22+could+be+improved">report issue</a>]</span>



hash_value()
------------

Declared in "`libtorrent/torrent_handle.hpp`__"


__ include/libtorrent/torrent_handle.hpp

.. parsed-literal::
	
	std::size_t **hash_value** (torrent\_handle const& h);
	

for std::hash (and to support using this type in unordered_map etc.)





.. _`BEP 19`: https://www.bittorrent.org/beps/bep_0019.html
.. _extensions: manual-ref.html#extensions
.. _`BEP 3`: https://www.bittorrent.org/beps/bep_0003.html
.. _`BEP 38`: https://www.bittorrent.org/beps/bep_0038.html
.. _`BEP 42`: https://www.bittorrent.org/beps/bep_0042.html
.. _`BEP 17`: https://www.bittorrent.org/beps/bep_0017.html
.. _`rate based choking`: manual-ref.html#rate-based-choking
.. raw:: html

	<a name="add_torrent_params"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+add_torrent_params&labels=documentation&body=Documentation+under+heading+%22class+add_torrent_params%22+could+be+improved">report issue</a>]</span>



add_torrent_params
------------------

Declared in "`libtorrent/add_torrent_params.hpp`__"


__ include/libtorrent/add_torrent_params.hpp

The `add_torrent_params`__ is a parameter pack for adding torrents to a
`session`__. The key fields when adding a torrent are:

* ti - when you have loaded a .torrent file into a `torrent_info`__ object
* info_hash - when you don't have the metadata (.torrent file) but. This
  is set when adding a magnet link.

one of those fields must be set. Another mandatory field is
``save_path``. The `add_torrent_params`__ object is 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()`__.


__ reference-Add_Torrent.html#add_torrent_params
__ reference-Session.html#session
__ reference-Torrent_Info.html#torrent_info
__ reference-Add_Torrent.html#add_torrent_params
__ reference-Session.html#session
__ reference-Resume_Data.html#read_resume_data()
__ reference-Resume_Data.html#write_resume_data()


.. parsed-literal::
	

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

.. raw:: html

	<a name="version"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:add_torrent_params%3A%3A%5Bversion%5D&labels=documentation&body=Documentation+under+heading+%22add_torrent_params%3A%3A%5Bversion%5D%22+could+be+improved">report issue</a>]</span>


version
	filled in by the constructor and should be left untouched. It is used
	for forward binary compatibility.
	


.. raw:: html

	<a name="ti"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:add_torrent_params%3A%3A%5Bti%5D&labels=documentation&body=Documentation+under+heading+%22add_torrent_params%3A%3A%5Bti%5D%22+could+be+improved">report issue</a>]</span>


ti
	`torrent_info`__ object with the torrent to add. Unless the
	info_hash is set, this is required to be initialized.
	

__ reference-Torrent_Info.html#torrent_info

.. raw:: html

	<a name="trackers"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:add_torrent_params%3A%3A%5Btrackers%5D&labels=documentation&body=Documentation+under+heading+%22add_torrent_params%3A%3A%5Btrackers%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="tracker_tiers"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:add_torrent_params%3A%3A%5Btracker_tiers%5D&labels=documentation&body=Documentation+under+heading+%22add_torrent_params%3A%3A%5Btracker_tiers%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="dht_nodes"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:add_torrent_params%3A%3A%5Bdht_nodes%5D&labels=documentation&body=Documentation+under+heading+%22add_torrent_params%3A%3A%5Bdht_nodes%5D%22+could+be+improved">report issue</a>]</span>


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.
	

__ reference-Session.html#session

.. raw:: html

	<a name="name"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:add_torrent_params%3A%3A%5Bname%5D&labels=documentation&body=Documentation+under+heading+%22add_torrent_params%3A%3A%5Bname%5D%22+could+be+improved">report issue</a>]</span>


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.
	

__ reference-Torrent_Info.html#torrent_info

.. raw:: html

	<a name="save_path"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:add_torrent_params%3A%3A%5Bsave_path%5D&labels=documentation&body=Documentation+under+heading+%22add_torrent_params%3A%3A%5Bsave_path%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="storage_mode"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:add_torrent_params%3A%3A%5Bstorage_mode%5D&labels=documentation&body=Documentation+under+heading+%22add_torrent_params%3A%3A%5Bstorage_mode%5D%22+could+be+improved">report issue</a>]</span>


storage_mode
	One of the values from `storage_mode_t`__. For more information, see
	`storage allocation`__.
	

__ reference-Storage.html#storage_mode_t
__ manual-ref.html#storage-allocation

.. raw:: html

	<a name="userdata"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:add_torrent_params%3A%3A%5Buserdata%5D&labels=documentation&body=Documentation+under+heading+%22add_torrent_params%3A%3A%5Buserdata%5D%22+could+be+improved">report issue</a>]</span>


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

__ reference-Torrent_Handle.html#add_extension()
__ reference-Torrent_Handle.html#userdata()

.. raw:: html

	<a name="file_priorities"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:add_torrent_params%3A%3A%5Bfile_priorities%5D&labels=documentation&body=Documentation+under+heading+%22add_torrent_params%3A%3A%5Bfile_priorities%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="trackerid"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:add_torrent_params%3A%3A%5Btrackerid%5D&labels=documentation&body=Documentation+under+heading+%22add_torrent_params%3A%3A%5Btrackerid%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="flags"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:add_torrent_params%3A%3A%5Bflags%5D&labels=documentation&body=Documentation+under+heading+%22add_torrent_params%3A%3A%5Bflags%5D%22+could+be+improved">report issue</a>]</span>


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.
	

__ reference-Core.html#torrent_flags_t

.. raw:: html

	<a name="info_hashes"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:add_torrent_params%3A%3A%5Binfo_hashes%5D&labels=documentation&body=Documentation+under+heading+%22add_torrent_params%3A%3A%5Binfo_hashes%5D%22+could+be+improved">report issue</a>]</span>


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.
	

__ reference-Core.html#parse_magnet_uri()
__ reference-Add_Torrent.html#add_torrent_params

.. raw:: html

	<a name="max_uploads"></a>
	<a name="max_connections"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:add_torrent_params%3A%3A%5Bmax_uploads+max_connections%5D&labels=documentation&body=Documentation+under+heading+%22add_torrent_params%3A%3A%5Bmax_uploads+max_connections%5D%22+could+be+improved">report issue</a>]</span>


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`__.
	

__ reference-Torrent_Handle.html#torrent_handle
__ reference-Torrent_Handle.html#torrent_handle
__ manual-ref.html#peer-classes

.. raw:: html

	<a name="upload_limit"></a>
	<a name="download_limit"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:add_torrent_params%3A%3A%5Bupload_limit+download_limit%5D&labels=documentation&body=Documentation+under+heading+%22add_torrent_params%3A%3A%5Bupload_limit+download_limit%5D%22+could+be+improved">report issue</a>]</span>


upload_limit download_limit
	the upload and download rate limits for this torrent, specified in
	bytes per second. -1 means unlimited.
	


.. raw:: html

	<a name="total_uploaded"></a>
	<a name="total_downloaded"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:add_torrent_params%3A%3A%5Btotal_uploaded+total_downloaded%5D&labels=documentation&body=Documentation+under+heading+%22add_torrent_params%3A%3A%5Btotal_uploaded+total_downloaded%5D%22+could+be+improved">report issue</a>]</span>


total_uploaded total_downloaded
	the total number of bytes uploaded and downloaded by this torrent so
	far.
	


.. raw:: html

	<a name="active_time"></a>
	<a name="finished_time"></a>
	<a name="seeding_time"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:add_torrent_params%3A%3A%5Bactive_time+finished_time+seeding_time%5D&labels=documentation&body=Documentation+under+heading+%22add_torrent_params%3A%3A%5Bactive_time+finished_time+seeding_time%5D%22+could+be+improved">report issue</a>]</span>


active_time finished_time seeding_time
	the number of seconds this torrent has spent in started, finished and
	seeding state so far, respectively.
	


.. raw:: html

	<a name="added_time"></a>
	<a name="completed_time"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:add_torrent_params%3A%3A%5Badded_time+completed_time%5D&labels=documentation&body=Documentation+under+heading+%22add_torrent_params%3A%3A%5Badded_time+completed_time%5D%22+could+be+improved">report issue</a>]</span>


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.
	

__ reference-Session.html#add_torrent()

.. raw:: html

	<a name="last_seen_complete"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:add_torrent_params%3A%3A%5Blast_seen_complete%5D&labels=documentation&body=Documentation+under+heading+%22add_torrent_params%3A%3A%5Blast_seen_complete%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="num_complete"></a>
	<a name="num_incomplete"></a>
	<a name="num_downloaded"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:add_torrent_params%3A%3A%5Bnum_complete+num_incomplete+num_downloaded%5D&labels=documentation&body=Documentation+under+heading+%22add_torrent_params%3A%3A%5Bnum_complete+num_incomplete+num_downloaded%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="http_seeds"></a>
	<a name="url_seeds"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:add_torrent_params%3A%3A%5Bhttp_seeds+url_seeds%5D&labels=documentation&body=Documentation+under+heading+%22add_torrent_params%3A%3A%5Bhttp_seeds+url_seeds%5D%22+could+be+improved">report issue</a>]</span>


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`_.
	


.. raw:: html

	<a name="peers"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:add_torrent_params%3A%3A%5Bpeers%5D&labels=documentation&body=Documentation+under+heading+%22add_torrent_params%3A%3A%5Bpeers%5D%22+could+be+improved">report issue</a>]</span>


peers
	peers to add to the torrent, to be tried to be connected to as
	bittorrent peers.
	


.. raw:: html

	<a name="banned_peers"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:add_torrent_params%3A%3A%5Bbanned_peers%5D&labels=documentation&body=Documentation+under+heading+%22add_torrent_params%3A%3A%5Bbanned_peers%5D%22+could+be+improved">report issue</a>]</span>


banned_peers
	peers banned from this torrent. The will not be connected to
	


.. raw:: html

	<a name="unfinished_pieces"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:add_torrent_params%3A%3A%5Bunfinished_pieces%5D&labels=documentation&body=Documentation+under+heading+%22add_torrent_params%3A%3A%5Bunfinished_pieces%5D%22+could+be+improved">report issue</a>]</span>


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.
	

__ reference-Utility.html#bitfield

.. raw:: html

	<a name="have_pieces"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:add_torrent_params%3A%3A%5Bhave_pieces%5D&labels=documentation&body=Documentation+under+heading+%22add_torrent_params%3A%3A%5Bhave_pieces%5D%22+could+be+improved">report issue</a>]</span>


have_pieces
	this is a `bitfield`__ indicating which pieces we already have of this
	torrent.
	

__ reference-Utility.html#bitfield

.. raw:: html

	<a name="verified_pieces"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:add_torrent_params%3A%3A%5Bverified_pieces%5D&labels=documentation&body=Documentation+under+heading+%22add_torrent_params%3A%3A%5Bverified_pieces%5D%22+could+be+improved">report issue</a>]</span>


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.
	

__ reference-Utility.html#bitfield

.. raw:: html

	<a name="piece_priorities"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:add_torrent_params%3A%3A%5Bpiece_priorities%5D&labels=documentation&body=Documentation+under+heading+%22add_torrent_params%3A%3A%5Bpiece_priorities%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="merkle_trees"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:add_torrent_params%3A%3A%5Bmerkle_trees%5D&labels=documentation&body=Documentation+under+heading+%22add_torrent_params%3A%3A%5Bmerkle_trees%5D%22+could+be+improved">report issue</a>]</span>


merkle_trees
	v2 hashes, if known
	


.. raw:: html

	<a name="merkle_tree_mask"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:add_torrent_params%3A%3A%5Bmerkle_tree_mask%5D&labels=documentation&body=Documentation+under+heading+%22add_torrent_params%3A%3A%5Bmerkle_tree_mask%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="verified_leaf_hashes"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:add_torrent_params%3A%3A%5Bverified_leaf_hashes%5D&labels=documentation&body=Documentation+under+heading+%22add_torrent_params%3A%3A%5Bverified_leaf_hashes%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="renamed_files"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:add_torrent_params%3A%3A%5Brenamed_files%5D&labels=documentation&body=Documentation+under+heading+%22add_torrent_params%3A%3A%5Brenamed_files%5D%22+could+be+improved">report issue</a>]</span>


renamed_files
	this is a map of file indices in the torrent and new filenames to be
	applied before the torrent is added.
	


.. raw:: html

	<a name="last_download"></a>
	<a name="last_upload"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:add_torrent_params%3A%3A%5Blast_download+last_upload%5D&labels=documentation&body=Documentation+under+heading+%22add_torrent_params%3A%3A%5Blast_download+last_upload%5D%22+could+be+improved">report issue</a>]</span>


last_download last_upload
	the posix time of the last time payload was received or sent for this
	torrent, respectively.
	


.. raw:: html

	<a name="client_data_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+client_data_t&labels=documentation&body=Documentation+under+heading+%22class+client_data_t%22+could+be+improved">report issue</a>]</span>



client_data_t
-------------

Declared in "`libtorrent/client_data.hpp`__"


__ include/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.




.. parsed-literal::
	

	struct client_data_t
	{
	   **client_data_t** () = default;
	   explicit **client_data_t** (T\* v);
	   client_data_t& **operator=** (T\* v);
	   T\* **get** () const;
	   explicit operator **T** () const;
	   client_data_t& **operator=** (void\*) = delete;
	   client_data_t& **operator=** (void const\*) = delete;
	   operator void **const*** () const = delete;
	   operator **void*** () const = delete;
	
	   template <typename T, typename **U**  = typename std::enable_if<std::is_pointer<T>::value>::type>
	};

.. raw:: html

	<a name="client_data_t()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:client_data_t%3A%3A%5Bclient_data_t%28%29%5D&labels=documentation&body=Documentation+under+heading+%22client_data_t%3A%3A%5Bclient_data_t%28%29%5D%22+could+be+improved">report issue</a>]</span>



client_data_t()
...............

.. parsed-literal::
	
	**client_data_t** () = default;
	

construct a nullptr client data



.. raw:: html

	<a name="operator=()"></a>
	<a name="const*()"></a>
	<a name="void*()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:client_data_t%3A%3A%5Boperator%3D%28%29+const%2A%28%29+void%2A%28%29%5D&labels=documentation&body=Documentation+under+heading+%22client_data_t%3A%3A%5Boperator%3D%28%29+const%2A%28%29+void%2A%28%29%5D%22+could+be+improved">report issue</a>]</span>



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

.. parsed-literal::
	
	client_data_t& **operator=** (void\*) = delete;
	client_data_t& **operator=** (void const\*) = delete;
	operator void **const*** () const = delete;
	operator **void*** () const = delete;
	

we don't allow type-unsafe operations





.. _`BEP 19`: https://www.bittorrent.org/beps/bep_0019.html
.. _extensions: manual-ref.html#extensions
.. _`BEP 3`: https://www.bittorrent.org/beps/bep_0003.html
.. _`BEP 38`: https://www.bittorrent.org/beps/bep_0038.html
.. _`BEP 42`: https://www.bittorrent.org/beps/bep_0042.html
.. _`BEP 17`: https://www.bittorrent.org/beps/bep_0017.html
.. _`rate based choking`: manual-ref.html#rate-based-choking
.. raw:: html

	<a name="web_seed_entry"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+web_seed_entry&labels=documentation&body=Documentation+under+heading+%22class+web_seed_entry%22+could+be+improved">report issue</a>]</span>



web_seed_entry
--------------

Declared in "`libtorrent/torrent_info.hpp`__"


__ include/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`_.


__ reference-Torrent_Info.html#web_seed_entry


.. parsed-literal::
	

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

.. raw:: html

	<a name="operator==()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:web_seed_entry%3A%3A%5Boperator%3D%3D%28%29%5D&labels=documentation&body=Documentation+under+heading+%22web_seed_entry%3A%3A%5Boperator%3D%3D%28%29%5D%22+could+be+improved">report issue</a>]</span>



operator==()
............

.. parsed-literal::
	
	bool **operator==** (web\_seed\_entry const& e) const;
	

URL and type comparison



.. raw:: html

	<a name="operator<()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:web_seed_entry%3A%3A%5Boperator%3C%28%29%5D&labels=documentation&body=Documentation+under+heading+%22web_seed_entry%3A%3A%5Boperator%3C%28%29%5D%22+could+be+improved">report issue</a>]</span>



operator<()
...........

.. parsed-literal::
	
	bool **operator<** (web\_seed\_entry const& e) const;
	

URL and type less-than comparison



.. raw:: html

	<a name="type_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+type_t&labels=documentation&body=Documentation+under+heading+%22enum+type_t%22+could+be+improved">report issue</a>]</span>



enum type_t
...........

Declared in "`libtorrent/torrent_info.hpp`__"


__ include/libtorrent/torrent_info.hpp

+-----------+-------+-------------+
| name      | value | description |
+===========+=======+=============+
| url_seed  | 0     |             |
+-----------+-------+-------------+
| http_seed | 1     |             |
+-----------+-------+-------------+



.. raw:: html

	<a name="url"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:web_seed_entry%3A%3A%5Burl%5D&labels=documentation&body=Documentation+under+heading+%22web_seed_entry%3A%3A%5Burl%5D%22+could+be+improved">report issue</a>]</span>


url
	The URL of the web seed
	


.. raw:: html

	<a name="auth"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:web_seed_entry%3A%3A%5Bauth%5D&labels=documentation&body=Documentation+under+heading+%22web_seed_entry%3A%3A%5Bauth%5D%22+could+be+improved">report issue</a>]</span>


auth
	Optional authentication. If this is set, it's passed
	in as HTTP basic auth to the web seed. The format is:
	username:password.
	


.. raw:: html

	<a name="extra_headers"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:web_seed_entry%3A%3A%5Bextra_headers%5D&labels=documentation&body=Documentation+under+heading+%22web_seed_entry%3A%3A%5Bextra_headers%5D%22+could+be+improved">report issue</a>]</span>


extra_headers
	Any extra HTTP headers that need to be passed to the web seed
	


.. raw:: html

	<a name="type"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:web_seed_entry%3A%3A%5Btype%5D&labels=documentation&body=Documentation+under+heading+%22web_seed_entry%3A%3A%5Btype%5D%22+could+be+improved">report issue</a>]</span>


type
	The type of web seed (see `type_t`__)
	

__ reference-Torrent_Info.html#type_t

.. raw:: html

	<a name="load_torrent_limits"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+load_torrent_limits&labels=documentation&body=Documentation+under+heading+%22class+load_torrent_limits%22+could+be+improved">report issue</a>]</span>



load_torrent_limits
-------------------

Declared in "`libtorrent/torrent_info.hpp`__"


__ include/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.




.. parsed-literal::
	

	struct load_torrent_limits
	{
	   int **max_buffer_size**  = 10000000;
	   int **max_pieces**  = 0x200000;
	   int **max_decode_depth**  = 100;
	   int **max_decode_tokens**  = 3000000;
	};

.. raw:: html

	<a name="max_buffer_size"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:load_torrent_limits%3A%3A%5Bmax_buffer_size%5D&labels=documentation&body=Documentation+under+heading+%22load_torrent_limits%3A%3A%5Bmax_buffer_size%5D%22+could+be+improved">report issue</a>]</span>


max_buffer_size
	the max size of a .torrent file to load into RAM
	


.. raw:: html

	<a name="max_pieces"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:load_torrent_limits%3A%3A%5Bmax_pieces%5D&labels=documentation&body=Documentation+under+heading+%22load_torrent_limits%3A%3A%5Bmax_pieces%5D%22+could+be+improved">report issue</a>]</span>


max_pieces
	the max number of pieces allowed in the torrent
	


.. raw:: html

	<a name="max_decode_depth"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:load_torrent_limits%3A%3A%5Bmax_decode_depth%5D&labels=documentation&body=Documentation+under+heading+%22load_torrent_limits%3A%3A%5Bmax_decode_depth%5D%22+could+be+improved">report issue</a>]</span>


max_decode_depth
	the max recursion depth in the bdecoded structure
	


.. raw:: html

	<a name="max_decode_tokens"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:load_torrent_limits%3A%3A%5Bmax_decode_tokens%5D&labels=documentation&body=Documentation+under+heading+%22load_torrent_limits%3A%3A%5Bmax_decode_tokens%5D%22+could+be+improved">report issue</a>]</span>


max_decode_tokens
	the max number of bdecode tokens
	


.. raw:: html

	<a name="torrent_info"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+torrent_info&labels=documentation&body=Documentation+under+heading+%22class+torrent_info%22+could+be+improved">report issue</a>]</span>



torrent_info
------------

Declared in "`libtorrent/torrent_info.hpp`__"


__ include/libtorrent/torrent_info.hpp

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


__ reference-Torrent_Info.html#torrent_info


.. parsed-literal::
	

	class torrent_info
	{
	   explicit **torrent_info** (span<char const> buffer, from\_span\_t);
	   **torrent_info** (bdecode\_node const& torrent\_file, error\_code& ec);
	   **torrent_info** (torrent\_info const& t);
	   explicit **torrent_info** (std\:\:string const& filename);
	   **torrent_info** (char const\* buffer, int size);
	   **torrent_info** (char const\* buffer, int size, error\_code& ec);
	   **torrent_info** (std\:\:string const& filename, error\_code& ec);
	   explicit **torrent_info** (info\_hash\_t const& info\_hash);
	   **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** (span<char const> buffer, load\_torrent\_limits const& cfg, from\_span\_t);
	   **torrent_info** (std\:\:string const& filename, load\_torrent\_limits const& cfg);
	   explicit **torrent_info** (bdecode\_node const& torrent\_file);
	   **~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);
	   void **remap_files** (file\_storage const& f);
	   void **add_tracker** (std\:\:string const& url, int tier = 0);
	   std::vector<announce_entry> const& **trackers** () const;
	   void **clear_trackers** ();
	   void **add_tracker** (std\:\:string const& url, int tier
	      , announce\_entry\:\:tracker\_source source);
	   std::vector<sha1_hash> **similar_torrents** () const;
	   std::vector<std::string> **collections** () 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());
	   std::vector<web_seed_entry> const& **web_seeds** () const;
	   void **set_web_seeds** (std\:\:vector<web\_seed\_entry> seeds);
	   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 **v1** () const;
	   bool **v2** () 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** ();
	};

.. raw:: html

	<a name="torrent_info()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_info%3A%3A%5Btorrent_info%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_info%3A%3A%5Btorrent_info%28%29%5D%22+could+be+improved">report issue</a>]</span>



torrent_info()
..............

.. parsed-literal::
	
	explicit **torrent_info** (span<char const> buffer, from\_span\_t);
	**torrent_info** (bdecode\_node const& torrent\_file, error\_code& ec);
	**torrent_info** (torrent\_info const& t);
	explicit **torrent_info** (std\:\:string const& filename);
	**torrent_info** (char const\* buffer, int size);
	**torrent_info** (char const\* buffer, int size, error\_code& ec);
	**torrent_info** (std\:\:string const& filename, error\_code& ec);
	explicit **torrent_info** (info\_hash\_t const& info\_hash);
	**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** (span<char const> buffer, load\_torrent\_limits const& cfg, from\_span\_t);
	**torrent_info** (std\:\:string const& filename, load\_torrent\_limits const& cfg);
	explicit **torrent_info** (bdecode\_node const& torrent\_file);
	

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


__ reference-Bdecoding.html#bdecode_node
__ reference-Torrent_Info.html#torrent_info
__ reference-Bdecoding.html#bdecode_node
__ reference-Bdecoding.html#bdecode_node
__ reference-Bdecoding.html#bdecode()
__ reference-Torrent_Info.html#torrent_info
__ reference-Torrent_Info.html#torrent_info

.. raw:: html

	<a name="~torrent_info()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_info%3A%3A%5B~torrent_info%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_info%3A%3A%5B~torrent_info%28%29%5D%22+could+be+improved">report issue</a>]</span>



~torrent_info()
...............

.. parsed-literal::
	
	**~torrent_info** ();
	

frees all storage associated with this `torrent_info`__ object


__ reference-Torrent_Info.html#torrent_info

.. raw:: html

	<a name="orig_files()"></a>
	<a name="files()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_info%3A%3A%5Borig_files%28%29+files%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_info%3A%3A%5Borig_files%28%29+files%28%29%5D%22+could+be+improved">report issue</a>]</span>



orig_files() files()
....................

.. parsed-literal::
	
	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.


__ reference-Storage.html#file_storage
__ reference-Torrent_Info.html#torrent_info
__ reference-Storage.html#file_storage
__ reference-Storage.html#file_storage

.. raw:: html

	<a name="rename_file()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_info%3A%3A%5Brename_file%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_info%3A%3A%5Brename_file%28%29%5D%22+could+be+improved">report issue</a>]</span>



rename_file()
.............

.. parsed-literal::
	
	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.


__ reference-Torrent_Info.html#files()
__ reference-Torrent_Info.html#orig_files()
__ reference-Torrent_Handle.html#move_storage()

.. raw:: html

	<a name="remap_files()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_info%3A%3A%5Bremap_files%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_info%3A%3A%5Bremap_files%28%29%5D%22+could+be+improved">report issue</a>]</span>



remap_files()
.............

.. parsed-literal::
	
	void **remap_files** (file\_storage const& f);
	

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


__ reference-Custom_Storage.html#disk_interface

.. raw:: html

	<a name="clear_trackers()"></a>
	<a name="trackers()"></a>
	<a name="add_tracker()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_info%3A%3A%5Bclear_trackers%28%29+trackers%28%29+add_tracker%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_info%3A%3A%5Bclear_trackers%28%29+trackers%28%29+add_tracker%28%29%5D%22+could+be+improved">report issue</a>]</span>



clear_trackers() trackers() add_tracker()
.........................................

.. parsed-literal::
	
	void **add_tracker** (std\:\:string const& url, int tier = 0);
	std::vector<announce_entry> const& **trackers** () const;
	void **clear_trackers** ();
	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.


__ reference-Trackers.html#announce_entry
__ reference-Bencoding.html#entry
__ reference-Trackers.html#announce_entry

.. raw:: html

	<a name="similar_torrents()"></a>
	<a name="collections()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_info%3A%3A%5Bsimilar_torrents%28%29+collections%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_info%3A%3A%5Bsimilar_torrents%28%29+collections%28%29%5D%22+could+be+improved">report issue</a>]</span>



similar_torrents() collections()
................................

.. parsed-literal::
	
	std::vector<sha1_hash> **similar_torrents** () const;
	std::vector<std::string> **collections** () 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.



.. raw:: html

	<a name="add_http_seed()"></a>
	<a name="set_web_seeds()"></a>
	<a name="add_url_seed()"></a>
	<a name="web_seeds()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_info%3A%3A%5Badd_http_seed%28%29+set_web_seeds%28%29+add_url_seed%28%29+web_seeds%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_info%3A%3A%5Badd_http_seed%28%29+set_web_seeds%28%29+add_url_seed%28%29+web_seeds%28%29%5D%22+could+be+improved">report issue</a>]</span>



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

.. parsed-literal::
	
	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());
	std::vector<web_seed_entry> const& **web_seeds** () const;
	void **set_web_seeds** (std\:\:vector<web\_seed\_entry> seeds);
	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.


__ reference-Bencoding.html#entry
__ manual-ref.html#http-seeding

.. raw:: html

	<a name="total_size()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_info%3A%3A%5Btotal_size%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_info%3A%3A%5Btotal_size%28%29%5D%22+could+be+improved">report issue</a>]</span>



total_size()
............

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="num_pieces()"></a>
	<a name="piece_length()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_info%3A%3A%5Bnum_pieces%28%29+piece_length%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_info%3A%3A%5Bnum_pieces%28%29+piece_length%28%29%5D%22+could+be+improved">report issue</a>]</span>



num_pieces() piece_length()
...........................

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="last_piece()"></a>
	<a name="end_piece()"></a>
	<a name="piece_range()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_info%3A%3A%5Blast_piece%28%29+end_piece%28%29+piece_range%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_info%3A%3A%5Blast_piece%28%29+end_piece%28%29+piece_range%28%29%5D%22+could+be+improved">report issue</a>]</span>



last_piece() end_piece() piece_range()
......................................

.. parsed-literal::
	
	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`__.


__ reference-Storage.html#file_storage

.. raw:: html

	<a name="info_hash()"></a>
	<a name="info_hashes()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_info%3A%3A%5Binfo_hash%28%29+info_hashes%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_info%3A%3A%5Binfo_hash%28%29+info_hashes%28%29%5D%22+could+be+improved">report issue</a>]</span>



info_hash() info_hashes()
.........................

.. parsed-literal::
	
	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



.. raw:: html

	<a name="v2()"></a>
	<a name="v1()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_info%3A%3A%5Bv2%28%29+v1%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_info%3A%3A%5Bv2%28%29+v1%28%29%5D%22+could+be+improved">report issue</a>]</span>



v2() v1()
.........

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="num_files()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_info%3A%3A%5Bnum_files%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_info%3A%3A%5Bnum_files%28%29%5D%22+could+be+improved">report issue</a>]</span>



num_files()
...........

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="map_block()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_info%3A%3A%5Bmap_block%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_info%3A%3A%5Bmap_block%28%29%5D%22+could+be+improved">report issue</a>]</span>



map_block()
...........

.. parsed-literal::
	
	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`__.


__ reference-Storage.html#file_slice

.. raw:: html

	<a name="map_file()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_info%3A%3A%5Bmap_file%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_info%3A%3A%5Bmap_file%28%29%5D%22+could+be+improved">report issue</a>]</span>



map_file()
..........

.. parsed-literal::
	
	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()``.


__ reference-Core.html#peer_request

.. raw:: html

	<a name="ssl_cert()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_info%3A%3A%5Bssl_cert%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_info%3A%3A%5Bssl_cert%28%29%5D%22+could+be+improved">report issue</a>]</span>



ssl_cert()
..........

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="is_valid()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_info%3A%3A%5Bis_valid%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_info%3A%3A%5Bis_valid%28%29%5D%22+could+be+improved">report issue</a>]</span>



is_valid()
..........

.. parsed-literal::
	
	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.


__ reference-Torrent_Info.html#torrent_info

.. raw:: html

	<a name="priv()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_info%3A%3A%5Bpriv%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_info%3A%3A%5Bpriv%28%29%5D%22+could+be+improved">report issue</a>]</span>



priv()
......

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="is_i2p()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_info%3A%3A%5Bis_i2p%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_info%3A%3A%5Bis_i2p%28%29%5D%22+could+be+improved">report issue</a>]</span>



is_i2p()
........

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="piece_size()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_info%3A%3A%5Bpiece_size%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_info%3A%3A%5Bpiece_size%28%29%5D%22+could+be+improved">report issue</a>]</span>



piece_size()
............

.. parsed-literal::
	
	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.


__ reference-Torrent_Info.html#piece_length()

.. raw:: html

	<a name="hash_for_piece_ptr()"></a>
	<a name="hash_for_piece()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_info%3A%3A%5Bhash_for_piece_ptr%28%29+hash_for_piece%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_info%3A%3A%5Bhash_for_piece_ptr%28%29+hash_for_piece%28%29%5D%22+could+be+improved">report issue</a>]</span>



hash_for_piece_ptr() hash_for_piece()
.....................................

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="name()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_info%3A%3A%5Bname%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_info%3A%3A%5Bname%28%29%5D%22+could+be+improved">report issue</a>]</span>



name()
......

.. parsed-literal::
	
	const std::string& **name** () const;
	

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



.. raw:: html

	<a name="creation_date()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_info%3A%3A%5Bcreation_date%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_info%3A%3A%5Bcreation_date%28%29%5D%22+could+be+improved">report issue</a>]</span>



creation_date()
...............

.. parsed-literal::
	
	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



.. raw:: html

	<a name="creator()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_info%3A%3A%5Bcreator%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_info%3A%3A%5Bcreator%28%29%5D%22+could+be+improved">report issue</a>]</span>



creator()
.........

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="comment()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_info%3A%3A%5Bcomment%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_info%3A%3A%5Bcomment%28%29%5D%22+could+be+improved">report issue</a>]</span>



comment()
.........

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="nodes()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_info%3A%3A%5Bnodes%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_info%3A%3A%5Bnodes%28%29%5D%22+could+be+improved">report issue</a>]</span>



nodes()
.......

.. parsed-literal::
	
	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).



.. raw:: html

	<a name="add_node()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_info%3A%3A%5Badd_node%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_info%3A%3A%5Badd_node%28%29%5D%22+could+be+improved">report issue</a>]</span>



add_node()
..........

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="parse_info_section()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_info%3A%3A%5Bparse_info_section%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_info%3A%3A%5Bparse_info_section%28%29%5D%22+could+be+improved">report issue</a>]</span>



parse_info_section()
....................

.. parsed-literal::
	
	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()`__.


__ reference-Torrent_Info.html#torrent_info
__ reference-Bdecoding.html#bdecode_node
__ reference-Settings.html#max_piece_count
__ reference-Resume_Data.html#read_resume_data()

.. raw:: html

	<a name="info()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_info%3A%3A%5Binfo%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_info%3A%3A%5Binfo%28%29%5D%22+could+be+improved">report issue</a>]</span>



info()
......

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="info_section()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_info%3A%3A%5Binfo_section%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_info%3A%3A%5Binfo_section%28%29%5D%22+could+be+improved">report issue</a>]</span>



info_section()
..............

.. parsed-literal::
	
	span<char const> **info_section** () const;
	

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


__ reference-Torrent_Info.html#torrent_info

.. raw:: html

	<a name="piece_layer()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_info%3A%3A%5Bpiece_layer%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_info%3A%3A%5Bpiece_layer%28%29%5D%22+could+be+improved">report issue</a>]</span>



piece_layer()
.............

.. parsed-literal::
	
	span<char const> **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.



.. raw:: html

	<a name="free_piece_layers()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_info%3A%3A%5Bfree_piece_layers%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_info%3A%3A%5Bfree_piece_layers%28%29%5D%22+could+be+improved">report issue</a>]</span>



free_piece_layers()
...................

.. parsed-literal::
	
	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.


__ reference-Torrent_Info.html#torrent_info
__ reference-Session.html#session



.. _`BEP 19`: https://www.bittorrent.org/beps/bep_0019.html
.. _extensions: manual-ref.html#extensions
.. _`BEP 3`: https://www.bittorrent.org/beps/bep_0003.html
.. _`BEP 38`: https://www.bittorrent.org/beps/bep_0038.html
.. _`BEP 42`: https://www.bittorrent.org/beps/bep_0042.html
.. _`BEP 17`: https://www.bittorrent.org/beps/bep_0017.html
.. _`rate based choking`: manual-ref.html#rate-based-choking
.. raw:: html

	<a name="storage_error"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+storage_error&labels=documentation&body=Documentation+under+heading+%22class+storage_error%22+could+be+improved">report issue</a>]</span>



storage_error
-------------

Declared in "`libtorrent/error_code.hpp`__"


__ include/libtorrent/error_code.hpp

used by storage to return errors
also includes which underlying file the
error happened on




.. parsed-literal::
	

	struct storage_error
	{
	   explicit operator **bool** () const;
	   file_index_t **file** () const;
	   void **file** (file\_index\_t f);
	
	   error_code ec;
	   operation_t operation;
	};

.. raw:: html

	<a name="bool()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:storage_error%3A%3A%5Bbool%28%29%5D&labels=documentation&body=Documentation+under+heading+%22storage_error%3A%3A%5Bbool%28%29%5D%22+could+be+improved">report issue</a>]</span>



bool()
......

.. parsed-literal::
	
	explicit operator **bool** () const;
	

explicitly converts to true if this object represents an error, and
false if it does not.



.. raw:: html

	<a name="file()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:storage_error%3A%3A%5Bfile%28%29%5D&labels=documentation&body=Documentation+under+heading+%22storage_error%3A%3A%5Bfile%28%29%5D%22+could+be+improved">report issue</a>]</span>



file()
......

.. parsed-literal::
	
	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`__.


__ reference-Torrent_Status.html#torrent_status

.. raw:: html

	<a name="ec"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:storage_error%3A%3A%5Bec%5D&labels=documentation&body=Documentation+under+heading+%22storage_error%3A%3A%5Bec%5D%22+could+be+improved">report issue</a>]</span>


ec
	the error that occurred
	


.. raw:: html

	<a name="operation"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:storage_error%3A%3A%5Boperation%5D&labels=documentation&body=Documentation+under+heading+%22storage_error%3A%3A%5Boperation%5D%22+could+be+improved">report issue</a>]</span>


operation
	A code from `operation_t`__ enum, indicating what
	kind of operation failed.
	

__ reference-Alerts.html#operation_t

.. raw:: html

	<a name="bdecode_category()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:bdecode_category%28%29&labels=documentation&body=Documentation+under+heading+%22bdecode_category%28%29%22+could+be+improved">report issue</a>]</span>



bdecode_category()
------------------

Declared in "`libtorrent/bdecode.hpp`__"


__ include/libtorrent/bdecode.hpp

.. parsed-literal::
	
	boost::system::error_category& **bdecode_category** ();
	




.. raw:: html

	<a name="pcp_category()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:pcp_category%28%29&labels=documentation&body=Documentation+under+heading+%22pcp_category%28%29%22+could+be+improved">report issue</a>]</span>



pcp_category()
--------------

Declared in "`libtorrent/natpmp.hpp`__"


__ include/libtorrent/natpmp.hpp

.. parsed-literal::
	
	boost::system::error_category& **pcp_category** ();
	




.. raw:: html

	<a name="socks_category()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:socks_category%28%29&labels=documentation&body=Documentation+under+heading+%22socks_category%28%29%22+could+be+improved">report issue</a>]</span>



socks_category()
----------------

Declared in "`libtorrent/socks5_stream.hpp`__"


__ include/libtorrent/socks5_stream.hpp

.. parsed-literal::
	
	boost::system::error_category& **socks_category** ();
	

returns the error_category for SOCKS5 errors



.. raw:: html

	<a name="i2p_category()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:i2p_category%28%29&labels=documentation&body=Documentation+under+heading+%22i2p_category%28%29%22+could+be+improved">report issue</a>]</span>



i2p_category()
--------------

Declared in "`libtorrent/i2p_stream.hpp`__"


__ include/libtorrent/i2p_stream.hpp

.. parsed-literal::
	
	boost::system::error_category& **i2p_category** ();
	

returns the error category for I2P errors



.. raw:: html

	<a name="upnp_category()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:upnp_category%28%29&labels=documentation&body=Documentation+under+heading+%22upnp_category%28%29%22+could+be+improved">report issue</a>]</span>



upnp_category()
---------------

Declared in "`libtorrent/upnp.hpp`__"


__ include/libtorrent/upnp.hpp

.. parsed-literal::
	
	boost::system::error_category& **upnp_category** ();
	

the boost.system error category for UPnP errors



.. raw:: html

	<a name="gzip_category()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:gzip_category%28%29&labels=documentation&body=Documentation+under+heading+%22gzip_category%28%29%22+could+be+improved">report issue</a>]</span>



gzip_category()
---------------

Declared in "`libtorrent/gzip.hpp`__"


__ include/libtorrent/gzip.hpp

.. parsed-literal::
	
	boost::system::error_category& **gzip_category** ();
	

get the ``error_category`` for zip errors



.. raw:: html

	<a name="libtorrent_category()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:libtorrent_category%28%29&labels=documentation&body=Documentation+under+heading+%22libtorrent_category%28%29%22+could+be+improved">report issue</a>]</span>



libtorrent_category()
---------------------

Declared in "`libtorrent/error_code.hpp`__"


__ include/libtorrent/error_code.hpp

.. parsed-literal::
	
	boost::system::error_category& **libtorrent_category** ();
	

return the instance of the libtorrent_error_category which
maps libtorrent error codes to human readable error messages.



.. raw:: html

	<a name="http_category()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:http_category%28%29&labels=documentation&body=Documentation+under+heading+%22http_category%28%29%22+could+be+improved">report issue</a>]</span>



http_category()
---------------

Declared in "`libtorrent/error_code.hpp`__"


__ include/libtorrent/error_code.hpp

.. parsed-literal::
	
	boost::system::error_category& **http_category** ();
	

returns the error_category for HTTP errors



.. raw:: html

	<a name="error_code_enum"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+error_code_enum&labels=documentation&body=Documentation+under+heading+%22enum+error_code_enum%22+could+be+improved">report issue</a>]</span>



enum error_code_enum
--------------------

Declared in "`libtorrent/bdecode.hpp`__"


__ include/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                                         |
|                |       |                                                                   |
+----------------+-------+-------------------------------------------------------------------+


__ reference-Alerts.html#int

.. raw:: html

	<a name="pcp_errors"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+pcp_errors&labels=documentation&body=Documentation+under+heading+%22enum+pcp_errors%22+could+be+improved">report issue</a>]</span>



enum pcp_errors
---------------

Declared in "`libtorrent/natpmp.hpp`__"


__ include/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    |             |
+-----------------------------+-------+-------------+



.. raw:: html

	<a name="socks_error_code"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+socks_error_code&labels=documentation&body=Documentation+under+heading+%22enum+socks_error_code%22+could+be+improved">report issue</a>]</span>



enum socks_error_code
---------------------

Declared in "`libtorrent/socks5_stream.hpp`__"


__ include/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    |             |
+------------------------------------+-------+-------------+



.. raw:: html

	<a name="i2p_error_code"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+i2p_error_code&labels=documentation&body=Documentation+under+heading+%22enum+i2p_error_code%22+could+be+improved">report issue</a>]</span>



enum i2p_error_code
-------------------

Declared in "`libtorrent/i2p_stream.hpp`__"


__ include/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     |             |
+-----------------+-------+-------------+



.. raw:: html

	<a name="error_code_enum"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+error_code_enum&labels=documentation&body=Documentation+under+heading+%22enum+error_code_enum%22+could+be+improved">report issue</a>]</span>



enum error_code_enum
--------------------

Declared in "`libtorrent/upnp.hpp`__"


__ include/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       |
|                                    |       |                                                       |
+------------------------------------+-------+-------------------------------------------------------+
| source_ip_cannot_be_wildcarded     | 715   | The source IP address cannot be wild-carded, but      |
|                                    |       | must be fully specified                               |
|                                    |       |                                                       |
+------------------------------------+-------+-------------------------------------------------------+
| external_port_cannot_be_wildcarded | 716   | The external port cannot be a wildcard, but must      |
|                                    |       | be specified                                          |
|                                    |       |                                                       |
+------------------------------------+-------+-------------------------------------------------------+
| port_mapping_conflict              | 718   | The port mapping `entry`__ specified conflicts with a |
|                                    |       | mapping assigned previously to another client         |
|                                    |       |                                                       |
+------------------------------------+-------+-------------------------------------------------------+
| internal_port_must_match_external  | 724   | Internal and external port value must be the same     |
|                                    |       |                                                       |
+------------------------------------+-------+-------------------------------------------------------+
| only_permanent_leases_supported    | 725   | The NAT implementation only supports permanent        |
|                                    |       | lease times on port mappings                          |
|                                    |       |                                                       |
+------------------------------------+-------+-------------------------------------------------------+
| remote_host_must_be_wildcard       | 726   | RemoteHost must be a wildcard and 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                                         |
|                                    |       |                                                       |
+------------------------------------+-------+-------------------------------------------------------+


__ reference-Bencoding.html#entry

.. raw:: html

	<a name="error_code_enum"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+error_code_enum&labels=documentation&body=Documentation+under+heading+%22enum+error_code_enum%22+could+be+improved">report issue</a>]</span>



enum error_code_enum
--------------------

Declared in "`libtorrent/gzip.hpp`__"


__ include/libtorrent/gzip.hpp

+-------------------------------------+-------+---------------------------------------------------------------------+
| name                                | value | description                                                         |
+=====================================+=======+=====================================================================+
| no_error                            | 0     | Not an error                                                        |
|                                     |       |                                                                     |
+-------------------------------------+-------+---------------------------------------------------------------------+
| invalid_gzip_header                 | 1     | the supplied gzip buffer has invalid header                         |
|                                     |       |                                                                     |
+-------------------------------------+-------+---------------------------------------------------------------------+
| inflated_data_too_large             | 2     | the gzip buffer would inflate to 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                                           |
|                                     |       |                                                                     |
+-------------------------------------+-------+---------------------------------------------------------------------+



.. raw:: html

	<a name="error_code_enum"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+error_code_enum&labels=documentation&body=Documentation+under+heading+%22enum+error_code_enum%22+could+be+improved">report issue</a>]</span>



enum error_code_enum
--------------------

Declared in "`libtorrent/error_code.hpp`__"


__ include/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                                      |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| torrent_is_no_dict                   | 3     | The .torrent file does not contain 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                             |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| torrent_invalid_length               | 9     | The length of a file, or of the 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         |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| invalid_swarm_metadata               | 14    | The metadata (.torrent file) that 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         |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| duplicate_torrent                    | 19    | There's already a torrent with 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                      |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| file_too_short                       | 23    | One of the files in the torrent was unexpectedly small. This              |
|                                      |       | might be caused by files being changed by an external process             |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| unsupported_url_protocol             | 24    | The 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_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                                               |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| port_blocked                         | 33    | The port is blocked by the port-filter, and prevented the                 |
|                                      |       | connection                                                                |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| expected_close_bracket_in_address    | 34    | The IPv6 address was expected to end with "]"                             |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| destructing_torrent                  | 35    | The torrent is being destructed, preventing the operation to              |
|                                      |       | succeed                                                                   |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| timed_out                            | 36    | The connection timed out                                                  |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| upload_upload_connection             | 37    | The peer is upload only, and we are upload only. There's no point         |
|                                      |       | in keeping the connection                                                 |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| uninteresting_upload_peer            | 38    | The peer is upload only, and we're 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           |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| invalid_have                         | 41    | The peer sent an invalid have 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                           |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| too_many_requests_when_choked        | 43    | The peer kept requesting pieces after it was choked, possible             |
|                                      |       | abuse attempt.                                                            |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| invalid_piece                        | 44    | The peer sent a piece message that 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               |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| invalid_piece_size                   | 48    | The peer sent a piece message with invalid size, either negative          |
|                                      |       | or greater than one block                                                 |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| timed_out_no_interest                | 49    | The peer has not been interesting 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              |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| timed_out_no_handshake               | 51    | The peer did not send a handshake within a reasonable amount of           |
|                                      |       | time, it might not be a bittorrent peer                                   |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| timed_out_no_request                 | 52    | The peer has been unchoked for too 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                            |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| invalid_hash_list                    | 58    | The peer sent an invalid hash-list message (this is part of the           |
|                                      |       | merkle-torrent extension)                                                 |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| invalid_hash_piece                   | 59    | The peer sent an invalid hash-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                 |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| unsupported_encryption_mode          | 73    | The peer does not support any of the encryption modes that the            |
|                                      |       | client supports                                                           |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| unsupported_encryption_mode_selected | 74    | The peer selected an encryption mode that the client did not              |
|                                      |       | advertise and does not support                                            |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| invalid_pad_size                     | 75    | The pad size used in the encryption handshake is of invalid size          |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| invalid_encrypt_handshake            | 76    | The encryption handshake is invalid                                       |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| no_incoming_encrypted                | 77    | The client is set to not support incoming encrypted connections           |
|                                      |       | and this is an encrypted connection                                       |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| no_incoming_regular                  | 78    | The client is set to not support 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                      |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| invalid_redirection                  | 85    | The web seed redirected to a path 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                 |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| optimistic_disconnect                | 97    | The peer was disconnected in order 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                         |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| too_frequent_pex                     | 108   | The peer sent an pex messages too often. This is a possible               |
|                                      |       | attempt of and attack                                                     |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| no_metadata                          | 109   | The 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_have                    | 110   | The 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_connection              | 111   | The peer tried to connect to an SSL torrent without connecting            |
|                                      |       | over SSL.                                                                 |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| invalid_ssl_cert                     | 112   | The peer tried to connect to a torrent with a certificate                 |
|                                      |       | for a different torrent.                                                  |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| not_an_ssl_torrent                   | 113   | the torrent is not an SSL torrent, and the operation requires             |
|                                      |       | an SSL torrent                                                            |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| banned_by_port_filter                | 114   | peer was banned because its listen 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`__    |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| mismatching_number_of_files          | 133   | The number of files in the resume data does not match the number          |
|                                      |       | of files in the torrent                                                   |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| mismatching_file_size                | 134   | One of the files on disk has a different size than in the fast            |
|                                      |       | resume file                                                               |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| mismatching_file_timestamp           | 135   | One of the files on disk has a 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     |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| missing_slots                        | 138   | The resume file is missing the ``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                                 |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| pieces_need_reorder                  | 142   | The 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_modified             | 143   | this 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_error                     | 150   | The HTTP header was not correctly formatted                               |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| http_missing_location                | 151   | The HTTP response was in the 300-399 range but lacked a location          |
|                                      |       | header                                                                    |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| http_failed_decompress               | 152   | The HTTP response was encoded with 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        |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| scrape_not_available                 | 170   | The tracker URL doesn't support 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                              |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+
| announce_skipped                     | 180   | skipped announce (because it's 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                                                 |
|                                      |       |                                                                           |
+--------------------------------------+-------+---------------------------------------------------------------------------+


__ reference-Bencoding.html#entry
__ reference-Bencoding.html#entry
__ reference-Bencoding.html#entry
__ reference-Bencoding.html#entry
__ reference-Bencoding.html#entry
__ reference-Session.html#session
__ reference-Session.html#session
__ reference-Torrent_Handle.html#torrent_handle
__ reference-Bencoding.html#entry
__ reference-Utility.html#bitfield
__ reference-Session.html#session
__ reference-Filter.html#port_filter
__ reference-Session.html#session_handle
__ reference-Bencoding.html#entry
__ reference-Bencoding.html#entry
__ reference-Bencoding.html#entry
__ reference-Bencoding.html#entry
__ reference-Bencoding.html#entry
__ reference-Bencoding.html#entry
__ reference-Torrent_Handle.html#only_if_modified
__ reference-Bencoding.html#entry
__ reference-Bencoding.html#entry
__ reference-Bencoding.html#entry
__ reference-Bencoding.html#entry
__ reference-Bencoding.html#entry

.. raw:: html

	<a name="http_errors"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+http_errors&labels=documentation&body=Documentation+under+heading+%22enum+http_errors%22+could+be+improved">report issue</a>]</span>



enum http_errors
----------------

Declared in "`libtorrent/error_code.hpp`__"


__ include/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   |             |
+-----------------------+-------+-------------+





.. _`BEP 19`: https://www.bittorrent.org/beps/bep_0019.html
.. _extensions: manual-ref.html#extensions
.. _`BEP 3`: https://www.bittorrent.org/beps/bep_0003.html
.. _`BEP 38`: https://www.bittorrent.org/beps/bep_0038.html
.. _`BEP 42`: https://www.bittorrent.org/beps/bep_0042.html
.. _`BEP 17`: https://www.bittorrent.org/beps/bep_0017.html
.. _`rate based choking`: manual-ref.html#rate-based-choking
.. raw:: html

	<a name="dht_storage_counters"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+dht_storage_counters&labels=documentation&body=Documentation+under+heading+%22class+dht_storage_counters%22+could+be+improved">report issue</a>]</span>



dht_storage_counters
--------------------

Declared in "`libtorrent/kademlia/dht_storage.hpp`__"


__ include/libtorrent/kademlia/dht_storage.hpp

This structure hold the relevant `counters`__ for the storage


__ reference-Stats.html#counters


.. parsed-literal::
	

	struct dht_storage_counters
	{
	   void **reset** ();
	
	   std::int32_t **torrents**  = 0;
	   std::int32_t **peers**  = 0;
	   std::int32_t **immutable_data**  = 0;
	   std::int32_t **mutable_data**  = 0;
	};

.. raw:: html

	<a name="reset()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_storage_counters%3A%3A%5Breset%28%29%5D&labels=documentation&body=Documentation+under+heading+%22dht_storage_counters%3A%3A%5Breset%28%29%5D%22+could+be+improved">report issue</a>]</span>



reset()
.......

.. parsed-literal::
	
	void **reset** ();
	

This member function set the `counters`__ to zero.


__ reference-Stats.html#counters

.. raw:: html

	<a name="dht_storage_interface"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+dht_storage_interface&labels=documentation&body=Documentation+under+heading+%22class+dht_storage_interface%22+could+be+improved">report issue</a>]</span>



dht_storage_interface
---------------------

Declared in "`libtorrent/kademlia/dht_storage.hpp`__"


__ include/libtorrent/kademlia/dht_storage.hpp

The DHT storage interface is a pure virtual class that can
be implemented to customize how the data for the DHT is stored.

The default storage implementation uses three maps in RAM to save
the peers, mutable and immutable items and it's designed to
provide a fast and fully compliant behavior of the BEPs.

libtorrent comes with one built-in storage implementation:
``dht_default_storage`` (private non-accessible class). Its
constructor function is called `dht_default_storage_constructor()`__.
You should know that if this storage becomes full of DHT items,
the current implementation could degrade in performance.


__ reference-DHT.html#dht_default_storage_constructor()


.. parsed-literal::
	

	struct dht_storage_interface
	{
	   virtual void **update_node_ids** (std\:\:vector<node\_id> const& ids) = 0;
	   virtual bool **get_peers** (sha1\_hash const& info\_hash
	      , bool noseed, bool scrape, address const& requester
	      , entry& peers) const = 0;
	   virtual void **announce_peer** (sha1\_hash const& info\_hash
	      , tcp\:\:endpoint const& endp
	      , string\_view name, bool seed) = 0;
	   virtual bool **get_immutable_item** (sha1\_hash const& target
	      , entry& item) const = 0;
	   virtual void **put_immutable_item** (sha1\_hash const& target
	      , span<char const> buf
	      , address const& addr) = 0;
	   virtual bool **get_mutable_item_seq** (sha1\_hash const& target
	      , sequence\_number& seq) const = 0;
	   virtual bool **get_mutable_item** (sha1\_hash const& target
	      , sequence\_number seq, bool force\_fill
	      , entry& item) const = 0;
	   virtual void **put_mutable_item** (sha1\_hash const& target
	      , span<char const> buf
	      , signature const& sig
	      , sequence\_number seq
	      , public\_key const& pk
	      , span<char const> salt
	      , address const& addr) = 0;
	   virtual int **get_infohashes_sample** (entry& item) = 0;
	   virtual void **tick** () = 0;
	   virtual dht_storage_counters **counters** () const = 0;
	};

.. raw:: html

	<a name="update_node_ids()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_storage_interface%3A%3A%5Bupdate_node_ids%28%29%5D&labels=documentation&body=Documentation+under+heading+%22dht_storage_interface%3A%3A%5Bupdate_node_ids%28%29%5D%22+could+be+improved">report issue</a>]</span>



update_node_ids()
.................

.. parsed-literal::
	
	virtual void **update_node_ids** (std\:\:vector<node\_id> const& ids) = 0;
	

This member function notifies the list of all node's ids
of each DHT running inside libtorrent. It's advisable
that the concrete implementation keeps a copy of this list
for an eventual prioritization when deleting an element
to make room for a new one.



.. raw:: html

	<a name="get_peers()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_storage_interface%3A%3A%5Bget_peers%28%29%5D&labels=documentation&body=Documentation+under+heading+%22dht_storage_interface%3A%3A%5Bget_peers%28%29%5D%22+could+be+improved">report issue</a>]</span>



get_peers()
...........

.. parsed-literal::
	
	virtual bool **get_peers** (sha1\_hash const& info\_hash
	      , bool noseed, bool scrape, address const& requester
	      , entry& peers) const = 0;
	

This function retrieve the peers tracked by the DHT
corresponding to the given info_hash. You can specify if
you want only seeds and/or you are scraping the data.

For future implementers:
If the torrent tracked contains a name, such a name
must be stored as a string in peers["n"]

If the scrape parameter is true, you should fill these keys:

   peers["BFpe"]
      with the standard bit representation of a
      256 bloom filter containing the downloaders
   peers["BFsd"]
      with the standard bit representation of a
      256 bloom filter containing the seeders

If the scrape parameter is false, you should fill the
key peers["values"] with a list containing a subset of
peers tracked by the given info_hash. Such a list should
consider the value of `settings_pack::dht_max_peers_reply`__.
If noseed is true only peers marked as no seed should be included.

returns true if the maximum number of peers are stored
for this info_hash.


__ reference-Settings.html#dht_max_peers_reply

.. raw:: html

	<a name="announce_peer()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_storage_interface%3A%3A%5Bannounce_peer%28%29%5D&labels=documentation&body=Documentation+under+heading+%22dht_storage_interface%3A%3A%5Bannounce_peer%28%29%5D%22+could+be+improved">report issue</a>]</span>



announce_peer()
...............

.. parsed-literal::
	
	virtual void **announce_peer** (sha1\_hash const& info\_hash
	      , tcp\:\:endpoint const& endp
	      , string\_view name, bool seed) = 0;
	

This function is named announce_peer for consistency with the
upper layers, but has nothing to do with networking. Its only
responsibility is store the peer in such a way that it's returned
in the `entry`__ with the lookup_peers.

The ``name`` parameter is the name of the torrent if provided in
the announce_peer DHT message. The length of this value should
have a maximum length in the final storage. The default
implementation truncate the value for a maximum of 50 characters.


__ reference-Bencoding.html#entry

.. raw:: html

	<a name="get_immutable_item()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_storage_interface%3A%3A%5Bget_immutable_item%28%29%5D&labels=documentation&body=Documentation+under+heading+%22dht_storage_interface%3A%3A%5Bget_immutable_item%28%29%5D%22+could+be+improved">report issue</a>]</span>



get_immutable_item()
....................

.. parsed-literal::
	
	virtual bool **get_immutable_item** (sha1\_hash const& target
	      , entry& item) const = 0;
	

This function retrieves the immutable item given its target hash.

For future implementers:
The value should be returned as an `entry`__ in the key item["v"].

returns true if the item is found and the data is returned
inside the (`entry`__) out parameter item.


__ reference-Bencoding.html#entry
__ reference-Bencoding.html#entry

.. raw:: html

	<a name="put_immutable_item()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_storage_interface%3A%3A%5Bput_immutable_item%28%29%5D&labels=documentation&body=Documentation+under+heading+%22dht_storage_interface%3A%3A%5Bput_immutable_item%28%29%5D%22+could+be+improved">report issue</a>]</span>



put_immutable_item()
....................

.. parsed-literal::
	
	virtual void **put_immutable_item** (sha1\_hash const& target
	      , span<char const> buf
	      , address const& addr) = 0;
	

Store the item's data. This layer is only for storage.
The authentication of the item is performed by the upper layer.

For implementers:
This data can be stored only if the target is not already
present. The implementation should consider the value of
`settings_pack::dht_max_dht_items`__.



__ reference-Settings.html#dht_max_dht_items

.. raw:: html

	<a name="get_mutable_item_seq()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_storage_interface%3A%3A%5Bget_mutable_item_seq%28%29%5D&labels=documentation&body=Documentation+under+heading+%22dht_storage_interface%3A%3A%5Bget_mutable_item_seq%28%29%5D%22+could+be+improved">report issue</a>]</span>



get_mutable_item_seq()
......................

.. parsed-literal::
	
	virtual bool **get_mutable_item_seq** (sha1\_hash const& target
	      , sequence\_number& seq) const = 0;
	

This function retrieves the sequence number of a mutable item.

returns true if the item is found and the data is returned
inside the out parameter seq.



.. raw:: html

	<a name="get_mutable_item()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_storage_interface%3A%3A%5Bget_mutable_item%28%29%5D&labels=documentation&body=Documentation+under+heading+%22dht_storage_interface%3A%3A%5Bget_mutable_item%28%29%5D%22+could+be+improved">report issue</a>]</span>



get_mutable_item()
..................

.. parsed-literal::
	
	virtual bool **get_mutable_item** (sha1\_hash const& target
	      , sequence\_number seq, bool force\_fill
	      , entry& item) const = 0;
	

This function retrieves the mutable stored in the DHT.

For implementers:
The item sequence should be stored in the key item["seq"].
if force_fill is true or (0 <= seq and seq < item["seq"])
the following keys should be filled
item["v"] - with the value no encoded.
item["sig"] - with a string representation of the signature.
item["k"] - with a string representation of the public key.

returns true if the item is found and the data is returned
inside the (`entry`__) out parameter item.


__ reference-Bencoding.html#entry

.. raw:: html

	<a name="put_mutable_item()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_storage_interface%3A%3A%5Bput_mutable_item%28%29%5D&labels=documentation&body=Documentation+under+heading+%22dht_storage_interface%3A%3A%5Bput_mutable_item%28%29%5D%22+could+be+improved">report issue</a>]</span>



put_mutable_item()
..................

.. parsed-literal::
	
	virtual void **put_mutable_item** (sha1\_hash const& target
	      , span<char const> buf
	      , signature const& sig
	      , sequence\_number seq
	      , public\_key const& pk
	      , span<char const> salt
	      , address const& addr) = 0;
	

Store the item's data. This layer is only for storage.
The authentication of the item is performed by the upper layer.

For implementers:
The sequence number should be checked if the item is already
present. The implementation should consider the value of
`settings_pack::dht_max_dht_items`__.



__ reference-Settings.html#dht_max_dht_items

.. raw:: html

	<a name="get_infohashes_sample()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_storage_interface%3A%3A%5Bget_infohashes_sample%28%29%5D&labels=documentation&body=Documentation+under+heading+%22dht_storage_interface%3A%3A%5Bget_infohashes_sample%28%29%5D%22+could+be+improved">report issue</a>]</span>



get_infohashes_sample()
.......................

.. parsed-literal::
	
	virtual int **get_infohashes_sample** (entry& item) = 0;
	

This function retrieves a sample info-hashes

For implementers:
The info-hashes should be stored in ["samples"] (N x 20 bytes).
the following keys should be filled
item["interval"] - the subset refresh interval in seconds.
item["num"] - number of info-hashes in storage.

Internally, this function is allowed to lazily evaluate, cache
and modify the actual sample to put in ``item``

returns the number of info-hashes in the sample.



.. raw:: html

	<a name="tick()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_storage_interface%3A%3A%5Btick%28%29%5D&labels=documentation&body=Documentation+under+heading+%22dht_storage_interface%3A%3A%5Btick%28%29%5D%22+could+be+improved">report issue</a>]</span>



tick()
......

.. parsed-literal::
	
	virtual void **tick** () = 0;
	

This function is called periodically (non-constant frequency).

For implementers:
Use this functions for expire peers or items or any other
storage cleanup.



.. raw:: html

	<a name="counters()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_storage_interface%3A%3A%5Bcounters%28%29%5D&labels=documentation&body=Documentation+under+heading+%22dht_storage_interface%3A%3A%5Bcounters%28%29%5D%22+could+be+improved">report issue</a>]</span>



counters()
..........

.. parsed-literal::
	
	virtual dht_storage_counters **counters** () const = 0;
	

return stats `counters`__ for the store


__ reference-Stats.html#counters

.. raw:: html

	<a name="dht_state"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+dht_state&labels=documentation&body=Documentation+under+heading+%22class+dht_state%22+could+be+improved">report issue</a>]</span>



dht_state
---------

Declared in "`libtorrent/kademlia/dht_state.hpp`__"


__ include/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`_

.. _`BEP 32`: https://www.bittorrent.org/beps/bep_0032.html




.. parsed-literal::
	

	struct dht_state
	{
	   void **clear** ();
	
	   node_ids_t nids;
	   std::vector<udp::endpoint> nodes;
	   std::vector<udp::endpoint> nodes6;
	};

.. raw:: html

	<a name="nodes"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_state%3A%3A%5Bnodes%5D&labels=documentation&body=Documentation+under+heading+%22dht_state%3A%3A%5Bnodes%5D%22+could+be+improved">report issue</a>]</span>


nodes
	the bootstrap nodes saved from the buckets node
	


.. raw:: html

	<a name="nodes6"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_state%3A%3A%5Bnodes6%5D&labels=documentation&body=Documentation+under+heading+%22dht_state%3A%3A%5Bnodes6%5D%22+could+be+improved">report issue</a>]</span>


nodes6
	the bootstrap nodes saved from the IPv6 buckets node
	


.. raw:: html

	<a name="dht_default_storage_constructor()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_default_storage_constructor%28%29&labels=documentation&body=Documentation+under+heading+%22dht_default_storage_constructor%28%29%22+could+be+improved">report issue</a>]</span>



dht_default_storage_constructor()
---------------------------------

Declared in "`libtorrent/kademlia/dht_storage.hpp`__"


__ include/libtorrent/kademlia/dht_storage.hpp

.. parsed-literal::
	
	std::unique_ptr<dht_storage_interface> **dht_default_storage_constructor** (
	   settings\_interface const& settings);
	

constructor for the default DHT storage. The DHT storage is responsible
for maintaining peers and mutable and immutable items announced and
stored/put to the DHT node.



.. raw:: html

	<a name="sign_mutable_item()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:sign_mutable_item%28%29&labels=documentation&body=Documentation+under+heading+%22sign_mutable_item%28%29%22+could+be+improved">report issue</a>]</span>



sign_mutable_item()
-------------------

Declared in "`libtorrent/kademlia/item.hpp`__"


__ include/libtorrent/kademlia/item.hpp

.. parsed-literal::
	
	signature **sign_mutable_item** (
	   span<char const> v
	   , span<char const> salt
	   , sequence\_number seq
	   , public\_key const& pk
	   , secret\_key const& sk);
	

given a byte range ``v`` and an optional byte range ``salt``, a
sequence number, public key ``pk`` (must be 32 bytes) and a secret key
``sk`` (must be 64 bytes), this function produces a signature which
is written into a 64 byte buffer pointed to by ``sig``. The caller
is responsible for allocating the destination buffer that's passed in
as the ``sig`` argument. Typically it would be allocated on the stack.



.. raw:: html

	<a name="announce_flags_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:announce_flags_t&labels=documentation&body=Documentation+under+heading+%22announce_flags_t%22+could+be+improved">report issue</a>]</span>



announce_flags_t
----------------

Declared in "`libtorrent/kademlia/announce_flags.hpp`__"


__ include/libtorrent/kademlia/announce_flags.hpp

.. raw:: html

	<a name="announce_flags_t::seed"></a>

seed
	announce to DHT as a seed
	


.. raw:: html

	<a name="announce_flags_t::implied_port"></a>

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.
	


.. raw:: html

	<a name="announce_flags_t::ssl_torrent"></a>

ssl_torrent
	Specify the port number for the SSL listen socket in the DHT announce.
	





.. _`BEP 19`: https://www.bittorrent.org/beps/bep_0019.html
.. _extensions: manual-ref.html#extensions
.. _`BEP 3`: https://www.bittorrent.org/beps/bep_0003.html
.. _`BEP 38`: https://www.bittorrent.org/beps/bep_0038.html
.. _`BEP 42`: https://www.bittorrent.org/beps/bep_0042.html
.. _`BEP 17`: https://www.bittorrent.org/beps/bep_0017.html
.. _`rate based choking`: manual-ref.html#rate-based-choking
.. raw:: html

	<a name="write_resume_data_buf()"></a>
	<a name="write_resume_data()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:write_resume_data_buf%28%29+write_resume_data%28%29&labels=documentation&body=Documentation+under+heading+%22write_resume_data_buf%28%29+write_resume_data%28%29%22+could+be+improved">report issue</a>]</span>



write_resume_data_buf() write_resume_data()
-------------------------------------------

Declared in "`libtorrent/write_resume_data.hpp`__"


__ include/libtorrent/write_resume_data.hpp

.. parsed-literal::
	
	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



.. raw:: html

	<a name="write_torrent_file()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:write_torrent_file%28%29&labels=documentation&body=Documentation+under+heading+%22write_torrent_file%28%29%22+could+be+improved">report issue</a>]</span>



write_torrent_file()
--------------------

Declared in "`libtorrent/write_resume_data.hpp`__"


__ include/libtorrent/write_resume_data.hpp

.. parsed-literal::
	
	entry **write_torrent_file** (add\_torrent\_params const& atp);
	

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


__ reference-Add_Torrent.html#add_torrent_params

.. raw:: html

	<a name="read_resume_data()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:read_resume_data%28%29&labels=documentation&body=Documentation+under+heading+%22read_resume_data%28%29%22+could+be+improved">report issue</a>]</span>



read_resume_data()
------------------

Declared in "`libtorrent/read_resume_data.hpp`__"


__ include/libtorrent/read_resume_data.hpp

.. parsed-literal::
	
	add_torrent_params **read_resume_data** (bdecode\_node const& rd
	   , int piece\_limit = 0x200000);
	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
	   , load\_torrent\_limits const& cfg = {});
	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()`__.


__ reference-Add_Torrent.html#add_torrent_params
__ reference-Torrent_Info.html#torrent_info
__ reference-Settings.html#max_piece_count
__ reference-Torrent_Info.html#parse_info_section()



.. _`BEP 19`: https://www.bittorrent.org/beps/bep_0019.html
.. _extensions: manual-ref.html#extensions
.. _`BEP 3`: https://www.bittorrent.org/beps/bep_0003.html
.. _`BEP 38`: https://www.bittorrent.org/beps/bep_0038.html
.. _`BEP 42`: https://www.bittorrent.org/beps/bep_0042.html
.. _`BEP 17`: https://www.bittorrent.org/beps/bep_0017.html
.. _`rate based choking`: manual-ref.html#rate-based-choking
.. raw:: html

	<a name="ed25519_create_seed()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:ed25519_create_seed%28%29&labels=documentation&body=Documentation+under+heading+%22ed25519_create_seed%28%29%22+could+be+improved">report issue</a>]</span>



ed25519_create_seed()
---------------------

Declared in "`libtorrent/kademlia/ed25519.hpp`__"


__ include/libtorrent/kademlia/ed25519.hpp

.. parsed-literal::
	
	std::array<char, 32> **ed25519_create_seed** ();
	

See documentation of internal random_bytes



.. raw:: html

	<a name="ed25519_create_keypair()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:ed25519_create_keypair%28%29&labels=documentation&body=Documentation+under+heading+%22ed25519_create_keypair%28%29%22+could+be+improved">report issue</a>]</span>



ed25519_create_keypair()
------------------------

Declared in "`libtorrent/kademlia/ed25519.hpp`__"


__ include/libtorrent/kademlia/ed25519.hpp

.. parsed-literal::
	
	std::tuple<public_key, secret_key> **ed25519_create_keypair** (
	   std\:\:array<char, 32> const& seed);
	

Creates a new key pair from the given seed.

It's important to clarify that the seed completely determines
the key pair. Then it's enough to save the seed and the
public key as the key-pair in a buffer of 64 bytes. The standard
is (32 bytes seed, 32 bytes public key).

This function does work with a given seed, giving you a pair of
(64 bytes private key, 32 bytes public key). It's a trade-off between
space and CPU, saving in one format or another.

The smaller format is not weaker by any means, in fact, it is only
the seed (32 bytes) that determines the point in the curve.



.. raw:: html

	<a name="ed25519_sign()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:ed25519_sign%28%29&labels=documentation&body=Documentation+under+heading+%22ed25519_sign%28%29%22+could+be+improved">report issue</a>]</span>



ed25519_sign()
--------------

Declared in "`libtorrent/kademlia/ed25519.hpp`__"


__ include/libtorrent/kademlia/ed25519.hpp

.. parsed-literal::
	
	signature **ed25519_sign** (span<char const> msg
	   , public\_key const& pk, secret\_key const& sk);
	

Creates a signature of the given message with the given key pair.



.. raw:: html

	<a name="ed25519_verify()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:ed25519_verify%28%29&labels=documentation&body=Documentation+under+heading+%22ed25519_verify%28%29%22+could+be+improved">report issue</a>]</span>



ed25519_verify()
----------------

Declared in "`libtorrent/kademlia/ed25519.hpp`__"


__ include/libtorrent/kademlia/ed25519.hpp

.. parsed-literal::
	
	bool **ed25519_verify** (signature const& sig
	   , span<char const> msg, public\_key const& pk);
	

Verifies the signature on the given message using ``pk``



.. raw:: html

	<a name="ed25519_add_scalar()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:ed25519_add_scalar%28%29&labels=documentation&body=Documentation+under+heading+%22ed25519_add_scalar%28%29%22+could+be+improved">report issue</a>]</span>



ed25519_add_scalar()
--------------------

Declared in "`libtorrent/kademlia/ed25519.hpp`__"


__ include/libtorrent/kademlia/ed25519.hpp

.. parsed-literal::
	
	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
side.

Warning: the last bit of the scalar is ignored - if comparing scalars make
sure to clear it with `scalar[31] &= 127`.

see http://crypto.stackexchange.com/a/6215/4697
see test_ed25519 for a practical example



.. raw:: html

	<a name="ed25519_key_exchange()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:ed25519_key_exchange%28%29&labels=documentation&body=Documentation+under+heading+%22ed25519_key_exchange%28%29%22+could+be+improved">report issue</a>]</span>



ed25519_key_exchange()
----------------------

Declared in "`libtorrent/kademlia/ed25519.hpp`__"


__ include/libtorrent/kademlia/ed25519.hpp

.. parsed-literal::
	
	std::array<char, 32> **ed25519_key_exchange** (
	   public\_key const& pk, secret\_key const& sk);
	

Performs a key exchange on the given public key and private key, producing a
shared secret. It is recommended to hash the shared secret before using it.

This is useful when two parties want to share a secret but both only knows
their respective public keys.
see test_ed25519 for a practical example





.. _`BEP 19`: https://www.bittorrent.org/beps/bep_0019.html
.. _extensions: manual-ref.html#extensions
.. _`BEP 3`: https://www.bittorrent.org/beps/bep_0003.html
.. _`BEP 38`: https://www.bittorrent.org/beps/bep_0038.html
.. _`BEP 42`: https://www.bittorrent.org/beps/bep_0042.html
.. _`BEP 17`: https://www.bittorrent.org/beps/bep_0017.html
.. _`rate based choking`: manual-ref.html#rate-based-choking
