
Not an error

expected digit in bencoded string

expected colon in bencoded string

unexpected end of file in bencoded string

expected value (list, dict, int or string) in bencoded string

bencoded recursion depth limit exceeded

bencoded item count limit exceeded

integer overflow

the number of error codes

libtorrent uses boost.system's ``error_code`` class to represent
errors. libtorrent has its own error category bdecode_category()
with the error codes defined by error_code_enum.

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

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

uninitialized or default constructed. This is also used
to indicate that a node was not found in some cases.

a dictionary node. The ``dict_find_`` functions are valid.

a list node. The ``list_`` functions are valid.

a string node, the ``string_`` functions are valid.

an integer node. The ``int_`` functions are valid.

the types of bdecoded nodes

the type of this node. See type_t.

returns true if type() != none_t.

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

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.

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.

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

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

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.

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.

Swap contents.

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

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

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

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.

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

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.

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
















See RFC 6887 Section 7.4


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.

saves settings (i.e. the settings_pack)

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

load or save state from plugins

load or save the IP filter set on the session

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

	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.

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.

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.

This will cause a dht_stats_alert to be posted.

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.

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

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

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

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

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

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

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.

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

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

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

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

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.

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.

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.

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

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.

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

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.

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.

uTorrent peer exchange
	Exchanges peers between clients.

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.


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.

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.

built-in peer classes

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

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:

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

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

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

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

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

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

delete just the part-file associated with this torrent

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

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

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.

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.

protocols used by add_port_mapping()

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.

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.

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.

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.

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.





converts a setting integer (from the enums string_types, int_types or
bool_types) to a string, and vice versa.

returns a settings_pack with every setting set to its default value



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


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.

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.

clear the settings pack from all settings

clear a specific setting from the pack

queries the current configuration option from the settings_pack.
``name`` is one of the enumeration values from string_types, int_types
or bool_types. The enum value must match the type of the get_*
function. If the specified setting field has not been set, the default
value is returned.






setting names (indices) are 16 bits. The two most significant
bits indicate what type the setting has. (string, int, bool)


disable writing to disk via mmap, always use normal write calls

prefer using memory mapped files for disk writes (at least for
large files where it might make sense)

determine whether to use pwrite or memory mapped files for disk
writes depending on the kind of storage behind the save path





This is the traditional choker with a fixed number of unchoke
slots (as specified by settings_pack::unchoke_slots_limit).

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



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.

unchokes the peers we can send to the fastest. This might be a
bit more reliable in utilizing all available capacity.

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.







disables the mixed mode bandwidth balancing

does not throttle uTP, throttles TCP to the same proportion
of throughput as there are TCP connections


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.

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.

only non-encrypted connections are allowed.

the encoding policy options for use with
settings_pack::out_enc_policy and settings_pack::in_enc_policy.

use only plain text encryption

use only RC4 encryption

allow both

the encryption levels, to be used with
settings_pack::allowed_enc_level.

No proxy server is used and all other fields are ignored.

The server is assumed to be a `SOCKS4 server`_ that requires a
username.


The server is assumed to be a SOCKS5 server (`RFC 1928`_) that does
not require any authentication. The username and password are
ignored.


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.


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.


The server is assumed to be an HTTP proxy that requires user
authorization. The username and password will be sent to the proxy.

route through a i2p SAM proxy


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.

The ``settings_pack`` only stores values for settings that have been
explicitly set on this object. However, it can still be queried for
settings that have not been set and returns the default value for those
settings.



If ``seed_mode`` is set, libtorrent will assume that all files
are present for this torrent and that they all match the hashes in
the torrent file. Each time a peer requests to download a block,
the piece is verified against the hash, unless it has been verified
already. If a hash fails, the torrent will automatically leave the
seed mode and recheck all the files. The use case for this mode is
if a torrent is created and seeded, or if the user already know
that the files are complete, this is a way to avoid the initial
file checks, and significantly reduce the startup time.

Setting ``seed_mode`` on a torrent without metadata (a
.torrent file) is a no-op and will be ignored.

It is not possible to *set* the ``seed_mode`` flag on a torrent after it has
been added to a session. It is possible to *clear* it though.

If ``upload_mode`` is set, the torrent will be initialized in
upload-mode, which means it will not make any piece requests. This
state is typically entered on disk I/O errors, and if the torrent
is also auto managed, it will be taken out of this state
periodically (see ``settings_pack::optimistic_disk_retry``).

This mode can be used to avoid race conditions when
adjusting priorities of pieces before allowing the torrent to start
downloading.

If the torrent is auto-managed (``auto_managed``), the torrent
will eventually be taken out of upload-mode, regardless of how it
got there. If it's important to manually control when the torrent
leaves upload mode, don't make it auto managed.

determines if the torrent should be added in *share mode* or not.
Share mode indicates that we are not interested in downloading the
torrent, but merely want to improve our share ratio (i.e. increase
it). A torrent started in share mode will do its best to never
download more than it uploads to the swarm. If the swarm does not
have enough demand for upload capacity, the torrent will not
download anything. This mode is intended to be safe to add any
number of torrents to, without manual screening, without the risk
of downloading more than is uploaded.

A torrent in share mode sets the priority to all pieces to 0,
except for the pieces that are downloaded, when pieces are decided
to be downloaded. This affects the progress bar, which might be set
to "100% finished" most of the time. Do not change file or piece
priorities for torrents in share mode, it will make it not work.

The share mode has one setting, the share ratio target, see
``settings_pack::share_mode_target`` for more info.

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.

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

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

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.

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

sets the torrent into super seeding/initial seeding mode. If the torrent
is not a seed, this flag has no effect.

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.

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

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

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

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.

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.

set this flag to disable local service discovery for this torrent.

set this flag to disable peer exchange for this torrent.

if this flag is set, the resume data will be assumed to be correct
without validating it against any files on disk. This may be used when
restoring a session by loading resume data from disk. It will save time
and also delay any hard disk errors until files are actually needed. If
the resume data cannot be trusted, or if a torrent is added for the first
time to some save path that may already have some of the files, this flag
should not be set.

default all file priorities to dont_download. This is useful for adding
magnet links where the number of files is unknown, but the
file_priorities is still set for some files. Any file not covered by
the file_priorities list will be set to normal download priority,
unless this flag is set, in which case they will be set to 0
(dont_download).

all torrent flags combined. Can conveniently be used when creating masks
for flags

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

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

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.

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

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

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.

set to true when we send a event=completed.



the local endpoint of the listen interface associated with this endpoint

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

set to false to not announce from this endpoint

announces are sent to each tracker using every listen socket
this class holds information about one listen socket for one tracker

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

tracker URL as it appeared in the torrent file

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

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

the tier this tracker belongs to

the max number of failures to announce to this tracker in
a row, before this tracker is not used anymore. 0 means unlimited

the tracker was part of the .torrent file

the tracker was added programmatically via the add_tracker() function

the tracker was part of a magnet link

the tracker was received from the swarm via tracker exchange

flags for the source bitmask, each indicating where
we heard about this tracker

a bitmask specifying which sources we got this tracker from.

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

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


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

append the following bytes to what is being hashed

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

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

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


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

append the following bytes to what is being hashed

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

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



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.

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.

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

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.

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.

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.

	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.

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

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

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

this function turns the resume data in an ``add_torrent_params`` object
into a bencoded structure

this makes write_torrent_file() not fail when attempting to write a
v2 torrent file that does not have all the piece layers

don't include http seeds in the torrent file, even if some are
present in the add_torrent_params object

When set, DHT nodes from the add_torrent_params objects are included
in the resulting .torrent file

writes only the fields to create a .torrent file. This function may fail
with a ``std::system_error`` exception if:

* The add_torrent_params object passed to this function does not contain the
 info dictionary (the ``ti`` field)
* The piece layers are not complete for all files that need them

The ``write_torrent_file_buf()`` overload returns the torrent file in
bencoded buffer form. This overload may be faster at the expense of lost
flexibility to add custom fields.












SOCKS5 error values. If an error_code has the
socks error category (get_socks_category()), these
are the error values.

returns the error_category for SOCKS5 errors


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



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)

default construct a holder that does not own any buffer

frees disk buffer held by this object

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

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

swap pointers of two disk buffer holders.

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

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


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.

compares if the torrent status objects come from the same torrent. i.e.
only the torrent_handle field is compared.

a handle to the torrent whose status the object represents.

The torrent has not started its download yet, and is
currently checking existing files.

The torrent is trying to download metadata from peers.
This implies the ut_metadata extension is in use.

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.

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.

In this state the torrent has finished downloading and
is a pure seeder.

If the torrent was started in full allocation mode, this
indicates that the (disk) storage for the torrent is
allocated.

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.

the different overall states a torrent can be in

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.

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;

special values for error_file to describe which file or component
encountered the error (``errc``).
the error did not occur on a file

the error occurred setting up the SSL context

the error occurred while loading the metadata for the torrent

there was a serious error reported in this torrent. The error code
or a torrent log alert may provide more information.

the error occurred with the partfile

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

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

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

the time until the torrent will announce itself to the tracker.

the URL of the last working tracker. If no tracker request has
been successful yet, it's set to an empty string.

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

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.

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.

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.

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.

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.

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

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.

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

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

are accumulated upload and download payload byte counters. They are
saved in and restored from resume data to keep totals across sessions.

the posix-time when this torrent was added. i.e. what ``time(nullptr)``
returned at the time.

the posix-time when this torrent was finished. If the torrent is not
yet finished, this is 0.

the time when we, or one of our peers, last saw a complete copy of
this torrent.

The allocation mode for the torrent. See storage_mode_t for the
options. For more information, see storage-allocation_.

a value in the range [0, 1], that represents the progress of the
torrent's current task. It may be checking files or downloading.

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.

the position this torrent has in the download
queue. If the torrent is a seed or finished, this is -1.

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.

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.

the number of peers that are seeding that this client is
currently connected to.

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

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.

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.

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.

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.

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.

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.

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

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.

the number of unchoked peers in this torrent.

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

the set limit of upload slots (unchoked peers) for this torrent.

the set limit of number of connections for this torrent.

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.

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

the main state the torrent is in. See torrent_status::state_t.

true if this torrent has unsaved changes
to its download state and statistics since the last resume data
was saved.

true if all pieces have been downloaded.

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.

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

true if there has ever been an incoming connection attempt to this
torrent.

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.

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.

the info-hash for this torrent

the timestamps of the last time this torrent uploaded or downloaded
payload to any peer.

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.

reflects several of the torrent's flags. For more
information, see ``torrent_handle::flags()``.

holds a snapshot of the status of a torrent, as queried by
torrent_handle::status().

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






Kinds of tracker announces. This is typically indicated as the ``&event=``
HTTP query string parameter to HTTP trackers.

The index of the piece in which the range starts.

The byte offset within that piece where the range starts.

The size of the range, in bytes.

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

represents a byte range within a piece. Internally this is is used for
incoming piece requests.

the peer supports protocol encryption

the peer is a seed

the peer supports the uTP, transport protocol over UDP.

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

protocol v2
this is not a standard flag, it is only used internally

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

copy bitfield from buffer ``b`` of ``bits`` number of bits, rounded up to
the nearest byte boundary.

query bit at ``index``. Returns true if bit is 1, otherwise false.

set bit at ``index`` to 0 (clear_bit) or 1 (set_bit).

returns true if all bits in the bitfield are set

returns true if no bit in the bitfield is set

returns the size of the bitfield in bits.

returns the number of 32 bit words are needed to represent all bits in
this bitfield.

returns true if the bitfield has zero size.

returns a pointer to the internal buffer of the bitfield, or
``nullptr`` if it's empty.

swaps the bit-fields two variables refer to

count the number of bits in the bitfield that are set to 1.

returns the index of the first set bit in the bitfield, i.e. 1 bit.

returns the index to the last cleared bit in the bitfield, i.e. 0 bit.

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











error values for the i2p_category error_category.

returns the error category for I2P errors

the major, minor and tiny versions of libtorrent

the major, minor and tiny versions of libtorrent

the major, minor and tiny versions of libtorrent

the libtorrent version in string form

the git commit of this libtorrent version

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

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.

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.

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.

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.

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.

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.

this flag enforces the file layout to be canonical according to the
bittorrent v2 specification (just like the ``canonical_files`` flag)
with the one exception that tail padding is not added to the last
file.
This behavior deviates from the specification but was the way
libtorrent created torrents in version up to and including 2.0.7.
This flag is here for backwards compatibility.

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

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

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

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

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


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

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

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

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

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

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

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

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

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.

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.

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.

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.

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.

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.

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.

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.


returns the number of pieces in the associated file_storage object.


all piece indices in the torrent to be created


all file indices in the torrent to be created

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

the total number of bytes of all files and pad files

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

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

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

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:

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.

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:

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.

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


No error

One of the arguments in the request is invalid

The request failed

The specified value does not exist in the array

The source IP address cannot be wild-carded, but
must be fully specified

The external port cannot be a wildcard, but must
be specified

The port mapping entry specified conflicts with a
mapping assigned previously to another client

Internal and external port value must be the same

The NAT implementation only supports permanent
lease times on port mappings

RemoteHost must be a wildcard and cannot be a
specific IP address or DNS name

ExternalPort must be a wildcard and cannot be a
specific port

error codes for the upnp_error_category. They hold error codes
returned by UPnP routers when mapping ports

the boost.system error category for UPnP errors

the error was unexpected and it is unknown which operation caused it

this is used when the bittorrent logic
determines to disconnect

a call to iocontrol failed

a call to ``getpeername()`` failed (querying the remote IP of a
connection)

a call to getname failed (querying the local IP of a
connection)

an attempt to allocate a receive buffer failed

an attempt to allocate a send buffer failed

writing to a file failed

reading from a file failed

a non-read and non-write file operation failed

a socket write operation failed

a socket read operation failed

a call to open(), to create a socket socket failed

a call to bind() on a socket failed

an attempt to query the number of bytes available to read from a socket
failed

a call related to bittorrent protocol encryption failed

an attempt to connect a socket failed

establishing an SSL connection failed

a connection failed to satisfy the bind interface setting

a call to listen() on a socket

a call to the ioctl to bind a socket to a specific network device or
adapter

a call to accept() on a socket

convert a string into a valid network address

enumeration network devices or adapters

invoking stat() on a file

copying a file

allocating storage for a file

creating a hard link

removing a file

renaming a file

opening a file

creating a directory

check fast resume data against files on disk

an unknown exception

allocate space for a piece in the cache

move a part-file

read from a part file

write to a part-file

a hostname lookup

create or read a symlink

handshake with a peer or server

set socket option

enumeration of network routes

moving read/write position in a file, operation_t::hostname_lookup

an async wait operation on a timer

call to mmap() (or windows counterpart)

call to ftruncate() (or SetEndOfFile() on windows)

these constants are used to identify the operation that failed, causing a
peer to disconnect

maps an operation id (from peer_error_alert and peer_disconnected_alert)
to its name. See operation_t for the constants







the types an entry can have

returns the concrete type of the entry

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


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

construct from bdecode_node parsed form (see bdecode())

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


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:

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

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

swaps the content of *this* with ``e``.

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

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.

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

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.

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







these match the socket types from socket_type.hpp
shifted one down







``add()`` and ``remove()`` adds and removes a peer class to be added
to new peers based on socket type.

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

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


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

natpmp can be NAT-PMP or PCP







Truncates files larger than specified in the file_storage, saved under
the specified save_path.

user defined alerts should use IDs greater than this

this constant represents "max_alert_index" + 1

the total number of nodes and replacement nodes
in the routing table

number of seconds since last activity

struct to hold information about a single DHT routing table bucket

returns the message associated with this alert

The torrent_handle pointing to the torrent this
alert is associated with.


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.


The peer's IP address and port.

the peer ID, if known.

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


endpoint of the listen interface being announced

returns a 0-terminated string of the tracker's URL

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.



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

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.




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.


refers to the index of the file that completed.

This is posted whenever an individual file completes its download. i.e.
All pieces overlapping this file have passed their hash check.



returns the new and previous file name, respectively.

refers to the index of the file that was renamed,

This is posted as a response to a torrent_handle::rename_file() call, if the rename
operation succeeds.



refers to the index of the file that was supposed to be renamed,
``error`` is the error code returned from the filesystem.

This is posted as a response to a torrent_handle::rename_file() call, if the rename
operation failed.

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.

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.

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.

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.

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:

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

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.

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



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.







This alert is generated when a limit is reached that might have a negative impact on
upload or download rate performance.



the new state of the torrent.

the previous state.

Generated whenever a torrent changes its state.



This member says how many times in a row this tracker has failed.

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.


if the tracker sent a "failure reason" string, it will be returned
here.

the bittorrent protocol version that was announced

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.



the message associated with this warning

the bittorrent protocol version that was announced

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.



the data returned in the scrape response. These numbers
may be -1 if the response was malformed.

the bittorrent protocol version that was scraped

This alert is generated when a scrape request succeeds.



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

if the error indicates there is an associated message, this returns
that message. Otherwise and empty string.

the bittorrent protocol version that was scraped

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.



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.

the bittorrent protocol version that was announced

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.




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.



specifies what event was sent to the tracker. See event_t.

the bittorrent protocol version that is announced

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.




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.



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.



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.



This alert is generated when a peer is snubbed, when it stops sending data when we request
it.



a 0-terminated string of the low-level operation that failed, or nullptr if
there was no low level disk operation.

tells you what error caused this alert.

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.






Tells you if the peer was incoming or outgoing


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.



the kind of socket this peer was connected over

the operation or level where the error occurred. Specified as an
value from the operation_t enum. Defined in operations.hpp.

tells you what error caused peer to disconnect.

the reason the peer disconnected (if specified)

This alert is generated when a peer is disconnected for any reason (other than the ones
covered by peer_error_alert ).



the request we received from the peer

true if we have this piece

true if the peer indicated that it was interested to download before
sending the request

if this is true, the peer is not allowed to download this piece because
of super-seeding rules.

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.



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.


the index of the piece that finished

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



This alert is generated when a peer rejects or ignores a piece request.



This alert is generated when a block request times out.



This alert is generated when a block request receives a response.



This alert is generated when a block request is sent to a peer.




This alert is generated when a block is received that was not requested or
whose request timed out.



the path the torrent was moved to and from, respectively.

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.




If the error happened for a specific file, this returns its path.

this indicates what underlying operation caused the error

The ``storage_moved_failed_alert`` is generated when an attempt to move the storage,
via torrent_handle::move_storage(), fails.



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.

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.



tells you why it failed.

the info hash of the torrent whose files failed to be deleted

This alert is generated when a request to delete the files of a torrent fails.
Just removing a torrent from the session cannot fail



the ``params`` object is populated with the torrent file whose resume
data was saved. It is suitable to be:

* added to a session with add_torrent() or async_add_torrent()
* saved to disk with write_resume_data()
* turned into a magnet link with make_magnet_uri()
* saved as a .torrent file with write_torrent_file()

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.



the error code from the resume_data failure

This alert is generated instead of ``save_resume_data_alert`` if there was an error
generating the resume data. ``error`` describes what went wrong.



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.



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.



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



the error the web seed encountered. If this is not set, the server
sent an error message, call ``error_message()``.

the URL the error is associated with

in case the web server sent an error message, this function returns
it.

This alert is generated when a HTTP seed name lookup fails.



the error code describing the error.

indicates which underlying operation caused the error

the file that experienced the error

If the storage fails to read or write files that it needs access to, this alert is
generated and the torrent is paused.



indicates what failed when parsing the metadata. This error is
what's returned from lazy_bdecode().

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.



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:

the source address associated with the error (if any)

the operation that failed

the error code describing the error

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.



the IP address that is believed to be our external IP

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.



the network device libtorrent attempted to listen on, or the IP address

the error the system returned

the underlying operation that failed

the type of listen socket this alert refers to.

the address libtorrent attempted to listen on
see alert documentation for validity of this value

the port libtorrent attempted to listen on
see alert documentation for validity of this value

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.



the address libtorrent ended up listening on. This address
refers to the local interface.

the port libtorrent ended up listening on.

the type of listen socket this alert refers to.

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.



refers to the mapping index of the port map that failed, i.e.
the index returned from add_mapping().

UPnP or NAT-PMP

the local network the port mapper is running on

tells you what failed.

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.



refers to the mapping index of the port map that failed, i.e.
the index returned from add_mapping().

the external port allocated for the mapping.



the local network the port mapper is running on

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.




the local network the port mapper is running on

the message associated with this log line

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.




If the error happened to a specific file, this returns the path to it.

the underlying operation that failed

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.












the reason for the peer being blocked. Is one of the values from the
reason_t enum.

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)




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.




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.


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.



This alert is generated when we receive a local service discovery message
from a peer for a torrent we're currently participating in.



The tracker ID returned by the tracker

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.



This alert is posted when the initial DHT bootstrap is done.



specifies which error the torrent encountered.

the filename (or object) the error occurred on.

This is posted whenever a torrent is transitioned into the error state.
If the error code is duplicate_torrent (error_code_enum) error, it suggests two magnet
links ended up resolving to the same hybrid torrent. For more details,
see BitTorrent-v2-torrents_.



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.



tells you what kind of socket the connection was accepted

is the IP address and port the connection came from.

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.



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

set to the error, if one occurred while adding the torrent.

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.



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.

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.



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.

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



the error code

the operation that failed

posted when something fails in the DHT. This is not necessarily a fatal
error, but it could prevent proper operation



the target hash of the immutable item. This must
match the SHA-1 hash of the bencoded form of ``item``.

the data for this item

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.



the public key that was looked up

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.

the sequence number of this item

the salt, if any, used to lookup and store this item. If no
salt was used, this is an empty string

the data for this item

the last response for mutable data is authoritative.

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.



the target hash the item was stored under if this was an *immutable*
item.

if a mutable item was stored, these are the public key, signature,
salt and sequence number the item was stored under.

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.

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.



the error that occurred in the i2p SAM connection

this alert is used to report errors in the i2p SAM connection



the info_hash of the torrent we're looking for peers for.

if this was an obfuscated lookup, this is the info-hash target
actually sent to the node.

the endpoint we're sending this query to

This alert is generated when we send a get_peers request
It belongs to the ``alert_category::dht`` category.



returns the log message

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.



returns the log message

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.






describes whether this log refers to in-flow or out-flow of the
peer. The exception is ``info`` which is neither incoming or outgoing.



string literal indicating the kind of event. For messages, this is the
message name.


returns the log message

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.



the local network the corresponding local service discovery is running
on

The error code

posted if the local service discovery socket fails to start properly.
it's categorized as ``alert_category::error``.

string literal indicating which kind of lookup this is

the number of outstanding request to individual nodes
this lookup has right now

the total number of requests that have timed out so far
for this lookup

the total number of responses we have received for this
lookup so far for this lookup

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.

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.

the number of seconds ago the
last message was sent that's still
outstanding

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

the node-id or info-hash target for this lookup

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



a vector of the currently running DHT lookups.

contains information about every bucket in the DHT routing
table.

the node ID of the DHT node instance

the local socket this DHT node is running on

contains current DHT state. Posted in response to session::post_dht_stats().



the request this peer sent to us

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.









the log message

the module, or part, of the DHT that produced this log message.

debug logging of the DHT when alert_category::dht_log is set in the alert
mask.






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.

whether this is an incoming or outgoing packet.

the DHT node we received this packet from, or sent this packet to
(depending on ``direction``).

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.






Posted when we receive a response to a DHT get_peers request.





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.




this is a bitmask of which features were enabled for this particular
pick. The bits are defined in the picker_flags_t enum.


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



The error code, if one is associated with this error

this alert is posted when the session encounters a serious error,
potentially fatal



the local DHT node's node-ID this routing table belongs to

the number of nodes in the routing table and the actual nodes.

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.



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



id of the node the request was sent to (and this response was received from)

the node the request was sent to (and this response was received from)

the interval to wait before making another request to this node

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.

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

The total number of nodes returned by ``nodes()``.

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.

posted as a response to a call to session::dht_sample_infohashes() with
the information from the DHT response message.



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.



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.

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



the error

the operation that failed

the endpoint configured as the proxy

this alert is posted with SOCKS5 related errors, when a SOCKS5 proxy is
configured. It's enabled with the alert_category::error alert category.



the error

the operation that failed

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.



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.



the handle to the torrent in conflict. The swarm associated with this
torrent handle did not download the metadata, but the downloaded
metadata collided with this swarm's info-hash.

the metadata that was received by one of the torrents in conflict.
One way to resolve the conflict is to remove both failing torrents
and re-add it using this metadata

this alert is posted when two separate torrents (magnet links) resolve to
the same torrent, thus causing the same torrent being added twice. In
that case, both torrents enter an error state with ``duplicate_torrent``
as the error code. This alert is posted containing the metadata. For more
information, see BitTorrent-v2-torrents_.
The torrent this alert originated from was the one that downloaded the

metadata (i.e. the `handle` member from the torrent_alert base class).




the name of the counter or gauge

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.

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

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

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.


indicates that IPs in this range should not be connected
to nor accepted as incoming connections

the flags defined for an IP range

returns true if the filter does not contain any rules

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.

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.

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.

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.


this flag indicates that destination ports in the
range should not be connected to

the defined flags for a port range

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.

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.

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.



returns the new value



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.

The original BitTorrent version, using SHA-1 hashes

Version 2 of the BitTorrent protocol, using SHA-256 hashes


BitTorrent version enumerator

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.

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

returns the has for the specified protocol version

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



calls the function object ``f`` for each hash that is available.
starting with v1. The signature of ``F`` is::

	void(sha1_hash const&, protocol_version);




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.


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

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

Enables alerts when peers send invalid requests, get banned or
snubbed.

Enables alerts for port mapping events. For NAT-PMP and UPnP.

Enables alerts for events related to the storage. File errors and
synchronization events for moving the storage, renaming files etc.

Enables all tracker events. Includes announcing to trackers,
receiving responses, warnings and errors.

Low level alerts for when peers are connected and disconnected.

Enables alerts for when a torrent or the session changes state.

Alerts when a peer is blocked by the ip blocker or port blocker.

Alerts when some limit is reached that might limit the download
or upload rate.

Alerts on events in the DHT node. For incoming searches or
bootstrapping being done etc.

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.

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.

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.

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.

enables the incoming_request_alert.

enables dht_log_alert, debug logging for the DHT

enable events from pure dht operations not related to torrents

enables port mapping log events. This log is useful
for debugging the UPnP or NAT-PMP implementation

enables verbose logging from the piece picker.

alerts when files complete downloading

alerts when pieces complete downloading or fail hash check

alerts when we upload blocks to other peers

alerts on individual blocks being requested, downloading, finished,
rejected, time-out and cancelled. This is likely to post alerts at a
high rate.

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.



a timestamp is automatically created in the constructor

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:

returns a string literal describing the type of the alert. It does
not include any information that might be bundled with the alert.

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.

returns a bitmask specifying which categories this alert belong to.

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

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.

 ``alert_cast<>`` can only cast to an exact alert type, not a base class

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.

All pieces will be written to the place where they belong and sparse files
will be used. This is the recommended, and default mode.

types of storage allocation used for add_torrent_params::storage_mode.





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.

return values from check_fastresume, and move_storage

replace any files in the destination when copying
or moving the storage

if any files that we want to copy exist in the destination
exist, fail the whole operation and don't perform
any copy or move. There is an 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.

if any file exist in the target, take those files instead
of the ones we may have in the source.

flags for async_move_storage



a parameter pack used to construct the storage for a torrent, used in
disk_interface

open the file for reading only

open the file for writing only

open the file for reading and writing

the mask for the bits determining read or write mode

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

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

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

the file is memory mapped

the index of the file this entry refers to into the ``file_storage``
file list of this torrent. This starts indexing at 0.

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

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

this contains information about a file that's currently open by the
libtorrent disk I/O subsystem. It's associated with a single torrent.

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.

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

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.

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.

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

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

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.

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.

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.

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

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

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.

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.

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

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

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.

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.

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.

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.

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.

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.

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.

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.

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.








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.
























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






The bt_peer_connection_handle provides a handle to the internal bittorrent
peer connection object to plugins. It's low level and may not be a stable API
across libtorrent versions.

This block has not been downloaded or requested form any peer.

The block has been requested, but not completely downloaded yet.

The block has been downloaded and is currently queued for being
written to disk.

The block has been written to disk.

this is the enum used for the block_info::state field.

The peer is the ip address of the peer this block was downloaded from.

the number of bytes that have been received for this block

the total number of bytes in this block.

the state this block is in (see block_state_t)

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.

holds the state of a block in a piece. Who we requested
it from and how far along we are at downloading it.

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.

the number of blocks in this piece

the number of blocks that are in the finished state

the number of blocks that are in the writing state

the number of blocks that are in the requested state

this is an array of ``blocks_in_piece`` number of
items. One for each block in the piece.

	that's owned by the session object. The next time
	get_download_queue() is called, it will be invalidated.

This class holds information about pieces that have outstanding requests
or outstanding writes

for std::hash (and to support using this type in unordered_map etc.)


constructs a torrent handle that does not refer to a torrent.
i.e. is_valid() will return false.

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.

This function will write ``data`` to the storage as piece ``piece``,
as if it had been downloaded from a peer.

By default, data that's already been downloaded is not overwritten by
this buffer. If you trust this data to be correct (and pass the piece
hash check) you may pass the overwrite_existing flag. This will
instruct libtorrent to overwrite any data that may already have been
downloaded with this data.

Since the data is written asynchronously, you may know that is passed
or failed 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.

The overload taking a raw pointer to the data is a blocking call. It
won't return until the libtorrent thread has copied the data into its
disk write buffer. ``data`` is expected to point to a buffer of as
many bytes as the size of the specified piece. See
file_storage::piece_size().

The data in the buffer is copied and passed on to the disk IO thread
to be written at a later point.

The overload taking a ``std::vector<char>`` is not blocking, it will
send the buffer to the main thread and return immediately.

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.

Returns true if this piece has been completely downloaded and written
to disk, and false otherwise.

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.

calculates ``distributed_copies``, ``distributed_full_copies`` and
``distributed_fraction``.

includes partial downloaded blocks in ``total_done`` and
``total_wanted_done``.

includes ``last_seen_complete``.

populate the ``pieces`` field in torrent_status.

includes ``verified_pieces`` (only applies to torrents in *seed
mode*).

includes ``torrent_file``, which is all the static information from
the .torrent file.

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.

includes ``save_path``, the path to the directory the files of the
torrent are saved to.

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

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

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.

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.

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.

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.

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

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.

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

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

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.

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.

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

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.

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.

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

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


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.

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.

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

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.

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

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.

``save_resume_data()`` asks libtorrent to generate fast-resume data for
this torrent. The fast resume data (stored in an add_torrent_params
object) can be used to resume a torrent in the next session without
having to check all files for which pieces have been downloaded. It
can also be used to save a .torrent file for a torrent_handle.

This operation is asynchronous, ``save_resume_data`` will return
immediately. The resume data is delivered when it's done through a
save_resume_data_alert.

The operation will fail, and post a save_resume_data_failed_alert
instead, in the following cases:

	1. The torrent is in the process of being removed.
	2. No torrent state has changed since the last saving of resume
	   data, and the only_if_modified flag is set.
	   metadata (see libtorrent's metadata-from-peers_ extension)

Note that some counters may be outdated by the time you receive the fast resume data

When saving resume data because of shutting down, make sure not to
remove_torrent() before you receive the save_resume_data_alert.
There's no need to pause the session or torrent when saving resume
data.

The paused state of a torrent is saved in the resume data, so pausing
all torrents before saving resume data will all torrents be restored
in a paused state.

 It is typically a good idea to save resume data whenever a torrent
 is completed or paused. If you save resume data for torrents when they are
 paused, you can accelerate the shutdown process by not saving resume
 data again for those torrents. Completed torrents should have their
 resume data saved when they complete and on exit, since their
 statistics might be updated.

Example code to pause and save resume data for all torrents and wait
for the alerts:

	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.

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.

	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.

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.

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

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.

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.

If you want to save a .torrent file from the torrent_handle, instead
call save_resume_data() and write_torrent_file() the
add_torrent_params object passed back in the alert.

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.

The torrent_file_with_hashes() is here for backwards compatibility
when constructing a create_torrent object from a torrent_info that's
in a session. Prefer save_resume_data() + write_torrent_file().

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.

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.

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.

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.

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

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.

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

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

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

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

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.

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

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

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.

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.

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.

comparison operators. The order of the torrents is unspecified
but stable.

returns a unique identifier for this torrent. It's not a dense index.
It's not preserved across sessions.

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.

returns the userdata pointer as set in add_torrent_params

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.

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.

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

	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.


filled in by the constructor and should be left untouched. It is used
for forward binary compatibility.

torrent_info object with the torrent to add. Unless the
info_hash is set, this is required to be initialized.

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.

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.

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.

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.

the path where the torrent is or will be stored.

	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.

One of the values from storage_mode_t. For more information, see
storage-allocation_.

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

can be set to control the initial file priorities when adding a
torrent. The semantics are the same as for
``torrent_handle::prioritize_files()``. The file priorities specified
in here take precedence over those specified in the resume data, if
any.
If this vector of file priorities is shorter than the number of files
in the torrent, the remaining files (not covered by this) will still
have the default download priority. This default can be changed by
setting the default_dont_download torrent_flag.

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.

flags controlling aspects of this torrent and how it's added. See
torrent_flags_t for details.

	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.

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.

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

the upload and download rate limits for this torrent, specified in
bytes per second. -1 means unlimited.

the total number of bytes uploaded and downloaded by this torrent so
far.

the number of seconds this torrent has spent in started, finished and
seeding state so far, respectively.

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.

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.

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.

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

peers to add to the torrent, to be tried to be connected to as
bittorrent peers.

peers banned from this torrent. The will not be connected to

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.

this is a bitfield indicating which pieces we already have of this
torrent.

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.

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.

v2 hashes, if known

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.

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.

this is a map of file indices in the torrent and new filenames to be
applied before the torrent is added.

the posix time of the last time payload was received or sent for this
torrent, respectively.

The add_torrent_params contains all the information in a .torrent file
along with all information necessary to add that torrent to a session.
The key fields when adding a torrent are:

* ti - the immutable info-dict part of the torrent
* info_hash - when you don't have the metadata (.torrent file). This
 uniquely identifies the torrent and can validate the info-dict when
 received from the swarm.

In order to add a torrent to a session, one of those fields must be set
in addition to ``save_path``. The add_torrent_params object can then be
passed into one of the ``session::add_torrent()`` overloads or
``session::async_add_torrent()``.

If you only specify the info-hash, the torrent file will be downloaded
from peers, which requires them to support the metadata extension. For
the metadata extension to work, libtorrent must be built with extensions
enabled (``TORRENT_DISABLE_EXTENSIONS`` must not be defined). It also
takes an optional ``name`` argument. This may be left empty in case no
name should be assigned to the torrent. In case it's not, the name is
used for the torrent as long as it doesn't have metadata. See
``torrent_handle::name``.

The ``add_torrent_params`` is also used when requesting resume data for a
torrent. It can be saved to and restored from a file and added back to a
new session. For serialization and de-serialization of
``add_torrent_params`` objects, see read_resume_data() and
write_resume_data().

The ``add_torrent_params`` is also used to represent a parsed .torrent
file. It can be loaded via load_torrent_file(), load_torrent_buffer() and
load_torrent_parsed(). It can be saved via write_torrent_file().

Generates a magnet URI from the specified torrent.

Several fields from the add_torrent_params objects are recorded in the
magnet link. In order to not include them, they have to be cleared before
calling make_magnet_uri(). These fields are used:

``ti``, ``info_hashes``, ``url_seeds``, ``dht_nodes``,
``file_priorities``, ``trackers``, ``name``, ``peers``.

Depending on what the use case for the resulting magnet link is, clearing
``peers`` and ``dht_nodes`` is probably a good idea if the add_torrent_params
came from a running torrent. Those lists may be long and be ephemeral.

If none of the ``info_hashes`` or ``ti`` fields are set, there is not
info-hash available, and a magnet link cannot be created. In this case
make_magnet_uri() returns an empty string.

The recommended way to generate a magnet link from a torrent_handle is to
call save_resume_data(), which will post a save_resume_data_alert
containing an add_torrent_params object. This can then be passed to
make_magnet_uri().

The overload that takes a torrent_handle will make blocking calls to
query information about the torrent. If the torrent handle is invalid,
an empty string is returned.

For more information about magnet links, see magnet-links_.

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.

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

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.

not used by libtorrent. It's intended as a potentially user-facing
identifier of this peer class.

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.

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.

holds settings for a peer class. Used in set_peer_class() and
get_peer_class() calls.

Don't download the file or piece. Partial pieces may still be downloaded when
setting file priorities.

The default priority for files and pieces.

The lowest priority for files and pieces.

The highest priority for files and pieces.

construct a nullptr client data





we don't allow type-unsafe operations

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.










A type describing kinds of sockets involved in various operations or events.

These functions load the content of a .torrent file into an
add_torrent_params object.
The immutable part of a torrent file (the info-dictionary) is stored in
the ``ti`` field in the add_torrent_params object (as a torrent_info
object).
The returned object is suitable to be:

 * added to a session via add_torrent() or async_add_torrent()
 * saved as a .torrent_file via write_torrent_file()
 * turned into a magnet link via make_magnet_uri()

the index of the file

the offset from the start of the file, in bytes

the size of the window, in bytes

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.

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.

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.

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.

renames the file at ``index`` to ``new_filename``. Keep in mind
that filenames are expected to be UTF-8 encoded.

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.

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.

returns the number of files in the file_storage

returns the index of the one-past-end file in the file storage

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.

returns the total number of bytes all the files in this torrent spans

set and get the number of pieces in the torrent

returns the index of the one-past-end piece in the file storage

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

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.

set and get the size of each piece in this torrent. It must be a power of two
and at least 16 kiB.

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

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.

returns the number of blocks in the specified piece, for v2 torrents.

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.

swap all content of *this* with *ti*.

arrange files and padding to match the canonical form required
by BEP 52

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

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.

index of first piece node in the merkle tree

returns the crc32 hash of file_path(index)

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.

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.

this file has the hidden attribute set. This is primarily
a windows attribute

this file has the executable attribute set.

this file is a symbolic link. It should have a link
target string associated with it.

returns a bitmask of flags from file_flags_t that apply
to file at ``index``.

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.

returns the index of the file at the given offset in the torrent

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

returns the piece index the given file starts at

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.

returns true if this torrent contains v2 metadata.

The ``file_storage`` class represents a file list and the piece
size. Everything necessary to interpret a regular bittorrent storage
file structure.

get the ``error_category`` for zip errors

Not an error

the supplied gzip buffer has invalid header

the gzip buffer would inflate to more bytes than the specified
maximum size, and was rejected.

available inflate data did not terminate

output space exhausted before completing inflate

invalid block type (type == 3)

stored block length did not match one's complement

dynamic block code description: too many length or distance codes

dynamic block code description: code lengths codes incomplete

dynamic block code description: repeat lengths with no first length

dynamic block code description: repeat more than specified lengths

dynamic block code description: invalid literal/length code lengths

dynamic block code description: invalid distance code lengths

invalid literal/length or distance code in fixed or dynamic block

distance is too far back in fixed or dynamic block

an unknown error occurred during gzip inflation

the number of error codes

libtorrent uses boost.system's ``error_code`` class to represent errors. libtorrent has
its own error category get_gzip_category() with the error codes defined by error_code_enum.

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.

include this bit if your plugin needs to have on_tick() called

include this bit if your plugin needs to have on_dht_request()
called

include this bit if your plugin needs to have on_alert()
called

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.

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

called when plugin is added to a session

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)

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

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

return true if the add_torrent_params should be added

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

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.


called on startup while loading settings state from the session_params

this is the base class for a session plugin. One primary feature
is that it is notified of all torrents that are added to the session,
and can add its own torrent_plugins.

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

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

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.

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.

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.

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

this is the first time we see this peer

this peer was not added because it was
filtered by the IP filter

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.

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.

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

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

called when the peer is being disconnected.

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.

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

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

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.

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.



called after a choke message has been sent to the peer

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

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

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.

this is not called for web seeds

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

called approximately once every second

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.

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



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


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.

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

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.

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

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

**we** are interested in pieces from this peer.

**we** have choked this peer.

the peer is interested in **us**

the peer has choked **us**.

means that this peer supports the
`extension protocol`__.

__ extension_protocol.html

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.

deprecated synonym for outgoing_connection

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

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

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.

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

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.

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.

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.

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.

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.

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

indicates that this socket is a uTP socket

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

this connection is obfuscated with RC4

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

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

The peer was received from the tracker.

The peer was received from the kademlia DHT.

The peer was received from the peer exchange
extension.

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

The peer was added from the fast resume data.

we received an incoming connection from this peer

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

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

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

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

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

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.

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

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

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

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

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

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

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

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

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

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.

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.

Regular bittorrent connection

HTTP connection using the `BEP 19`_ protocol

HTTP connection using the `BEP 17`_ protocol

the kind of connection this peer uses. See connection_type_t.

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

number of outstanding bytes to read
from disk

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.

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.

the number of pieces this peer has.

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.

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

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

the IP-address to this peer. The type is an asio endpoint. For
more info, see the asio_ documentation.


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.

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

The peer is waiting for the rate limiter.

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.

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

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.

holds information and statistics about one peer
that libtorrent is connected to



http seeds are different from url seeds in the
protocol they use. http seeds follows the original
http seed spec. by John Hoffman

URL and type comparison

URL and type less-than comparison

The URL of the web seed

Optional authentication. If this is set, it's passed
in as HTTP basic auth to the web seed. The format is:
username:password.

Any extra HTTP headers that need to be passed to the web seed

The type of web seed (see type_t)

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

the max size of a .torrent file to load into RAM

the max number of pieces allowed in the torrent

the max recursion depth in the bdecoded structure

the max number of bdecode tokens

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.

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

frees all storage associated with this torrent_info object

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.

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.

	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.

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

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.

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

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

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

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

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

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.

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.

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.

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

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.

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.

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.

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.

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.

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


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

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

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

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

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

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.

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

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.

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

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.

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.

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

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.

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

The settings to configure the session with

the plugins to add to the session as it is constructed

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

function object to construct the storage object for DHT items.

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

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

the IP filter to use for the session. This restricts which peers are allowed
to connect. As if passed to set_ip_filter().

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

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.

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


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

Not an error

Two torrents has files which end up overwriting each other

A piece did not match its piece hash

The .torrent file does not contain a bencoded dictionary at
its top level

The .torrent file does not have an ``info`` dictionary

The .torrent file's ``info`` entry is not a dictionary

The .torrent file does not have a ``piece length`` entry

The .torrent file does not have a ``name`` entry

The .torrent file's name entry is invalid

The length of a file, or of the whole .torrent file is invalid.
Either negative or not an integer

Failed to parse a file entry in the .torrent

The ``pieces`` field is missing or invalid in the .torrent file

The ``pieces`` string has incorrect length

The .torrent file has more pieces than is supported by libtorrent

The metadata (.torrent file) that was received from the swarm
matched the info-hash, but failed to be parsed

The file or buffer is not correctly bencoded

The .torrent file does not contain any files

The string was not properly url-encoded as expected

Operation is not permitted since the session is shutting down

There's already a torrent with that info-hash added to the
session

The supplied torrent_handle is not referring to a valid torrent

The type requested from the entry did not match its type

The specified URI does not contain a valid info-hash

One of the files in the torrent was unexpectedly small. This
might be caused by files being changed by an external process

The URL used an unknown protocol. Currently ``http`` and
``https`` (if built with openssl support) are recognized. For
trackers ``udp`` is recognized as well.

The URL did not conform to URL syntax and failed to be parsed

The peer sent a piece message of length 0

A bencoded structure was corrupt and failed to be parsed

The fast resume file was missing or had an invalid file version
tag

The fast resume file was missing or had an invalid info-hash

The info-hash did not match the torrent

The URL contained an invalid hostname

The URL had an invalid port

The port is blocked by the port-filter, and prevented the
connection

The IPv6 address was expected to end with "]"

The torrent is being destructed, preventing the operation to
succeed

The connection timed out

The peer is upload only, and we are upload only. There's no point
in keeping the connection

The peer is upload only, and we're not interested in it. There's
no point in keeping the connection

The peer sent an unknown info-hash

The torrent is paused, preventing the operation from succeeding

The peer sent an invalid have message, either wrong size or
referring to a piece that doesn't exist in the torrent

The bitfield message had the incorrect size

The peer kept requesting pieces after it was choked, possible
abuse attempt.

The peer sent a piece message that does not correspond to a
piece request sent by the client

memory allocation failed

The torrent is aborted, preventing the operation to succeed

The peer is a connection to ourself, no point in keeping it

The peer sent a piece message with invalid size, either negative
or greater than one block

The peer has not been interesting or interested in us for too
long, no point in keeping it around

The peer has not said anything in a long time, possibly dead

The peer did not send a handshake within a reasonable amount of
time, it might not be a bittorrent peer

The peer has been unchoked for too long without requesting any
data. It might be lying about its interest in us

The peer sent an invalid choke message

The peer send an invalid unchoke message

The peer sent an invalid interested message

The peer sent an invalid not-interested message

The peer sent an invalid piece request message

The peer sent an invalid hash-list message (this is part of the
merkle-torrent extension)

The peer sent an invalid hash-piece message (this is part of the
merkle-torrent extension)

The peer sent an invalid cancel message

The peer sent an invalid DHT port-message

The peer sent an invalid suggest piece-message

The peer sent an invalid have all-message

The peer sent an invalid have none-message

The peer sent an invalid reject message

The peer sent an invalid allow fast-message

The peer sent an invalid extension message ID

The peer sent an invalid message ID

The synchronization hash was not found in the encrypted handshake

The encryption constant in the handshake is invalid

The peer does not support plain text, which is the selected mode

The peer does not support RC4, which is the selected mode

The peer does not support any of the encryption modes that the
client supports

The peer selected an encryption mode that the client did not
advertise and does not support

The pad size used in the encryption handshake is of invalid size

The encryption handshake is invalid

The client is set to not support incoming encrypted connections
and this is an encrypted connection

The client is set to not support incoming regular bittorrent
connections, and this is a regular connection

The client is already connected to this peer-ID

Torrent was removed

The packet size exceeded the upper sanity check-limit


The web server responded with an error

The web server response is missing a location header

The web seed redirected to a path that no longer matches the
.torrent directory structure

The connection was closed because it redirected to a different
URL

The HTTP range header is invalid

The HTTP response did not have a content length

The IP is blocked by the IP filter

At the connection limit

The peer is marked as banned

The torrent is stopping, causing the operation to fail

The peer has sent too many corrupt pieces and is banned

The torrent is not ready to receive peers

The peer is not completely constructed yet

The session is closing, causing the operation to fail

The peer was disconnected in order to leave room for a
potentially better peer

The torrent is finished

No UPnP router found

The metadata message says the metadata exceeds the limit

The peer sent an invalid metadata request message

The peer advertised an invalid metadata size

The peer sent a message with an invalid metadata offset

The peer sent an invalid metadata message

The peer sent a peer exchange message that was too large

The peer sent an invalid peer exchange message

The peer sent an invalid tracker exchange message

The peer sent an pex messages too often. This is a possible
attempt of and attack

The operation failed because it requires the torrent to have
the metadata (.torrent file) and it doesn't have it yet.
This happens for magnet links before they have downloaded the
metadata, and also torrents added by URL.

The peer sent an invalid ``dont_have`` message. The don't have
message is an extension to allow peers to advertise that the
no longer has a piece they previously had.

The peer tried to connect to an SSL torrent without connecting
over SSL.

The peer tried to connect to a torrent with a certificate
for a different torrent.

the torrent is not an SSL torrent, and the operation requires
an SSL torrent

peer was banned because its listen port is within a banned port
range, as specified by the port_filter.

The session_handle is not referring to a valid session_impl

the listen socket associated with this request was closed









The resume data file is missing the ``file sizes`` entry

The resume data file ``file sizes`` entry is empty

The resume data file is missing the ``pieces`` and ``slots`` entry

The number of files in the resume data does not match the number
of files in the torrent

One of the files on disk has a different size than in the fast
resume file

One of the files on disk has a different timestamp than in the
fast resume file

The resume data file is not a dictionary

The ``blocks per piece`` entry is invalid in the resume data file

The resume file is missing the ``slots`` entry, which is required
for torrents with compact allocation. *DEPRECATED*

The resume file contains more slots than the torrent

The ``slot`` entry is invalid in the resume data

One index in the ``slot`` list is invalid

The pieces on disk needs to be re-ordered for the specified
allocation mode. This happens if you specify sparse allocation
and the files on disk are using compact storage. The pieces needs
to be moved to their right position. *DEPRECATED*

this error is returned when asking to save resume data and
specifying the flag to only save when there's anything new to save
(torrent_handle::only_if_modified) and there wasn't anything changed.

The HTTP header was not correctly formatted

The HTTP response was in the 300-399 range but lacked a location
header

The HTTP response was encoded with gzip or deflate but
decompressing it failed

The URL specified an i2p address, but no i2p router is configured

i2p acceptor is not available yet, can't announce without endpoint

The tracker URL doesn't support transforming it into a scrape
URL. i.e. it doesn't contain "announce.

invalid tracker response

invalid peer dictionary entry. Not a dictionary

tracker sent a failure message

missing or invalid ``files`` entry

missing or invalid ``hash`` entry

missing or invalid ``peers`` and ``peers6`` entry

UDP tracker response packet has invalid size

invalid transaction id in UDP tracker response

invalid action field in UDP tracker response

skipped announce (because it's assumed to be unreachable over the
given source network interface)

random number generation failed

blocked by SSRF mitigation

blocked because IDNA host names are banned

the torrent file has an unknown meta version

the v2 torrent file has no file tree

the torrent contains v2 keys but does not specify meta version 2

the v1 and v2 file metadata does not match

one or more files are missing piece layer hashes

a piece layer has the wrong size or failed hash check

a v2 file entry has no root hash

the v1 and v2 hashes do not describe the same data

a file in the v2 metadata has the pad attribute set

the number of error codes

libtorrent uses boost.system's ``error_code`` class to represent
errors. libtorrent has its own error category
libtorrent_category() with the error codes defined by
error_code_enum.


















HTTP errors are reported in the libtorrent::http_category, with error code enums in
the ``libtorrent::errors`` namespace.

return the instance of the libtorrent_error_category which
maps libtorrent error codes to human readable error messages.

returns the error_category for HTTP errors

explicitly converts to true if this object represents an error, and
false if it does not.

the error that occurred

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.

A code from operation_t enum, indicating what
kind of operation failed.

used by storage to return errors
also includes which underlying file the
error happened on

constructs a memory mapped file disk I/O object.

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.

See documentation of internal random_bytes

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.

Creates a signature of the given message with the given key pair.

Verifies the signature on the given message using ``pk``

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

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


This member function set the counters to zero.

This structure hold the relevant counters for the storage

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.

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.

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.

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.

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.


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.

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.

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.


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.

This function is called periodically (non-constant frequency).

For implementers:
Use this functions for expire peers or items or any other
storage cleanup.

return stats counters for the store

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.

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.

announce to DHT as a seed

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.

Specify the port number for the SSL listen socket in the DHT announce.

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.


the bootstrap nodes saved from the buckets node

the bootstrap nodes saved from the IPv6 buckets node


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`_


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

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

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

