<p>Declared in "<aclass="reference external"href="../include/libtorrent/add_torrent_params.hpp">libtorrent/add_torrent_params.hpp</a>"</p>
<p>The <aclass="reference external"href="reference-Session.html#add_torrent_params">add_torrent_params</a> is a parameter pack for adding torrents to a <aclass="reference external"href="reference-Session.html#session">session</a>.
The key fields when adding a torrent are:</p>
<ulclass="simple">
<li>ti - when you have a .torrent file</li>
<li>url - when you have a magnet link or http URL to the .torrent file</li>
<li>info_hash - when all you have is an info-hash (this is similar to a magnet link)</li>
</ul>
<p>one of those fields need to be set. Another mandatory field is <ttclass="docutils literal">save_path</tt>.
The <aclass="reference external"href="reference-Session.html#add_torrent_params">add_torrent_params</a> object is passed into one of the <ttclass="docutils literal"><spanclass="pre">session::add_torrent()</span></tt>
overloads or <ttclass="docutils literal"><spanclass="pre">session::async_add_torrent()</span></tt>.</p>
<p>If you only specify the info-hash, the torrent file will be downloaded from peers,
which requires them to support the metadata extension. For the metadata extension
to work, libtorrent must be built with extensions enabled (<ttclass="docutils literal">TORRENT_DISABLE_EXTENSIONS</tt> must not be
defined). It also takes an optional <ttclass="docutils literal">name</tt> argument. This may be left empty in case no
name should be assigned to the torrent. In case it's not, the name is used for
the torrent as long as it doesn't have metadata. See <ttclass="docutils literal"><spanclass="pre">torrent_handle::name</span></tt>.</p>
<p>The constructor can be used to initialize the storage constructor, which determines
the storage mechanism for the downloaded or seeding data for the torrent. For more
information, see the <ttclass="docutils literal">storage</tt> field.</p>
<aname="flags_t"></a></div>
<divclass="section"id="enum-flags-t">
<h2>enum flags_t</h2>
<p>Declared in "<aclass="reference external"href="../include/libtorrent/add_torrent_params.hpp">libtorrent/add_torrent_params.hpp</a>"</p>
<tableborder="1"class="docutils">
<colgroup>
<colwidth="21%"/>
<colwidth="5%"/>
<colwidth="74%"/>
</colgroup>
<theadvalign="bottom">
<tr><thclass="head">name</th>
<thclass="head">value</th>
<thclass="head">description</th>
</tr>
</thead>
<tbodyvalign="top">
<tr><td>flag_seed_mode</td>
<td>1</td>
<td><pclass="first">If <ttclass="docutils literal">flag_seed_mode</tt> is set, libtorrent will assume that all files are present
for this torrent and that they all match the hashes in the torrent file. Each time
a peer requests to download a block, the piece is verified against the hash, unless
it has been verified already. If a hash fails, the torrent will automatically leave
the seed mode and recheck all the files. The use case for this mode is if a torrent
is created and seeded, or if the user already know that the files are complete, this
is a way to avoid the initial file checks, and significantly reduce the startup time.</p>
<p>Setting <ttclass="docutils literal">flag_seed_mode</tt> on a torrent without metadata (a .torrent file) is a no-op
and will be ignored.</p>
<pclass="last">If resume data is passed in with this torrent, the seed mode saved in there will
override the seed mode you set here.</p>
</td>
</tr>
<tr><td>flag_override_resume_data</td>
<td>2</td>
<td><pclass="first">If <ttclass="docutils literal">flag_override_resume_data</tt> is set, the <ttclass="docutils literal">paused</tt> and <ttclass="docutils literal">auto_managed</tt>
state of the torrent are not loaded from the resume data, but the states requested
by the flags in <ttclass="docutils literal">add_torrent_params</tt> will override them.</p>
<pclass="last">If you pass in resume data, the paused state of the torrent when the resume data
was saved will override the paused state you pass in here. You can override this
by setting <ttclass="docutils literal">flag_override_resume_data</tt>.</p>
</td>
</tr>
<tr><td>flag_upload_mode</td>
<td>4</td>
<td><pclass="first">If <ttclass="docutils literal">flag_upload_mode</tt> is set, the torrent will be initialized in upload-mode,
which means it will not make any piece requests. This state is typically entered
on disk I/O errors, and if the torrent is also auto managed, it will be taken out
of this state periodically. This mode can be used to avoid race conditions when
adjusting priorities of pieces before allowing the torrent to start downloading.</p>
<pclass="last">If the torrent is auto-managed (<ttclass="docutils literal">flag_auto_managed</tt>), the torrent will eventually
be taken out of upload-mode, regardless of how it got there. If it's important to
manually control when the torrent leaves upload mode, don't make it auto managed.</p>
</td>
</tr>
<tr><td>flag_share_mode</td>
<td>8</td>
<td><pclass="first">determines if the torrent should be added in <em>share mode</em> or not.
Share mode indicates that we are not interested in downloading the torrent, but
merley want to improve our share ratio (i.e. increase it). A torrent started in
share mode will do its best to never download more than it uploads to the swarm.
If the swarm does not have enough demand for upload capacity, the torrent will
not download anything. This mode is intended to be safe to add any number of torrents
to, without manual screening, without the risk of downloading more than is uploaded.</p>
<p>A torrent in share mode sets the priority to all pieces to 0, except for the pieces
that are downloaded, when pieces are decided to be downloaded. This affects the progress
bar, which might be set to "100% finished" most of the time. Do not change file or piece
priorities for torrents in share mode, it will make it not work.</p>
<pclass="last">The share mode has one setting, the share ratio target, see <ttclass="docutils literal"><spanclass="pre">session_settings::share_mode_target</span></tt>
for more info.</p>
</td>
</tr>
<tr><td>flag_apply_ip_filter</td>
<td>16</td>
<td>determines if the IP filter should apply to this torrent or not. By
default all torrents are subject to filtering by the IP filter (i.e. this flag is set by
default). This is useful if certain torrents needs to be excempt for some reason, being
an auto-update torrent for instance.</td>
</tr>
<tr><td>flag_paused</td>
<td>32</td>
<td>specifies whether or not the torrent is to be started in a paused
state. I.e. it won't connect to the tracker or any of the peers until it's
resumed. This is typically a good way of avoiding race conditions when setting
configuration options on torrents before starting them.</td>
</tr>
<tr><td>flag_auto_managed</td>
<td>64</td>
<td><pclass="first">If the torrent is auto-managed (<ttclass="docutils literal">flag_auto_managed</tt>), the torrent may be resumed
at any point, regardless of how it paused. If it's important to manually control
when the torrent is paused and resumed, don't make it auto managed.</p>
<p>If <ttclass="docutils literal">flag_auto_managed</tt> is set, the torrent will be queued, started and seeded
automatically by libtorrent. When this is set, the torrent should also be started
as paused. The default queue order is the order the torrents were added. They
are all downloaded in that order. For more details, see <aclass="reference external"href="manual-ref.html#queuing">queuing</a>.</p>
<pclass="last">If you pass in resume data, the auto_managed state of the torrent when the resume data
was saved will override the auto_managed state you pass in here. You can override this
by setting <ttclass="docutils literal">override_resume_data</tt>.</p>
</td>
</tr>
<tr><td>flag_duplicate_is_error</td>
<td>128</td>
<td> </td>
</tr>
<tr><td>flag_merge_resume_trackers</td>
<td>256</td>
<td>defaults to off and specifies whether tracker URLs loaded from
resume data should be added to the trackers in the torrent or replace the trackers.</td>
</tr>
<tr><td>flag_update_subscribe</td>
<td>512</td>
<td>on by default and means that this torrent will be part of state
updates when calling <aclass="reference external"href="reference-Session.html#post_torrent_updates()">post_torrent_updates()</a>.</td>
</tr>
<tr><td>flag_super_seeding</td>
<td>1024</td>
<td>sets the torrent into super seeding mode. If the torrent
is not a seed, this flag has no effect. It has the same effect as calling
<ttclass="docutils literal"><spanclass="pre">torrent_handle::super_seeding(true)</span></tt> on the torrent handle immediately
after adding it.</td>
</tr>
<tr><td>flag_sequential_download</td>
<td>2048</td>
<td>sets the sequential download state for the torrent.
It has the same effect as calling <ttclass="docutils literal"><spanclass="pre">torrent_handle::sequential_download(true)</span></tt>
on the torrent handle immediately after adding it.</td>
</tr>
</tbody>
</table>
<aname="version"></a><dlclass="docutils">
<dt>version</dt>
<dd>filled in by the constructor and should be left untouched. It
is used for forward binary compatibility.</dd>
</dl>
<aname="ti"></a><dlclass="docutils">
<dt>ti</dt>
<dd><aclass="reference external"href="reference-Core.html#torrent_info">torrent_info</a> object with the torrent to add. Unless the url or info_hash
is set, this is required to be initiazlied.</dd>
</dl>
<aname="trackers"></a><dlclass="docutils">
<dt>trackers</dt>
<dd>If the torrent doesn't have a tracker, but relies on the DHT to find peers, the
<ttclass="docutils literal">trackers</tt> can specify tracker URLs for the torrent.</dd>
</dl>
<aname="dht_nodes"></a>
<aname="name"></a>
<aname="save_path"></a><dlclass="docutils">
<dt>dht_nodes name save_path</dt>
<dd>a list of hostname and port pairs, representing DHT nodes to be
added to the <aclass="reference external"href="reference-Session.html#session">session</a> (if DHT is enabled). The hostname may be an IP address.</dd>
</dl>
<aname="resume_data"></a><dlclass="docutils">
<dt>resume_data</dt>
<dd>The optional parameter, <ttclass="docutils literal">resume_data</tt> can be given if up to date fast-resume data
is available. The fast-resume data can be acquired from a running torrent 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>. See <aclass="reference external"href="manual-ref.html#fast-resume">fast resume</a>. The <ttclass="docutils literal">vector</tt> that is
passed in will be swapped into the running torrent instance with <ttclass="docutils literal"><spanclass="pre">std::vector::swap()</span></tt>.</dd>
</dl>
<aname="storage_mode"></a><dlclass="docutils">
<dt>storage_mode</dt>
<dd>One of the values from <aclass="reference external"href="reference-Storage.html#storage_mode_t">storage_mode_t</a>. For more information, see <aclass="reference external"href="manual-ref.html#storage-allocation">storage allocation</a>.</dd>
</dl>
<aname="storage"></a><dlclass="docutils">
<dt>storage</dt>
<dd>can be used to customize how the data is stored. The default
storage will simply write the data to the files it belongs to, but it could be
overridden to save everything to a single file at a specific location or encrypt the
content on disk for instance. For more information about the <aclass="reference external"href="reference-Custom_Storage.html#storage_interface">storage_interface</a>
that needs to be implemented for a custom storage, see <aclass="reference external"href="reference-Custom_Storage.html#storage_interface">storage_interface</a>.</dd>
</dl>
<aname="userdata"></a><dlclass="docutils">
<dt>userdata</dt>
<dd>The <ttclass="docutils literal">userdata</tt> parameter is optional and will be passed on to the extension
constructor functions, if any (see <aclass="reference internal"href="#add-extension">add_extension()</a>).</dd>
</dl>
<aname="file_priorities"></a><dlclass="docutils">
<dt>file_priorities</dt>
<dd>can be set to control the initial file priorities when adding
a torrent. The semantics are the same as for <ttclass="docutils literal"><spanclass="pre">torrent_handle::prioritize_files()</span></tt>.</dd>
</dl>
<aname="trackerid"></a><dlclass="docutils">
<dt>trackerid</dt>
<dd>the default tracker id to be used when announcing to trackers. By default
this is empty, and no tracker ID is used, since this is an optional argument. If
a tracker returns a tracker ID, that ID is used instead of this.</dd>
</dl>
<aname="url"></a><dlclass="docutils">
<dt>url</dt>
<dd><pclass="first">If you specify a <ttclass="docutils literal">url</tt>, the torrent will be set in <ttclass="docutils literal">downloading_metadata</tt> state
until the .torrent file has been downloaded. If there's any error while downloading,
the torrent will be stopped and the torrent error state (<ttclass="docutils literal"><spanclass="pre">torrent_status::error</span></tt>)
will indicate what went wrong. The <ttclass="docutils literal">url</tt> may refer to a magnet link or a regular
http URL.</p>
<p>If it refers to an HTTP URL, the info-hash for the added torrent will not be the
true info-hash of the .torrent. Instead a placeholder, unique, info-hash is used
which is later updated once the .torrent file has been downloaded.</p>
<pclass="last">Once the info-hash change happens, a <aclass="reference external"href="reference-Alerts.html#torrent_update_alert">torrent_update_alert</a> is posted.</p>
</dd>
</dl>
<aname="uuid"></a><dlclass="docutils">
<dt>uuid</dt>
<dd>if <ttclass="docutils literal">uuid</tt> is specified, it is used to find duplicates. If another torrent is already
running with the same UUID as the one being added, it will be considered a duplicate. This
is mainly useful for RSS feed items which has UUIDs specified.</dd>
</dl>
<aname="source_feed_url"></a><dlclass="docutils">
<dt>source_feed_url</dt>
<dd>should point to the URL of the RSS feed this torrent comes from,
if it comes from an RSS feed.</dd>
</dl>
<aname="flags"></a><dlclass="docutils">
<dt>flags</dt>
<dd>flags controlling aspects of this torrent and how it's added. See <aclass="reference external"href="reference-Core.html#flags_t">flags_t</a> for details.</dd>
</dl>
<aname="info_hash"></a><dlclass="docutils">
<dt>info_hash</dt>
<dd>set this to the info hash of the torrent to add in case the info-hash
is the only known property of the torrent. i.e. you don't have a
to the <ttclass="docutils literal">set_max_uploads()</tt>, <ttclass="docutils literal">set_max_connections()</tt>, <ttclass="docutils literal">set_upload_limit()</tt> and
<ttclass="docutils literal">set_download_limit()</tt> functions on <aclass="reference external"href="reference-Core.html#torrent_handle">torrent_handle</a>. These values let you initialize
these settings when the torrent is added, instead of calling these functions immediately
following adding it.</p>
<pclass="last">-1 means unlimited on these settings
just like their counterpart functions
on <aclass="reference external"href="reference-Core.html#torrent_handle">torrent_handle</a></p>
</dd>
</dl>
<aname="cache_status"></a></div>
</div>
<divclass="section"id="cache-status">
<h1>cache_status</h1>
<p>Declared in "<aclass="reference external"href="../include/libtorrent/disk_io_thread.hpp">libtorrent/disk_io_thread.hpp</a>"</p>
<p>this struct holds a number of statistics counters
relevant for the disk io thread and disk cache.</p>
<p>this is a holder for the internal <aclass="reference external"href="reference-Session.html#session">session</a> implementation object. Once the
<aclass="reference external"href="reference-Session.html#session">session</a> destruction is explicitly initiated, this holder is used to
synchronize the completion of the shutdown. The lifetime of this object
may outlive <aclass="reference external"href="reference-Session.html#session">session</a>, causing the <aclass="reference external"href="reference-Session.html#session">session</a> destructor to not block. The
<aclass="reference external"href="reference-Session.html#session_proxy">session_proxy</a> destructor will block however, until the underlying <aclass="reference external"href="reference-Session.html#session">session</a>
<p>loads and saves all <aclass="reference external"href="reference-Session.html#session">session</a> settings, including <aclass="reference external"href="reference-Settings.html#dht_settings">dht_settings</a>,
encryption settings and proxy settings. <ttclass="docutils literal">save_state</tt> writes all keys
to the <ttclass="docutils literal">entry</tt> that's passed in, which needs to either not be
initialized, or initialized as a dictionary.</p>
<p><ttclass="docutils literal">load_state</tt> expects a <aclass="reference external"href="reference-Bencoding.html#lazy_entry">lazy_entry</a> which can be built from a bencoded
buffer with <aclass="reference external"href="reference-Bencoding.html#lazy_bdecode()">lazy_bdecode()</a>.</p>
<p>The <ttclass="docutils literal">flags</tt> arguments passed in to <ttclass="docutils literal">save_state</tt> can be used to
filter which parts of the <aclass="reference external"href="reference-Session.html#session">session</a> state to save. By default, all state
is saved (except for the individual torrents). see <aclass="reference external"href="reference-Session.html#save_state_flags_t">save_state_flags_t</a></p>
<p><ttclass="docutils literal">get_torrent_status</tt> returns a vector of the <aclass="reference external"href="reference-Core.html#torrent_status">torrent_status</a> for
every torrent which satisfies <ttclass="docutils literal">pred</tt>, which is a predicate function
which determines if a torrent should be included in the returned set
or not. Returning true means it should be included and false means
excluded. The <ttclass="docutils literal">flags</tt> argument is the same as to
<ttclass="docutils literal"><spanclass="pre">torrent_handle::status()</span></tt>. Since <ttclass="docutils literal">pred</tt> is guaranteed to be
called for every torrent, it may be used to count the number of
torrents of different categories as well.</p>
<p><ttclass="docutils literal">refresh_torrent_status</tt> takes a vector of <aclass="reference external"href="reference-Core.html#torrent_status">torrent_status</a> structs
(for instance the same vector that was returned by
<aclass="reference external"href="reference-Session.html#get_torrent_status()">get_torrent_status()</a> ) and refreshes the status based on the
<ttclass="docutils literal">handle</tt> member. It is possible to use this function by first
setting up a vector of default constructed <ttclass="docutils literal">torrent_status</tt> objects,
only initializing the <ttclass="docutils literal">handle</tt> member, in order to request the
torrent status for multiple torrents in a single call. This can save a
significant amount of time if you have a lot of torrents.</p>
<p>Any <aclass="reference external"href="reference-Core.html#torrent_status">torrent_status</a> object whose <ttclass="docutils literal">handle</tt> member is not referring to
<p>This functions instructs the <aclass="reference external"href="reference-Session.html#session">session</a> to post the <aclass="reference external"href="reference-Alerts.html#state_update_alert">state_update_alert</a>,
containing the status of all torrents whose state changed since the
last time this function was called.</p>
<p>Only torrents who has the state subscription flag set will be
included. This flag is on by default. See <aclass="reference external"href="reference-Session.html#add_torrent_params">add_torrent_params</a>.</p>
<p><ttclass="docutils literal">find_torrent()</tt> looks for a torrent with the given info-hash. In
case there is such a torrent in the <aclass="reference external"href="reference-Session.html#session">session</a>, a <aclass="reference external"href="reference-Core.html#torrent_handle">torrent_handle</a> to that
torrent is returned. In case the torrent cannot be found, an invalid
<aclass="reference external"href="reference-Core.html#torrent_handle">torrent_handle</a> is returned.</p>
<p>See <ttclass="docutils literal"><spanclass="pre">torrent_handle::is_valid()</span></tt> to know if the torrent was found or
not.</p>
<p><ttclass="docutils literal">get_torrents()</tt> returns a vector of torrent_handles to all the
torrents currently in the <aclass="reference external"href="reference-Session.html#session">session</a>.</p>
The <aclass="reference external"href="reference-Core.html#torrent_handle">torrent_handle</a> returned by <aclass="reference external"href="reference-Session.html#add_torrent()">add_torrent()</a> can be used to retrieve
information about the torrent's progress, its peers etc. It is also
used to abort a torrent.</p>
<p>If the torrent you are trying to add already exists in the <aclass="reference external"href="reference-Session.html#session">session</a> (is
either queued for checking, being checked or downloading)
<ttclass="docutils literal">add_torrent()</tt> will throw <aclass="reference external"href="reference-Error_Codes.html#libtorrent_exception">libtorrent_exception</a> which derives from
<ttclass="docutils literal"><spanclass="pre">std::exception</span></tt> unless duplicate_is_error is set to false. In that
case, <aclass="reference external"href="reference-Session.html#add_torrent()">add_torrent()</a> will return the handle to the existing torrent.</p>
<p>In case you want to destruct the <aclass="reference external"href="reference-Session.html#session">session</a> asynchrounously, you can
request a <aclass="reference external"href="reference-Session.html#session">session</a> destruction proxy. If you don't do this, the
destructor of the <aclass="reference external"href="reference-Session.html#session">session</a> object will block while the trackers are
contacted. If you keep one <ttclass="docutils literal">session_proxy</tt> to the <aclass="reference external"href="reference-Session.html#session">session</a> when
destructing it, the destructor will not block, but start to close down
the <aclass="reference external"href="reference-Session.html#session">session</a>, the destructor of the proxy will then synchronize the
threads. So, the destruction of the <aclass="reference external"href="reference-Session.html#session">session</a> is performed from the
<ttclass="docutils literal">session</tt> destructor call until the <ttclass="docutils literal">session_proxy</tt> destructor
call. The <ttclass="docutils literal">session_proxy</tt> does not have any operations on it (since
the <aclass="reference external"href="reference-Session.html#session">session</a> is being closed down, no operations are allowed on it).
The only valid operation is calling the destructor:</p>
<p><ttclass="docutils literal">dht_state</tt> will return the current state of the dht node, this can
be used to start up the node again, passing this <aclass="reference external"href="reference-Bencoding.html#entry">entry</a> to
<ttclass="docutils literal">start_dht</tt>. It is a good idea to save this to disk when the <aclass="reference external"href="reference-Session.html#session">session</a>
is closed, and read it up again when starting.</p>
<p>If the port the DHT is supposed to listen on is already in use, and
exception is thrown, <ttclass="docutils literal"><spanclass="pre">asio::error</span></tt>.</p>
int <strong>as_for_ip</strong> (address const& addr);
</pre>
<p>These functions are not available if <ttclass="docutils literal">TORRENT_DISABLE_GEO_IP</tt> is defined. They
expects a path to the <aclass="reference external"href="http://www.maxmind.com/app/asnum">MaxMind ASN database</a> and <aclass="reference external"href="http://www.maxmind.com/app/geolitecountry">MaxMind GeoIP database</a>
respectively. This will be used to look up which AS and country peers belong to.</p>
<p><ttclass="docutils literal">as_for_ip</tt> returns the AS number for the IP address specified. If the IP is not
in the database or the ASN database is not loaded, 0 is returned.</p>
<p>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 <aclass="reference external"href="reference-Filter.html#ip_filter">ip_filter</a>.</p>
<p>Each time a peer is blocked because of the IP filter, a
<aclass="reference external"href="reference-Alerts.html#peer_blocked_alert">peer_blocked_alert</a> is generated. <ttclass="docutils literal">get_ip_filter()</tt> Returns the
<aclass="reference external"href="reference-Filter.html#ip_filter">ip_filter</a> currently in the <aclass="reference external"href="reference-Session.html#session">session</a>. See <aclass="reference external"href="reference-Filter.html#ip_filter">ip_filter</a>.</p>
<p>apply <aclass="reference external"href="reference-Filter.html#port_filter">port_filter</a><ttclass="docutils literal">f</tt> 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.</p>
<p><ttclass="docutils literal">is_listening()</tt> will tell you whether or not the <aclass="reference external"href="reference-Session.html#session">session</a> has
successfully opened a listening port. If it hasn't, this function will
return false, and then you can use <ttclass="docutils literal">listen_on()</tt> to make another
attempt.</p>
<p><ttclass="docutils literal">listen_port()</tt> returns the port we ended up listening on. Since you
just pass a port-range to the constructor and to <ttclass="docutils literal">listen_on()</tt>, to
know which port it ended up using, you have to ask the <aclass="reference external"href="reference-Session.html#session">session</a> using
this function.</p>
<p><ttclass="docutils literal">listen_on()</tt> will change the listen port and/or the listen
interface. If the <aclass="reference external"href="reference-Session.html#session">session</a> is already listening on a port, this socket
will be closed and a new socket will be opened with these new
settings. The port range is the ports it will try to listen on, if the
first port fails, it will continue trying the next port within the
range and so on. The interface parameter can be left as 0, in that
case the os will decide which interface to listen on, otherwise it
should be the ip-address of the interface you want the listener socket
bound to. <ttclass="docutils literal">listen_on()</tt> returns the error code of the operation in
<ttclass="docutils literal">ec</tt>. If this indicates success, the <aclass="reference external"href="reference-Session.html#session">session</a> is listening on a port
within the specified range. If it fails, it will also generate an
<p>If all ports in the specified range fails to be opened for listening,
libtorrent will try to use port 0 (which tells the operating system to
pick a port that's free). If that still fails you may see a
<aclass="reference external"href="reference-Alerts.html#listen_failed_alert">listen_failed_alert</a> with port 0 even if you didn't ask to listen on
it.</p>
<p>It is possible to prevent libtorrent from binding to port 0 by passing
in the flag <ttclass="docutils literal"><spanclass="pre">session::no_system_port</span></tt> in the <ttclass="docutils literal">flags</tt> argument.</p>
<p>The interface parameter can also be a hostname that will resolve to
the device you want to listen on. If you don't specify an interface,
libtorrent may attempt to listen on multiple interfaces (typically
0.0.0.0 and ::). This means that if your IPv6 interface doesn't work,
you may still see a <aclass="reference external"href="reference-Alerts.html#listen_failed_alert">listen_failed_alert</a>, even though the IPv4 port
succeeded.</p>
<p>The <ttclass="docutils literal">flags</tt> parameter can either be 0 or
<ttclass="docutils literal"><spanclass="pre">session::listen_reuse_address</span></tt>, which will set the reuse address
socket option on the listen socket(s). By default, the listen socket
does not use reuse address. If you're running a service that needs to
run on a specific port no matter if it's in use, set this flag.</p>
<p>If you're also starting the DHT, it is a good idea to do that after
you've called <ttclass="docutils literal">listen_on()</tt>, since the default listen port for the
DHT is the same as the tcp listen socket. If you start the DHT first,
it will assume the tcp port is free and open the udp socket on that
port, then later, when <ttclass="docutils literal">listen_on()</tt> is called, it may turn out that
the tcp port is in use. That results in the DHT and the bittorrent
socket listening on different ports. If the DHT is active when
<ttclass="docutils literal">listen_on</tt> is called, the udp port will be rebound to the new port,
if it was configured to use the same port as the tcp socket, and if
the listen_on call failed to bind to the same port that the udp uses.</p>
<p>If you want the OS to pick a port for you, pass in 0 as both first and
second.</p>
<p>The reason why it's a good idea to run the DHT and the bittorrent
socket on the same port is because that is an assumption that may be
used to increase performance. One way to accelerate the connecting of
peers on windows may be to first ping all peers with a DHT ping
packet, and connect to those that responds first. On windows one can
only connect to a few peers at a time because of a built in limitation
<p><ttclass="docutils literal">remove_torrent()</tt> will close all peer connections associated with
the torrent and tell the tracker that we've stopped participating in
the swarm. This operation cannot fail. When it completes, you will
receive a <aclass="reference external"href="reference-Alerts.html#torrent_removed_alert">torrent_removed_alert</a>.</p>
<p>The optional second argument <ttclass="docutils literal">options</tt> can be used to delete all the
files downloaded by this torrent. To do so, pass in the value
<ttclass="docutils literal"><spanclass="pre">session::delete_files</span></tt>. The removal of the torrent is asyncronous,
there is no guarantee that adding the same torrent immediately after
it was removed will not throw a <aclass="reference external"href="reference-Error_Codes.html#libtorrent_exception">libtorrent_exception</a> exception. Once
See <aclass="reference external"href="reference-Settings.html#session_settings">session_settings</a> and <aclass="reference external"href="reference-Settings.html#pe_settings">pe_settings</a> for more information on available
<p>For more information on what settings are available for proxies, see
<aclass="reference external"href="reference-Settings.html#proxy_settings">proxy_settings</a>. If the <aclass="reference external"href="reference-Session.html#session">session</a> is not in anonymous mode, proxies that
<p><ttclass="docutils literal">set_i2p_proxy</tt> sets the <aclass="reference external"href="http://www.i2p2.de">i2p</a> proxy, and tries to open a persistant
connection to it. The only used fields in the proxy settings structs
are <ttclass="docutils literal">hostname</tt> and <ttclass="docutils literal">port</tt>.</p>
<p><ttclass="docutils literal">i2p_proxy</tt> returns the current i2p proxy in use.</p>
<p><ttclass="docutils literal">pop_alert()</tt> is used to ask the <aclass="reference external"href="reference-Session.html#session">session</a> if any errors or events has
occurred. With <aclass="reference external"href="reference-Session.html#set_alert_mask()">set_alert_mask()</a> you can filter which alerts to receive
through <ttclass="docutils literal">pop_alert()</tt>. For information about the <aclass="reference external"href="reference-Alerts.html#alert">alert</a> categories,
see <aclass="reference external"href="manual-ref.html#alerts">alerts</a>.</p>
<p><ttclass="docutils literal">pop_alerts()</tt> pops all pending alerts in a single call. In high
performance environments with a very high <aclass="reference external"href="reference-Alerts.html#alert">alert</a> churn rate, this can
save significant amount of time compared to popping alerts one at a
time. Each call requires one round-trip to the network thread. If
alerts are produced in a higher rate than they can be popped (when
popped one at a time) it's easy to get stuck in an infinite loop,
trying to drain the <aclass="reference external"href="reference-Alerts.html#alert">alert</a> queue. Popping the entire queue at once
avoids this problem.</p>
<p>However, the <ttclass="docutils literal">pop_alerts</tt> function comes with significantly more
responsibility. You pass in an <em>empty</em><ttclass="docutils literal"><spanclass="pre">std::dequeue<alert*></span></tt> to it.
If it's not empty, all elements in it will be deleted and then
cleared. All currently pending alerts are returned by being swapped
into the passed in container. The responsibility of deleting the
alerts is transferred to the caller. This means you need to call
delete for each item in the returned dequeue. It's probably a good
idea to delete the alerts as you handle them, to save one extra pass
over the dequeue.</p>
<p>Alternatively, you can pass in the same container the next time you
<p><ttclass="docutils literal">wait_for_alert</tt> blocks until an <aclass="reference external"href="reference-Alerts.html#alert">alert</a> is available, or for no more
than <ttclass="docutils literal">max_wait</tt> time. If <ttclass="docutils literal">wait_for_alert</tt> returns because of the
time-out, and no alerts are available, it returns 0. If at least one
<aclass="reference external"href="reference-Alerts.html#alert">alert</a> was generated, a pointer to that <aclass="reference external"href="reference-Alerts.html#alert">alert</a> is returned. The <aclass="reference external"href="reference-Alerts.html#alert">alert</a> is
not popped, any subsequent calls to <ttclass="docutils literal">wait_for_alert</tt> will return the
same pointer until the <aclass="reference external"href="reference-Alerts.html#alert">alert</a> is popped by calling <ttclass="docutils literal">pop_alert</tt>. This
is useful for leaving any <aclass="reference external"href="reference-Alerts.html#alert">alert</a> dispatching mechanism independent of
this blocking call, the dispatcher can be called and it can pop the
<p><aclass="reference external"href="reference-Alerts.html#save_resume_data_alert">save_resume_data_alert</a> and <aclass="reference external"href="reference-Alerts.html#save_resume_data_failed_alert">save_resume_data_failed_alert</a> are always
posted, regardelss of the <aclass="reference external"href="reference-Alerts.html#alert">alert</a> mask.</p>
<p>This sets a function to be called (from within libtorrent's netowrk
thread) every time an <aclass="reference external"href="reference-Alerts.html#alert">alert</a> is posted. Since the function (<ttclass="docutils literal">fun</tt>) is
run in libtorrent's internal thread, it may not call any of
libtorrent's external API functions. Doing so results in a dead lock.</p>
<p>The main intention with this function is to support integration with
platform-dependent message queues or signalling systems. For instance,
on windows, one could post a message to an HNWD or on linux, write to
<p>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.</p>
<p>The upnp object returned by <ttclass="docutils literal">start_upnp()</tt> can be used to add and
remove arbitrary port mappings. Mapping status is returned through the
<aclass="reference external"href="reference-Alerts.html#portmap_alert">portmap_alert</a> and the <aclass="reference external"href="reference-Alerts.html#portmap_error_alert">portmap_error_alert</a>. The object will be valid
until <ttclass="docutils literal">stop_upnp()</tt> is called. See <aclass="reference external"href="manual-ref.html#upnp-and-nat-pmp">upnp and nat pmp</a>.</p>
whichever is enabled. The return value is a handle referring to the
port mapping that was just created. Pass it to <aclass="reference external"href="reference-Session.html#delete_port_mapping()">delete_port_mapping()</a>
<p>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.</p>
<p>The natpmp object returned by <ttclass="docutils literal">start_natpmp()</tt> can be used to add
and remove arbitrary port mappings. Mapping status is returned through
the <aclass="reference external"href="reference-Alerts.html#portmap_alert">portmap_alert</a> and the <aclass="reference external"href="reference-Alerts.html#portmap_error_alert">portmap_error_alert</a>. The object will be
valid until <ttclass="docutils literal">stop_natpmp()</tt> is called. See <aclass="reference external"href="manual-ref.html#upnp-and-nat-pmp">upnp and nat pmp</a>.</p>
<dd>the number of bytes that has been received more than once.
This can happen if a request from a peer times out and is requested from a different
peer, and then received again from the first one. To make this lower, increase the
<ttclass="docutils literal">request_timeout</tt> and the <ttclass="docutils literal">piece_timeout</tt> in the <aclass="reference external"href="reference-Session.html#session">session</a> settings.</dd>
