<p>The interface of libtorrent consists of a few classes. The main class is
the <ttclass="docutils literal">session</tt>, it contains the main loop that serves all torrents.</p>
<p>The basic usage is as follows:</p>
<ul>
<li><pclass="first">construct a <aclass="reference external"href="reference-Session.html#session">session</a></p>
</li>
<li><pclass="first">load <aclass="reference external"href="reference-Session.html#session">session</a> state from settings file (see <aclass="reference external"href="reference-Session.html#load_state()">load_state()</a>)</p>
</li>
<li><pclass="first">start extensions (see <aclass="reference external"href="reference-Core.html#add_extension()">add_extension()</a>).</p>
<li><pclass="first">parse .torrent-files and add them to the <aclass="reference external"href="reference-Session.html#session">session</a> (see <aclass="reference external"href="reference-Core.html#torrent_info">torrent_info</a>,
<aclass="reference external"href="reference-Session.html#async_add_torrent()">async_add_torrent()</a> and <aclass="reference external"href="reference-Session.html#add_torrent()">add_torrent()</a>)</p>
<li><pclass="first">main loop (see <aclass="reference external"href="reference-Session.html#session">session</a>)</p>
<blockquote>
<ulclass="simple">
<li>poll for alerts (see <aclass="reference external"href="reference-Session.html#wait_for_alert()">wait_for_alert()</a>, <aclass="reference external"href="reference-Session.html#pop_alerts()">pop_alerts()</a>)</li>
<li>handle updates to torrents, (see <aclass="reference external"href="reference-Alerts.html#state_update_alert">state_update_alert</a>).</li>
<li>handle other alerts, (see <aclass="reference external"href="reference-Alerts.html#alert">alert</a>).</li>
<li>query the <aclass="reference external"href="reference-Session.html#session">session</a> for information (see <aclass="reference external"href="reference-Session.html#status()">session::status()</a>).</li>
<li>add and remove torrents from the <aclass="reference external"href="reference-Session.html#session">session</a> (<aclass="reference external"href="reference-Session.html#remove_torrent()">remove_torrent()</a>)</li>
<li><pclass="first">save <aclass="reference external"href="reference-Session.html#session">session</a> state (see <aclass="reference external"href="reference-Session.html#save_state()">save_state()</a>)</p>
<p>Each class and function is described in this manual.</p>
<p>For a description on how to create torrent files, see <aclass="reference external"href="reference-Create_Torrents.html#create_torrent">create_torrent</a>.</p>
</div>
<divclass="section"id="things-to-keep-in-mind">
<h1>things to keep in mind</h1>
<p>A common problem developers are facing is torrents stopping without explanation.
Here is a description on which conditions libtorrent will stop your torrents,
how to find out about it and what to do about it.</p>
<p>Make sure to keep track of the paused state, the error state and the upload
mode of your torrents. By default, torrents are auto-managed, which means
libtorrent will pause them, unpause them, scrape them and take them out
of upload-mode automatically.</p>
<p>Whenever a torrent encounters a fatal error, it will be stopped, and the
<ttclass="docutils literal"><spanclass="pre">torrent_status::error</span></tt> will describe the error that caused it. If a torrent
is auto managed, it is scraped periodically and paused or resumed based on
the number of downloaders per seed. This will effectively seed torrents that
are in the greatest need of seeds.</p>
<p>If a torrent hits a disk write error, it will be put into upload mode. This
means it will not download anything, but only upload. The assumption is that
the write error is caused by a full disk or write permission errors. If the
torrent is auto-managed, it will periodically be taken out of the upload
mode, trying to write things to the disk again. This means torrent will recover
from certain disk errors if the problem is resolved. If the torrent is not
auto managed, you have to call <aclass="reference external"href="reference-Core.html#set_upload_mode()">set_upload_mode()</a> to turn
downloading back on again.</p>
</div>
<divclass="section"id="network-primitives">
<h1>network primitives</h1>
<p>There are a few typedefs in the <ttclass="docutils literal">libtorrent</tt> namespace which pulls
in network types from the <ttclass="docutils literal">asio</tt> namespace. These are:</p>
<preclass="literal-block">
typedef asio::ip::address address;
typedef asio::ip::address_v4 address_v4;
typedef asio::ip::address_v6 address_v6;
using asio::ip::tcp;
using asio::ip::udp;
</pre>
<p>These are declared in the <ttclass="docutils literal"><libtorrent/socket.hpp></tt> header.</p>
<p>The <ttclass="docutils literal">using</tt> statements will give easy access to:</p>
<preclass="literal-block">
tcp::endpoint
udp::endpoint
</pre>
<p>Which are the endpoint types used in libtorrent. An endpoint is an address
with an associated port.</p>
<p>For documentation on these types, please refer to the <aclass="reference external"href="http://asio.sourceforge.net/asio-0.3.8/doc/asio/reference.html">asio documentation</a>.</p>
</div>
<divclass="section"id="exceptions">
<h1>exceptions</h1>
<p>Many functions in libtorrent have two versions, one that throws exceptions on
errors and one that takes an <ttclass="docutils literal">error_code</tt> reference which is filled with the
error code on errors.</p>
<p>There is one exception class that is used for errors in libtorrent, it is based
on boost.system's <ttclass="docutils literal">error_code</tt> class to carry the error code.</p>
<p>For more information, see <aclass="reference external"href="reference-Error_Codes.html#libtorrent_exception">libtorrent_exception</a> and <aclass="reference external"href="reference-Error_Codes.html#error_code_enum">error_code_enum</a>.</p>
<divclass="section"id="translating-error-codes">
<h2>translating error codes</h2>
<p>The error_code::message() function will typically return a localized error string,
for system errors. That is, errors that belong to the generic or system category.</p>
<p>Errors that belong to the libtorrent error category are not localized however, they
are only available in english. In order to translate libtorrent errors, compare the
error category of the <ttclass="docutils literal">error_code</tt> object against <ttclass="docutils literal"><spanclass="pre">libtorrent::get_libtorrent_category()</span></tt>,
and if matches, you know the error code refers to the list above. You can provide
your own mapping from error code to string, which is localized. In this case, you
cannot rely on <ttclass="docutils literal"><spanclass="pre">error_code::message()</span></tt> to generate your strings.</p>
<p>The numeric values of the errors are part of the API and will stay the same, although
new error codes may be appended at the end.</p>
<p>Here's a simple example of how to translate error codes:</p>
<p>Torrents that are <em>auto managed</em> are subject to the queuing and the active
torrents limits. To make a torrent auto managed, set <ttclass="docutils literal">auto_managed</tt> to true
when adding the torrent (see <aclass="reference external"href="reference-Session.html#async_add_torrent()">async_add_torrent()</a> and <aclass="reference external"href="reference-Session.html#add_torrent()">add_torrent()</a>).</p>
<ttclass="docutils literal">active_downloads</tt>, <ttclass="docutils literal">active_seeds</tt> and <ttclass="docutils literal">active_limit</tt> in
<aclass="reference external"href="reference-Settings.html#session_settings">session_settings</a>. These limits takes non auto managed torrents into account as
well. If there are more non-auto managed torrents being downloaded than the
<ttclass="docutils literal">active_downloads</tt> setting, any auto managed torrents will be queued until
torrents are removed so that the number drops below the limit.</p>
<p>At a regular interval, torrents are checked if there needs to be any
re-ordering of which torrents are active and which are queued. This interval
can be controlled via <ttclass="docutils literal">auto_manage_interval</tt> in <aclass="reference external"href="reference-Settings.html#session_settings">session_settings</a>. It defaults
to every 30 seconds.</p>
<p>For queuing to work, resume data needs to be saved and restored for all
torrents. See <aclass="reference external"href="reference-Core.html#save_resume_data()">save_resume_data()</a>.</p>
<aclass="reference external"href="reference-Core.html#queue_position_top()">queue_position_top()</a> and <aclass="reference external"href="reference-Core.html#queue_position_bottom()">queue_position_bottom()</a>.</p>
<p>The relevant settings to control these limits are <ttclass="docutils literal">share_ratio_limit</tt>,
<ttclass="docutils literal">seed_time_ratio_limit</tt> and <ttclass="docutils literal">seed_time_limit</tt> in <aclass="reference external"href="reference-Settings.html#session_settings">session_settings</a>.</p>
</div>
</div>
<divclass="section"id="fast-resume">
<h1>fast resume</h1>
<p>The fast resume mechanism is a way to remember which pieces are downloaded
and where they are put between sessions. You can generate fast resume data by
calling <aclass="reference external"href="reference-Core.html#save_resume_data()">save_resume_data()</a> on <aclass="reference external"href="reference-Core.html#torrent_handle">torrent_handle</a>. You can
then save this data to disk and use it when resuming the torrent. libtorrent
will not check the piece hashes then, and rely on the information given in the
fast-resume data. The fast-resume data also contains information about which
blocks, in the unfinished pieces, were downloaded, so it will not have to
start from scratch on the partially downloaded pieces.</p>
<p>To use the fast-resume data you simply give it to <aclass="reference external"href="reference-Session.html#async_add_torrent()">async_add_torrent()</a> and
<aclass="reference external"href="reference-Session.html#add_torrent()">add_torrent()</a>, and it will skip the time consuming checks. It may have to do
the checking anyway, if the fast-resume data is corrupt or doesn't fit the
storage for that torrent, then it will not trust the fast-resume data and just
<p>The allocation mode is selected when a torrent is started. It is passed as an
argument to <aclass="reference external"href="reference-Session.html#add_torrent()">session::add_torrent()</a> or <aclass="reference external"href="reference-Session.html#async_add_torrent()">session::async_add_torrent()</a>.</p>
<p>This extension is deprecated in favor of the more widely supported
<ttclass="docutils literal">ut_metadata</tt> extension, see <aclass="reference external"href="http://bittorrent.org/beps/bep_0009.html">BEP 9</a>. The point with this extension is that
you don't have to distribute the metadata (.torrent-file) separately. The
metadata can be distributed through the bittorrent swarm. The only thing you
need to download such a torrent is the tracker url and the info-hash of the
torrent.</p>
<p>It works by assuming that the initial seeder has the metadata and that the
metadata will propagate through the network as more peers join.</p>
<p>There are three kinds of messages in the metadata extension. These packets are
put as payload to the extension message. The three packets are:</p>
<p>There are two kinds of HTTP seeding. One with that assumes a smart (and polite)
client and one that assumes a smart server. These are specified in <aclass="reference external"href="http://bittorrent.org/beps/bep_0019.html">BEP 19</a>
and <aclass="reference external"href="http://bittorrent.org/beps/bep_0017.html">BEP 17</a> respectively.</p>
<p>libtorrent supports both. In the libtorrent source code and API, BEP 19 urls
are typically referred to as <em>url seeds</em> and BEP 17 urls are typically referred
to as <em>HTTP seeds</em>.</p>
<p>The libtorrent implementation of <aclass="reference external"href="http://bittorrent.org/beps/bep_0019.html">BEP 19</a> assumes that, if the URL ends with a
slash ('/'), the filename should be appended to it in order to request pieces
from that file. The way this works is that if the torrent is a single-file
torrent, only that filename is appended. If the torrent is a multi-file
torrent, the torrent's name '/' the file name is appended. This is the same
directory structure that libtorrent will download torrents into.</p>
<p>This threshold is controlled by <aclass="reference external"href="reference-Settings.html#whole_pieces_threshold">session_settings::whole_pieces_threshold</a>.</p>
<p><em>TODO: piece affinity by speed category</em>
<em>TODO: piece priorities</em></p>
</div>
</div>
<divclass="section"id="ssl-torrents">
<h1>SSL torrents</h1>
<p>Torrents may have an SSL root (CA) certificate embedded in them. Such torrents
<p>During the SSL handshake, both peers need to authenticate by providing a
certificate that is signed by the CA certificate found in the .torrent file.
These peer certificates are expected to be privided to peers through some other
means than bittorrent. Typically by a peer generating a certificate request
which is sent to the publisher of the torrent, and the publisher returning a
signed certificate.</p>
<p>In libtorrent, <aclass="reference external"href="reference-Core.html#set_ssl_certificate()">set_ssl_certificate()</a> in <aclass="reference external"href="reference-Core.html#torrent_handle">torrent_handle</a> is used to tell
libtorrent where to find the peer certificate and the private key for it. When
an SSL torrent is loaded, the <aclass="reference external"href="reference-Alerts.html#torrent_need_cert_alert">torrent_need_cert_alert</a> is posted to remind the
user to provide a certificate.</p>
<p>A peer connecting to an SSL torrent MUST provide the <em>SNI</em> TLS extension
(server name indication). The server name is the hex encoded info-hash of the
torrent to connect to. This is required for the client accepting the connection
to know which certificate to present.</p>
<p>SSL connections are accepted on a separate socket from normal bittorrent
connections. To pick which port the SSL socket should bind to, set
<aclass="reference external"href="reference-Settings.html#ssl_listen">session_settings::ssl_listen</a> to a different port. It defaults to port 4433.
This setting is only taken into account when the normal listen socket is opened
(i.e. just changing this setting won't necessarily close and re-open the SSL
socket). To not listen on an SSL socket at all, set <ttclass="docutils literal">ssl_listen</tt> to 0.</p>
<p>This feature is only available if libtorrent is build with openssl support
(<ttclass="docutils literal">TORRENT_USE_OPENSSL</tt>) and requires at least openSSL version 1.0, since it
needs SNI support.</p>
<p>Peer certificates must have at least one <em>SubjectAltName</em> field of type
dNSName. At least one of the fields must <em>exactly</em> match the name of the
torrent. This is a byte-by-byte comparison, the UTF-8 encoding must be
identical (i.e. there's no unicode normalization going on). This is the
recommended way of verifying certificates for HTTPS servers according to <aclass="reference external"href="http://www.ietf.org/rfc/rfc2818.txt">RFC
2818</a>. Note the difference that for torrents only <em>dNSName</em> fields are taken
into account (not IP address fields). The most specific (i.e. last) <em>Common
Name</em> field is also taken into account if no <em>SubjectAltName</em> did not match.</p>
<p>If any of these fields contain a single asterisk ("*"), the certificate is
considered covering any torrent, allowing it to be reused for any torrent.</p>
<p>The purpose of matching the torrent name with the fields in the peer
certificate is to allow a publisher to have a single root certificate for all
torrents it distributes, and issue separate peer certificates for each torrent.
A peer receiving a certificate will not necessarily be able to access all
torrents published by this root certificate (only if it has a "star cert").</p>
