Version: 0.0.1

home

Table of contents

[report issue]

session_params

Declared in "libtorrent/session_params.hpp"

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

struct session_params
{
   session_params (settings_pack const& sp);
   session_params (settings_pack&& sp);
   session_params ();
   session_params (settings_pack&& sp
      , std::vector<std::shared_ptr<plugin>> exts);
   session_params (settings_pack const& sp
      , std::vector<std::shared_ptr<plugin>> exts);

   settings_pack settings;
   session_flags_t flags {};
   std::vector<std::shared_ptr<plugin>> extensions;
   dht::dht_state dht_state;
   dht::dht_storage_constructor_type dht_storage_constructor;
   disk_io_constructor_type disk_io_constructor;
   std::map<std::string, std::string> ext_state;
   libtorrent::ip_filter ip_filter;
};
[report issue]

session_params()

session_params (settings_pack const& sp);
session_params (settings_pack&& sp);
session_params ();

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

[report issue]

session_params()

session_params (settings_pack&& sp
      , std::vector<std::shared_ptr<plugin>> exts);
session_params (settings_pack const& sp
      , std::vector<std::shared_ptr<plugin>> exts);

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

[report issue]
settings
The settings to configure the session with
[report issue]
flags
specifies flags affecting the session construction. E.g. they can be used to start a session in paused mode (by passing in session::paused).
[report issue]
extensions
the plugins to add to the session as it is constructed
[report issue]
dht_state
DHT node ID and node addresses to bootstrap the DHT with.
[report issue]
dht_storage_constructor
function object to construct the storage object for DHT items.
[report issue]
disk_io_constructor
function object to create the disk I/O subsystem. Defaults to default_disk_io_constructor.
[report issue]
ext_state
this container can be used by extensions/plugins to store settings. It's primarily here to make it convenient to save and restore state across sessions, using read_session_params() and write_session_params().
[report issue]
ip_filter
the IP filter to use for the session. This restricts which peers are allowed to connect. As if passed to set_ip_filter().
[report issue]

session_handle

Declared in "libtorrent/session_handle.hpp"

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

struct session_handle
{
   bool is_valid () const;
   session_params session_state (save_state_flags_t flags = save_state_flags_t::all()) const;
   void post_session_stats ();
   void post_dht_stats ();
   void set_dht_state (dht::dht_state&& st);
   void set_dht_state (dht::dht_state const& st);
   bool is_dht_running () const;
   void set_dht_storage (dht::dht_storage_constructor_type sc);
   void add_dht_node (std::pair<std::string, int> const& node);
   void dht_get_item (sha256_hash const& target);
   void dht_get_item (std::array<char, 32> key
      , std::string salt = std::string());
   sha256_hash dht_put_item (entry data);
   void dht_put_item (std::array<char, 32> key
      , std::function<void(entry&, std::array<char, 64>&
      , std::int64_t&, std::string const&)> cb
      , std::string salt = std::string());
   void dht_live_nodes (sha256_hash const& nid);
   void add_extension (std::shared_ptr<plugin> ext);
   ip_filter get_ip_filter () const;
   void set_ip_filter (ip_filter f);
   void set_port_filter (port_filter const& f);
   bool is_listening () const;
   unsigned short ssl_listen_port () const;
   unsigned short listen_port () const;
   ip_filter get_peer_class_filter () const;
   void set_peer_class_filter (ip_filter const& f);
   void set_peer_class_type_filter (peer_class_type_filter const& f);
   peer_class_type_filter get_peer_class_type_filter () const;
   peer_class_t create_peer_class (char const* name);
   void delete_peer_class (peer_class_t cid);
   void set_peer_class (peer_class_t cid, peer_class_info const& pci);
   peer_class_info get_peer_class (peer_class_t cid) const;
   settings_pack get_settings () const;
   void apply_settings (settings_pack const&);
   void apply_settings (settings_pack&&);
   void pop_alerts (std::vector<alert*>* alerts);
   void set_alert_notify (std::function<void()> const& fun);
   alert* wait_for_alert (time_duration max_wait);
   void delete_port_mapping (port_mapping_t handle);
   std::vector<port_mapping_t> add_port_mapping (portmap_protocol t, int external_port, int local_port);
   void reopen_network_sockets (reopen_network_flags_t options = reopen_map_ports);
   std::shared_ptr<aux::session_impl> native_handle () const;

   static constexpr save_state_flags_t save_settings  = 0_bit;
   static constexpr save_state_flags_t save_dht_state  = 2_bit;
   static constexpr save_state_flags_t save_extension_state  = 11_bit;
   static constexpr save_state_flags_t save_ip_filter  = 12_bit;
   static constexpr peer_class_t global_peer_class_id {0};
   static constexpr peer_class_t tcp_peer_class_id {1};
   static constexpr peer_class_t local_peer_class_id {2};
   static constexpr remove_flags_t delete_files  = 0_bit;
   static constexpr remove_flags_t delete_partfile  = 1_bit;
   static constexpr session_flags_t paused  = 2_bit;
   static constexpr portmap_protocol udp  = portmap_protocol::udp;
   static constexpr portmap_protocol tcp  = portmap_protocol::tcp;
   static constexpr reopen_network_flags_t reopen_map_ports  = 0_bit;
};
[report issue]

is_valid()

bool is_valid () const;

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

[report issue]

session_state()

session_params session_state (save_state_flags_t flags = save_state_flags_t::all()) const;

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

[report issue]

post_session_stats()

void post_session_stats ();

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

For more information, see the session statistics section.

[report issue]

post_dht_stats()

void post_dht_stats ();

This will cause a dht_stats_alert to be posted.

[report issue]

set_dht_state()

void set_dht_state (dht::dht_state&& st);
void set_dht_state (dht::dht_state const& st);

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

[report issue]

is_dht_running()

bool is_dht_running () const;

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

[report issue]

set_dht_storage()

void set_dht_storage (dht::dht_storage_constructor_type sc);

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

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

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

[report issue]

add_dht_node()

void add_dht_node (std::pair<std::string, int> const& node);

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

[report issue]

dht_get_item()

void dht_get_item (sha256_hash const& target);

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

[report issue]

dht_get_item()

void dht_get_item (std::array<char, 32> key
      , std::string salt = std::string());

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

[report issue]

dht_put_item()

sha256_hash dht_put_item (entry data);

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

[report issue]

dht_put_item()

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

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

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

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

[report issue]

dht_live_nodes()

void dht_live_nodes (sha256_hash const& nid);

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

[report issue]

get_ip_filter() set_ip_filter()

ip_filter get_ip_filter () const;
void set_ip_filter (ip_filter f);

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

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

[report issue]

set_port_filter()

void set_port_filter (port_filter const& f);

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

[report issue]

is_listening() listen_port() ssl_listen_port()

bool is_listening () const;
unsigned short ssl_listen_port () const;
unsigned short listen_port () const;

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

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

[report issue]

set_peer_class_filter() get_peer_class_filter()

ip_filter get_peer_class_filter () const;
void set_peer_class_filter (ip_filter const& f);

Sets the peer class filter for this session. All new peer connections will take this into account and be added to the peer classes specified by this filter, based on the peer's IP address.

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

For more info, see ip_filter.

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

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

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

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

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

The get_peer_class_filter() function returns the current filter.

For more information, see peer classes.

[report issue]

set_peer_class_type_filter() get_peer_class_type_filter()

void set_peer_class_type_filter (peer_class_type_filter const& f);
peer_class_type_filter get_peer_class_type_filter () const;

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

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

The order of these rules being applied are:

  1. peer-class IP filter
  2. peer-class type filter, removing classes
  3. peer-class type filter, adding classes

For more information, see peer classes.

[report issue]

create_peer_class()

peer_class_t create_peer_class (char const* name);

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

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

For more information on peer classes, see peer classes.

[report issue]

delete_peer_class()

void delete_peer_class (peer_class_t cid);

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

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

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

For more information on peer classes, see peer classes.

[report issue]

get_peer_class() set_peer_class()

void set_peer_class (peer_class_t cid, peer_class_info const& pci);
peer_class_info get_peer_class (peer_class_t cid) const;

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

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

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

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

For more information, see peer classes.

[report issue]

apply_settings() get_settings()

settings_pack get_settings () const;
void apply_settings (settings_pack const&);
void apply_settings (settings_pack&&);

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

[report issue]

pop_alerts() set_alert_notify() wait_for_alert()

void pop_alerts (std::vector<alert*>* alerts);
void set_alert_notify (std::function<void()> const& fun);
alert* wait_for_alert (time_duration max_wait);

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

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

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

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

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

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

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

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

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

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

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

[report issue]

delete_port_mapping() add_port_mapping()

void delete_port_mapping (port_mapping_t handle);
std::vector<port_mapping_t> add_port_mapping (portmap_protocol t, int external_port, int local_port);

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

[report issue]

reopen_network_sockets()

void reopen_network_sockets (reopen_network_flags_t options = reopen_map_ports);

Instructs the session to reopen all listen and outgoing sockets.

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

[report issue]

native_handle()

std::shared_ptr<aux::session_impl> native_handle () const;

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

[report issue]
save_settings
saves settings (i.e. the settings_pack)
[report issue]
save_dht_state
saves dht state such as nodes and node-id, possibly accelerating joining the DHT if provided at next session startup.
[report issue]
save_extension_state
load or save state from plugins
[report issue]
save_ip_filter
load or save the IP filter set on the session
[report issue]
global_peer_class_id tcp_peer_class_id local_peer_class_id
built-in peer classes
[report issue]
delete_files
delete the files belonging to the torrent from disk. including the part-file, if there is one
[report issue]
delete_partfile
delete just the part-file associated with this torrent
[report issue]
paused
when set, the session will start paused. Call session_handle::resume() to start
[report issue]
udp tcp
protocols used by add_port_mapping()
[report issue]
reopen_map_ports
This option indicates if the ports are mapped using natpmp and upnp. If mapping was already made, they are deleted and added again. This only works if natpmp and/or upnp are configured to be enable.
[report issue]

session_proxy

Declared in "libtorrent/session.hpp"

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

struct session_proxy
{
   session_proxy& operator= (session_proxy&&) & noexcept;
   session_proxy& operator= (session_proxy const&) &;
   session_proxy ();
   session_proxy (session_proxy const&);
   ~session_proxy ();
   session_proxy (session_proxy&&) noexcept;
};
[report issue]

session_proxy() operator=() ~session_proxy()

session_proxy& operator= (session_proxy&&) & noexcept;
session_proxy& operator= (session_proxy const&) &;
session_proxy ();
session_proxy (session_proxy const&);
~session_proxy ();
session_proxy (session_proxy&&) noexcept;

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

[report issue]

session

Declared in "libtorrent/session.hpp"

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

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

see apply_settings().

struct session : session_handle
{
   explicit session (session_params&& params);
   explicit session (session_params const& params);
   session ();
   session (session_params const& params, io_context& ios);
   session (session_params&& params, io_context& ios);
   ~session ();
   session_proxy abort ();
};
[report issue]

session()

explicit session (session_params&& params);
explicit session (session_params const& params);

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.

[report issue]

session()

session (session_params const& params, io_context& ios);
session (session_params&& params, io_context& ios);

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

Warning

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

[report issue]

~session()

~session ();

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

[report issue]

abort()

session_proxy abort ();

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

struct session_proxy {};
[report issue]

write_session_params_buf() write_session_params() read_session_params()

Declared in "libtorrent/session_params.hpp"

entry write_session_params (session_params const& sp
   , save_state_flags_t flags = save_state_flags_t::all());
std::vector<char> write_session_params_buf (session_params const& sp
   , save_state_flags_t flags = save_state_flags_t::all());
session_params read_session_params (bdecode_node const& e
   , save_state_flags_t flags = save_state_flags_t::all());
session_params read_session_params (span<char const> buf
   , save_state_flags_t flags = save_state_flags_t::all());

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

[report issue]

default_disk_io_constructor()

Declared in "libtorrent/session.hpp"

std::unique_ptr<disk_interface> default_disk_io_constructor (
   io_context& ios, settings_interface const&, counters& cnt);

the constructor function for the default storage. On systems that support memory mapped files (and a 64 bit address space) the memory mapped storage will be constructed, otherwise the portable posix storage.

[report issue]

stats_metric

Declared in "libtorrent/session_stats.hpp"

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

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

session_stats_metrics()

Declared in "libtorrent/session_stats.hpp"

std::vector<stats_metric> session_stats_metrics ();

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

[report issue]

find_metric_idx()

Declared in "libtorrent/session_stats.hpp"

int find_metric_idx (string_view name);

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

[report issue]

enum metric_type_t

Declared in "libtorrent/session_stats.hpp"

name value description
counter 0  
gauge 1  

The pop_alerts() function on session is the main interface for retrieving alerts (warnings, messages and errors from libtorrent). If no alerts have been posted by libtorrent pop_alerts() will return an empty list.

By default, only errors are reported. settings_pack::alert_mask can be used to specify which kinds of events should be reported. The alert mask is a combination of the alert_category_t flags in the alert class.

Every alert belongs to one or more category. There is a cost associated with posting alerts. Only alerts that belong to an enabled category are posted. Setting the alert bitmask to 0 will disable all alerts (except those that are non-discardable). Alerts that are responses to API calls such as save_resume_data() and post_session_stats() are non-discardable and will be posted even if their category is disabled.

There are other alert base classes that some alerts derive from, all the alerts that are generated for a specific torrent are derived from torrent_alert, and tracker events derive from tracker_alert.

Alerts returned by pop_alerts() are only valid until the next call to pop_alerts(). You may not copy an alert object to access it after the next call to pop_alerts(). Internal members of alerts also become invalid once pop_alerts() is called again.

[report issue]

alert

Declared in "libtorrent/alert.hpp"

The alert class is the base class that specific messages are derived from. alert types are not copyable, and cannot be constructed by the client. The pointers returned by libtorrent are short lived (the details are described under session_handle::pop_alerts())

struct alert
{
   time_point timestamp () const;
   virtual int type () const noexcept = 0;
   virtual char const* what () const noexcept = 0;
   virtual std::string message () const = 0;
   virtual alert_category_t category () const noexcept = 0;

   static inline constexpr alert_category_t error_notification  = 0_bit;
   static inline constexpr alert_category_t peer_notification  = 1_bit;
   static inline constexpr alert_category_t port_mapping_notification  = 2_bit;
   static inline constexpr alert_category_t storage_notification  = 3_bit;
   static inline constexpr alert_category_t tracker_notification  = 4_bit;
   static inline constexpr alert_category_t connect_notification  = 5_bit;
   static inline constexpr alert_category_t status_notification  = 6_bit;
   static inline constexpr alert_category_t ip_block_notification  = 8_bit;
   static inline constexpr alert_category_t performance_warning  = 9_bit;
   static inline constexpr alert_category_t dht_notification  = 10_bit;
   static inline constexpr alert_category_t session_log_notification  = 13_bit;
   static inline constexpr alert_category_t torrent_log_notification  = 14_bit;
   static inline constexpr alert_category_t peer_log_notification  = 15_bit;
   static inline constexpr alert_category_t incoming_request_notification  = 16_bit;
   static inline constexpr alert_category_t dht_log_notification  = 17_bit;
   static inline constexpr alert_category_t dht_operation_notification  = 18_bit;
   static inline constexpr alert_category_t port_mapping_log_notification  = 19_bit;
   static inline constexpr alert_category_t picker_log_notification  = 20_bit;
   static inline constexpr alert_category_t file_progress_notification  = 21_bit;
   static inline constexpr alert_category_t piece_progress_notification  = 22_bit;
   static inline constexpr alert_category_t upload_notification  = 23_bit;
   static inline constexpr alert_category_t block_progress_notification  = 24_bit;
   static inline constexpr alert_category_t all_categories  = alert_category_t::all();
};
[report issue]

timestamp()

time_point timestamp () const;

a timestamp is automatically created in the constructor

[report issue]

type()

virtual int type () const noexcept = 0;

returns an integer that is unique to this alert type. It can be compared against a specific alert by querying a static constant called alert_type in the alert. It can be used to determine the run-time type of an alert* in order to cast to that alert type and access specific members.

e.g:

std::vector<alert*> alerts;
ses.pop_alerts(&alerts);
for (alert* a : alerts) {
        switch (a->type()) {

                case read_piece_alert::alert_type:
                {
                        auto* p = static_cast<read_piece_alert*>(a);
                        if (p->ec) {
                                // read_piece failed
                                break;
                        }
                        // use p
                        break;
                }
                case file_renamed_alert::alert_type:
                {
                        // etc...
                }
        }
}
[report issue]

what()

virtual char const* what () const noexcept = 0;

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

[report issue]

message()

virtual std::string message () const = 0;

generate a string describing the alert and the information bundled with it. This is mainly intended for debug and development use. It is not suitable to use this for applications that may be localized. Instead, handle each alert type individually and extract and render the information from the alert depending on the locale.

[report issue]

category()

virtual alert_category_t category () const noexcept = 0;

returns a bitmask specifying which categories this alert belong to.

[report issue]

dht_routing_bucket

Declared in "libtorrent/alert_types.hpp"

struct to hold information about a single DHT routing table bucket

struct dht_routing_bucket
{
   int num_nodes;
   int num_replacements;
   int last_active;
};
[report issue]
num_nodes num_replacements
the total number of nodes and replacement nodes in the routing table
[report issue]
last_active
number of seconds since last activity
[report issue]

torrent_alert

Declared in "libtorrent/alert_types.hpp"

This is a base class for alerts that are associated with a specific torrent. It contains a handle to the torrent.

Note that by the time the client receives a torrent_alert, its handle member may be invalid.

struct torrent_alert : alert
{
   std::string message () const override;
   char const* torrent_name () const;

   torrent_handle handle;
};
[report issue]

message()

std::string message () const override;

returns the message associated with this alert

[report issue]
handle
The torrent_handle pointing to the torrent this alert is associated with.
[report issue]

peer_alert

Declared in "libtorrent/alert_types.hpp"

The peer alert is a base class for alerts that refer to a specific peer. It includes all the information to identify the peer. i.e. ip and peer-id.

struct peer_alert : torrent_alert
{
   std::string message () const override;

   aux::noexcept_movable<tcp::endpoint> endpoint;
   peer_id pid;
};
[report issue]
endpoint
The peer's IP address and port.
[report issue]
pid
the peer ID, if known.
[report issue]

udp_error_alert

Declared in "libtorrent/alert_types.hpp"

This alert is posted when there is an error on a UDP socket. The UDP sockets are used for all uTP, DHT and UDP tracker traffic. They are global to the session.

struct udp_error_alert final : alert
{
   std::string message () const override;

   static inline constexpr alert_category_t static_category  = alert_category::error;
   aux::noexcept_movable<udp::endpoint> endpoint;
   operation_t operation;
   error_code const error;
};
[report issue]
endpoint
the source address associated with the error (if any)
[report issue]
operation
the operation that failed
[report issue]
error
the error code describing the error
[report issue]

external_ip_alert

Declared in "libtorrent/alert_types.hpp"

Whenever libtorrent learns about the machines external IP, this alert is generated. The external IP address can be acquired from the tracker (if it supports that) or from peers that supports the extension protocol. The address can be accessed through the external_address member.

struct external_ip_alert final : alert
{
   std::string message () const override;

   static inline constexpr alert_category_t static_category  = alert_category::status;
   aux::noexcept_movable<address> external_address;
};
[report issue]
external_address
the IP address that is believed to be our external IP
[report issue]

listen_failed_alert

Declared in "libtorrent/alert_types.hpp"

This alert is generated when none of the ports, given in the port range, to session can be opened for listening. The listen_interface member is the interface that failed, error is the error code describing the failure.

In the case an endpoint was created before generating the alert, it is represented by address and port. The combinations of socket type and operation in which such address and port are not valid are: accept - i2p accept - socks5 enum_if - tcp

libtorrent may sometimes try to listen on port 0, if all other ports failed. Port 0 asks the operating system to pick a port that's free). If that fails you may see a listen_failed_alert with port 0 even if you didn't ask to listen on it.

struct listen_failed_alert final : alert
{
   std::string message () const override;
   char const* listen_interface () const;

   static inline constexpr alert_category_t static_category  = alert_category::status | alert_category::error;
   error_code const error;
   operation_t op;
   lt::socket_type_t const socket_type;
   aux::noexcept_movable<lt::address> address;
   int const port;
};
[report issue]

listen_interface()

char const* listen_interface () const;

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

[report issue]
error
the error the system returned
[report issue]
op
the underlying operation that failed
[report issue]
socket_type
the type of listen socket this alert refers to.
[report issue]
address
the address libtorrent attempted to listen on see alert documentation for validity of this value
[report issue]
port
the port libtorrent attempted to listen on see alert documentation for validity of this value
[report issue]

listen_succeeded_alert

Declared in "libtorrent/alert_types.hpp"

This alert is posted when the listen port succeeds to be opened on a particular interface. address and port is the endpoint that successfully was opened for listening.

struct listen_succeeded_alert final : alert
{
   std::string message () const override;

   static inline constexpr alert_category_t static_category  = alert_category::status;
   aux::noexcept_movable<lt::address> address;
   int const port;
   lt::socket_type_t const socket_type;
};
[report issue]
address
the address libtorrent ended up listening on. This address refers to the local interface.
[report issue]
port
the port libtorrent ended up listening on.
[report issue]
socket_type
the type of listen socket this alert refers to.
[report issue]

portmap_error_alert

Declared in "libtorrent/alert_types.hpp"

This alert is generated when a NAT router was successfully found but some part of the port mapping request failed. It contains a text message that may help the user figure out what is wrong. This alert is not generated in case it appears the client is not running on a NAT:ed network or if it appears there is no NAT router that can be remote controlled to add port mappings.

struct portmap_error_alert final : alert
{
   std::string message () const override;

   static inline constexpr alert_category_t static_category  = alert_category::port_mapping
   | alert_category::error;
   port_mapping_t const mapping;
   portmap_transport map_transport;
   aux::noexcept_movable<address> local_address;
   error_code const error;
};
[report issue]
mapping
refers to the mapping index of the port map that failed, i.e. the index returned from add_mapping().
[report issue]
map_transport
UPnP or NAT-PMP
[report issue]
local_address
the local network the port mapper is running on
[report issue]
error
tells you what failed.
[report issue]

portmap_alert

Declared in "libtorrent/alert_types.hpp"

This alert is generated when a NAT router was successfully found and a port was successfully mapped on it. On a NAT:ed network with a NAT-PMP capable router, this is typically generated once when mapping the TCP port and, if DHT is enabled, when the UDP port is mapped.

struct portmap_alert final : alert
{
   std::string message () const override;

   static inline constexpr alert_category_t static_category  = alert_category::port_mapping;
   port_mapping_t const mapping;
   int const external_port;
   portmap_protocol const map_protocol;
   portmap_transport const map_transport;
   aux::noexcept_movable<address> local_address;
};
[report issue]
mapping
refers to the mapping index of the port map that failed, i.e. the index returned from add_mapping().
[report issue]
external_port
the external port allocated for the mapping.
[report issue]
local_address
the local network the port mapper is running on
[report issue]

portmap_log_alert

Declared in "libtorrent/alert_types.hpp"

This alert is generated to log informational events related to either UPnP or NAT-PMP. They contain a log line and the type (0 = NAT-PMP and 1 = UPnP). Displaying these messages to an end user is only useful for debugging the UPnP or NAT-PMP implementation. This alert is only posted if the alert_category::port_mapping_log flag is enabled in the alert mask.

struct portmap_log_alert final : alert
{
   std::string message () const override;
   char const* log_message () const;

   static inline constexpr alert_category_t static_category  = alert_category::port_mapping_log;
   portmap_transport const map_transport;
   aux::noexcept_movable<address> local_address;
};
[report issue]

log_message()

char const* log_message () const;

the message associated with this log line

[report issue]
local_address
the local network the port mapper is running on
[report issue]

dht_announce_alert

Declared in "libtorrent/alert_types.hpp"

This alert is generated when a DHT node announces to an info-hash on our DHT node. It belongs to the alert_category::dht category.

struct dht_announce_alert final : alert
{
   std::string message () const override;

   static inline constexpr alert_category_t static_category  = alert_category::dht;
   aux::noexcept_movable<address> ip;
   int port;
   sha256_hash info_hash;
};
[report issue]

dht_get_peers_alert

Declared in "libtorrent/alert_types.hpp"

This alert is generated when a DHT node sends a get_peers message to our DHT node. It belongs to the alert_category::dht category.

struct dht_get_peers_alert final : alert
{
   std::string message () const override;

   static inline constexpr alert_category_t static_category  = alert_category::dht;
   sha256_hash info_hash;
};
[report issue]

dht_bootstrap_alert

Declared in "libtorrent/alert_types.hpp"

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

struct dht_bootstrap_alert final : alert
{
   std::string message () const override;

   static inline constexpr alert_category_t static_category  = alert_category::dht;
};
[report issue]

torrent_error_alert

Declared in "libtorrent/alert_types.hpp"

This is posted whenever a torrent is transitioned into the error state.

struct torrent_error_alert final : torrent_alert
{
   std::string message () const override;
   char const* filename () const;

   static inline constexpr alert_category_t static_category  = alert_category::error | alert_category::status;
   error_code const error;
};
[report issue]

filename()

char const* filename () const;

the filename (or object) the error occurred on.

[report issue]
error
specifies which error the torrent encountered.
[report issue]

incoming_connection_alert

Declared in "libtorrent/alert_types.hpp"

The incoming connection alert is posted every time we successfully accept an incoming connection, through any mean. The most straight-forward ways of accepting incoming connections are through the TCP listen socket and the UDP listen socket for uTP sockets. However, connections may also be accepted through a Socks5 or i2p listen socket, or via an SSL listen socket.

struct incoming_connection_alert final : alert
{
   std::string message () const override;

   static inline constexpr alert_category_t static_category  = alert_category::peer;
   socket_type_t socket_type;
   aux::noexcept_movable<tcp::endpoint> endpoint;
};
[report issue]
socket_type
tells you what kind of socket the connection was accepted
[report issue]
endpoint
is the IP address and port the connection came from.
[report issue]

state_update_alert

Declared in "libtorrent/alert_types.hpp"

This alert is only posted when requested by the user, by calling session::post_torrent_updates() on the session. It contains the torrent status of all torrents that changed since last time this message was posted. Its category is alert_category::status, but it's not subject to filtering, since it's only manually posted anyway.

struct state_update_alert final : alert
{
   std::string message () const override;

   static inline constexpr alert_category_t static_category  = alert_category::status;
   std::vector<torrent_status> status;
};
[report issue]
status
contains the torrent status of all torrents that changed since last time this message was posted. Note that you can map a torrent status to a specific torrent via its handle member. The receiving end is suggested to have all torrents sorted by the torrent_handle or hashed by it, for efficient updates.
[report issue]

session_stats_alert

Declared in "libtorrent/alert_types.hpp"

The session_stats_alert is posted when the user requests session statistics by calling post_session_stats() on the session object. This alert does not have a category, since it's only posted in response to an API call. It is not subject to the alert_mask filter.

the message() member function returns a string representation of the values that properly match the line returned in session_stats_header_alert::message().

this specific output is parsed by tools/parse_session_stats.py if this is changed, that parser should also be changed

struct session_stats_alert final : alert
{
   std::string message () const override;
   span<std::int64_t const> counters () const;

   static inline constexpr alert_category_t static_category  = {};
};
[report issue]

counters()

span<std::int64_t const> counters () const;

An array are a mix of counters and gauges, which meanings can be queries via the session_stats_metrics() function on the session. The mapping from a specific metric to an index into this array is constant for a specific version of libtorrent, but may differ for other versions. The intended usage is to request the mapping, i.e. call session_stats_metrics(), once on startup, and then use that mapping to interpret these values throughout the process' runtime.

For more information, see the session statistics section.

[report issue]

dht_error_alert

Declared in "libtorrent/alert_types.hpp"

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

struct dht_error_alert final : alert
{
   std::string message () const override;

   static inline constexpr alert_category_t static_category  = alert_category::error | alert_category::dht;
   error_code error;
   operation_t op;
};
[report issue]
error
the error code
[report issue]
op
the operation that failed
[report issue]

dht_immutable_item_alert

Declared in "libtorrent/alert_types.hpp"

this alert is posted as a response to a call to session::get_item(), specifically the overload for looking up immutable items in the DHT.

struct dht_immutable_item_alert final : alert
{
   std::string message () const override;

   static inline constexpr alert_category_t static_category  = alert_category::dht;
   sha256_hash target;
   entry item;
};
[report issue]
target
the target hash of the immutable item. This must match the SHA-2 hash of the bencoded form of item.
[report issue]
item
the data for this item
[report issue]

dht_mutable_item_alert

Declared in "libtorrent/alert_types.hpp"

this alert is posted as a response to a call to session::get_item(), specifically the overload for looking up mutable items in the DHT.

struct dht_mutable_item_alert final : alert
{
   std::string message () const override;

   static inline constexpr alert_category_t static_category  = alert_category::dht;
   std::array<char, 32> key;
   std::array<char, 64> signature;
   std::int64_t seq;
   std::string salt;
   entry item;
   bool authoritative;
};
[report issue]
key
the public key that was looked up
[report issue]
signature
the signature of the data. This is not the signature of the plain encoded form of the item, but it includes the sequence number and possibly the hash as well. See the dht_store document for more information. This is primarily useful for echoing back in a store request.
[report issue]
seq
the sequence number of this item
[report issue]
salt
the salt, if any, used to lookup and store this item. If no salt was used, this is an empty string
[report issue]
item
the data for this item
[report issue]
authoritative
the last response for mutable data is authoritative.
[report issue]

dht_put_alert

Declared in "libtorrent/alert_types.hpp"

this is posted when a DHT put operation completes. This is useful if the client is waiting for a put to complete before shutting down for instance.

struct dht_put_alert final : alert
{
   std::string message () const override;

   static inline constexpr alert_category_t static_category  = alert_category::dht;
   sha256_hash target;
   std::array<char, 32> public_key;
   std::array<char, 64> signature;
   std::string salt;
   std::int64_t seq;
   int num_success;
};
[report issue]
target
the target hash the item was stored under if this was an immutable item.
[report issue]
public_key signature salt seq
if a mutable item was stored, these are the public key, signature, salt and sequence number the item was stored under.
[report issue]
num_success
DHT put operation usually writes item to k nodes, maybe the node is stale so no response, or the node doesn't support 'put', or the token for write is out of date, etc. num_success is the number of successful responses we got from the puts.
[report issue]

dht_outgoing_get_peers_alert

Declared in "libtorrent/alert_types.hpp"

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

struct dht_outgoing_get_peers_alert final : alert
{
   std::string message () const override;

   static inline constexpr alert_category_t static_category  = alert_category::dht;
   sha256_hash info_hash;
   sha256_hash obfuscated_info_hash;
   aux::noexcept_movable<udp::endpoint> endpoint;
};
[report issue]
info_hash
the info_hash of the torrent we're looking for peers for.
[report issue]
obfuscated_info_hash
if this was an obfuscated lookup, this is the info-hash target actually sent to the node.
[report issue]
endpoint
the endpoint we're sending this query to
[report issue]

log_alert

Declared in "libtorrent/alert_types.hpp"

This alert is posted by some session wide event. Its main purpose is trouble shooting and debugging. It's not enabled by the default alert mask and is enabled by the alert_category::session_log bit. Furthermore, it's by default disabled as a build configuration.

struct log_alert final : alert
{
   std::string message () const override;
   char const* log_message () const;

   static inline constexpr alert_category_t static_category  = alert_category::session_log;
};
[report issue]

log_message()

char const* log_message () const;

returns the log message

[report issue]

peer_log_alert

Declared in "libtorrent/alert_types.hpp"

This alert is posted by events specific to a peer. It's meant to be used for trouble shooting and debugging. It's not enabled by the default alert mask and is enabled by the alert_category::peer_log bit. By default it is disabled as a build configuration.

struct peer_log_alert final : peer_alert
{
   std::string message () const override;
   char const* log_message () const;

   enum direction_t
   {
      incoming_message,
      outgoing_message,
      incoming,
      outgoing,
      info,
   };

   static inline constexpr alert_category_t static_category  = alert_category::peer_log;
   char const* event_type;
   direction_t direction;
};
[report issue]

log_message()

char const* log_message () const;

returns the log message

[report issue]

enum direction_t

Declared in "libtorrent/alert_types.hpp"

name value description
incoming_message 0  
outgoing_message 1  
incoming 2  
outgoing 3  
info 4  
[report issue]
event_type
string literal indicating the kind of event. For messages, this is the message name.
[report issue]

dht_lookup

Declared in "libtorrent/alert_types.hpp"

holds statistics about a current dht_lookup operation. a DHT lookup is the traversal of nodes, looking up a set of target nodes in the DHT for retrieving and possibly storing information in the DHT

struct dht_lookup
{
   char const* type;
   int outstanding_requests;
   int timeouts;
   int responses;
   int branch_factor;
   int nodes_left;
   int last_sent;
   int first_timeout;
   sha1_hash target;
};
[report issue]
type
string literal indicating which kind of lookup this is
[report issue]
outstanding_requests
the number of outstanding request to individual nodes this lookup has right now
[report issue]
timeouts
the total number of requests that have timed out so far for this lookup
[report issue]
responses
the total number of responses we have received for this lookup so far for this lookup
[report issue]
branch_factor
the branch factor for this lookup. This is the number of nodes we keep outstanding requests to in parallel by default. when nodes time out we may increase this.
[report issue]
nodes_left
the number of nodes left that could be queries for this lookup. Many of these are likely to be part of the trail while performing the lookup and would never end up actually being queried.
[report issue]
last_sent
the number of seconds ago the last message was sent that's still outstanding
[report issue]
first_timeout
the number of outstanding requests that have exceeded the short timeout and are considered timed out in the sense that they increased the branch factor
[report issue]
target
the node-id or info-hash target for this lookup
[report issue]

dht_stats_alert

Declared in "libtorrent/alert_types.hpp"

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

struct dht_stats_alert final : alert
{
   std::string message () const override;

   static inline constexpr alert_category_t static_category  = {};
   std::vector<dht_lookup> active_requests;
   std::vector<dht_routing_bucket> routing_table;
   sha256_hash nid;
   aux::noexcept_movable<udp::endpoint> local_endpoint;
};
[report issue]
active_requests
a vector of the currently running DHT lookups.
[report issue]
routing_table
contains information about every bucket in the DHT routing table.
[report issue]
nid
the node ID of the DHT node instance
[report issue]
local_endpoint
the local socket this DHT node is running on
[report issue]

dht_log_alert

Declared in "libtorrent/alert_types.hpp"

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

struct dht_log_alert final : alert
{
   std::string message () const override;
   char const* log_message () const;

   enum dht_module_t
   {
      tracker,
      node,
      routing_table,
      rpc_manager,
      traversal,
   };

   static inline constexpr alert_category_t static_category  = alert_category::dht_log;
   dht_module_t module;
};
[report issue]

log_message()

char const* log_message () const;

the log message

[report issue]

enum dht_module_t

Declared in "libtorrent/alert_types.hpp"

name value description
tracker 0  
node 1  
routing_table 2  
rpc_manager 3  
traversal 4  
[report issue]
module
the module, or part, of the DHT that produced this log message.
[report issue]

dht_pkt_alert

Declared in "libtorrent/alert_types.hpp"

This alert is posted every time a DHT message is sent or received. It is only posted if the alert_category::dht_log alert category is enabled. It contains a verbatim copy of the message.

struct dht_pkt_alert final : alert
{
   std::string message () const override;
   span<char const> pkt_buf () const;

   enum direction_t
   {
      incoming,
      outgoing,
   };

   static inline constexpr alert_category_t static_category  = alert_category::dht_log;
   direction_t direction;
   aux::noexcept_movable<udp::endpoint> node;
};
[report issue]

pkt_buf()

span<char const> pkt_buf () const;

returns a pointer to the packet buffer and size of the packet, respectively. This buffer is only valid for as long as the alert itself is valid, which is owned by libtorrent and reclaimed whenever pop_alerts() is called on the session.

[report issue]

enum direction_t

Declared in "libtorrent/alert_types.hpp"

name value description
incoming 0  
outgoing 1  
[report issue]
direction
whether this is an incoming or outgoing packet.
[report issue]
node
the DHT node we received this packet from, or sent this packet to (depending on direction).
[report issue]

dht_get_peers_reply_alert

Declared in "libtorrent/alert_types.hpp"

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

struct dht_get_peers_reply_alert final : alert
{
   std::string message () const override;
   int num_peers () const;
   std::vector<tcp::endpoint> peers () const;

   static inline constexpr alert_category_t static_category  = alert_category::dht_operation;
   sha1_hash info_hash;
};
[report issue]

dht_direct_response_alert

Declared in "libtorrent/alert_types.hpp"

This is posted exactly once for every call to session_handle::dht_direct_request. If the request failed, response() will return a default constructed bdecode_node.

struct dht_direct_response_alert final : alert
{
   std::string message () const override;
   bdecode_node response () const;

   static inline constexpr alert_category_t static_category  = alert_category::dht;
   client_data_t userdata;
   aux::noexcept_movable<udp::endpoint> endpoint;
};
[report issue]

picker_log_alert

Declared in "libtorrent/alert_types.hpp"

this is posted when one or more blocks are picked by the piece picker, assuming the verbose piece picker logging is enabled (see alert_category::picker_log).

struct picker_log_alert final : peer_alert
{
   std::string message () const override;
   std::vector<piece_block> blocks () const;

   static inline constexpr alert_category_t static_category  = alert_category::picker_log;
   static inline constexpr picker_flags_t partial_ratio  = 0_bit;
   static inline constexpr picker_flags_t prioritize_partials  = 1_bit;
   static inline constexpr picker_flags_t rarest_first_partials  = 2_bit;
   static inline constexpr picker_flags_t rarest_first  = 3_bit;
   static inline constexpr picker_flags_t reverse_rarest_first  = 4_bit;
   static inline constexpr picker_flags_t suggested_pieces  = 5_bit;
   static inline constexpr picker_flags_t prio_sequential_pieces  = 6_bit;
   static inline constexpr picker_flags_t sequential_pieces  = 7_bit;
   static inline constexpr picker_flags_t reverse_pieces  = 8_bit;
   static inline constexpr picker_flags_t time_critical  = 9_bit;
   static inline constexpr picker_flags_t random_pieces  = 10_bit;
   static inline constexpr picker_flags_t prefer_contiguous  = 11_bit;
   static inline constexpr picker_flags_t reverse_sequential  = 12_bit;
   static inline constexpr picker_flags_t backup1  = 13_bit;
   static inline constexpr picker_flags_t backup2  = 14_bit;
   static inline constexpr picker_flags_t end_game  = 15_bit;
   static inline constexpr picker_flags_t extent_affinity  = 16_bit;
   picker_flags_t picker_flags;
};
[report issue]
picker_flags
this is a bitmask of which features were enabled for this particular pick. The bits are defined in the picker_flags_t enum.
[report issue]

session_error_alert

Declared in "libtorrent/alert_types.hpp"

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

struct session_error_alert final : alert
{
   std::string message () const override;

   static inline constexpr alert_category_t static_category  = alert_category::error;
   error_code const error;
};
[report issue]
error
The error code, if one is associated with this error
[report issue]

dht_live_nodes_alert

Declared in "libtorrent/alert_types.hpp"

posted in response to a call to session::dht_live_nodes(). It contains the live nodes from the DHT routing table of one of the DHT nodes running locally.

struct dht_live_nodes_alert final : alert
{
   std::string message () const override;
   int num_nodes () const;
   std::vector<std::pair<sha256_hash, udp::endpoint>> nodes () const;

   static inline constexpr alert_category_t static_category  = alert_category::dht;
   sha256_hash node_id;
};
[report issue]

num_nodes() nodes()

int num_nodes () const;
std::vector<std::pair<sha256_hash, udp::endpoint>> nodes () const;

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

[report issue]
node_id
the local DHT node's node-ID this routing table belongs to
[report issue]

session_stats_header_alert

Declared in "libtorrent/alert_types.hpp"

The session_stats_header alert is posted the first time post_session_stats() is called

the message() member function returns a string representation of the header that properly match the stats values string returned in session_stats_alert::message().

this specific output is parsed by tools/parse_session_stats.py if this is changed, that parser should also be changed

struct session_stats_header_alert final : alert
{
   std::string message () const override;

   static inline constexpr alert_category_t static_category  = {};
};
[report issue]

dht_sample_infohashes_alert

Declared in "libtorrent/alert_types.hpp"

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

struct dht_sample_infohashes_alert final : alert
{
   std::string message () const override;
   std::vector<sha256_hash> samples () const;
   int num_samples () const;
   int num_nodes () const;
   std::vector<std::pair<sha256_hash, udp::endpoint>> nodes () const;

   static inline constexpr alert_category_t static_category  = alert_category::dht_operation;
   sha256_hash node_id;
   aux::noexcept_movable<udp::endpoint> endpoint;
   time_duration const interval;
   int const num_infohashes;
};
[report issue]

samples() num_samples()

std::vector<sha256_hash> samples () const;
int num_samples () const;

returns the number of info-hashes returned by the node, as well as the actual info-hashes. num_samples() is more efficient than samples().size().

[report issue]

num_nodes()

int num_nodes () const;

The total number of nodes returned by nodes().

[report issue]

nodes()

std::vector<std::pair<sha256_hash, udp::endpoint>> nodes () const;

This is the set of more DHT nodes returned by the request.

The information is included so that indexing nodes can perform a key space traversal with a single RPC per node by adjusting the target value for each RPC.

[report issue]
node_id
id of the node the request was sent to (and this response was received from)
[report issue]
endpoint
the node the request was sent to (and this response was received from)
[report issue]
interval
the interval to wait before making another request to this node
[report issue]
num_infohashes
This field indicates how many info-hash keys are currently in the node's storage. If the value is larger than the number of returned samples it indicates that the indexer may obtain additional samples after waiting out the interval.
[report issue]

alerts_dropped_alert

Declared in "libtorrent/alert_types.hpp"

this alert is posted to indicate to the client that some alerts were dropped. Dropped meaning that the alert failed to be delivered to the client. The most common cause of such failure is that the internal alert queue grew too big (controlled by alert_queue_size).

struct alerts_dropped_alert final : alert
{
   std::string message () const override;
   static_assert (num_alert_types <= abi_alert_count, "need to increase bitset. This is an ABI break");

   static inline constexpr alert_category_t static_category  = alert_category::error;
   std::bitset<abi_alert_count> dropped_alerts;
};
[report issue]
dropped_alerts
a bitmask indicating which alerts were dropped. Each bit represents the alert type ID, where bit 0 represents whether any alert of type 0 has been dropped, and so on.
[report issue]

socks5_alert

Declared in "libtorrent/alert_types.hpp"

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

struct socks5_alert final : alert
{
   std::string message () const override;

   static inline constexpr alert_category_t static_category  = alert_category::error;
   error_code error;
   operation_t op;
   aux::noexcept_movable<tcp::endpoint> ip;
};
[report issue]
error
the error
[report issue]
op
the operation that failed
[report issue]
ip
the endpoint configured as the proxy
[report issue]

communication_new_device_id_alert

Declared in "libtorrent/alert_types.hpp"

this alert is posted when new device id is found on net.

struct communication_new_device_id_alert final : alert
{
   std::string message () const override;

   static constexpr alert_category_t static_category  = alert_category::communication;
   aux::bytesConstRef device_id;
};
[report issue]
device_id
device id found
[report issue]

communication_new_message_alert

Declared in "libtorrent/alert_types.hpp"

this alert is posted when new message is found from other peers.

struct communication_new_message_alert final : alert
{
   std::string message () const override;

   static constexpr alert_category_t static_category  = alert_category::communication;
   communication::message msg;
};
[report issue]
msg
message found from peers.
[report issue]

communication_confirmation_root_alert

Declared in "libtorrent/alert_types.hpp"

this alert is posted when message hash is confirmed by peers.

struct communication_confirmation_root_alert final : alert
{
   std::string message () const override;

   static constexpr alert_category_t static_category  = alert_category::communication;
   aux::bytesConstRef confirmation_root;
};
[report issue]
confirmation_root
confirmation root
[report issue]

communication_syncing_message_alert

Declared in "libtorrent/alert_types.hpp"

this alert is posted when a message is syncing.

struct communication_syncing_message_alert final : alert
{
   std::string message () const override;

   static constexpr alert_category_t static_category  = alert_category::communication;
   aux::bytesConstRef syncing_msg_hash;
};
[report issue]
syncing_msg_hash
syncing message hash
[report issue]

communication_friend_info_alert

Declared in "libtorrent/alert_types.hpp"

this alert is posted when friend info found in new mutable data.

struct communication_friend_info_alert final : alert
{
   std::string message () const override;

   static constexpr alert_category_t static_category  = alert_category::communication;
   aux::bytes friend_info;
};
[report issue]
friend_info
friend info
[report issue]

alert_cast()

Declared in "libtorrent/alert.hpp"

template <typename T> T const* alert_cast (alert const* a);
template <typename T> T* alert_cast (alert* a);

When you get an alert, you can use alert_cast<> to attempt to cast the pointer to a specific alert type, in order to query it for more information.

Note

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

[report issue]

alert_category_t

Declared in "libtorrent/alert.hpp"

error

Enables alerts that report an error. This includes:

  • tracker errors
  • tracker warnings
  • file errors
  • resume data failures
  • web seed errors
  • .torrent files errors
  • listen socket errors
  • port mapping errors
peer
Enables alerts when peers send invalid requests, get banned or snubbed.
port_mapping
Enables alerts for port mapping events. For NAT-PMP and UPnP.
storage
Enables alerts for events related to the storage. File errors and synchronization events for moving the storage, renaming files etc.
tracker
Enables all tracker events. Includes announcing to trackers, receiving responses, warnings and errors.
connect
Low level alerts for when peers are connected and disconnected.
status
Enables alerts for when a torrent or the session changes state.
ip_block
Alerts when a peer is blocked by the ip blocker or port blocker.
performance_warning
Alerts when some limit is reached that might limit the download or upload rate.
dht
Alerts on events in the DHT node. For incoming searches or bootstrapping being done etc.
stats
If you enable these alerts, you will receive a stats_alert approximately once every second, for every active torrent. These alerts contain all statistics counters for the interval since the lasts stats alert.
session_log
Enables debug logging alerts. These are available unless libtorrent was built with logging disabled (TORRENT_DISABLE_LOGGING). The alerts being posted are log_alert and are session wide.
torrent_log
Enables debug logging alerts for torrents. These are available unless libtorrent was built with logging disabled (TORRENT_DISABLE_LOGGING). The alerts being posted are torrent_log_alert and are torrent wide debug events.
peer_log
Enables debug logging alerts for peers. These are available unless libtorrent was built with logging disabled (TORRENT_DISABLE_LOGGING). The alerts being posted are peer_log_alert and low-level peer events and messages.
incoming_request
enables the incoming_request_alert.
dht_log
enables dht_log_alert, debug logging for the DHT
dht_operation
enable events from pure dht operations not related to torrents
port_mapping_log
enables port mapping log events. This log is useful for debugging the UPnP or NAT-PMP implementation
picker_log
enables verbose logging from the piece picker.
file_progress
alerts when files complete downloading
piece_progress
alerts when pieces complete downloading or fail hash check
upload
alerts when we upload blocks to other peers
block_progress
alerts on individual blocks being requested, downloading, finished, rejected, time-out and cancelled. This is likely to post alerts at a high rate.
communication
alerts on events in communication
all

The full bitmask, representing all available categories.

since the enum is signed, make sure this isn't interpreted as -1. For instance, boost.python does that and fails when assigning it to an unsigned parameter.

[report issue]

int

Declared in "libtorrent/alert_types.hpp"

user_alert_id
user defined alerts should use IDs greater than this
num_alert_types
this constant represents "max_alert_index" + 1
[report issue]

ip_filter

Declared in "libtorrent/ip_filter.hpp"

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

A default constructed ip_filter does not filter any address.

struct ip_filter
{
   ip_filter& operator= (ip_filter&&);
   ip_filter (ip_filter&&);
   ~ip_filter ();
   ip_filter ();
   ip_filter& operator= (ip_filter const&);
   ip_filter (ip_filter const&);
   bool empty () const;
   void add_rule (address const& first, address const& last, std::uint32_t flags);
   std::uint32_t access (address const& addr) const;
   filter_tuple_t export_filter () const;

   enum access_flags
   {
      blocked,
   };
};
[report issue]

empty()

bool empty () const;

returns true if the filter does not contain any rules

[report issue]

add_rule()

void add_rule (address const& first, address const& last, std::uint32_t flags);

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

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

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

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

[report issue]

access()

std::uint32_t access (address const& addr) const;

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

[report issue]

export_filter()

filter_tuple_t export_filter () const;

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

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

[report issue]

enum access_flags

Declared in "libtorrent/ip_filter.hpp"

name value description
blocked 1 indicates that IPs in this range should not be connected to nor accepted as incoming connections
[report issue]

port_filter

Declared in "libtorrent/ip_filter.hpp"

the port filter maps non-overlapping port ranges to flags. This is primarily used to indicate whether a range of ports should be connected to or not. The default is to have the full port range (0-65535) set to flag 0.

class port_filter
{
   port_filter ();
   port_filter (port_filter const&);
   port_filter (port_filter&&);
   port_filter& operator= (port_filter const&);
   ~port_filter ();
   port_filter& operator= (port_filter&&);
   void add_rule (std::uint16_t first, std::uint16_t last, std::uint32_t flags);
   std::uint32_t access (std::uint16_t port) const;

   enum access_flags
   {
      blocked,
   };
};
[report issue]

add_rule()

void add_rule (std::uint16_t first, std::uint16_t last, std::uint32_t flags);

set the flags for the specified port range (first, last) to flags overwriting any existing rule for those ports. The range is inclusive, i.e. the port last also has the flag set on it.

[report issue]

access()

std::uint32_t access (std::uint16_t port) const;

test the specified port (port) for whether it is blocked or not. The returned value is the flags set for this port. see access_flags.

[report issue]

enum access_flags

Declared in "libtorrent/ip_filter.hpp"

name value description
blocked 1 this flag indicates that destination ports in the range should not be connected to
[report issue]

peer_class_type_filter

Declared in "libtorrent/peer_class_type_filter.hpp"

peer_class_type_filter is a simple container for rules for adding and subtracting peer-classes from peers. It is applied after the peer class filter is applied (which is based on the peer's IP address).

struct peer_class_type_filter
{
   void remove (socket_type_t const st, peer_class_t const peer_class);
   void add (socket_type_t const st, peer_class_t const peer_class);
   void disallow (socket_type_t const st, peer_class_t const peer_class);
   void allow (socket_type_t const st, peer_class_t const peer_class);
   std::uint32_t apply (socket_type_t const st, std::uint32_t peer_class_mask);
   friend bool operator== (peer_class_type_filter const& lhs
      , peer_class_type_filter const& rhs);

   enum socket_type_t
   {
      tcp_socket,
      utp_socket,
      ssl_tcp_socket,
      ssl_utp_socket,
      i2p_socket,
      rtc_socket,
      num_socket_types,
   };
};
[report issue]

remove() add()

void remove (socket_type_t const st, peer_class_t const peer_class);
void add (socket_type_t const st, peer_class_t const peer_class);

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

[report issue]

allow() disallow()

void disallow (socket_type_t const st, peer_class_t const peer_class);
void allow (socket_type_t const st, peer_class_t const peer_class);

disallow() and allow() adds and removes a peer class to be removed from new peers based on socket type.

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

[report issue]

apply()

std::uint32_t apply (socket_type_t const st, std::uint32_t peer_class_mask);

takes a bitmask of peer classes and returns a new bitmask of peer classes after the rules have been applied, based on the socket type argument (st).

[report issue]

enum socket_type_t

Declared in "libtorrent/peer_class_type_filter.hpp"

name value description
tcp_socket 0 these match the socket types from socket_type.hpp shifted one down
utp_socket 1  
ssl_tcp_socket 2  
ssl_utp_socket 3  
i2p_socket 4  
rtc_socket 5  
num_socket_types 6  
[report issue]

info_hash_t

Declared in "libtorrent/info_hash.hpp"

class holding the info-hash of a torrent. It can hold a v1 info-hash (SHA-1) or a v2 info-hash (SHA-256) or both.

Note

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

struct info_hash_t
{
   explicit info_hash_t (sha1_hash h1) noexcept;
   info_hash_t () noexcept = default;
   explicit info_hash_t (sha256_hash h2) noexcept;
   info_hash_t (sha1_hash h1, sha256_hash h2) noexcept;
   bool has_v2 () const;
   bool has (protocol_version v) const;
   bool has_v1 () const;
   sha1_hash get (protocol_version v) const;
   sha1_hash get_best () const;
   friend bool operator!= (info_hash_t const& lhs, info_hash_t const& rhs);
   friend bool operator== (info_hash_t const& lhs, info_hash_t const& rhs) noexcept;
   template <typename F> void for_each (F f) const;
   bool operator< (info_hash_t const& o) const;
   friend std::ostream& operator<< (std::ostream& os, info_hash_t const& ih);

   sha1_hash v1;
   sha256_hash v2;
};
[report issue]

info_hash_t()

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

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

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

[report issue]

has() has_v2() has_v1()

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

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

[report issue]

get()

sha1_hash get (protocol_version v) const;

returns the has for the specified protocol version

[report issue]

get_best()

sha1_hash get_best () const;

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

[report issue]

for_each()

template <typename F> void for_each (F f) const;

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

void(sha1_hash, protocol_version);
[report issue]

enum protocol_version

Declared in "libtorrent/info_hash.hpp"

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

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

The settings_pack object is a collection of settings updates that are applied to the session when passed to session::apply_settings(). It's empty when constructed.

You have control over proxy and authorization settings and also the user-agent that will be sent to the tracker. The user-agent will also be used to identify the client with other peers.

Each configuration option is named with an enum value inside the settings_pack class. These are the available settings:

[report issue]

settings_interface

Declared in "libtorrent/settings_pack.hpp"

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

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

settings_pack

Declared in "libtorrent/settings_pack.hpp"

The settings_pack struct, contains the names of all settings as enum values. These values are passed in to the set_str(), set_int(), set_bool() functions, to specify the setting to change.

name type default
user_agent string libtorrent/

this is the client identification to the tracker. The recommended format of this string is: "client-name/client-version libtorrent/libtorrent-version". This name will not only be used when making HTTP requests, but also when sending extended headers to peers that support that extension. It may not contain r or n

name type default
announce_ip string nullptr

announce_ip is the ip address passed along to trackers as the &ip= parameter. If left as the default, that parameter is omitted.

Note

This setting is only meant for very special cases where a seed is running on the same host as the tracker, and the tracker accepts the IP parameter (which normal trackers don't). Do not set this option unless you also control the tracker.

name type default
handshake_client_version string nullptr

this is the client name and version identifier sent to peers in the handshake message. If this is an empty string, the user_agent is used instead. This string must be a UTF-8 encoded unicode string.

name type default
outgoing_interfaces string  

This controls which IP address outgoing TCP peer connections are bound to, in addition to controlling whether such connections are also bound to a specific network interface/adapter (bind-to-device).

This string is a comma-separated list of IP addresses and interface names. An empty string will not bind TCP sockets to a device, and let the network stack assign the local address.

A list of names will be used to bind outgoing TCP sockets in a round-robin fashion. An IP address will simply be used to bind() the socket. An interface name will attempt to bind the socket to that interface. If that fails, or is unsupported, one of the IP addresses configured for that interface is used to bind() the socket to. If the interface or adapter doesn't exist, the outgoing peer connection will fail with an error message suggesting the device cannot be found. Adapter names on Unix systems are of the form "eth0", "eth1", "tun0", etc. This may be useful for clients that are multi-homed. Binding an outgoing connection to a local IP does not necessarily make the connection via the associated NIC/Adapter.

When outgoing interfaces are specified, incoming connections or packets sent to a local interface or IP that's not in this list will be rejected with a peer_blocked_alert with invalid_local_interface as the reason.

Note that these are just interface/adapter names or IP addresses. There are no ports specified in this list. IPv6 addresses without port should be specified without enclosing [, ].

name type default
listen_interfaces string 0.0.0.0:6881,[::]:6881

a comma-separated list of (IP or device name, port) pairs. These are the listen ports that will be opened for accepting incoming uTP and TCP peer connections. These are also used for outgoing uTP and UDP tracker connections and DHT nodes.

It is possible to listen on multiple interfaces and multiple ports. Binding to port 0 will make the operating system pick the port.

Note

There are reasons to stick to the same port across sessions, which would mean only using port 0 on the first start, and recording the port that was picked for subsequent startups. Trackers, the DHT and other peers will remember the port they see you use and hand that port out to other peers trying to connect to you, as well as trying to connect to you themselves.

A port that has an "s" suffix will accept SSL peer connections. (note that SSL sockets are only available in builds with SSL support)

A port that has an "l" suffix will be considered a local network. i.e. it's assumed to only be able to reach hosts in the same local network as the IP address (based on the netmask associated with the IP, queried from the operating system).

if binding fails, the listen_failed_alert is posted. Once a socket binding succeeds (if it does), the listen_succeeded_alert is posted. There may be multiple failures before a success.

If a device name that does not exist is configured, no listen socket will be opened for that interface. If this is the only interface configured, it will be as if no listen ports are configured.

If no listen ports are configured (e.g. listen_interfaces is an empty string), networking will be disabled. No DHT will start, no outgoing uTP or tracker connections will be made. No incoming TCP or uTP connections will be accepted. (outgoing TCP connections will still be possible, depending on settings_pack::outgoing_interfaces).

For example: [::1]:8888 - will only accept connections on the IPv6 loopback address on port 8888.

eth0:4444,eth1:4444 - will accept connections on port 4444 on any IP address bound to device eth0 or eth1.

[::]:0s - will accept SSL connections on a port chosen by the OS. And not accept non-SSL connections at all.

0.0.0.0:6881,[::]:6881 - binds to all interfaces on port 6881.

10.0.1.13:6881l - binds to the local IP address, port 6881, but only allow talking to peers on the same local network. The netmask is queried from the operating system. Interfaces marked l are not announced to trackers, unless the tracker is also on the same local network.

Windows OS network adapter device name must be specified with GUID. It can be obtained from "netsh lan show interfaces" command output. GUID must be uppercased string embraced in curly brackets. {E4F0B674-0DFC-48BB-98A5-2AA730BDB6D6}:7777 - will accept connections on port 7777 on adapter with this GUID.

For more information, see the Multi-homed hosts section.

name type default
proxy_hostname string  

when using a proxy, this is the hostname where the proxy is running see proxy_type. Note that when using a proxy, the settings_pack::listen_interfaces setting is overridden and only a single interface is created, just to contact the proxy. This means a proxy cannot be combined with SSL torrents or multiple listen interfaces. This proxy listen interface will not accept incoming TCP connections, will not map ports with any gateway and will not enable local service discovery. All traffic is supposed to be channeled through the proxy.

name type default
proxy_username string  
proxy_password string  

when using a proxy, these are the credentials (if any) to use when connecting to it. see proxy_type

name type default
i2p_hostname string  

sets the i2p SAM bridge to connect to. set the port with the i2p_port setting.

name type default
peer_fingerprint string -LT2030-

this is the fingerprint for the client. It will be used as the prefix to the peer_id. If this is 20 bytes (or longer) it will be truncated to 20 bytes and used as the entire peer-id

There is a utility function, generate_fingerprint() that can be used to generate a standard client peer ID fingerprint prefix.

name type default
db_dir string /.libTAU

The directory for storing db. Now using leveldb and sqlite3.

name type default
account_seed string  

User's seed. since session constructor and given from apply layer.

name type default
dht_bootstrap_nodes string dht.libtorrent.org:25401

This is a comma-separated list of IP port-pairs. They will be added to the DHT node (if it's enabled) as back-up nodes in case we don't know of any.

Changing these after the DHT has been started may not have any effect until the DHT is restarted.

name type default
webtorrent_stun_server string stun.l.google.com:19302

This is the STUN server used by WebTorrent to enable ICE NAT traversal for WebRTC. It must have the format hostname:port.

name type default
allow_multiple_connections_per_ip bool false

determines if connections from the same IP address as existing connections should be rejected or not. Rejecting multiple connections from the same IP address will prevent abusive behavior by peers. The logic for determining whether connections are to the same peer is more complicated with this enabled, and more likely to fail in some edge cases. It is not recommended to enable this feature.

name type default
send_redundant_have bool true

send_redundant_have controls if have messages will be sent to peers that already have the piece. This is typically not necessary, but it might be necessary for collecting statistics in some cases.

name type default
use_dht_as_fallback bool false

use_dht_as_fallback determines how the DHT is used. If this is true, the DHT will only be used for torrents where all trackers in its tracker list has failed. Either by an explicit error message or a time out. If this is false, the DHT is used regardless of if the trackers fail or not.

name type default
upnp_ignore_nonrouters bool false

upnp_ignore_nonrouters indicates whether or not the UPnP implementation should ignore any broadcast response from a device whose address is not on our subnet. i.e. it's a way to not talk to other people's routers by mistake.

name type default
use_parole_mode bool true

use_parole_mode specifies if parole mode should be used. Parole mode means that peers that participate in pieces that fail the hash check are put in a mode where they are only allowed to download whole pieces. If the whole piece a peer in parole mode fails the hash check, it is banned. If a peer participates in a piece that passes the hash check, it is taken out of parole mode.

name type default
auto_manage_prefer_seeds bool false

if true, prefer seeding torrents when determining which torrents to give active slots to. If false, give preference to downloading torrents

name type default
close_redundant_connections bool true

close_redundant_connections specifies whether libtorrent should close connections where both ends have no utility in keeping the connection open. For instance if both ends have completed their downloads, there's no point in keeping it open.

name type default
prioritize_partial_pieces bool false

If prioritize_partial_pieces is true, partial pieces are picked before pieces that are more rare. If false, rare pieces are always prioritized, unless the number of partial pieces is growing out of proportion.

name type default
rate_limit_ip_overhead bool true

if set to true, the estimated TCP/IP overhead is drained from the rate limiters, to avoid exceeding the limits with the total traffic

name type default
announce_to_all_tiers bool false
announce_to_all_trackers bool false

announce_to_all_trackers controls how multi tracker torrents are treated. If this is set to true, all trackers in the same tier are announced to in parallel. If all trackers in tier 0 fails, all trackers in tier 1 are announced as well. If it's set to false, the behavior is as defined by the multi tracker specification.

announce_to_all_tiers also controls how multi tracker torrents are treated. When this is set to true, one tracker from each tier is announced to. This is the uTorrent behavior. To be compliant with the Multi-tracker specification, set it to false.

name type default
prefer_udp_trackers bool true

prefer_udp_trackers: true means that trackers may be rearranged in a way that udp trackers are always tried before http trackers for the same hostname. Setting this to false means that the tracker's tier is respected and there's no preference of one protocol over another.

name type default
disable_hash_checks bool false

when set to true, all data downloaded from peers will be assumed to be correct, and not tested to match the hashes in the torrent this is only useful for simulation and testing purposes (typically combined with disabled_storage)

name type default
allow_i2p_mixed bool false

if this is true, i2p torrents are allowed to also get peers from other sources than the tracker, and connect to regular IPs, not providing any anonymization. This may be useful if the user is not interested in the anonymization of i2p, but still wants to be able to connect to i2p peers.

name type default
no_atime_storage bool true

no_atime_storage this is a Linux-only option and passes in the O_NOATIME to open() when opening files. This may lead to some disk performance improvements.

name type default
incoming_starts_queued_torrents bool false

incoming_starts_queued_torrents. If a torrent has been paused by the auto managed feature in libtorrent, i.e. the torrent is paused and auto managed, this feature affects whether or not it is automatically started on an incoming connection. The main reason to queue torrents, is not to make them unavailable, but to save on the overhead of announcing to the trackers, the DHT and to avoid spreading one's unchoke slots too thin. If a peer managed to find us, even though we're no in the torrent anymore, this setting can make us start the torrent and serve it.

name type default
report_true_downloaded bool false

when set to true, the downloaded counter sent to trackers will include the actual number of payload bytes downloaded including redundant bytes. If set to false, it will not include any redundancy bytes

name type default
strict_end_game_mode bool true

strict_end_game_mode controls when a block may be requested twice. If this is true, a block may only be requested twice when there's at least one request to every piece that's left to download in the torrent. This may slow down progress on some pieces sometimes, but it may also avoid downloading a lot of redundant bytes. If this is false, libtorrent attempts to use each peer connection to its max, by always requesting something, even if it means requesting something that has been requested from another peer already.

name type default
enable_outgoing_utp bool true
enable_incoming_utp bool true
enable_outgoing_tcp bool true
enable_incoming_tcp bool true

Enables incoming and outgoing, TCP and uTP peer connections. false is disabled and true is enabled. When outgoing connections are disabled, libtorrent will simply not make outgoing peer connections with the specific transport protocol. Disabled incoming peer connections will simply be rejected. These options only apply to peer connections, not tracker- or any other kinds of connections.

name type default
no_recheck_incomplete_resume bool false

no_recheck_incomplete_resume determines if the storage should check the whole files when resume data is incomplete or missing or whether it should simply assume we don't have any of the data. If false, any existing files will be checked. By setting this setting to true, the files won't be checked, but will go straight to download mode.

name type default
anonymous_mode bool false

anonymous_mode: When set to true, the client tries to hide its identity to a certain degree. The user-agent will be reset to an empty string (except for private torrents). Trackers will only be used if they are using a proxy server. The listen sockets are closed, and incoming connections will only be accepted through a SOCKS5 or I2P proxy (if a peer proxy is set up and is run on the same machine as the tracker proxy). Since no incoming connections are accepted, NAT-PMP, UPnP, DHT and local peer discovery are all turned off when this setting is enabled.

If you're using I2P, it might make sense to enable anonymous mode as well.

name type default
report_web_seed_downloads bool true

specifies whether downloads from web seeds is reported to the tracker or not. Turning it off also excludes web seed traffic from other stats and download rate reporting via the libtorrent API.

name type default
seeding_outgoing_connections bool true

seeding_outgoing_connections determines if seeding (and finished) torrents should attempt to make outgoing connections or not. It may be set to false in very specific applications where the cost of making outgoing connections is high, and there are no or small benefits of doing so. For instance, if no nodes are behind a firewall or a NAT, seeds don't need to make outgoing connections.

name type default
no_connect_privileged_ports bool false

when this is true, libtorrent will not attempt to make outgoing connections to peers whose port is < 1024. This is a safety precaution to avoid being part of a DDoS attack

name type default
smooth_connects bool true

smooth_connects means the number of connection attempts per second may be limited to below the connection_speed, in case we're close to bump up against the limit of number of connections. The intention of this setting is to more evenly distribute our connection attempts over time, instead of attempting to connect in batches, and timing them out in batches.

name type default
always_send_user_agent bool false

always send user-agent in every web seed request. If false, only the first request per http connection will include the user agent

name type default
apply_ip_filter_to_trackers bool true

apply_ip_filter_to_trackers determines whether the IP filter applies to trackers as well as peers. If this is set to false, trackers are exempt from the IP filter (if there is one). If no IP filter is set, this setting is irrelevant.

name type default
ban_web_seeds bool true

when true, web seeds sending bad data will be banned

name type default
allow_partial_disk_writes bool true

when set to false, the write_cache_line_size will apply across piece boundaries. this is a bad idea unless the piece picker also is configured to have an affinity to pick pieces belonging to the same write cache line as is configured in the disk cache.

name type default
support_share_mode bool true

if false, prevents libtorrent to advertise share-mode support

name type default
report_redundant_bytes bool true

if this is true, the number of redundant bytes is sent to the tracker

name type default
listen_system_port_fallback bool true

if this is true, libtorrent will fall back to listening on a port chosen by the operating system (i.e. binding to port 0). If a failure is preferred, set this to false.

name type default
announce_crypto_support bool true

when this is true, and incoming encrypted connections are enabled, &supportcrypt=1 is included in http tracker announces

name type default
enable_upnp bool true

Starts and stops the UPnP service. When started, the listen port and the DHT port are attempted to be forwarded on local UPnP router devices.

The upnp object returned by start_upnp() can be used to add and remove arbitrary port mappings. Mapping status is returned through the portmap_alert and the portmap_error_alert. The object will be valid until stop_upnp() is called. See upnp and nat pmp.

name type default
enable_natpmp bool true

Starts and stops the NAT-PMP service. When started, the listen port and the DHT port are attempted to be forwarded on the router through NAT-PMP.

The natpmp object returned by start_natpmp() can be used to add and remove arbitrary port mappings. Mapping status is returned through the portmap_alert and the portmap_error_alert. The object will be valid until stop_natpmp() is called. See upnp and nat pmp.

name type default
enable_dht bool true

starts the dht node and makes the trackerless service available to torrents.

name type default
prefer_rc4 bool false

if the allowed encryption level is both, setting this to true will prefer RC4 if both methods are offered, plain text otherwise

name type default
proxy_hostnames bool true

if true, hostname lookups are done via the configured proxy (if any). This is only supported by SOCKS5 and HTTP.

name type default
proxy_peer_connections bool true

if true, peer connections are made (and accepted) over the configured proxy, if any. Web seeds as well as regular bittorrent peer connections are considered "peer connections". Anything transporting actual torrent payload (trackers and DHT traffic are not considered peer connections).

name type default
proxy_tracker_connections bool true

if true, tracker connections are made over the configured proxy, if any.

name type default
enable_ip_notifier bool true

Starts and stops the internal IP table route changes notifier.

The current implementation supports multiple platforms, and it is recommended to have it enable, but you may want to disable it if it's supported but unreliable, or if you have a better way to detect the changes. In the later case, you should manually call session_handle::reopen_network_sockets to ensure network changes are taken in consideration.

name type default
dht_prefer_verified_node_ids bool true

when this is true, nodes whose IDs are derived from their source IP according to BEP 42 are preferred in the routing table.

name type default
dht_restrict_routing_ips bool true

determines if the routing table entries should restrict entries to one per IP. This defaults to true, which helps mitigate some attacks on the DHT. It prevents adding multiple nodes with IPs with a very close CIDR distance.

when set, nodes whose IP address that's in the same /24 (or /64 for IPv6) range in the same routing table bucket. This is an attempt to mitigate node ID spoofing attacks also restrict any IP to only have a single entry in the whole routing table

name type default
dht_restrict_search_ips bool true

determines if DHT searches should prevent adding nodes with IPs with very close CIDR distance. This also defaults to true and helps mitigate certain attacks on the DHT.

name type default
dht_extended_routing_table bool true

makes the first buckets in the DHT routing table fit 128, 64, 32 and 16 nodes respectively, as opposed to the standard size of 8. All other buckets have size 8 still.

name type default
dht_aggressive_lookups bool true

slightly changes the lookup behavior in terms of how many outstanding requests we keep. Instead of having branch factor be a hard limit, we always keep branch factor outstanding requests to the closest nodes. i.e. every time we get results back with closer nodes, we query them right away. It lowers the lookup times at the cost of more outstanding queries.

name type default
dht_privacy_lookups bool false

when set, perform lookups in a way that is slightly more expensive, but which minimizes the amount of information leaked about you.

name type default
dht_enforce_node_id bool false

when set, node's whose IDs that are not correctly generated based on its external IP are ignored. When a query arrives from such node, an error message is returned with a message saying "invalid node ID".

name type default
dht_ignore_dark_internet bool true

ignore DHT messages from parts of the internet we wouldn't expect to see any traffic from

name type default
dht_read_only bool false

when set, the other nodes won't keep this node in their routing tables, it's meant for low-power and/or ephemeral devices that cannot support the DHT, it is also useful for mobile devices which are sensitive to network traffic and battery life. this node no longer responds to 'query' messages, and will place a 'ro' key (value = 1) in the top-level message dictionary of outgoing query messages.

name type default
piece_extent_affinity bool false

when this is true, create an affinity for downloading 4 MiB extents of adjacent pieces. This is an attempt to achieve better disk I/O throughput by downloading larger extents of bytes, for torrents with small piece sizes

name type default
validate_https_trackers bool true

when set to true, the certificate of HTTPS trackers and HTTPS web seeds will be validated against the system's certificate store (as defined by OpenSSL). If the system does not have a certificate store, this option may have to be disabled in order to get trackers and web seeds to work).

name type default
ssrf_mitigation bool true

when enabled, tracker and web seed requests are subject to certain restrictions.

An HTTP(s) tracker requests to localhost (loopback) must have the request path start with "/announce". This is the conventional bittorrent tracker request. Any other HTTP(S) tracker request to loopback will be rejected. This applies to trackers that redirect to loopback as well.

Web seeds that end up on the client's local network (i.e. in a private IP address range) may not include query string arguments. This applies to web seeds redirecting to the local network as well.

Web seeds on global IPs (i.e. not local network) may not redirect to a local network address

name type default
allow_idna bool false

when disabled, any tracker or web seed with an IDNA hostname (internationalized domain name) is ignored. This is a security precaution to avoid various unicode encoding attacks that might happen at the application level.

name type default
enable_set_file_valid_data bool false

when set to true, enables the attempt to use SetFileValidData() to pre-allocate disk space. This system call will only work when running with Administrator privileges on Windows, and so this setting is only relevant in that scenario. Using SetFileValidData() poses a security risk, as it may reveal previously deleted information from the disk.

name type default
tracker_completion_timeout int 30

tracker_completion_timeout is the number of seconds the tracker connection will wait from when it sent the request until it considers the tracker to have timed-out.

name type default
tracker_receive_timeout int 10

tracker_receive_timeout is the number of seconds to wait to receive any data from the tracker. If no data is received for this number of seconds, the tracker will be considered as having timed out. If a tracker is down, this is the kind of timeout that will occur.

name type default
stop_tracker_timeout int 5

stop_tracker_timeout is the number of seconds to wait when sending a stopped message before considering a tracker to have timed out. This is usually shorter, to make the client quit faster. If the value is set to 0, the connections to trackers with the stopped event are suppressed.

name type default
tracker_maximum_response_length int 1024*1024

this is the maximum number of bytes in a tracker response. If a response size passes this number of bytes it will be rejected and the connection will be closed. On gzipped responses this size is measured on the uncompressed data. So, if you get 20 bytes of gzip response that'll expand to 2 megabytes, it will be interrupted before the entire response has been uncompressed (assuming the limit is lower than 2 MiB).

name type default
piece_timeout int 20

the number of seconds from a request is sent until it times out if no piece response is returned.

name type default
request_timeout int 60

the number of seconds one block (16 kiB) is expected to be received within. If it's not, the block is requested from a different peer

name type default
request_queue_time int 3

the length of the request queue given in the number of seconds it should take for the other end to send all the pieces. i.e. the actual number of requests depends on the download rate and this number.

name type default
max_allowed_in_request_queue int 2000

the number of outstanding block requests a peer is allowed to queue up in the client. If a peer sends more requests than this (before the first one has been sent) the last request will be dropped. the higher this is, the faster upload speeds the client can get to a single peer.

name type default
max_out_request_queue int 500

max_out_request_queue is the maximum number of outstanding requests to send to a peer. This limit takes precedence over request_queue_time. i.e. no matter the download speed, the number of outstanding requests will never exceed this limit.

name type default
whole_pieces_threshold int 20

if a whole piece can be downloaded in this number of seconds, or less, the peer_connection will prefer to request whole pieces at a time from this peer. The benefit of this is to better utilize disk caches by doing localized accesses and also to make it easier to identify bad peers if a piece fails the hash check.

name type default
peer_timeout int 120

peer_timeout is the number of seconds the peer connection should wait (for any activity on the peer connection) before closing it due to time out. 120 seconds is specified in the protocol specification. After half the time out, a keep alive message is sent.

name type default
urlseed_timeout int 20

same as peer_timeout, but only applies to url-seeds. this is usually set lower, because web servers are expected to be more reliable.

name type default
urlseed_pipeline_size int 5

controls the pipelining size of url and http seeds. i.e. the number of HTTP request to keep outstanding before waiting for the first one to complete. It's common for web servers to limit this to a relatively low number, like 5

name type default
urlseed_wait_retry int 30

number of seconds until a new retry of a url-seed takes place. Default retry value for http-seeds that don't provide a valid retry-after header.

name type default
file_pool_size int 40

sets the upper limit on the total number of files this session will keep open. The reason why files are left open at all is that some anti virus software hooks on every file close, and scans the file for viruses. deferring the closing of the files will be the difference between a usable system and a completely hogged down system. Most operating systems also has a limit on the total number of file descriptors a process may have open.

name type default
max_failcount int 40

max_failcount is the maximum times we try to connect to a peer before stop connecting again. If a peer succeeds, the failure counter is reset. If a peer is retrieved from a peer source (other than DHT) the failcount is decremented by one, allowing another try.

name type default
min_reconnect_time int 60

the number of seconds to wait to reconnect to a peer. this time is multiplied with the failcount.

name type default
peer_connect_timeout int 15

peer_connect_timeout the number of seconds to wait after a connection attempt is initiated to a peer until it is considered as having timed out. This setting is especially important in case the number of half-open connections are limited, since stale half-open connection may delay the connection of other peers considerably.

name type default
connection_speed int 30

connection_speed is the number of connection attempts that are made per second. If a number < 0 is specified, it will default to 200 connections per second. If 0 is specified, it means don't make outgoing connections at all.

name type default
inactivity_timeout int 600

if a peer is uninteresting and uninterested for longer than this number of seconds, it will be disconnected.

name type default
unchoke_interval int 15

unchoke_interval is the number of seconds between chokes/unchokes. On this interval, peers are re-evaluated for being choked/unchoked. This is defined as 30 seconds in the protocol, and it should be significantly longer than what it takes for TCP to ramp up to it's max rate.

name type default
optimistic_unchoke_interval int 30

optimistic_unchoke_interval is the number of seconds between each optimistic unchoke. On this timer, the currently optimistically unchoked peer will change.

name type default
num_want int 200

num_want is the number of peers we want from each tracker request. It defines what is sent as the &num_want= parameter to the tracker.

name type default
initial_picker_threshold int 4

initial_picker_threshold specifies the number of pieces we need before we switch to rarest first picking. The first initial_picker_threshold pieces in any torrent are picked at random , the following pieces are picked in rarest first order.

name type default
allowed_fast_set_size int 5

the number of allowed pieces to send to peers that supports the fast extensions

name type default
suggest_mode int settings_pack::no_piece_suggestions

suggest_mode controls whether or not libtorrent will send out suggest messages to create a bias of its peers to request certain pieces. The modes are:

  • no_piece_suggestions which will not send out suggest messages.
  • suggest_read_cache which will send out suggest messages for the most recent pieces that are in the read cache.
name type default
max_queued_disk_bytes int 1024 * 1024

max_queued_disk_bytes is the maximum number of bytes, to be written to disk, that can wait in the disk I/O thread queue. This queue is only for waiting for the disk I/O thread to receive the job and either write it to disk or insert it in the write cache. When this limit is reached, the peer connections will stop reading data from their sockets, until the disk thread catches up. Setting this too low will severely limit your download rate.

name type default
handshake_timeout int 10

the number of seconds to wait for a handshake response from a peer. If no response is received within this time, the peer is disconnected.

name type default
send_buffer_low_watermark int 10 * 1024
send_buffer_watermark int 500 * 1024
send_buffer_watermark_factor int 50

send_buffer_low_watermark the minimum send buffer target size (send buffer includes bytes pending being read from disk). For good and snappy seeding performance, set this fairly high, to at least fit a few blocks. This is essentially the initial window size which will determine how fast we can ramp up the send rate

if the send buffer has fewer bytes than send_buffer_watermark, we'll read another 16 kiB block onto it. If set too small, upload rate capacity will suffer. If set too high, memory will be wasted. The actual watermark may be lower than this in case the upload rate is low, this is the upper limit.

the current upload rate to a peer is multiplied by this factor to get the send buffer watermark. The factor is specified as a percentage. i.e. 50 -> 0.5 This product is clamped to the send_buffer_watermark setting to not exceed the max. For high speed upload, this should be set to a greater value than 100. For high capacity connections, setting this higher can improve upload performance and disk throughput. Setting it too high may waste RAM and create a bias towards read jobs over write jobs.

name type default
choking_algorithm int settings_pack::fixed_slots_choker
seed_choking_algorithm int settings_pack::round_robin

choking_algorithm specifies which algorithm to use to determine how many peers to unchoke. The unchoking algorithm for downloading torrents is always "tit-for-tat", i.e. the peers we download the fastest from are unchoked.

The options for choking algorithms are defined in the choking_algorithm_t enum.

seed_choking_algorithm controls the seeding unchoke behavior. i.e. How we select which peers to unchoke for seeding torrents. Since a seeding torrent isn't downloading anything, the tit-for-tat mechanism cannot be used. The available options are defined in the seed_choking_algorithm_t enum.

name type default
disk_io_write_mode int settings_pack::enable_os_cache
disk_io_read_mode int settings_pack::enable_os_cache

determines how files are opened when they're in read only mode versus read and write mode. The options are:

enable_os_cache
Files are opened normally, with the OS caching reads and writes.
disable_os_cache
This opens all files in no-cache mode. This corresponds to the OS not letting blocks for the files linger in the cache. This makes sense in order to avoid the bittorrent client to potentially evict all other processes' cache by simply handling high throughput and large files. If libtorrent's read cache is disabled, enabling this may reduce performance.

One reason to disable caching is that it may help the operating system from growing its file cache indefinitely.

name type default
outgoing_port int 0
num_outgoing_ports int 0

this is the first port to use for binding outgoing connections to. This is useful for users that have routers that allow QoS settings based on local port. when binding outgoing connections to specific ports, num_outgoing_ports is the size of the range. It should be more than a few

Warning

setting outgoing ports will limit the ability to keep multiple connections to the same client, even for different torrents. It is not recommended to change this setting. Its main purpose is to use as an escape hatch for cheap routers with QoS capability but can only classify flows based on port numbers.

It is a range instead of a single port because of the problems with failing to reconnect to peers if a previous socket to that peer and port is in TIME_WAIT state.

name type default
peer_tos int 0x20

peer_tos determines the TOS byte set in the IP header of every packet sent to peers (including web seeds). 0x0 means no marking, 0x20 represents the QBone scavenger service. For more details, see QBSS.

name type default
active_downloads int 3
active_seeds int 5
active_checking int 1
active_dht_limit int 88
active_tracker_limit int 1600
active_lsd_limit int 60
active_limit int 500

for auto managed torrents, these are the limits they are subject to. If there are too many torrents some of the auto managed ones will be paused until some slots free up. active_downloads and active_seeds controls how many active seeding and downloading torrents the queuing mechanism allows. The target number of active torrents is min(active_downloads + active_seeds, active_limit). active_downloads and active_seeds are upper limits on the number of downloading torrents and seeding torrents respectively. Setting the value to -1 means unlimited.

For example if there are 10 seeding torrents and 10 downloading torrents, and active_downloads is 4 and active_seeds is 4, there will be 4 seeds active and 4 downloading torrents. If the settings are active_downloads = 2 and active_seeds = 4, then there will be 2 downloading torrents and 4 seeding torrents active. Torrents that are not auto managed are not counted against these limits.

active_checking is the limit of number of simultaneous checking torrents.

active_limit is a hard limit on the number of active (auto managed) torrents. This limit also applies to slow torrents.

active_dht_limit is the max number of torrents to announce to the DHT.

active_tracker_limit is the max number of torrents to announce to their trackers.

active_lsd_limit is the max number of torrents to announce to the local network over the local service discovery protocol.

You can have more torrents active, even though they are not announced to the DHT, lsd or their tracker. If some peer knows about you for any reason and tries to connect, it will still be accepted, unless the torrent is paused, which means it won't accept any connections.

name type default
auto_manage_interval int 30

auto_manage_interval is the number of seconds between the torrent queue is updated, and rotated.

name type default
seed_time_limit int 24 * 60 * 60

this is the limit on the time a torrent has been an active seed (specified in seconds) before it is considered having met the seed limit criteria. See queuing.

name type default
auto_scrape_interval int 1800
auto_scrape_min_interval int 300

auto_scrape_interval is the number of seconds between scrapes of queued torrents (auto managed and paused torrents). Auto managed torrents that are paused, are scraped regularly in order to keep track of their downloader/seed ratio. This ratio is used to determine which torrents to seed and which to pause.

auto_scrape_min_interval is the minimum number of seconds between any automatic scrape (regardless of torrent). In case there are a large number of paused auto managed torrents, this puts a limit on how often a scrape request is sent.

name type default
max_peerlist_size int 3000
max_paused_peerlist_size int 1000

max_peerlist_size is the maximum number of peers in the list of known peers. These peers are not necessarily connected, so this number should be much greater than the maximum number of connected peers. Peers are evicted from the cache when the list grows passed 90% of this limit, and once the size hits the limit, peers are no longer added to the list. If this limit is set to 0, there is no limit on how many peers we'll keep in the peer list.

max_paused_peerlist_size is the max peer list size used for torrents that are paused. This can be used to save memory for paused torrents, since it's not as important for them to keep a large peer list.

name type default
min_announce_interval int 5 * 60

this is the minimum allowed announce interval for a tracker. This is specified in seconds and is used as a sanity check on what is returned from a tracker. It mitigates hammering mis-configured trackers.

name type default
auto_manage_startup int 60

this is the number of seconds a torrent is considered active after it was started, regardless of upload and download speed. This is so that newly started torrents are not considered inactive until they have a fair chance to start downloading.

name type default
seeding_piece_quota int 20

seeding_piece_quota is the number of pieces to send to a peer, when seeding, before rotating in another peer to the unchoke set.

name type default
max_rejects int 50

max_rejects is the number of piece requests we will reject in a row while a peer is choked before the peer is considered abusive and is disconnected.

name type default
recv_socket_buffer_size int 0
send_socket_buffer_size int 0

specifies the buffer sizes set on peer sockets. 0 means the OS default (i.e. don't change the buffer sizes). The socket buffer sizes are changed using setsockopt() with SOL_SOCKET/SO_RCVBUF and SO_SNDBUFFER.

name type default
max_peer_recv_buffer_size int 2 * 1024 * 1024

the max number of bytes a single peer connection's receive buffer is allowed to grow to.

name type default
read_cache_line_size int 32
write_cache_line_size int 16

read_cache_line_size is the number of blocks to read into the read cache when a read cache miss occurs. Setting this to 0 is essentially the same thing as disabling read cache. The number of blocks read into the read cache is always capped by the piece boundary.

When a piece in the write cache has write_cache_line_size contiguous blocks in it, they will be flushed. Setting this to 1 effectively disables the write cache.

name type default
optimistic_disk_retry int 10 * 60

optimistic_disk_retry is the number of seconds from a disk write errors occur on a torrent until libtorrent will take it out of the upload mode, to test if the error condition has been fixed.

libtorrent will only do this automatically for auto managed torrents.

You can explicitly take a torrent out of upload only mode using set_upload_mode().

name type default
max_suggest_pieces int 16

max_suggest_pieces is the max number of suggested piece indices received from a peer that's remembered. If a peer floods suggest messages, this limit prevents libtorrent from using too much RAM.

name type default
local_service_announce_interval int 5 * 60

local_service_announce_interval is the time between local network announces for a torrent. This interval is specified in seconds.

name type default
dht_announce_interval int 15 * 60

dht_announce_interval is the number of seconds between announcing torrents to the distributed hash table (DHT).

name type default
udp_tracker_token_expiry int 60

udp_tracker_token_expiry is the number of seconds libtorrent will keep UDP tracker connection tokens around for. This is specified to be 60 seconds. The higher this value is, the fewer packets have to be sent to the UDP tracker. In order for higher values to work, the tracker needs to be configured to match the expiration time for tokens.

name type default
num_optimistic_unchoke_slots int 0

num_optimistic_unchoke_slots is the number of optimistic unchoke slots to use. Having a higher number of optimistic unchoke slots mean you will find the good peers faster but with the trade-off to use up more bandwidth. 0 means automatic, where libtorrent opens up 20% of your allowed upload slots as optimistic unchoke slots.

name type default
max_pex_peers int 50

the max number of peers we accept from pex messages from a single peer. this limits the number of concurrent peers any of our peers claims to be connected to. If they claim to be connected to more than this, we'll ignore any peer that exceeds this limit

name type default
tick_interval int 500

tick_interval specifies the number of milliseconds between internal ticks. This is the frequency with which bandwidth quota is distributed to peers. It should not be more than one second (i.e. 1000 ms). Setting this to a low value (around 100) means higher resolution bandwidth quota distribution, setting it to a higher value saves CPU cycles.

name type default
share_mode_target int 3

share_mode_target specifies the target share ratio for share mode torrents. If set to 3, we'll try to upload 3 times as much as we download. Setting this very high, will make it very conservative and you might end up not downloading anything ever (and not affecting your share ratio). It does not make any sense to set this any lower than 2. For instance, if only 3 peers need to download the rarest piece, it's impossible to download a single piece and upload it more than 3 times. If the share_mode_target is set to more than 3, nothing is downloaded.

name type default
upload_rate_limit int 0
download_rate_limit int 0

upload_rate_limit and download_rate_limit sets the session-global limits of upload and download rate limits, in bytes per second. By default peers on the local network are not rate limited.

A value of 0 means unlimited.

For fine grained control over rate limits, including making them apply to local peers, see peer classes.

name type default
dht_upload_rate_limit int 8000

the number of bytes per second (on average) the DHT is allowed to send. If the incoming requests causes to many bytes to be sent in responses, incoming requests will be dropped until the quota has been replenished.

name type default
unchoke_slots_limit int 0

unchoke_slots_limit is the max number of unchoked peers in the session. The number of unchoke slots may be ignored depending on what choking_algorithm is set to. Setting this limit to -1 means unlimited, i.e. all peers will always be unchoked.

name type default
connections_limit int 200

connections_limit sets a global limit on the number of connections opened. The number of connections is set to a hard minimum of at least two per torrent, so if you set a too low connections limit, and open too many torrents, the limit will not be met.

name type default
connections_slack int 10

connections_slack is the number of incoming connections exceeding the connection limit to accept in order to potentially replace existing ones.

name type default
utp_target_delay int 100
utp_gain_factor int 3000
utp_min_timeout int 500
utp_syn_resends int 2
utp_fin_resends int 2
utp_num_resends int 3
utp_connect_timeout int 3000
utp_loss_multiplier int 50

utp_target_delay is the target delay for uTP sockets in milliseconds. A high value will make uTP connections more aggressive and cause longer queues in the upload bottleneck. It cannot be too low, since the noise in the measurements would cause it to send too slow. utp_gain_factor is the number of bytes the uTP congestion window can increase at the most in one RTT. If this is set too high, the congestion controller reacts too hard to noise and will not be stable, if it's set too low, it will react slow to congestion and not back off as fast.

utp_min_timeout is the shortest allowed uTP socket timeout, specified in milliseconds. The timeout depends on the RTT of the connection, but is never smaller than this value. A connection times out when every packet in a window is lost, or when a packet is lost twice in a row (i.e. the resent packet is lost as well).

The shorter the timeout is, the faster the connection will recover from this situation, assuming the RTT is low enough. utp_syn_resends is the number of SYN packets that are sent (and timed out) before giving up and closing the socket. utp_num_resends is the number of times a packet is sent (and lost or timed out) before giving up and closing the connection. utp_connect_timeout is the number of milliseconds of timeout for the initial SYN packet for uTP connections. For each timed out packet (in a row), the timeout is doubled. utp_loss_multiplier controls how the congestion window is changed when a packet loss is experienced. It's specified as a percentage multiplier for cwnd. Do not change this value unless you know what you're doing. Never set it higher than 100.

name type default
mixed_mode_algorithm int settings_pack::peer_proportional

The mixed_mode_algorithm determines how to treat TCP connections when there are uTP connections. Since uTP is designed to yield to TCP, there's an inherent problem when using swarms that have both TCP and uTP connections. If nothing is done, uTP connections would often be starved out for bandwidth by the TCP connections. This mode is prefer_tcp. The peer_proportional mode simply looks at the current throughput and rate limits all TCP connections to their proportional share based on how many of the connections are TCP. This works best if uTP connections are not rate limited by the global rate limiter (which they aren't by default).

name type default
listen_queue_size int 5

listen_queue_size is the value passed in to listen() for the listen socket. It is the number of outstanding incoming connections to queue up while we're not actively waiting for a connection to be accepted. 5 should be sufficient for any normal client. If this is a high performance server which expects to receive a lot of connections, or used in a simulator or test, it might make sense to raise this number. It will not take affect until the listen_interfaces settings is updated.

name type default
torrent_connect_boost int 30

torrent_connect_boost is the number of peers to try to connect to immediately when the first tracker response is received for a torrent. This is a boost to given to new torrents to accelerate them starting up. The normal connect scheduler is run once every second, this allows peers to be connected immediately instead of waiting for the session tick to trigger connections. This may not be set higher than 255.

name type default
alert_queue_size int 2000

alert_queue_size is the maximum number of alerts queued up internally. If alerts are not popped, the queue will eventually fill up to this level. Once the alert queue is full, additional alerts will be dropped, and not delivered to the client. Once the client drains the queue, new alerts may be delivered again. In order to know that alerts have been dropped, see session_handle::dropped_alerts().

name type default
max_metadata_size int 3 * 1024 * 10240

max_metadata_size is the maximum allowed size (in bytes) to be received by the metadata extension, i.e. magnet links.

name type default
hashing_threads int 2

hashing_threads is the number of disk I/O threads to use for piece hash verification. These threads are in addition to the regular disk I/O threads specified by settings_pack::aio_threads. The hasher threads do not only compute hashes, but also perform the read from disk. On storage optimal for sequential access, such as hard drives, this setting should probably be set to 1.

name type default
checking_mem_usage int 256

the number of blocks to keep outstanding at any given time when checking torrents. Higher numbers give faster re-checks but uses more memory. Specified in number of 16 kiB blocks

name type default
predictive_piece_announce int 0

if set to > 0, pieces will be announced to other peers before they are fully downloaded (and before they are hash checked). The intention is to gain 1.5 potential round trip times per downloaded piece. When non-zero, this indicates how many milliseconds in advance pieces should be announced, before they are expected to be completed.

name type default
aio_threads int 10

for some aio back-ends, aio_threads specifies the number of io-threads to use.

name type default
tracker_backoff int 250

tracker_backoff determines how aggressively to back off from retrying failing trackers. This value determines x in the following formula, determining the number of seconds to wait until the next retry:

delay = 5 + 5 * x / 100 * fails^2

This setting may be useful to make libtorrent more or less aggressive in hitting trackers.

name type default
share_ratio_limit int 200
seed_time_ratio_limit int 700

when a seeding torrent reaches either the share ratio (bytes up / bytes down) or the seed time ratio (seconds as seed / seconds as downloader) or the seed time limit (seconds as seed) it is considered done, and it will leave room for other torrents. These are specified as percentages. Torrents that are considered done will still be allowed to be seeded, they just won't have priority anymore. For more, see queuing.

name type default
peer_turnover int 4
peer_turnover_cutoff int 90
peer_turnover_interval int 300

peer_turnover is the percentage of peers to disconnect every turnover peer_turnover_interval (if we're at the peer limit), this is specified in percent when we are connected to more than limit * peer_turnover_cutoff peers disconnect peer_turnover fraction of the peers. It is specified in percent peer_turnover_interval is the interval (in seconds) between optimistic disconnects if the disconnects happen and how many peers are disconnected is controlled by peer_turnover and peer_turnover_cutoff

name type default
connect_seed_every_n_download int 10

this setting controls the priority of downloading torrents over seeding or finished torrents when it comes to making peer connections. Peer connections are throttled by the connection_speed and the half-open connection limit. This makes peer connections a limited resource. Torrents that still have pieces to download are prioritized by default, to avoid having many seeding torrents use most of the connection attempts and only give one peer every now and then to the downloading torrent. libtorrent will loop over the downloading torrents to connect a peer each, and every n:th connection attempt, a finished torrent is picked to be allowed to connect to a peer. This setting controls n.

name type default
max_http_recv_buffer_size int 4*1024*204

the max number of bytes to allow an HTTP response to be when announcing to trackers or downloading .torrent files via the url provided in add_torrent_params.

name type default
max_retry_port_bind int 10

if binding to a specific port fails, should the port be incremented by one and tried again? This setting specifies how many times to retry a failed port bind

name type default
alert_mask int int

a bitmask combining flags from alert_category_t defining which kinds of alerts to receive

name type default
out_enc_policy int settings_pack::pe_enabled
in_enc_policy int settings_pack::pe_enabled

control the settings for incoming and outgoing connections respectively. see enc_policy enum for the available options. Keep in mind that protocol encryption degrades performance in several respects:

  1. It prevents "zero copy" disk buffers being sent to peers, since each peer needs to mutate the data (i.e. encrypt it) the data must be copied per peer connection rather than sending the same buffer to multiple peers.
  2. The encryption itself requires more CPU than plain bittorrent protocol. The highest cost is the Diffie Hellman exchange on connection setup.
  3. The encryption handshake adds several round-trips to the connection setup, and delays transferring data.
name type default
allowed_enc_level int settings_pack::pe_both

determines the encryption level of the connections. This setting will adjust which encryption scheme is offered to the other peer, as well as which encryption scheme is selected by the client. See enc_level enum for options.

name type default
inactive_down_rate int 2048
inactive_up_rate int 2048

the download and upload rate limits for a torrent to be considered active by the queuing mechanism. A torrent whose download rate is less than inactive_down_rate and whose upload rate is less than inactive_up_rate for auto_manage_startup seconds, is considered inactive, and another queued torrent may be started. This logic is disabled if dont_count_slow_torrents is false.

name type default
proxy_type int settings_pack::none

proxy to use. see proxy_type_t.

name type default
proxy_port int 0

the port of the proxy server

name type default
i2p_port int 0

sets the i2p SAM bridge port to connect to. set the hostname with the i2p_hostname setting.

name type default
urlseed_max_request_bytes int 16 * 1024 * 1024

The maximum request range of an url seed in bytes. This value defines the largest possible sequential web seed request. Lower values are possible but will be ignored if they are lower then piece size. This value should be related to your download speed to prevent libtorrent from creating too many expensive http requests per second. You can select a value as high as you want but keep in mind that libtorrent can't create parallel requests if the first request did already select the whole file. If you combine bittorrent seeds with web seeds and pick strategies like rarest first you may find your web seed requests split into smaller parts because we don't download already picked pieces twice.

name type default
web_seed_name_lookup_retry int 1800

time to wait until a new retry of a web seed name lookup

name type default
close_file_interval int 0

the number of seconds between closing the file opened the longest ago. 0 means to disable the feature. The purpose of this is to periodically close files to trigger the operating system flushing disk cache. Specifically it has been observed to be required on windows to not have the disk cache grow indefinitely. This defaults to 120 seconds on windows, and disabled on other systems.

name type default
utp_cwnd_reduce_timer int 100

When uTP experiences packet loss, it will reduce the congestion window, and not reduce it again for this many milliseconds, even if experiencing another lost packet.

name type default
max_web_seed_connections int 3

the max number of web seeds to have connected per torrent at any given time.

name type default
resolver_cache_timeout int 1200

the number of seconds before the internal host name resolver considers a cache value timed out, negative values are interpreted as zero.

name type default
send_not_sent_low_watermark int 16384

specify the not-sent low watermark for socket send buffers. This corresponds to the, Linux-specific, TCP_NOTSENT_LOWAT TCP socket option.

name type default
rate_choker_initial_threshold int 1024

the rate based choker compares the upload rate to peers against a threshold that increases proportionally by its size for every peer it visits, visiting peers in decreasing upload rate. The number of upload slots is determined by the number of peers whose upload rate exceeds the threshold. This option sets the start value for this threshold. A higher value leads to fewer unchoke slots, a lower value leads to more.

name type default
upnp_lease_duration int 3600

The expiration time of UPnP port-mappings, specified in seconds. 0 means permanent lease. Some routers do not support expiration times on port-maps (nor correctly returning an error indicating lack of support). In those cases, set this to 0. Otherwise, don't set it any lower than 5 minutes.

name type default
max_concurrent_http_announces int 50

limits the number of concurrent HTTP tracker announces. Once the limit is hit, tracker requests are queued and issued when an outstanding announce completes.

name type default
dht_max_peers_reply int 100

the maximum number of peers to send in a reply to get_peers

name type default
dht_search_branching int 5

the number of concurrent search request the node will send when announcing and refreshing the routing table. This parameter is called alpha in the kademlia paper

name type default
dht_max_fail_count int 20

the maximum number of failed tries to contact a node before it is removed from the routing table. If there are known working nodes that are ready to replace a failing node, it will be replaced immediately, this limit is only used to clear out nodes that don't have any node that can replace them.

name type default
dht_max_torrents int 2000

the total number of torrents to track from the DHT. This is simply an upper limit to make sure malicious DHT nodes cannot make us allocate an unbounded amount of memory.

name type default
dht_max_dht_items int 700

max number of items the DHT will store

name type default
dht_max_peers int 500

the max number of peers to store per torrent (for the DHT)

name type default
dht_block_timeout int 5 * 60

the number of seconds a DHT node is banned if it exceeds the rate limit. The rate limit is averaged over 10 seconds to allow for bursts above the limit.

name type default
dht_block_ratelimit int 5

the max number of packets per second a DHT node is allowed to send without getting banned.

name type default
dht_item_lifetime int 0

the number of seconds a immutable/mutable item will be expired. default is 0, means never expires.

name type default
dht_sample_infohashes_interval int 21600

the info-hashes sample recomputation interval (in seconds). The node will precompute a subset of the tracked info-hashes and return that instead of calculating it upon each request. The permissible range is between 0 and 21600 seconds (inclusive).

name type default
dht_max_infohashes_sample_count int 20

the maximum number of elements in the sampled subset of info-hashes. If this number is too big, expect the DHT storage implementations to clamp it in order to allow UDP packets go through

name type default
max_piece_count int 0x200000

max_piece_count is the maximum allowed number of pieces in metadata received via magnet links. Loading large torrents (with more pieces than the default limit) may also require passing in a higher limit to read_resume_data() and torrent_info::parse_info_section(), if those are used.

struct settings_pack final : settings_interface
{
   friend  void apply_pack_impl (settings_pack const*
      , aux::session_settings_single_thread&
      , std::vector<void(aux::session_impl::*)()>*);
   void set_int (int name, int val) override;
   void set_int (int name, flags::bitfield_flag<Type, Tag> const val);
   void set_str (int name, std::string val) override;
   void set_bool (int name, bool val) override;
   bool has_val (int name) const override;
   void clear ();
   void clear (int name);
   int get_int (int name) const override;
   std::string const& get_str (int name) const override;
   bool get_bool (int name) const override;
   void for_each (Fun&& f) const;

   enum type_bases
   {
      string_type_base,
      int_type_base,
      bool_type_base,
      type_mask,
      index_mask,
   };

   enum suggest_mode_t
   {
      no_piece_suggestions,
      suggest_read_cache,
   };

   enum choking_algorithm_t
   {
      fixed_slots_choker,
      rate_based_choker,
      deprecated_bittyrant_choker,
   };

   enum seed_choking_algorithm_t
   {
      round_robin,
      fastest_upload,
      anti_leech,
   };

   enum io_buffer_mode_t
   {
      enable_os_cache,
      deprecated_disable_os_cache_for_aligned_files,
      disable_os_cache,
   };

   enum bandwidth_mixed_algo_t
   {
      prefer_tcp,
      peer_proportional,
   };

   enum enc_policy
   {
      pe_forced,
      pe_enabled,
      pe_disabled,
   };

   enum enc_level
   {
      pe_plaintext,
      pe_rc4,
      pe_both,
   };

   enum proxy_type_t
   {
      none,
      socks4,
      socks5,
      socks5_pw,
      http,
      http_pw,
      i2p_proxy,
   };
};
[report issue]

set_bool() set_str() set_int()

void set_int (int name, int val) override;
void set_int (int name, flags::bitfield_flag<Type, Tag> const val);
void set_str (int name, std::string val) override;
void set_bool (int name, bool val) override;

set a configuration option in the settings_pack. name is one of the enum values from string_types, int_types or bool_types. They must match the respective type of the set_* function.

[report issue]

has_val()

bool has_val (int name) const override;

queries whether the specified configuration option has a value set in this pack. name can be any enumeration value from string_types, int_types or bool_types.

[report issue]

clear()

void clear ();

clear the settings pack from all settings

[report issue]

clear()

void clear (int name);

clear a specific setting from the pack

[report issue]

get_bool() get_int() get_str()

int get_int (int name) const override;
std::string const& get_str (int name) const override;
bool get_bool (int name) const override;

queries the current configuration option from the settings_pack. name is one of the enumeration values from string_types, int_types or bool_types. The enum value must match the type of the get_* function.

[report issue]

enum type_bases

Declared in "libtorrent/settings_pack.hpp"

name value description
string_type_base 0  
int_type_base 16384  
bool_type_base 32768  
type_mask 49152  
index_mask 16383  
[report issue]

enum suggest_mode_t

Declared in "libtorrent/settings_pack.hpp"

name value description
no_piece_suggestions 0  
suggest_read_cache 1  
[report issue]

enum choking_algorithm_t

Declared in "libtorrent/settings_pack.hpp"

name value description
fixed_slots_choker 0 This is the traditional choker with a fixed number of unchoke slots (as specified by settings_pack::unchoke_slots_limit).
rate_based_choker 2

This opens up unchoke slots based on the upload rate achieved to peers. The more slots that are opened, the marginal upload rate required to open up another slot increases. Configure the initial threshold with settings_pack::rate_choker_initial_threshold.

For more information, see rate based choking.

deprecated_bittyrant_choker 3  
[report issue]

enum seed_choking_algorithm_t

Declared in "libtorrent/settings_pack.hpp"

name value description
round_robin 0 which round-robins the peers that are unchoked when seeding. This distributes the upload bandwidth uniformly and fairly. It minimizes the ability for a peer to download everything without redistributing it.
fastest_upload 1 unchokes the peers we can send to the fastest. This might be a bit more reliable in utilizing all available capacity.
anti_leech 2 prioritizes peers who have just started or are just about to finish the download. The intention is to force peers in the middle of the download to trade with each other. This does not just take into account the pieces a peer is reporting having downloaded, but also the pieces we have sent to it.
[report issue]

enum io_buffer_mode_t

Declared in "libtorrent/settings_pack.hpp"

name value description
enable_os_cache 0  
deprecated_disable_os_cache_for_aligned_files 1  
disable_os_cache 2  
[report issue]

enum bandwidth_mixed_algo_t

Declared in "libtorrent/settings_pack.hpp"

name value description
prefer_tcp 0 disables the mixed mode bandwidth balancing
peer_proportional 1 does not throttle uTP, throttles TCP to the same proportion of throughput as there are TCP connections
[report issue]

enum enc_policy

Declared in "libtorrent/settings_pack.hpp"

name value description
pe_forced 0 Only encrypted connections are allowed. Incoming connections that are not encrypted are closed and if the encrypted outgoing connection fails, a non-encrypted retry will not be made.
pe_enabled 1 encrypted connections are enabled, but non-encrypted connections are allowed. An incoming non-encrypted connection will be accepted, and if an outgoing encrypted connection fails, a non- encrypted connection will be tried.
pe_disabled 2 only non-encrypted connections are allowed.
[report issue]

enum enc_level

Declared in "libtorrent/settings_pack.hpp"

name value description
pe_plaintext 1 use only plain text encryption
pe_rc4 2 use only RC4 encryption
pe_both 3 allow both
[report issue]

enum proxy_type_t

Declared in "libtorrent/settings_pack.hpp"

name value description
none 0 No proxy server is used and all other fields are ignored.
socks4 1 The server is assumed to be a SOCKS4 server that requires a username.
socks5 2 The server is assumed to be a SOCKS5 server (RFC 1928) that does not require any authentication. The username and password are ignored.
socks5_pw 3 The server is assumed to be a SOCKS5 server that supports plain text username and password authentication (RFC 1929). The username and password specified may be sent to the proxy if it requires.
http 4 The server is assumed to be an HTTP proxy. If the transport used for the connection is non-HTTP, the server is assumed to support the CONNECT method. i.e. for web seeds and HTTP trackers, a plain proxy will suffice. The proxy is assumed to not require authorization. The username and password will not be used.
http_pw 5 The server is assumed to be an HTTP proxy that requires user authorization. The username and password will be sent to the proxy.
i2p_proxy 6 route through a i2p SAM proxy
[report issue]

min_memory_usage() high_performance_seed()

Declared in "libtorrent/session.hpp"

settings_pack high_performance_seed ();
settings_pack min_memory_usage ();

The default values of the session settings are set for a regular bittorrent client running on a desktop system. There are functions that can set the session settings to pre set settings for other environments. These can be used for the basis, and should be tweaked to fit your needs better.

min_memory_usage returns settings that will use the minimal amount of RAM, at the potential expense of upload and download performance. It adjusts the socket buffer sizes, disables the disk cache, lowers the send buffer watermarks so that each connection only has at most one block in use at any one time. It lowers the outstanding blocks send to the disk I/O thread so that connections only have one block waiting to be flushed to disk at any given time. It lowers the max number of peers in the peer list for torrents. It performs multiple smaller reads when it hashes pieces, instead of reading it all into memory before hashing.

This configuration is intended to be the starting point for embedded devices. It will significantly reduce memory usage.

high_performance_seed returns settings optimized for a seed box, serving many peers and that doesn't do any downloading. It has a 128 MB disk cache and has a limit of 400 files in its file pool. It support fast upload rates by allowing large send buffers.

[report issue]

setting_by_name() name_for_setting()

Declared in "libtorrent/settings_pack.hpp"

int setting_by_name (string_view name);
char const* name_for_setting (int s);

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

[report issue]

default_settings()

Declared in "libtorrent/settings_pack.hpp"

settings_pack default_settings ();

returns a settings_pack with every setting set to its default value

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

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

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

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

[report issue]

entry

Declared in "libtorrent/entry.hpp"

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

struct entry : entry_types::variant_type
{
   data_type type () const;
   entry (string_type);
   entry (dictionary_type);
   entry (string_view);
   entry (preformatted_type);
   entry (integer_type);
   entry (span<char const>);
   entry (list_type);
   entry (U v);
   entry (data_type t);
   entry (bdecode_node const& n);
   entry& operator= (string_view) &;
   entry& operator= (entry const&) &;
   entry& operator= (integer_type) &;
   entry& operator= (string_type) &;
   entry& operator= (span<char const>) &;
   entry& operator= (entry&&) & ;
   entry& operator= (preformatted_type) &;
   entry& operator= (dictionary_type) &;
   entry& operator= (list_type) &;
   entry& operator= (bdecode_node const&) &;
   entry& operator= (U v) &;
   dictionary_type const& dict () const;
   integer_type const& integer () const;
   dictionary_type& dict ();
   preformatted_type& preformatted ();
   string_type const& string () const;
   preformatted_type const& preformatted () const;
   integer_type& integer ();
   list_type const& list () const;
   string_type& string ();
   list_type& list ();
   entry const& operator[] (string_view key) const;
   entry& operator[] (string_view key);
   entry const* find_key (string_view key) const;
   entry* find_key (string_view key);
   std::string to_string (bool single_line = false) const;

   enum data_type
   {
      int_t,
      string_t,
      list_t,
      dictionary_t,
      preformatted_t,
      undefined_t,
   };
};
[report issue]

type()

data_type type () const;

returns the concrete type of the entry

[report issue]

entry()

entry (string_type);
entry (dictionary_type);
entry (string_view);
entry (preformatted_type);
entry (integer_type);
entry (span<char const>);
entry (list_type);

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

[report issue]

entry()

entry (data_type t);

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

[report issue]

entry()

entry (bdecode_node const& n);

construct from bdecode_node parsed form (see bdecode())

[report issue]

operator=()

entry& operator= (string_view) &;
entry& operator= (entry const&) &;
entry& operator= (integer_type) &;
entry& operator= (string_type) &;
entry& operator= (span<char const>) &;
entry& operator= (entry&&) & ;
entry& operator= (preformatted_type) &;
entry& operator= (dictionary_type) &;
entry& operator= (list_type) &;
entry& operator= (bdecode_node const&) &;

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

[report issue]

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

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

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

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

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

entry torrent_file;
// ...

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

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

entry torrent_file;
// ...

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

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

[report issue]

operator[]()

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

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

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

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

[report issue]

find_key()

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

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

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

[report issue]

to_string()

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

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

[report issue]

enum data_type

Declared in "libtorrent/entry.hpp"

name value description
int_t 0  
string_t 1  
list_t 2  
dictionary_t 3  
preformatted_t 4  
undefined_t 5  
[report issue]

operator<<()

Declared in "libtorrent/entry.hpp"

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

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

[report issue]

bencode()

Declared in "libtorrent/bencode.hpp"

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

This function will encode data to bencoded form.

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

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

std::vector<char> buffer;
bencode(std::back_inserter(buf), e);
[report issue]

bdecode_node

Declared in "libtorrent/bdecode.hpp"

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

There are 5 different types of nodes, see type_t.

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

   enum type_t
   {
      none_t,
      dict_t,
      list_t,
      string_t,
      int_t,
   };
};
[report issue]

bdecode_node()

bdecode_node () = default;

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

[report issue]

bdecode_node() operator=()

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

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

[report issue]

type()

type_t type () const noexcept;

the type of this node. See type_t.

[report issue]

bool()

explicit operator bool () const noexcept;

returns true if type() != none_t.

[report issue]

non_owning()

bdecode_node non_owning () const;

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

[report issue]

data_section() data_offset()

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

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

[report issue]

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

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

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

[report issue]

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

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

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

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

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

[report issue]

int_value()

std::int64_t int_value () const;

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

[report issue]

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

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

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

[report issue]

clear()

void clear ();

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

[report issue]

swap()

void swap (bdecode_node& n);

Swap contents.

[report issue]

reserve()

void reserve (int tokens);

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

[report issue]

switch_underlying_buffer()

void switch_underlying_buffer (char const* buf) noexcept;

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

[report issue]

has_soft_error()

bool has_soft_error (span<char> error) const;

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

[report issue]

enum type_t

Declared in "libtorrent/bdecode.hpp"

name value description
none_t 0 uninitialized or default constructed. This is also used to indicate that a node was not found in some cases.
dict_t 1 a dictionary node. The dict_find_ functions are valid.
list_t 2 a list node. The list_ functions are valid.
string_t 3 a string node, the string_ functions are valid.
int_t 4 an integer node. The int_ functions are valid.
[report issue]

print_entry()

Declared in "libtorrent/bdecode.hpp"

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

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

[report issue]

bdecode()

Declared in "libtorrent/bdecode.hpp"

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

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

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

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

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

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

[report issue]

hasher

Declared in "libtorrent/hasher.hpp"

this is a SHA-1 hash class.

You use it by first instantiating it, then call update() to feed it with data. i.e. you don't have to keep the entire buffer of which you want to create the hash in memory. You can feed the hasher parts of it at a time. When You have fed the hasher with all the data, you call final() and it will return the sha1-hash of the data.

The constructor that takes a char const* and an integer will construct the sha1 context and feed it the data passed in.

If you want to reuse the hasher object once you have created a hash, you have to call reset() to reinitialize it.

The built-in software version of sha1-algorithm was implemented by Steve Reid and released as public domain. For more info, see src/sha1.cpp.

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

hasher() operator=()

hasher (char const* data, int len);
hasher (hasher const&);
hasher& operator= (hasher const&) &;
explicit hasher (span<char const> data);

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

[report issue]

update()

hasher& update (char const* data, int len);
hasher& update (span<char const> data);

append the following bytes to what is being hashed

[report issue]

final()

sha1_hash final ();

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

[report issue]

reset()

void reset ();

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

[report issue]

hasher256

Declared in "libtorrent/hasher.hpp"

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

hasher256() operator=()

hasher256 (char const* data, int len);
hasher256 (hasher256 const&);
explicit hasher256 (span<char const> data);
hasher256& operator= (hasher256 const&) &;

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

[report issue]

update()

hasher256& update (char const* data, int len);
hasher256& update (span<char const> data);

append the following bytes to what is being hashed

[report issue]

final()

sha256_hash final ();

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

[report issue]

reset()

void reset ();

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

[report issue]

dht_state

Declared in "libtorrent/kademlia/dht_state.hpp"

This structure helps to store and load the state of the dht_tracker. At this moment the library is only a dual stack implementation of the DHT. See BEP 32

struct dht_state
{
   void clear ();

   node_ids_t nids;
   std::vector<udp::endpoint> nodes;
   std::vector<udp::endpoint> nodes6;
};
[report issue]
nodes
the bootstrap nodes saved from the buckets node
[report issue]
nodes6
the bootstrap nodes saved from the IPv6 buckets node
[report issue]

dht_storage_counters

Declared in "libtorrent/kademlia/dht_storage.hpp"

This structure hold the relevant counters for the storage

struct dht_storage_counters
{
   void reset ();

   std::int32_t torrents  = 0;
   std::int32_t peers  = 0;
   std::int32_t immutable_data  = 0;
   std::int32_t mutable_data  = 0;
};
[report issue]

reset()

void reset ();

This member function set the counters to zero.

[report issue]

dht_storage_interface

Declared in "libtorrent/kademlia/dht_storage.hpp"

The DHT storage interface is a pure virtual class that can be implemented to customize how the data for the DHT is stored.

The default storage implementation uses three maps in RAM to save the peers, mutable and immutable items and it's designed to provide a fast and fully compliant behavior of the BEPs.

libtorrent comes with one built-in storage implementation: dht_default_storage (private non-accessible class). Its constructor function is called dht_default_storage_constructor(). You should know that if this storage becomes full of DHT items, the current implementation could degrade in performance.

struct dht_storage_interface
{
   virtual void update_node_ids (std::vector<node_id> const& ids) = 0;
   virtual bool get_immutable_item (sha256_hash const& target
      , entry& item) const = 0;
   virtual void put_immutable_item (sha256_hash const& target
      , span<char const> buf
      , address const& addr) = 0;
   virtual bool get_mutable_item_seq (sha256_hash const& target
      , sequence_number& seq) const = 0;
   virtual bool get_mutable_item (sha256_hash const& target
      , sequence_number seq, bool force_fill
      , entry& item) const = 0;
   virtual void put_mutable_item (sha256_hash const& target
      , span<char const> buf
      , signature const& sig
      , sequence_number seq
      , public_key const& pk
      , span<char const> salt
      , address const& addr) = 0;
   virtual void tick () = 0;
   virtual dht_storage_counters counters () const = 0;
};
[report issue]

update_node_ids()

virtual void update_node_ids (std::vector<node_id> const& ids) = 0;

This member function notifies the list of all node's ids of each DHT running inside libtorrent. It's advisable that the concrete implementation keeps a copy of this list for an eventual prioritization when deleting an element to make room for a new one.

[report issue]

get_immutable_item()

virtual bool get_immutable_item (sha256_hash const& target
      , entry& item) const = 0;

This function retrieves the immutable item given its target hash.

For future implementers: The value should be returned as an entry in the key item["v"].

returns true if the item is found and the data is returned inside the (entry) out parameter item.

[report issue]

put_immutable_item()

virtual void put_immutable_item (sha256_hash const& target
      , span<char const> buf
      , address const& addr) = 0;

Store the item's data. This layer is only for storage. The authentication of the item is performed by the upper layer.

For implementers: This data can be stored only if the target is not already present. The implementation should consider the value of settings_pack::dht_max_dht_items.

[report issue]

get_mutable_item_seq()

virtual bool get_mutable_item_seq (sha256_hash const& target
      , sequence_number& seq) const = 0;

This function retrieves the sequence number of a mutable item.

returns true if the item is found and the data is returned inside the out parameter seq.

[report issue]

get_mutable_item()

virtual bool get_mutable_item (sha256_hash const& target
      , sequence_number seq, bool force_fill
      , entry& item) const = 0;

This function retrieves the mutable stored in the DHT.

For implementers: The item sequence should be stored in the key item["seq"]. if force_fill is true or (0 <= seq and seq < item["seq"]) the following keys should be filled item["v"] - with the value no encoded. item["sig"] - with a string representation of the signature. item["k"] - with a string representation of the public key.

returns true if the item is found and the data is returned inside the (entry) out parameter item.

[report issue]

put_mutable_item()

virtual void put_mutable_item (sha256_hash const& target
      , span<char const> buf
      , signature const& sig
      , sequence_number seq
      , public_key const& pk
      , span<char const> salt
      , address const& addr) = 0;

Store the item's data. This layer is only for storage. The authentication of the item is performed by the upper layer.

For implementers: The sequence number should be checked if the item is already present. The implementation should consider the value of settings_pack::dht_max_dht_items.

[report issue]

tick()

virtual void tick () = 0;

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

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

[report issue]

counters()

virtual dht_storage_counters counters () const = 0;

return stats counters for the store

[report issue]

node_entry

Declared in "libtorrent/kademlia/node_entry.hpp"

struct node_entry
{
   node_entry (node_id const& id_, udp::endpoint const& ep, int roundtriptime = 0xffff
      , bool pinged = false);
   node_entry () = default;
   void update_rtt (int new_rtt);
   explicit node_entry (udp::endpoint const& ep);
   int port () const;
   void set_pinged ();
   void reset_fail_count ();
   void timed_out ();
   address addr () const;
   bool pinged () const;
   int fail_count () const;
   udp::endpoint ep () const;
   bool confirmed () const;
   bool operator< (node_entry const& rhs) const;
   time_point last_queried = min_time ();

   time_point first_seen  = aux::time_now();
   node_id id {nullptr};
   aux::union_endpoint endpoint;
   std::uint16_t rtt  = 0xffff;
   std::uint8_t timeout_count  = 0xff;
   bool verified  = false;
};
[report issue]

operator<()

bool operator< (node_entry const& rhs) const;

compares which node_entry is "better". Smaller is better

[report issue]

min_time()

time_point last_queried = min_time ();

the time we last received a response for a request to this peer

[report issue]
rtt
the average RTT of this node
[report issue]
timeout_count
the number of times this node has failed to respond in a row 0xff is a special value to indicate we have not pinged this node yet
[report issue]

dht_default_storage_constructor()

Declared in "libtorrent/kademlia/dht_storage.hpp"

std::unique_ptr<dht_storage_interface> dht_default_storage_constructor (
   settings_interface const& settings);

constructor for the default DHT storage. The DHT storage is responsible for maintaining peers and mutable and immutable items announced and stored/put to the DHT node.

[report issue]

sign_mutable_item()

Declared in "libtorrent/kademlia/item.hpp"

signature sign_mutable_item (
   span<char const> v
   , span<char const> salt
   , sequence_number seq
   , public_key const& pk
   , secret_key const& sk);

given a byte range v and an optional byte range salt, a sequence number, public key pk (must be 32 bytes) and a secret key sk (must be 64 bytes), this function produces a signature which is written into a 64 byte buffer pointed to by sig. The caller is responsible for allocating the destination buffer that's passed in as the sig argument. Typically it would be allocated on the stack.

[report issue]

announce_flags_t

Declared in "libtorrent/kademlia/announce_flags.hpp"

seed
announce to DHT as a seed
implied_port
announce to DHT with the implied-port flag set. This tells the network to use your source UDP port as your listen port, rather than the one specified in the message. This may improve the chances of traversing NATs when using uTP.
ssl_torrent
Specify the port number for the SSL listen socket in the DHT announce.

communication模块主要负责朋友或者区块链群组之间消息的沟通, 同时作为time server,通过统计网络中位数时间,为其它模块提供时间基准

[report issue]

new_msg_signal

Declared in "libtorrent/communication/new_msg_signal.hpp"

The new_msg_signal class represents one type of mutable wrapper, is used to publish new message info in XY channel

class new_msg_signal
{
   new_msg_signal (aux::bytesConstRef _rlp);
   aux::bytes device_id () const;
   aux::bytes hash_prefix_bytes () const;
   uint32_t timestamp () const;
   void streamRLP (aux::RLPStream& _s) const;
   aux::bytes rlp () const;
};
[report issue]

new_msg_signal()

new_msg_signal (aux::bytesConstRef _rlp);

@param _rlp rlp encode

[report issue]

device_id()

aux::bytes device_id () const;

@returns device id

[report issue]

hash_prefix_bytes()

aux::bytes hash_prefix_bytes () const;

@returns hash prefix bytes

[report issue]

timestamp()

uint32_t timestamp () const;

@returns timestamp

[report issue]

streamRLP()

void streamRLP (aux::RLPStream& _s) const;

Serialises this new message signal to an RLPStream

[report issue]

rlp()

aux::bytes rlp () const;

@returns the RLP serialisation of this new message signal

[report issue]

message

Declared in "libtorrent/communication/message.hpp"

The message class shows message struct

class message
{
   message () = default;
   message (aux::bytesConstRef _rlp);
   message_version version () const;
   uint32_t timestamp () const;
   const aux::bytes &sender () const;
   const aux::bytes &receiver () const;
   const aux::bytes &logic_msg_hash () const;
   const aux::bigint &nonce () const;
   message_type type () const;
   const aux::bytes &encrypted_content () const;
   void streamRLP (aux::RLPStream& _s) const;
   aux::bytes rlp () const;
   sha256_hash sha256 () const;
   std::string to_string () const;
};
[report issue]

message()

message (aux::bytesConstRef _rlp);

@param _rlp rlp encode

[report issue]

version()

message_version version () const;

@returns message version

[report issue]

timestamp()

uint32_t timestamp () const;

@returns message timestamp

[report issue]

&sender()

const aux::bytes &sender () const;

@returns message sender

[report issue]

&receiver()

const aux::bytes &receiver () const;

@returns message receiver

[report issue]

&logic_msg_hash()

const aux::bytes &logic_msg_hash () const;

@returns message logic msg hash

[report issue]

&nonce()

const aux::bigint &nonce () const;

@returns message nonce

[report issue]

type()

message_type type () const;

@returns message type

[report issue]

&encrypted_content()

const aux::bytes &encrypted_content () const;

@returns encrypted content

[report issue]

streamRLP()

void streamRLP (aux::RLPStream& _s) const;

Serialises this message to an RLPStream

[report issue]

rlp()

aux::bytes rlp () const;

@returns the RLP serialisation of this message

[report issue]

sha256()

sha256_hash sha256 () const;

@returns the SHA256 hash of the RLP serialisation of this message

[report issue]

to_string()

std::string to_string () const;

@returns a pretty-printed string representation of message structure

[report issue]

communication

Declared in "libtorrent/communication/communication.hpp"

class communication final: public std::enable_shared_from_this<communication>
{
   bool start ();
   bool stop ();
   void set_loop_time_interval (int milliseconds);
   bool add_new_friend (const aux::bytes& pubkey);
   bool delete_friend (const aux::bytes& pubkey);
   aux::bytes get_friend_info (aux::bytes pubkey);
   bool update_friend_info (aux::bytes pubkey, aux::bytes friend_info);
   void set_chatting_friend (aux::bytes chatting_friend);
   void unset_chatting_friend ();
   void set_active_friends (std::vector<aux::bytes> &&active_friends);
   bool add_new_message (const message& msg);
   void account_changed ();
};
[report issue]

start()

bool start ();

start communication

[report issue]

stop()

bool stop ();

stop

[report issue]

set_loop_time_interval()

void set_loop_time_interval (int milliseconds);

set main loop time interval (ms)

[report issue]

add_new_friend()

bool add_new_friend (const aux::bytes& pubkey);

add new friend in memory & db

[report issue]

delete_friend()

bool delete_friend (const aux::bytes& pubkey);

delete friend and all related data in memory & db

[report issue]

get_friend_info()

aux::bytes get_friend_info (aux::bytes pubkey);

get friend info by public key

[report issue]

update_friend_info()

bool update_friend_info (aux::bytes pubkey, aux::bytes friend_info);

save friend info

[report issue]

set_chatting_friend()

void set_chatting_friend (aux::bytes chatting_friend);

set chatting friends

[report issue]

unset_chatting_friend()

void unset_chatting_friend ();

unset chatting friends

[report issue]

set_active_friends()

void set_active_friends (std::vector<aux::bytes> &&active_friends);

set active friends

[report issue]

add_new_message()

bool add_new_message (const message& msg);

add a new message

[report issue]

account_changed()

void account_changed ();

reset when account changed

[report issue]

message_container

Declared in "libtorrent/communication/message_container.hpp"

The message_container class represents one type of mutable wrapper, is used to put multiple messages together

class message_container
{
   explicit message_container (aux::bytesConstRef _rlp);
   explicit message_container (std::vector<message> messages);
   std::vector<message> messages () const;
   void streamRLP (aux::RLPStream& _s) const;
   aux::bytes rlp () const;
};
[report issue]

messages()

std::vector<message> messages () const;

@returns all messages in this container

[report issue]

streamRLP()

void streamRLP (aux::RLPStream& _s) const;

Serialises this message container to an RLPStream

[report issue]

rlp()

aux::bytes rlp () const;

@returns the RLP serialisation of this message container

[report issue]

message_db_interface

Declared in "libtorrent/communication/message_db_interface.hpp"

The message_db_interface 提供message相关的存储接口, 包括朋友公钥的存取删除,消息的存取删除,以及最新消息哈希列表编码的存取删除, 每一个朋友都会对应一个最新消息哈希集合,该集合是该通信对最新200个消息完整哈希的时间排列的顺序列表, 每当有更新的消息加入该列表,列表满载时会删除其最老的消息哈希,并根据该哈希删除相应的消息; 并且,该哈希列表也用来生成对应的莱温斯坦数组,只需取哈希的第一个字节,并按对应顺序排列即可

struct message_db_interface
{
   virtual bool init () = 0;
   virtual std::vector<aux::bytes> get_all_friends () = 0;
   virtual bool save_friend (aux::bytes public_key) = 0;
   virtual bool delete_friend (aux::bytes public_key) = 0;
   virtual aux::bytes get_friend_info (aux::bytes public_key) = 0;
   virtual bool save_friend_info (aux::bytes public_key, aux::bytes friend_info) = 0;
   virtual bool delete_friend_info (aux::bytes public_key) = 0;
   virtual communication::message get_message (aux::bytes hash) = 0;
   virtual bool save_message (communication::message msg) = 0;
   virtual bool delete_message (aux::bytes hash) = 0;
   virtual aux::bytes get_latest_message_hash_list_encode (aux::bytes public_key) = 0;
   virtual bool save_latest_message_hash_list_encode (aux::bytes public_key, aux::bytes encode) = 0;
   virtual bool delete_latest_message_hash_list_encode (aux::bytes public_key) = 0;
   virtual ~message_db_interface ();
};
[report issue]

init()

virtual bool init () = 0;

init db

[report issue]

get_all_friends()

virtual std::vector<aux::bytes> get_all_friends () = 0;

get all friends

[report issue]

save_friend()

virtual bool save_friend (aux::bytes public_key) = 0;

save a friend in db

[report issue]

delete_friend()

virtual bool delete_friend (aux::bytes public_key) = 0;

delete a friend

[report issue]

get_friend_info()

virtual aux::bytes get_friend_info (aux::bytes public_key) = 0;

get friend info by public key

[report issue]

save_friend_info()

virtual bool save_friend_info (aux::bytes public_key, aux::bytes friend_info) = 0;

save friend info

[report issue]

delete_friend_info()

virtual bool delete_friend_info (aux::bytes public_key) = 0;

delete friend info

[report issue]

get_message()

virtual communication::message get_message (aux::bytes hash) = 0;

get message by hash

[report issue]

save_message()

virtual bool save_message (communication::message msg) = 0;

save message

[report issue]

delete_message()

virtual bool delete_message (aux::bytes hash) = 0;

delete message

[report issue]

get_latest_message_hash_list_encode()

virtual aux::bytes get_latest_message_hash_list_encode (aux::bytes public_key) = 0;

get encode of the latest message hash list

[report issue]

save_latest_message_hash_list_encode()

virtual bool save_latest_message_hash_list_encode (aux::bytes public_key, aux::bytes encode) = 0;

save encode of the latest message hash list

[report issue]

delete_latest_message_hash_list_encode()

virtual bool delete_latest_message_hash_list_encode (aux::bytes public_key) = 0;

delete encode of the latest message hash list

[report issue]

message_hash_list

Declared in "libtorrent/communication/message_hash_list.hpp"

The message_hash_list class is a list, encode/decode message hash list

class message_hash_list
{
   explicit message_hash_list (aux::bytesConstRef _rlp);
   explicit message_hash_list (std::vector<aux::bytes> message_hash_list);
   std::vector<aux::bytes> hash_list () const;
   void streamRLP (aux::RLPStream& _s) const;
   aux::bytes rlp () const;
};
[report issue]

hash_list()

std::vector<aux::bytes> hash_list () const;

@returns all message hash in this container

[report issue]

streamRLP()

void streamRLP (aux::RLPStream& _s) const;

Serialises this message hash list to an RLPStream

[report issue]

rlp()

aux::bytes rlp () const;

@returns the RLP serialisation of this message hash list

[report issue]

mutable_data_wrapper

Declared in "libtorrent/communication/mutable_data_wrapper.hpp"

The mutable_data_wrapper class represents wrap all mutable data including message container, online signal, new message signal.

class mutable_data_wrapper
{
   explicit mutable_data_wrapper (aux::bytesConstRef _rlp);
   mutable_data_wrapper (uint32_t mTimestamp, mutable_data_type mType, aux::bytes mPayload);
   uint32_t timestamp () const;
   mutable_data_type type () const;
   aux::bytes payload () const;
   void streamRLP (aux::RLPStream& _s) const;
   aux::bytes rlp () const;
};
[report issue]

mutable_data_wrapper()

explicit mutable_data_wrapper (aux::bytesConstRef _rlp);

@param _rlp rlp encode

[report issue]

timestamp()

uint32_t timestamp () const;

@returns timestamp

[report issue]

type()

mutable_data_type type () const;

@returns type

[report issue]

payload()

aux::bytes payload () const;

@returns payload

[report issue]

streamRLP()

void streamRLP (aux::RLPStream& _s) const;

Serialises this mutable data wrapper to an RLPStream

[report issue]

rlp()

aux::bytes rlp () const;

@returns the RLP serialisation of this mutable data wrapper

[report issue]

online_signal

Declared in "libtorrent/communication/online_signal.hpp"

The online_signal class represents one type of mutable wrapper, is used to publish online info in XX channel

struct online_signal
{
   online_signal (aux::bytesConstRef _rlp);
   inline aux::bytes device_id () const;
   inline aux::bytes hash_prefix_bytes () const;
   inline uint32_t timestamp () const;
   inline aux::bytes friend_info () const;
   void streamRLP (aux::RLPStream& _s) const;
   aux::bytes rlp () const;
};
[report issue]

online_signal()

online_signal (aux::bytesConstRef _rlp);

@param _rlp rlp encode

[report issue]

device_id()

inline aux::bytes device_id () const;

@returns device id

[report issue]

hash_prefix_bytes()

inline aux::bytes hash_prefix_bytes () const;

@returns hash prefix bytes

[report issue]

timestamp()

inline uint32_t timestamp () const;

@returns timestamp

[report issue]

friend_info()

inline aux::bytes friend_info () const;

@returns friend info bytes

[report issue]

streamRLP()

void streamRLP (aux::RLPStream& _s) const;

Serialises this online signal to an RLPStream

[report issue]

rlp()

aux::bytes rlp () const;

@returns the RLP serialisation of this message

[report issue]

enum message_version

Declared in "libtorrent/communication/message.hpp"

name value description
VERSION_1 0 current version
UNSUPPORTED_VERSION 1 unsupported version
[report issue]

enum message_type

Declared in "libtorrent/communication/message.hpp"

name value description
TEXT 0 message type is text
PICTURE 1 message type is picture
UNSUPPORTED_TYPE 2 unsupported message type
[report issue]

enum mutable_data_type

Declared in "libtorrent/communication/mutable_data_wrapper.hpp"

name value description
MESSAGE 0  
MESSAGE_CONTAINER 1  
ONLINE_SIGNAL 2  
NEW_MSG_SIGNAL 3  
UNKNOWN 4  
[report issue]

int

Declared in "libtorrent/communication/communication.hpp"

communication_default_refresh_time
default refresh time of main task
communication_max_message_list_size
max message list size(used in Levenshtein Distance)
communication_short_address_length
short address(public key) length
[report issue]

bdecode_category()

Declared in "libtorrent/bdecode.hpp"

boost::system::error_category& bdecode_category ();
[report issue]

enum error_code_enum

Declared in "libtorrent/bdecode.hpp"

name value description
no_error 0 Not an error
expected_digit 1 expected digit in bencoded string
expected_colon 2 expected colon in bencoded string
unexpected_eof 3 unexpected end of file in bencoded string
expected_value 4 expected value (list, dict, int or string) in bencoded string
depth_exceeded 5 bencoded recursion depth limit exceeded
limit_exceeded 6 bencoded item count limit exceeded
overflow 7 integer overflow
error_code_max 8 the number of error codes
[report issue]

ed25519_create_seed()

Declared in "libtorrent/kademlia/ed25519.hpp"

std::array<char, 32> ed25519_create_seed ();

See documentation of internal random_bytes

[report issue]

ed25519_create_keypair()

Declared in "libtorrent/kademlia/ed25519.hpp"

std::tuple<public_key, secret_key> ed25519_create_keypair (
   std::array<char, 32> const& seed);

Creates a new key pair from the given seed.

It's important to clarify that the seed completely determines the key pair. Then it's enough to save the seed and the public key as the key-pair in a buffer of 64 bytes. The standard is (32 bytes seed, 32 bytes public key).

This function does work with a given seed, giving you a pair of (64 bytes private key, 32 bytes public key). It's a trade-off between space and CPU, saving in one format or another.

The smaller format is not weaker by any means, in fact, it is only the seed (32 bytes) that determines the point in the curve.

[report issue]

ed25519_sign()

Declared in "libtorrent/kademlia/ed25519.hpp"

signature ed25519_sign (span<char const> msg
   , public_key const& pk, secret_key const& sk);

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

[report issue]

ed25519_verify()

Declared in "libtorrent/kademlia/ed25519.hpp"

bool ed25519_verify (signature const& sig
   , span<char const> msg, public_key const& pk);

Verifies the signature on the given message using pk

[report issue]

ed25519_add_scalar()

Declared in "libtorrent/kademlia/ed25519.hpp"

public_key ed25519_add_scalar (public_key const& pk
   , std::array<char, 32> const& scalar);
secret_key ed25519_add_scalar (secret_key const& sk
   , std::array<char, 32> const& scalar);

Adds a scalar to the given key pair where scalar is a 32 byte buffer (possibly generated with ed25519_create_seed), generating a new key pair.

You can calculate the public key sum without knowing the private key and vice versa by passing in null for the key you don't know. This is useful when a third party (an authoritative server for example) needs to enforce randomness on a key pair while only knowing the public key of the other side.

Warning: the last bit of the scalar is ignored - if comparing scalars make sure to clear it with scalar[31] &= 127.

see http://crypto.stackexchange.com/a/6215/4697 see test_ed25519 for a practical example

[report issue]

ed25519_key_exchange()

Declared in "libtorrent/kademlia/ed25519.hpp"

std::array<char, 32> ed25519_key_exchange (
   public_key const& pk, secret_key const& sk);

Performs a key exchange on the given public key and private key, producing a shared secret. It is recommended to hash the shared secret before using it.

This is useful when two parties want to share a secret but both only knows their respective public keys. see test_ed25519 for a practical example