premiere
/
premiere-libtorrent
2
2
Fork 1
Code Issues Pull Requests Releases Wiki Activity

reflow comments to break at 80 columns

This commit is contained in:
Arvid Norberg 2014-02-02 05:09:18 +00:00
parent 9612ef193e
commit 312fce78a1
5 changed files with 670 additions and 645 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

82
docs/reference-Core.html
View File

@ -55,17 +55,16 @@
<div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of contents</p>
<ul class="simple">
<li><a class="reference internal" href="#disk-buffer-holder" id="id169">disk_buffer_holder</a></li>
<li><a class="reference internal" href="#peer-info" id="id170">peer_info</a></li>
<li><a class="reference internal" href="#peer-list-entry" id="id171">peer_list_entry</a></li>
<li><a class="reference internal" href="#peer-request" id="id172">peer_request</a></li>
<li><a class="reference internal" href="#piece-block-progress" id="id173">piece_block_progress</a></li>
<li><a class="reference internal" href="#block-info" id="id174">block_info</a></li>
<li><a class="reference internal" href="#partial-piece-info" id="id175">partial_piece_info</a></li>
<li><a class="reference internal" href="#torrent-handle" id="id176">torrent_handle</a></li>
<li><a class="reference internal" href="#torrent-status" id="id177">torrent_status</a></li>
<li><a class="reference internal" href="#announce-entry" id="id178">announce_entry</a></li>
<li><a class="reference internal" href="#torrent-info" id="id179">torrent_info</a></li>
<li><a class="reference internal" href="#disk-buffer-holder" id="id166">disk_buffer_holder</a></li>
<li><a class="reference internal" href="#peer-info" id="id167">peer_info</a></li>
<li><a class="reference internal" href="#peer-request" id="id168">peer_request</a></li>
<li><a class="reference internal" href="#piece-block-progress" id="id169">piece_block_progress</a></li>
<li><a class="reference internal" href="#block-info" id="id170">block_info</a></li>
<li><a class="reference internal" href="#partial-piece-info" id="id171">partial_piece_info</a></li>
<li><a class="reference internal" href="#torrent-handle" id="id172">torrent_handle</a></li>
<li><a class="reference internal" href="#torrent-status" id="id173">torrent_status</a></li>
<li><a class="reference internal" href="#announce-entry" id="id174">announce_entry</a></li>
<li><a class="reference internal" href="#torrent-info" id="id175">torrent_info</a></li>
</ul>
</div>
<a name="disk_buffer_holder"></a><div class="section" id="disk-buffer-holder">
@ -735,47 +734,6 @@ reset to 0 on reconnect.</dd>
address of the interface it's going out over. This may be useful for multi-homed
clients with multiple interfaces to the internet.</dd>
</dl>
<a name="peer_list_entry"></a></div>
</div>
<div class="section" id="peer-list-entry">
<h1>peer_list_entry</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/peer_info.hpp">libtorrent/peer_info.hpp</a>&quot;</p>
<pre class="literal-block">
struct peer_list_entry
{
enum flags_t
{
banned,
};
<a class="reference external" href="tcp::endpoint">tcp::endpoint</a> ip;
int flags;
boost::uint8_t failcount;
boost::uint8_t source;
};
</pre>
<a name="flags_t"></a><div class="section" id="enum-flags-t">
<h2>enum flags_t</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/peer_info.hpp">libtorrent/peer_info.hpp</a>&quot;</p>
<table border="1" class="docutils">
<colgroup>
<col width="29%" />
<col width="25%" />
<col width="46%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">name</th>
<th class="head">value</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>banned</td>
<td>1</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<a name="peer_request"></a></div>
</div>
<div class="section" id="peer-request">
@ -1189,7 +1147,7 @@ struct torrent_handle
};
};
</pre>
<a name="torrent_handle()"></a><div class="section" id="id28">
<a name="torrent_handle()"></a><div class="section" id="id26">
<h2>torrent_handle()</h2>
<pre class="literal-block">
<strong>torrent_handle</strong> ();
@ -2071,7 +2029,7 @@ Doing so results in a dead-lock. For such routines, the <tt class="docutils lite
underlying type representing the torrent. This type does not have a stable API and should
be relied on as little as possible.</p>
<a name="flags_t"></a></div>
<div class="section" id="id97">
<div class="section" id="enum-flags-t">
<h2>enum flags_t</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/torrent_handle.hpp">libtorrent/torrent_handle.hpp</a>&quot;</p>
<table border="1" class="docutils">
@ -2363,7 +2321,7 @@ bool <strong>operator==</strong> (torrent_status const&amp; st) const;
<p>compres if the torrent status objects come from the same torrent. i.e.
only the <a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a> field is compared.</p>
<a name="state_t"></a></div>
<div class="section" id="id108">
<div class="section" id="id105">
<h2>enum state_t</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/torrent_handle.hpp">libtorrent/torrent_handle.hpp</a>&quot;</p>
<table border="1" class="docutils">
@ -2913,7 +2871,7 @@ allowed to force another tracker update with this tracker.</p>
<p>If the last time this tracker was contacted failed, <tt class="docutils literal">last_error</tt> is the error
code describing what error occurred.</p>
<a name="reset()"></a></div>
<div class="section" id="id128">
<div class="section" id="id125">
<h2>reset()</h2>
<pre class="literal-block">
void <strong>reset</strong> ();
@ -3129,7 +3087,7 @@ class torrent_info : public intrusive_ptr_base&lt;torrent_info&gt;
bool <strong>is_merkle_torrent</strong> () const;
};
</pre>
<a name="torrent_info()"></a><div class="section" id="id132">
<a name="torrent_info()"></a><div class="section" id="id129">
<h2>torrent_info()</h2>
<pre class="literal-block">
<strong>torrent_info</strong> (std::string const&amp; filename, int flags = 0);
@ -3161,7 +3119,7 @@ always throw if an error occurs. These overloads are not available when building
exception support.</p>
<p>The <tt class="docutils literal">flags</tt> argument is currently unused.</p>
<a name="~torrent_info()"></a></div>
<div class="section" id="id140">
<div class="section" id="id137">
<h2>~torrent_info()</h2>
<pre class="literal-block">
<strong>~torrent_info</strong> ();
@ -3186,7 +3144,7 @@ names. Filename may be chaged using <tt class="docutils literal"><span class="pr
<p>For more information on the <a class="reference external" href="reference-Storage.html#file_storage">file_storage</a> object, see the separate document on how
to create torrents.</p>
<a name="rename_file()"></a></div>
<div class="section" id="id146">
<div class="section" id="id143">
<h2>rename_file()</h2>
<pre class="literal-block">
void <strong>rename_file</strong> (int index, std::string const&amp; new_filename);
@ -3271,7 +3229,7 @@ the piece index as argument and gives you the exact size of that piece. It will
be the same as <tt class="docutils literal">piece_length()</tt> except in the case of the last piece, which may
be smaller.</p>
<a name="info_hash()"></a></div>
<div class="section" id="id153">
<div class="section" id="id150">
<h2>info_hash()</h2>
<pre class="literal-block">
const sha1_hash&amp; <strong>info_hash</strong> () const;
@ -3318,7 +3276,7 @@ std::string <strong>ssl_cert</strong> () const;
torrent. Otherwise returns an empty string. The certificate is
the the public certificate in x509 format.</p>
<a name="is_valid()"></a></div>
<div class="section" id="id156">
<div class="section" id="id153">
<h2>is_valid()</h2>
<pre class="literal-block">
bool <strong>is_valid</strong> () const;
@ -3431,7 +3389,7 @@ lazy_entry const* <strong>info</strong> (char const* key) const;
It can be used to access extension values put in the .torrent file. If the specified
key cannot be found, it returns NULL.</p>
<a name="swap()"></a></div>
<div class="section" id="id161">
<div class="section" id="id158">
<h2>swap()</h2>
<pre class="literal-block">
void <strong>swap</strong> (torrent_info&amp; ti);

1
docs/reference.html
View File

@ -57,7 +57,6 @@
<div class="line-block">
<div class="line"><a class="reference external" href="reference-Core.html#disk_buffer_holder">disk_buffer_holder</a></div>
<div class="line"><a class="reference external" href="reference-Core.html#peer_info">peer_info</a></div>
<div class="line"><a class="reference external" href="reference-Core.html#peer_list_entry">peer_list_entry</a></div>
<div class="line"><a class="reference external" href="reference-Core.html#peer_request">peer_request</a></div>
<div class="line"><a class="reference external" href="reference-Core.html#piece_block_progress">piece_block_progress</a></div>
<div class="line"><a class="reference external" href="reference-Core.html#block_info">block_info</a></div>

117
include/libtorrent/peer_info.hpp
View File

@ -201,9 +201,8 @@ namespace libtorrent
enum bw_state_deprecated { bw_torrent = bw_limit, bw_global = bw_limit };
#endif
// bitmasks indicating what state this peer
// is in with regards to sending and receiving data. The states are declared in the
// bw_state enum.
// bitmasks indicating what state this peer is in with regards to sending
// and receiving data. The states are declared in the bw_state enum.
char read_state;
char write_state;
@ -213,27 +212,24 @@ namespace libtorrent
// .. _asio: http://asio.sourceforge.net/asio-0.3.8/doc/asio/reference.html
tcp::endpoint ip;
// the current upload and download speed
// we have to and from this peer (including any protocol messages).
// updated about once per second
// the current upload and download speed we have to and from this peer
// (including any protocol messages). updated about once per second
int up_speed;
int down_speed;
// The transfer rates
// of payload data only
// updated about once per second
// The transfer rates of payload data only updated about once per second
int payload_up_speed;
int payload_down_speed;
// the total number of bytes downloaded
// from and uploaded to this peer. These numbers do not include the protocol chatter, but only
// the payload data.
// the total number of bytes downloaded from and uploaded to this peer.
// These numbers do not include the protocol chatter, but only the
// payload data.
size_type total_download;
size_type total_upload;
// the peer's id as used in the bit torrent protocol. This id can be used to
// extract 'fingerprints' from the peer. Sometimes it can tell you which client the peer
// is using. See identify_client()_
// the peer's id as used in the bit torrent protocol. This id can be used
// to extract 'fingerprints' from the peer. Sometimes it can tell you
// which client the peer is using. See identify_client()_
peer_id pid;
// a bitfield, with one bit per piece in the torrent.
@ -241,9 +237,9 @@ namespace libtorrent
// or if the peer miss that piece (set to 0).
bitfield pieces;
// the number of bytes per second we are allowed to send to or receive from this
// peer. It may be -1 if there's no local limit on the peer. The global
// limit and the torrent limit may also be enforced.
// the number of bytes per second we are allowed to send to or receive
// from this peer. It may be -1 if there's no local limit on the peer.
// The global limit and the torrent limit may also be enforced.
int upload_limit;
int download_limit;
@ -257,8 +253,9 @@ namespace libtorrent
time_duration download_queue_time;
int queue_bytes;
// the number of seconds until the current front piece request
// will time out. This timeout can be adjusted through ``session_settings::request_timeout``.
// the number of seconds until the current front piece request will time
// out. This timeout can be adjusted through
// ``session_settings::request_timeout``.
// -1 means that there is not outstanding request.
int request_timeout;
@ -276,12 +273,13 @@ namespace libtorrent
// sending us that turned out to fail the hash check.
int num_hashfails;
// the two letter `ISO 3166 country code`__ for the country the peer
// is connected from. If the country hasn't been resolved yet, both chars are set
// to 0. If the resolution failed for some reason, the field is set to "--". If the
// resolution service returns an invalid country code, it is set to "!!".
// The ``countries.nerd.dk`` service is used to look up countries. This field will
// remain set to 0 unless the torrent is set to resolve countries, see `resolve_countries()`_.
// the two letter `ISO 3166 country code`__ for the country the peer is
// connected from. If the country hasn't been resolved yet, both chars
// are set to 0. If the resolution failed for some reason, the field is
// set to "--". If the resolution service returns an invalid country
// code, it is set to "!!". The ``countries.nerd.dk`` service is used to
// look up countries. This field will remain set to 0 unless the torrent
// is set to resolve countries, see `resolve_countries()`_.
//
// __ http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html
char country[2];
@ -293,11 +291,11 @@ namespace libtorrent
// the AS number the peer is located in.
int inet_as;
// a measurement of the balancing of free download (that we get)
// and free upload that we give. Every peer gets a certain amount of free upload, but
// this member says how much *extra* free upload this peer has got. If it is a negative
// number it means that this was a peer from which we have got this amount of free
// download.
// a measurement of the balancing of free download (that we get) and free
// upload that we give. Every peer gets a certain amount of free upload,
// but this member says how much *extra* free upload this peer has got.
// If it is a negative number it means that this was a peer from which we
// have got this amount of free download.
size_type load_balancing;
// this is the number of requests
@ -329,29 +327,31 @@ namespace libtorrent
// that we haven't answered with a piece yet.
int upload_queue_length;
// the number of times this peer has "failed". i.e. failed to connect
// or disconnected us. The failcount is decremented when we see this peer in a tracker
// response or peer exchange message.
// the number of times this peer has "failed". i.e. failed to connect or
// disconnected us. The failcount is decremented when we see this peer in
// a tracker response or peer exchange message.
int failcount;
// You can know which piece, and which part of that piece, that is currently being
// downloaded from a specific peer by looking at these four members.
// ``downloading_piece_index`` is the index of the piece that is currently being downloaded.
// This may be set to -1 if there's currently no piece downloading from this peer. If it is
// >= 0, the other three members are valid. ``downloading_block_index`` is the index of the
// block (or sub-piece) that is being downloaded. ``downloading_progress`` is the number
// of bytes of this block we have received from the peer, and ``downloading_total`` is
// the total number of bytes in this block.
// You can know which piece, and which part of that piece, that is
// currently being downloaded from a specific peer by looking at these
// four members. ``downloading_piece_index`` is the index of the piece
// that is currently being downloaded. This may be set to -1 if there's
// currently no piece downloading from this peer. If it is >= 0, the
// other three members are valid. ``downloading_block_index`` is the
// index of the block (or sub-piece) that is being downloaded.
// ``downloading_progress`` is the number of bytes of this block we have
// received from the peer, and ``downloading_total`` is the total number
// of bytes in this block.
int downloading_piece_index;
int downloading_block_index;
int downloading_progress;
int downloading_total;
// a string describing the software at the other end of the connection.
// In some cases this information is not available, then it will contain a string
// that may give away something about which software is running in the other end.
// In the case of a web seed, the server type and version will be a part of this
// string.
// In some cases this information is not available, then it will contain
// a string that may give away something about which software is running
// in the other end. In the case of a web seed, the server type and
// version will be a part of this string.
std::string client;
enum connection_type_t
@ -376,27 +376,27 @@ namespace libtorrent
// bytes per second.
int remote_dl_rate;
// the number of bytes this peer has pending in the
// disk-io thread. Downloaded and waiting to be written to disk. This is what
// is capped by ``session_settings::max_queued_disk_bytes``.
// the number of bytes this peer has pending in the disk-io thread.
// Downloaded and waiting to be written to disk. This is what is capped
// by ``session_settings::max_queued_disk_bytes``.
int pending_disk_bytes;
// the number of bytes this peer has been
// assigned to be allowed to send and receive until it has to request more quota
// from the bandwidth manager.
// the number of bytes this peer has been assigned to be allowed to send
// and receive until it has to request more quota from the bandwidth
// manager.
int send_quota;
int receive_quota;
// an estimated round trip time to this peer, in milliseconds. It is
// estimated by timing the the tcp ``connect()``. It may be 0 for incoming connections.
// estimated by timing the the tcp ``connect()``. It may be 0 for
// incoming connections.
int rtt;
// the number of pieces this peer has.
int num_pieces;
// the highest download and upload
// rates seen on this connection. They are given in bytes per second. This number is
// reset to 0 on reconnect.
// the highest download and upload rates seen on this connection. They
// are given in bytes per second. This number is reset to 0 on reconnect.
int download_rate_peak;
int upload_rate_peak;
@ -411,11 +411,12 @@ namespace libtorrent
int estimated_reciprocation_rate;
// the IP and port pair the socket is bound to locally. i.e. the IP
// address of the interface it's going out over. This may be useful for multi-homed
// clients with multiple interfaces to the internet.
// address of the interface it's going out over. This may be useful for
// multi-homed clients with multiple interfaces to the internet.
tcp::endpoint local_endpoint;
};
// internal
struct TORRENT_EXPORT peer_list_entry
{
enum flags_t

579
include/libtorrent/session.hpp
View File

@ -82,25 +82,29 @@ namespace libtorrent
class connection_queue;
class alert;
// 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.
// 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.
// ``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 inteded to be the starting point for embedded devices. It will
// significantly reduce memory usage.
// This configuration is inteded 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.
// ``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.
TORRENT_EXPORT session_settings min_memory_usage();
TORRENT_EXPORT session_settings high_performance_seed();
@ -115,13 +119,12 @@ namespace libtorrent
struct session_impl;
}
// 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.
// 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.
class TORRENT_EXPORT session_proxy
{
friend class session;
@ -141,28 +144,33 @@ namespace libtorrent
#define TORRENT_LOGPATH_ARG_DEFAULT
#endif
// 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.
// 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.
class TORRENT_EXPORT session: public boost::noncopyable
{
public:
// If the fingerprint in the first overload is omited, the client will get a default
// fingerprint stating the version of libtorrent. The fingerprint is a short string that will be
// used in the peer-id to identify the client and the client's version. For more details see the
// fingerprint class. The constructor that only takes a fingerprint will not open a
// listen port for the session, to get it running you'll have to call ``session::listen_on()``.
// The other constructor, that takes a port range and an interface as well as the fingerprint
// will automatically try to listen on a port on the given interface. For more information about
// the parameters, see ``listen_on()`` function.
// If the fingerprint in the first overload is omited, the client will
// get a default fingerprint stating the version of libtorrent. The
// fingerprint is a short string that will be used in the peer-id to
// identify the client and the client's version. For more details see the
// fingerprint class. The constructor that only takes a fingerprint will
// not open a listen port for the session, to get it running you'll have
// to call ``session::listen_on()``. The other constructor, that takes a
// port range and an interface as well as the fingerprint will
// automatically try to listen on a port on the given interface. For more
// information about the parameters, see ``listen_on()`` function.
//
// The flags paramater can be used to start default features (upnp & nat-pmp) and default plugins
// (ut_metadata, ut_pex and smart_ban). The default is to start those things. If you do not want
// them to start, pass 0 as the flags parameter.
// The flags paramater can be used to start default features (upnp &
// nat-pmp) and default plugins (ut_metadata, ut_pex and smart_ban). The
// default is to start those things. If you do not want them to start,
// pass 0 as the flags parameter.
//
// The ``alert_mask`` is the same mask that you would send to set_alert_mask().
// The ``alert_mask`` is the same mask that you would send to
// set_alert_mask().
session(fingerprint const& print = fingerprint("LT"
, LIBTORRENT_VERSION_MAJOR, LIBTORRENT_VERSION_MINOR, 0, 0)
, int flags = start_default_features | add_default_plugins
@ -193,11 +201,12 @@ namespace libtorrent
start(flags);
}
// 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 ``set_settings()``.
// 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 ``set_settings()``.
~session();
// flags that determines which aspects of the session should be
@ -238,88 +247,94 @@ namespace libtorrent
#endif
};
// loads and saves all session settings, including dht_settings, encryption settings and proxy
// settings. ``save_state`` writes all keys to the ``entry`` that's passed in, which needs to
// either not be initialized, or initialized as a dictionary.
// loads and saves all session settings, including dht_settings,
// encryption settings and proxy settings. ``save_state`` writes all keys
// to the ``entry`` that's passed in, which needs to either not be
// initialized, or initialized as a dictionary.
//
// ``load_state`` expects a lazy_entry which can be built from a bencoded buffer with
// lazy_bdecode().
// ``load_state`` expects a lazy_entry which can be built from a bencoded
// buffer with lazy_bdecode().
//
// The ``flags`` arguments passed in to ``save_state`` can be used to filter which parts
// of the session state to save. By default, all state is saved (except for the individual
// torrents). see save_state_flags_t
// The ``flags`` arguments passed in to ``save_state`` can be used to
// filter which parts of the session state to save. By default, all state
// is saved (except for the individual torrents). see save_state_flags_t
void save_state(entry& e, boost::uint32_t flags = 0xffffffff) const;
void load_state(lazy_entry const& e);
// .. note::
// these calls are potentially expensive and won't scale well
// with lots of torrents. If you're concerned about performance, consider
// these calls are potentially expensive and won't scale well with
// lots of torrents. If you're concerned about performance, consider
// using ``post_torrent_updates()`` instead.
//
// ``get_torrent_status`` returns a vector of the torrent_status for every
// torrent which satisfies ``pred``, which is a predicate function which determines
// if a torrent should be included in the returned set or not. Returning true means
// it should be included and false means excluded. The ``flags`` argument is the same
// as to ``torrent_handle::status()``. Since ``pred`` is guaranteed to be called for
// every torrent, it may be used to count the number of torrents of different categories
// as well.
// ``get_torrent_status`` returns a vector of the torrent_status for
// every torrent which satisfies ``pred``, which is a predicate function
// which determines if a torrent should be included in the returned set
// or not. Returning true means it should be included and false means
// excluded. The ``flags`` argument is the same as to
// ``torrent_handle::status()``. Since ``pred`` is guaranteed to be
// called for every torrent, it may be used to count the number of
// torrents of different categories as well.
//
// ``refresh_torrent_status`` takes a vector of torrent_status structs (for instance
// the same vector that was returned by get_torrent_status() ) and refreshes the
// status based on the ``handle`` member. It is possible to use this function by
// first setting up a vector of default constructed ``torrent_status`` objects, only
// initializing the ``handle`` member, in order to request the torrent status for
// multiple torrents in a single call. This can save a significant amount of time
// if you have a lot of torrents.
// ``refresh_torrent_status`` takes a vector of torrent_status structs
// (for instance the same vector that was returned by
// get_torrent_status() ) and refreshes the status based on the
// ``handle`` member. It is possible to use this function by first
// setting up a vector of default constructed ``torrent_status`` objects,
// only initializing the ``handle`` member, in order to request the
// torrent status for multiple torrents in a single call. This can save a
// significant amount of time if you have a lot of torrents.
//
// Any torrent_status object whose ``handle`` member is not referring to a
// valid torrent are ignored.
// Any torrent_status object whose ``handle`` member is not referring to
// a valid torrent are ignored.
void get_torrent_status(std::vector<torrent_status>* ret
, boost::function<bool(torrent_status const&)> const& pred
, boost::uint32_t flags = 0) const;
void refresh_torrent_status(std::vector<torrent_status>* ret
, boost::uint32_t flags = 0) const;
// This functions instructs the session to post the state_update_alert, containing
// the status of all torrents whose state changed since the last time this function
// was called.
// This functions instructs the session to post the state_update_alert,
// containing the status of all torrents whose state changed since the
// last time this function was called.
//
// Only torrents who has the state subscription flag set will be included. This flag
// is on by default. See add_torrent_params.
// Only torrents who has the state subscription flag set will be
// included. This flag is on by default. See add_torrent_params.
void post_torrent_updates();
// internal
io_service& get_io_service();
// ``find_torrent()`` looks for a torrent with the given info-hash. In case there
// is such a torrent in the session, a torrent_handle to that torrent is returned.
// In case the torrent cannot be found, an invalid torrent_handle is returned.
// ``find_torrent()`` looks for a torrent with the given info-hash. In
// case there is such a torrent in the session, a torrent_handle to that
// torrent is returned. In case the torrent cannot be found, an invalid
// torrent_handle is returned.
//
// See ``torrent_handle::is_valid()`` to know if the torrent was found or not.
// See ``torrent_handle::is_valid()`` to know if the torrent was found or
// not.
//
// ``get_torrents()`` returns a vector of torrent_handles to all the torrents
// currently in the session.
// ``get_torrents()`` returns a vector of torrent_handles to all the
// torrents currently in the session.
torrent_handle find_torrent(sha1_hash const& info_hash) const;
std::vector<torrent_handle> get_torrents() const;
// You add torrents through the add_torrent() function where you give an
// object with all the parameters. The add_torrent() overloads will block
// until the torrent has been added (or failed to be added) and returns an
// error code and a torrent_handle. In order to add torrents more efficiently,
// consider using async_add_torrent() which returns immediately, without
// waiting for the torrent to add. Notification of the torrent being added is sent
// as add_torrent_alert.
// until the torrent has been added (or failed to be added) and returns
// an error code and a torrent_handle. In order to add torrents more
// efficiently, consider using async_add_torrent() which returns
// immediately, without waiting for the torrent to add. Notification of
// the torrent being added is sent as add_torrent_alert.
//
// The overload that does not take an error_code throws an exception on
// error and is not available when building without exception support.
// The torrent_handle returned by add_torrent() can be used to retrieve information
// about the torrent's progress, its peers etc. It is also used to abort a torrent.
// The torrent_handle returned by add_torrent() can be used to retrieve
// information about the torrent's progress, its peers etc. It is also
// used to abort a torrent.
//
// If the torrent you are trying to add already exists in the session (is either queued
// for checking, being checked or downloading) ``add_torrent()`` will throw
// libtorrent_exception which derives from ``std::exception`` unless duplicate_is_error
// is set to false. In that case, add_torrent() will return the handle to the existing
// torrent.
// If the torrent you are trying to add already exists in the session (is
// either queued for checking, being checked or downloading)
// ``add_torrent()`` will throw libtorrent_exception which derives from
// ``std::exception`` unless duplicate_is_error is set to false. In that
// case, add_torrent() will return the handle to the existing torrent.
//
// all torrent_handles must be destructed before the session is destructed!
#ifndef BOOST_NO_EXCEPTIONS
@ -366,15 +381,17 @@ namespace libtorrent
#endif
#endif
// In case you want to destruct the session asynchrounously, 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::
// In case you want to destruct the session asynchrounously, 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::
//
// class session_proxy
// {
@ -384,20 +401,22 @@ namespace libtorrent
// };
session_proxy abort() { return session_proxy(m_impl); }
// Pausing the session has the same effect as pausing every torrent in it, except that
// torrents will not be resumed by the auto-manage mechanism. Resuming will restore the
// torrents to their previous paused state. i.e. the session pause state is separate from
// the torrent pause state. A torrent is inactive if it is paused or if the session is
// Pausing the session has the same effect as pausing every torrent in
// it, except that torrents will not be resumed by the auto-manage
// mechanism. Resuming will restore the torrents to their previous paused
// state. i.e. the session pause state is separate from the torrent pause
// state. A torrent is inactive if it is paused or if the session is
// paused.
void pause();
void resume();
bool is_paused() const;
// returns session wide-statistics and status. For more information, see the ``session_status`` struct.
// returns session wide-statistics and status. For more information, see
// the ``session_status`` struct.
session_status status() const;
// Returns status of the disk cache for this session.
// For more information, see the cache_status type.
// Returns status of the disk cache for this session. For more
// information, see the cache_status type.
cache_status get_cache_status() const;
// fills out the supplied vector with information for
@ -410,12 +429,11 @@ namespace libtorrent
// regularly and optionally add all torrents from the feed, as they
// appear.
//
// Before adding the feed, you must set the ``url`` field to the
// feed's url. It may point to an RSS or an atom feed.
// The returned feed_handle is a handle which is used to interact
// with the feed, things like forcing a refresh or querying for
// information about the items in the feed. For more information,
// see feed_handle.
// Before adding the feed, you must set the ``url`` field to the feed's
// url. It may point to an RSS or an atom feed. The returned feed_handle
// is a handle which is used to interact with the feed, things like
// forcing a refresh or querying for information about the items in the
// feed. For more information, see feed_handle.
feed_handle add_feed(feed_settings const& feed);
// Removes a feed from being watched by the session. When this
@ -426,41 +444,43 @@ namespace libtorrent
// Returns a list of all RSS feeds that are being watched by the session.
void get_feeds(std::vector<feed_handle>& f) const;
// starts/stops UPnP, NATPMP or LSD port mappers
// they are stopped by default
// These functions are not available in case ``TORRENT_DISABLE_DHT`` is
// defined. ``start_dht`` starts the dht node and makes the trackerless service
// available to torrents. The startup state is optional and can contain nodes
// and the node id from the previous session. The dht node state is a bencoded
// dictionary with the following entries:
// starts/stops UPnP, NATPMP or LSD port mappers they are stopped by
// default These functions are not available in case
// ``TORRENT_DISABLE_DHT`` is defined. ``start_dht`` starts the dht node
// and makes the trackerless service available to torrents. The startup
// state is optional and can contain nodes and the node id from the
// previous session. The dht node state is a bencoded dictionary with the
// following entries:
//
// nodes
// A list of strings, where each string is a node endpoint encoded in binary. If
// the string is 6 bytes long, it is an IPv4 address of 4 bytes, encoded in
// network byte order (big endian), followed by a 2 byte port number (also
// network byte order). If the string is 18 bytes long, it is 16 bytes of IPv6
// address followed by a 2 bytes port number (also network byte order).
// A list of strings, where each string is a node endpoint encoded in
// binary. If the string is 6 bytes long, it is an IPv4 address of 4
// bytes, encoded in network byte order (big endian), followed by a 2
// byte port number (also network byte order). If the string is 18
// bytes long, it is 16 bytes of IPv6 address followed by a 2 bytes
// port number (also network byte order).
//
// node-id
// The node id written as a readable string as a hexadecimal number.
//
// ``dht_state`` will return the current state of the dht node, this can be used
// to start up the node again, passing this entry to ``start_dht``. It is a good
// idea to save this to disk when the session is closed, and read it up again
// when starting.
// ``dht_state`` will return the current state of the dht node, this can
// be used to start up the node again, passing this entry to
// ``start_dht``. It is a good idea to save this to disk when the session
// is closed, and read it up again when starting.
//
// If the port the DHT is supposed to listen on is already in use, and exception
// is thrown, ``asio::error``.
// If the port the DHT is supposed to listen on is already in use, and
// exception is thrown, ``asio::error``.
//
// ``stop_dht`` stops the dht node.
//
// ``add_dht_node`` adds a node to the routing table. This can be used if your
// client has its own source of bootstrapping nodes.
// ``add_dht_node`` adds a node to the routing table. This can be used if
// your client has its own source of bootstrapping nodes.
//
// ``set_dht_settings`` sets some parameters availavle to the dht node. See
// dht_settings for more information.
// ``set_dht_settings`` sets some parameters availavle to the dht node.
// See dht_settings for more information.
//
// ``is_dht_running()`` returns true if the DHT support has been started and false
// ``is_dht_running()`` returns true if the DHT support has been started
// and false
// otherwise.
void start_dht();
void stop_dht();
@ -571,22 +591,21 @@ namespace libtorrent
entry state() const TORRENT_DEPRECATED;
#endif
// 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.
// 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.
// 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.
void set_ip_filter(ip_filter const& f);
ip_filter get_ip_filter() const;
// 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.
// 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.
void set_port_filter(port_filter const& f);
// sets and gets the raw peer ID used by libtorrent. When anonymous
@ -600,62 +619,72 @@ namespace libtorrent
void set_key(int key);
// ``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 use ``listen_on()`` to make another attempt.
// ``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 use ``listen_on()`` to make another
// attempt.
//
// ``listen_port()`` returns the port we ended up listening on. Since you just pass
// a port-range to the constructor and to ``listen_on()``, to know which port it
// ended up using, you have to ask the session using this function.
// ``listen_port()`` returns the port we ended up listening on. Since you
// just pass a port-range to the constructor and to ``listen_on()``, to
// know which port it ended up using, you have to ask the session using
// this function.
//
// ``listen_on()`` will change the listen port and/or the listen interface. If the
// session 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. ``listen_on()`` returns the
// error code of the operation in ``ec``. If this indicates success, the session is
// listening on a port within the specified range. If it fails, it will also
// generate an appropriate alert (listen_failed_alert).
// ``listen_on()`` will change the listen port and/or the listen
// interface. If the session 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. ``listen_on()`` returns the error code of the operation in
// ``ec``. If this indicates success, the session is listening on a port
// within the specified range. If it fails, it will also generate an
// appropriate alert (listen_failed_alert).
//
// 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 listen_failed_alert with port 0 even if you didn't
// ask to listen on it.
// 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
// listen_failed_alert with port 0 even if you didn't ask to listen on
// it.
//
// It is possible to prevent libtorrent from binding to port 0 by passing in the flag
// ``session::no_system_port`` in the ``flags`` argument.
// It is possible to prevent libtorrent from binding to port 0 by passing
// in the flag ``session::no_system_port`` in the ``flags`` argument.
//
// 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 listen_failed_alert, even though
// the IPv4 port succeeded.
// 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 listen_failed_alert, even though the IPv4 port
// succeeded.
//
// The ``flags`` parameter can either be 0 or ``session::listen_reuse_address``, 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.
// The ``flags`` parameter can either be 0 or
// ``session::listen_reuse_address``, 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.
//
// If you're also starting the DHT, it is a good idea to do that after you've called
// ``listen_on()``, 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 ``listen_on()`` 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 ``listen_on`` 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.
// If you're also starting the DHT, it is a good idea to do that after
// you've called ``listen_on()``, 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 ``listen_on()`` 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
// ``listen_on`` 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.
//
// If you want the OS to pick a port for you, pass in 0 as both first and second.
// If you want the OS to pick a port for you, pass in 0 as both first and
// second.
//
// 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 (in XP
// Service pack 2).
// 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
// (in XP Service pack 2).
void listen_on(
std::pair<int, int> const& port_range
, error_code& ec
@ -665,17 +694,13 @@ namespace libtorrent
unsigned short ssl_listen_port() const;
bool is_listening() const;
// if the listen port failed in some way
// you can retry to listen on another port-
// range with this function. If the listener
// succeeded and is currently listening,
// a call to this function will shut down the
// listen port and reopen it using these new
// properties (the given interface and port range).
// As usual, if the interface is left as 0
// this function will return false on failure.
// If it fails, it will also generate alerts describing
// the error. It will return true on success.
// if the listen port failed in some way you can retry to listen on
// another port- range with this function. If the listener succeeded and
// is currently listening, a call to this function will shut down the
// listen port and reopen it using these new properties (the given
// interface and port range). As usual, if the interface is left as 0
// this function will return false on failure. If it fails, it will also
// generate alerts describing the error. It will return true on success.
enum listen_on_flags_t
{
#ifndef TORRENT_NO_DEPRECATE
@ -713,14 +738,16 @@ namespace libtorrent
start_default_features = 2
};
// ``remove_torrent()`` will close all peer connections associated with the torrent and tell
// the tracker that we've stopped participating in the swarm. This operation cannot fail.
// When it completes, you will receive a torrent_removed_alert.
// ``remove_torrent()`` will close all peer connections associated with
// the torrent and tell the tracker that we've stopped participating in
// the swarm. This operation cannot fail. When it completes, you will
// receive a torrent_removed_alert.
//
// The optional second argument ``options`` can be used to delete all the files downloaded
// by this torrent. To do so, pass in the value ``session::delete_files``. 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 libtorrent_exception exception. Once
// The optional second argument ``options`` can be used to delete all the
// files downloaded by this torrent. To do so, pass in the value
// ``session::delete_files``. 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 libtorrent_exception exception. Once
// the torrent is deleted, a torrent_deleted_alert is posted.
void remove_torrent(const torrent_handle& h, int options = 0);
@ -732,13 +759,15 @@ namespace libtorrent
void set_pe_settings(pe_settings const& settings);
pe_settings get_pe_settings() const;
// These functions sets and queries the proxy settings to be used for the session.
// These functions sets and queries the proxy settings to be used for the
// session.
//
// For more information on what settings are available for proxies, see
// proxy_settings. If the session is not in anonymous mode, proxies that
// aren't working or fail, will automatically be disabled and packets will
// flow without using any proxy. If you want to enforce using a proxy, even when
// the proxy doesn't work, enable anonymous_mode in session_settings.
// aren't working or fail, will automatically be disabled and packets
// will flow without using any proxy. If you want to enforce using a
// proxy, even when the proxy doesn't work, enable anonymous_mode in
// session_settings.
void set_proxy(proxy_settings const& s);
proxy_settings proxy() const;
@ -821,42 +850,51 @@ namespace libtorrent
int max_uploads() const TORRENT_DEPRECATED;
#endif
// ``pop_alert()`` is used to ask the session if any errors or events has occurred. With
// set_alert_mask() you can filter which alerts to receive through ``pop_alert()``.
// For information about the alert categories, see alerts_.
// ``pop_alert()`` is used to ask the session if any errors or events has
// occurred. With set_alert_mask() you can filter which alerts to receive
// through ``pop_alert()``. For information about the alert categories,
// see alerts_.
//
// ``pop_alerts()`` pops all pending alerts in a single call. In high performance environments
// with a very high alert 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 alert queue. Popping the entire
// queue at once avoids this problem.
// ``pop_alerts()`` pops all pending alerts in a single call. In high
// performance environments with a very high alert 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 alert queue. Popping the entire queue at once
// avoids this problem.
//
// However, the ``pop_alerts`` function comes with significantly more responsibility. You pass
// in an *empty* ``std::dequeue<alert*>`` 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.
// However, the ``pop_alerts`` function comes with significantly more
// responsibility. You pass in an *empty* ``std::dequeue<alert*>`` 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.
//
// Alternatively, you can pass in the same container the next time you call ``pop_alerts``.
// Alternatively, you can pass in the same container the next time you
// call ``pop_alerts``.
//
// ``wait_for_alert`` blocks until an alert is available, or for no more than ``max_wait``
// time. If ``wait_for_alert`` returns because of the time-out, and no alerts are available,
// it returns 0. If at least one alert was generated, a pointer to that alert is returned.
// The alert is not popped, any subsequent calls to ``wait_for_alert`` will return the
// same pointer until the alert is popped by calling ``pop_alert``. This is useful for
// leaving any alert dispatching mechanism independent of this blocking call, the dispatcher
// can be called and it can pop the alert independently.
// ``wait_for_alert`` blocks until an alert is available, or for no more
// than ``max_wait`` time. If ``wait_for_alert`` returns because of the
// time-out, and no alerts are available, it returns 0. If at least one
// alert was generated, a pointer to that alert is returned. The alert is
// not popped, any subsequent calls to ``wait_for_alert`` will return the
// same pointer until the alert is popped by calling ``pop_alert``. This
// is useful for leaving any alert dispatching mechanism independent of
// this blocking call, the dispatcher can be called and it can pop the
// alert independently.
//
// In the python binding, ``wait_for_alert`` takes the number of milliseconds to wait as an integer.
// In the python binding, ``wait_for_alert`` takes the number of
// milliseconds to wait as an integer.
//
// To control the max number of alerts that's queued by the session, see
// ``session_settings::alert_queue_size``.
//
// save_resume_data_alert and save_resume_data_failed_alert are always posted, regardelss
// of the alert mask.
// save_resume_data_alert and save_resume_data_failed_alert are always
// posted, regardelss of the alert mask.
std::auto_ptr<alert> pop_alert();
void pop_alerts(std::deque<alert*>* alerts);
alert const* wait_for_alert(time_duration max_wait);
@ -869,19 +907,22 @@ namespace libtorrent
size_t set_alert_queue_size_limit(size_t queue_size_limit_) TORRENT_DEPRECATED;
#endif
// Changes the mask of which alerts to receive. By default only errors are reported.
// ``m`` is a bitmask where each bit represents a category of alerts.
// Changes the mask of which alerts to receive. By default only errors
// are reported. ``m`` is a bitmask where each bit represents a category
// of alerts.
//
// See category_t enum for options.
void set_alert_mask(boost::uint32_t m);
// This sets a function to be called (from within libtorrent's netowrk thread) every time an alert
// is posted. Since the function (``fun``) 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.
// This sets a function to be called (from within libtorrent's netowrk
// thread) every time an alert is posted. Since the function (``fun``) 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.
//
// 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 a pipe or an eventfd.
// 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
// a pipe or an eventfd.
void set_alert_dispatch(boost::function<void(std::auto_ptr<alert>)> const& fun);
// internal
@ -895,13 +936,14 @@ namespace libtorrent
void start_lsd();
void stop_lsd();
// 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.
// 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_.
// 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_.
//
// It is off by default.
void start_upnp();
@ -911,19 +953,20 @@ namespace libtorrent
enum protocol_type { udp = 1, tcp = 2 };
// add_port_mapping adds a port forwarding on UPnP and/or NAT-PMP,
// whichever is enabled. The return value is a handle referring to
// the port mapping that was just created. Pass it to delete_port_mapping()
// whichever is enabled. The return value is a handle referring to the
// port mapping that was just created. Pass it to delete_port_mapping()
// to remove it.
int add_port_mapping(protocol_type t, int external_port, int local_port);
void delete_port_mapping(int handle);
// 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.
// 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_.
// 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_.
//
// It is off by default.
void start_natpmp();

536
include/libtorrent/torrent_handle.hpp
View File

@ -477,7 +477,8 @@ namespace libtorrent
// passing in the internal torrent object and the specified userdata
// pointer. The function is expected to return a shared pointer to
// a torrent_plugin instance.
void add_extension(boost::function<boost::shared_ptr<torrent_plugin>(torrent*, void*)> const& ext
void add_extension(
boost::function<boost::shared_ptr<torrent_plugin>(torrent*, void*)> const& ext
, void* userdata = 0);
// ``set_metadata`` expects the *info* section of metadata. i.e. The
@ -882,29 +883,30 @@ namespace libtorrent
// ================ end deprecation ============
#endif
// ``use_interface()`` sets the network interface this torrent will use when it opens outgoing
// connections. By default, it uses the same interface as the session uses to listen on. The
// parameter must be a string containing one or more, comma separated, ip-address (either an
// IPv4 or IPv6 address). When specifying multiple interfaces, the torrent will round-robin
// which interface to use for each outgoing conneciton. This is useful for clients that are
// multi-homed.
// ``use_interface()`` sets the network interface this torrent will use
// when it opens outgoing connections. By default, it uses the same
// interface as the session uses to listen on. The parameter must be a
// string containing one or more, comma separated, ip-address (either an
// IPv4 or IPv6 address). When specifying multiple interfaces, the
// torrent will round-robin which interface to use for each outgoing
// conneciton. This is useful for clients that are multi-homed.
void use_interface(const char* net_interface) const;
// Fills the specified ``std::vector<int>`` with the availability for each
// piece in this torrent. libtorrent does not keep track of availability for
// seeds, so if the torrent is seeding the availability for all pieces is
// reported as 0.
// Fills the specified ``std::vector<int>`` with the availability for
// each piece in this torrent. libtorrent does not keep track of
// availability for seeds, so if the torrent is seeding the availability
// for all pieces is reported as 0.
//
// The piece availability is the number of peers that we are connected that has
// advertized having a particular piece. This is the information that libtorrent
// uses in order to prefer picking rare pieces.
// The piece availability is the number of peers that we are connected
// that has advertized having a particular piece. This is the information
// that libtorrent uses in order to prefer picking rare pieces.
void piece_availability(std::vector<int>& avail) const;
// These functions are used to set and get the prioritiy of individual pieces.
// By default all pieces have priority 1. That means that the random rarest
// first algorithm is effectively active for all pieces. You may however
// change the priority of individual pieces. There are 8 different priority
// levels:
// These functions are used to set and get the prioritiy of individual
// pieces. By default all pieces have priority 1. That means that the
// random rarest first algorithm is effectively active for all pieces.
// You may however change the priority of individual pieces. There are 8
// different priority levels:
//
// 0. piece is not downloaded at all
// 1. normal priority. Download order is dependent on availability
@ -915,22 +917,22 @@ namespace libtorrent
// lower availability
// 5. *currently the same as 4*
// 6. piece is as likely to be picked as any piece with availability 1
// 7. maximum priority, availability is disregarded, the piece is preferred
// over any other piece with lower priority
// 7. maximum priority, availability is disregarded, the piece is
// preferred over any other piece with lower priority
//
// The exact definitions of these priorities are implementation details, and
// subject to change. The interface guarantees that higher number means higher
// priority, and that 0 means do not download.
// The exact definitions of these priorities are implementation details,
// and subject to change. The interface guarantees that higher number
// means higher priority, and that 0 means do not download.
//
// ``piece_priority`` sets or gets the priority for an individual piece,
// specified by ``index``.
//
// ``prioritize_pieces`` takes a vector of integers, one integer per piece in
// the torrent. All the piece priorities will be updated with the priorities
// in the vector.
// ``prioritize_pieces`` takes a vector of integers, one integer per
// piece in the torrent. All the piece priorities will be updated with
// the priorities in the vector.
//
// ``piece_priorities`` returns a vector with one element for each piece in the
// torrent. Each element is the current priority of that piece.
// ``piece_priorities`` returns a vector with one element for each piece
// in the torrent. Each element is the current priority of that piece.
void piece_priority(int index, int priority) const;
int piece_priority(int index) const;
void prioritize_pieces(std::vector<int> const& pieces) const;
@ -940,20 +942,23 @@ namespace libtorrent
//
// ``file_priority()`` queries or sets the priority of file ``index``.
//
// ``prioritize_files()`` takes a vector that has at as many elements as there are
// files in the torrent. Each entry is the priority of that file. The function
// sets the priorities of all the pieces in the torrent based on the vector.
// ``prioritize_files()`` takes a vector that has at as many elements as
// there are files in the torrent. Each entry is the priority of that
// file. The function sets the priorities of all the pieces in the
// torrent based on the vector.
//
// ``file_priorities()`` returns a vector with the priorities of all files.
// ``file_priorities()`` returns a vector with the priorities of all
// files.
//
// The priority values are the same as for piece_priority().
//
// Whenever a file priority is changed, all other piece priorities are reset
// to match the file priorities. In order to maintain sepcial priorities for
// particular pieces, piece_priority() has to be called again for those pieces.
// Whenever a file priority is changed, all other piece priorities are
// reset to match the file priorities. In order to maintain sepcial
// priorities for particular pieces, piece_priority() has to be called
// again for those pieces.
//
// You cannot set the file priorities on a torrent that does not yet
// have metadata or a torrent that is a seed. ``file_priority(int, int)`` and
// You cannot set the file priorities on a torrent that does not yet have
// metadata or a torrent that is a seed. ``file_priority(int, int)`` and
// prioritize_files() are both no-ops for such torrents.
void file_priority(int index, int priority) const;
int file_priority(int index) const;
@ -986,59 +991,69 @@ namespace libtorrent
void force_reannounce(boost::posix_time::time_duration) const TORRENT_DEPRECATED;
#endif
// ``scrape_tracker()`` will send a scrape request to the tracker. A scrape request queries the
// tracker for statistics such as total number of incomplete peers, complete peers, number of
// downloads etc.
// ``scrape_tracker()`` will send a scrape request to the tracker. A
// scrape request queries the tracker for statistics such as total number
// of incomplete peers, complete peers, number of downloads etc.
//
// This request will specifically update the ``num_complete`` and ``num_incomplete`` fields in
// the torrent_status struct once it completes. When it completes, it will generate a
// scrape_reply_alert. If it fails, it will generate a scrape_failed_alert.
// This request will specifically update the ``num_complete`` and
// ``num_incomplete`` fields in the torrent_status struct once it
// completes. When it completes, it will generate a scrape_reply_alert.
// If it fails, it will generate a scrape_failed_alert.
void scrape_tracker() const;
// ``set_upload_limit`` will limit the upload bandwidth used by this particular torrent to the
// limit you set. It is given as the number of bytes per second the torrent is allowed to upload.
// ``set_download_limit`` works the same way but for download bandwidth instead of upload bandwidth.
// Note that setting a higher limit on a torrent then the global limit (``session_settings::upload_rate_limit``)
// will not override the global rate limit. The torrent can never upload more than the global rate
// ``set_upload_limit`` will limit the upload bandwidth used by this
// particular torrent to the limit you set. It is given as the number of
// bytes per second the torrent is allowed to upload.
// ``set_download_limit`` works the same way but for download bandwidth
// instead of upload bandwidth. Note that setting a higher limit on a
// torrent then the global limit
// (``session_settings::upload_rate_limit``) will not override the global
// rate limit. The torrent can never upload more than the global rate
// limit.
//
// ``upload_limit`` and ``download_limit`` will return the current limit setting, for upload and
// download, respectively.
// ``upload_limit`` and ``download_limit`` will return the current limit
// setting, for upload and download, respectively.
void set_upload_limit(int limit) const;
int upload_limit() const;
void set_download_limit(int limit) const;
int download_limit() const;
// ``set_sequential_download()`` enables or disables *sequential download*. When enabled, the piece
// picker will pick pieces in sequence instead of rarest first.
// ``set_sequential_download()`` enables or disables *sequential
// download*. When enabled, the piece picker will pick pieces in sequence
// instead of rarest first.
//
// Enabling sequential download will affect the piece distribution negatively in the swarm. It should be
// used sparingly.
// Enabling sequential download will affect the piece distribution
// negatively in the swarm. It should be used sparingly.
void set_sequential_download(bool sd) const;
// ``connect_peer()`` is a way to manually connect to peers that one believe is a part of the
// torrent. If the peer does not respond, or is not a member of this torrent, it will simply
// be disconnected. No harm can be done by using this other than an unnecessary connection
// attempt is made. If the torrent is uninitialized or in queued or checking mode, this
// will throw libtorrent_exception. The second (optional) argument will be bitwised ORed into
// the source mask of this peer. Typically this is one of the source flags in peer_info.
// i.e. ``tracker``, ``pex``, ``dht`` etc.
// ``connect_peer()`` is a way to manually connect to peers that one
// believe is a part of the torrent. If the peer does not respond, or is
// not a member of this torrent, it will simply be disconnected. No harm
// can be done by using this other than an unnecessary connection attempt
// is made. If the torrent is uninitialized or in queued or checking
// mode, this will throw libtorrent_exception. The second (optional)
// argument will be bitwised ORed into the source mask of this peer.
// Typically this is one of the source flags in peer_info. i.e.
// ``tracker``, ``pex``, ``dht`` etc.
void connect_peer(tcp::endpoint const& adr, int source = 0) const;
// ``set_max_uploads()`` sets the maximum number of peers that's unchoked at the same time on this
// torrent. If you set this to -1, there will be no limit. This defaults to infinite. The primary
// setting controlling this is the global unchoke slots limit, set by unchoke_slots_limit
// in session_settings.
// ``set_max_uploads()`` sets the maximum number of peers that's unchoked
// at the same time on this torrent. If you set this to -1, there will be
// no limit. This defaults to infinite. The primary setting controlling
// this is the global unchoke slots limit, set by unchoke_slots_limit in
// session_settings.
//
// ``max_uploads()`` returns the current settings.
void set_max_uploads(int max_uploads) const;
int max_uploads() const;
// ``set_max_connections()`` sets the maximum number of connection this torrent will open. If all
// connections are used up, incoming connections may be refused or poor connections may be closed.
// This must be at least 2. The default is unlimited number of connections. If -1 is given to the
// function, it means unlimited. There is also a global limit of the number of connections, set
// by ``connections_limit`` in session_settings.
// ``set_max_connections()`` sets the maximum number of connection this
// torrent will open. If all connections are used up, incoming
// connections may be refused or poor connections may be closed. This
// must be at least 2. The default is unlimited number of connections. If
// -1 is given to the function, it means unlimited. There is also a
// global limit of the number of connections, set by
// ``connections_limit`` in session_settings.
//
// ``max_connections()`` returns the current settings.
void set_max_connections(int max_connections) const;
@ -1049,50 +1064,58 @@ namespace libtorrent
void set_tracker_login(std::string const& name
, std::string const& password) const;
// Moves the file(s) that this torrent are currently seeding from or downloading to. If
// the given ``save_path`` is not located on the same drive as the original save path,
// the files will be copied to the new drive and removed from their original location.
// This will block all other disk IO, and other torrents download and upload rates may
// drop while copying the file.
// Moves the file(s) that this torrent are currently seeding from or
// downloading to. If the given ``save_path`` is not located on the same
// drive as the original save path, the files will be copied to the new
// drive and removed from their original location. This will block all
// other disk IO, and other torrents download and upload rates may drop
// while copying the file.
//
// Since disk IO is performed in a separate thread, this operation is also asynchronous.
// Once the operation completes, the ``storage_moved_alert`` is generated, with the new
// path as the message. If the move fails for some reason, ``storage_moved_failed_alert``
// is generated instead, containing the error message.
// Since disk IO is performed in a separate thread, this operation is
// also asynchronous. Once the operation completes, the
// ``storage_moved_alert`` is generated, with the new path as the
// message. If the move fails for some reason,
// ``storage_moved_failed_alert`` is generated instead, containing the
// error message.
//
// The ``flags`` argument determines the behavior of the copying/moving of the files
// in the torrent. see move_flags_t.
// The ``flags`` argument determines the behavior of the copying/moving
// of the files in the torrent. see move_flags_t.
//
// * always_replace_files = 0
// * fail_if_exist = 1
// * dont_replace = 2
//
// ``always_replace_files`` is the default and replaces any file that exist in both the
// source directory and the target directory.
// ``always_replace_files`` is the default and replaces any file that
// exist in both the source directory and the target directory.
//
// ``fail_if_exist`` first check to see that none of the copy operations would cause an
// overwrite. If it would, it will fail. Otherwise it will proceed as if it was in
// ``always_replace_files`` mode. Note that there is an inherent race condition here.
// If the files in the target directory appear after the check but before the copy
// or move completes, they will be overwritten. When failing because of files already
// existing in the target path, the ``error`` of ``move_storage_failed_alert`` is set
// to ``boost::system::errc::file_exists``.
// ``fail_if_exist`` first check to see that none of the copy operations
// would cause an overwrite. If it would, it will fail. Otherwise it will
// proceed as if it was in ``always_replace_files`` mode. Note that there
// is an inherent race condition here. If the files in the target
// directory appear after the check but before the copy or move
// completes, they will be overwritten. When failing because of files
// already existing in the target path, the ``error`` of
// ``move_storage_failed_alert`` is set to
// ``boost::system::errc::file_exists``.
//
// The intention is that a client may use this as a probe, and if it fails, ask the user
// which mode to use. The client may then re-issue the ``move_storage`` call with one
// of the other modes.
// The intention is that a client may use this as a probe, and if it
// fails, ask the user which mode to use. The client may then re-issue
// the ``move_storage`` call with one of the other modes.
//
// ``dont_replace`` always takes the existing file in the target directory, if there is
// one. The source files will still be removed in that case.
// ``dont_replace`` always takes the existing file in the target
// directory, if there is one. The source files will still be removed in
// that case.
//
// Files that have been renamed to have absolute pahts are not moved by this function.
// Keep in mind that files that don't belong to the torrent but are stored in the torrent's
// directory may be moved as well. This goes for files that have been renamed to
// absolute paths that still end up inside the save path.
// Files that have been renamed to have absolute pahts are not moved by
// this function. Keep in mind that files that don't belong to the
// torrent but are stored in the torrent's directory may be moved as
// well. This goes for files that have been renamed to absolute paths
// that still end up inside the save path.
void move_storage(std::string const& save_path, int flags = 0) const;
// Renames the file with the given index asynchronously. The rename operation is complete
// when either a file_renamed_alert or file_rename_failed_alert is posted.
// Renames the file with the given index asynchronously. The rename
// operation is complete when either a file_renamed_alert or
// file_rename_failed_alert is posted.
void rename_file(int index, std::string const& new_name) const;
#ifndef TORRENT_NO_DEPRECATE
@ -1123,11 +1146,12 @@ namespace libtorrent
bool operator<(const torrent_handle& h) const
{ return m_torrent.lock() < h.m_torrent.lock(); }
// This function is intended only for use by plugins and the alert dispatch function. Any code
// that runs in libtorrent's network thread may not use the public API of torrent_handle.
// Doing so results in a dead-lock. For such routines, the ``native_handle`` gives access to the
// underlying type representing the torrent. This type does not have a stable API and should
// be relied on as little as possible.
// This function is intended only for use by plugins and the alert
// dispatch function. Any code that runs in libtorrent's network thread
// may not use the public API of torrent_handle. Doing so results in a
// dead-lock. For such routines, the ``native_handle`` gives access to
// the underlying type representing the torrent. This type does not have
// a stable API and should be relied on as little as possible.
boost::shared_ptr<torrent> native_handle() const;
private:
@ -1140,7 +1164,8 @@ namespace libtorrent
};
// holds a snapshot of the status of a torrent, as queried by torrent_handle::status().
// holds a snapshot of the status of a torrent, as queried by
// torrent_handle::status().
struct TORRENT_EXPORT torrent_status
{
// hidden
@ -1235,108 +1260,109 @@ namespace libtorrent
// been successful yet, it's set to an empty string.
std::string current_tracker;
// the number of bytes downloaded and
// uploaded to all peers, accumulated, *this session* only. The session is considered
// to restart when a torrent is paused and restarted again. When a torrent is paused,
// these counters are reset to 0. If you want complete, persistent, stats, see
// the number of bytes downloaded and uploaded to all peers, accumulated,
// *this session* only. The session is considered to restart when a
// torrent is paused and restarted again. When a torrent is paused, these
// counters are reset to 0. If you want complete, persistent, stats, see
// ``all_time_upload`` and ``all_time_download``.
size_type total_download;
size_type total_upload;
// counts the amount of bytes
// send and received this session, but only the actual payload data (i.e the interesting
// data), these counters ignore any protocol overhead.
// counts the amount of bytes send and received this session, but only
// the actual payload data (i.e the interesting data), these counters
// ignore any protocol overhead.
size_type total_payload_download;
size_type total_payload_upload;
// the number of bytes that has been downloaded and that
// has failed the piece hash test. In other words, this is just how much crap that
// has been downloaded.
// the number of bytes that has been downloaded and that has failed the
// piece hash test. In other words, this is just how much crap that has
// been downloaded.
size_type total_failed_bytes;
// the number of bytes that has been downloaded even
// though that data already was downloaded. The reason for this is that in some
// situations the same data can be downloaded by mistake. When libtorrent sends
// requests to a peer, and the peer doesn't send a response within a certain
// timeout, libtorrent will re-request that block. Another situation when
// libtorrent may re-request blocks is when the requests it sends out are not
// replied in FIFO-order (it will re-request blocks that are skipped by an out of
// order block). This is supposed to be as low as possible.
// the number of bytes that has been downloaded even though that data
// already was downloaded. The reason for this is that in some situations
// the same data can be downloaded by mistake. When libtorrent sends
// requests to a peer, and the peer doesn't send a response within a
// certain timeout, libtorrent will re-request that block. Another
// situation when libtorrent may re-request blocks is when the requests
// it sends out are not replied in FIFO-order (it will re-request blocks
// that are skipped by an out of order block). This is supposed to be as
// low as possible.
size_type total_redundant_bytes;
// a bitmask that represents which pieces we have (set to true) and
// the pieces we don't have. It's a pointer and may be set to 0 if the torrent isn't
// downloading or seeding.
// a bitmask that represents which pieces we have (set to true) and the
// pieces we don't have. It's a pointer and may be set to 0 if the
// torrent isn't downloading or seeding.
bitfield pieces;
// a bitmask representing which pieces has had their hash
// checked. This only applies to torrents in *seed mode*. If the torrent is not
// in seed mode, this bitmask may be empty.
// a bitmask representing which pieces has had their hash checked. This
// only applies to torrents in *seed mode*. If the torrent is not in seed
// mode, this bitmask may be empty.
bitfield verified_pieces;
// the total number of bytes of the file(s) that we have. All
// this does not necessarily has to be downloaded during this session (that's
// the total number of bytes of the file(s) that we have. All this does
// not necessarily has to be downloaded during this session (that's
// ``total_payload_download``).
size_type total_done;
// the number of bytes we have downloaded, only counting the
// pieces that we actually want to download. i.e. excluding any pieces that we have but
// have priority 0 (i.e. not wanted).
// the number of bytes we have downloaded, only counting the pieces that
// we actually want to download. i.e. excluding any pieces that we have
// but have priority 0 (i.e. not wanted).
size_type total_wanted_done;
// The total number of bytes we want to download.
// This may be smaller than the total torrent size
// in case any pieces are prioritized to 0, i.e. not wanted
// The total number of bytes we want to download. This may be smaller
// than the total torrent size in case any pieces are prioritized to 0,
// i.e. not wanted
size_type total_wanted;
// are accumulated upload and download
// payload byte counters. They are saved in and restored from resume data to keep totals
// across sessions.
// are accumulated upload and download payload byte counters. They are
// saved in and restored from resume data to keep totals across sessions.
size_type all_time_upload;
size_type all_time_download;
// the posix-time when this torrent was added. i.e. what
// ``time(NULL)`` returned at the time.
// the posix-time when this torrent was added. i.e. what ``time(NULL)``
// returned at the time.
time_t added_time;
// the posix-time when this torrent was finished. If
// the torrent is not yet finished, this is 0.
// the posix-time when this torrent was finished. If the torrent is not
// yet finished, this is 0.
time_t completed_time;
// the time when we, or one of our peers, last
// saw a complete copy of this torrent.
// the time when we, or one of our peers, last saw a complete copy of
// this torrent.
time_t last_seen_complete;
// The allocation mode for the torrent. See storage_mode_t for the options.
// For more information, see storage-allocation_.
// The allocation mode for the torrent. See storage_mode_t for the
// options. For more information, see storage-allocation_.
storage_mode_t storage_mode;
// a value in the range [0, 1], that represents the progress of the
// torrent's current task. It may be checking files or downloading.
float progress;
// progress parts per million (progress * 1000000)
// when disabling floating point operations, this is
// the only option to query progress
// progress parts per million (progress * 1000000) when disabling
// floating point operations, this is the only option to query progress
// reflects the same value as ``progress``, but instead in a range
// [0, 1000000] (ppm = parts per million). When floating point operations are disabled,
// this is the only alternative to the floating point value in progress.
// reflects the same value as ``progress``, but instead in a range [0,
// 1000000] (ppm = parts per million). When floating point operations are
// disabled, this is the only alternative to the floating point value in
// progress.
int progress_ppm;
// the position this torrent has in the download
// queue. If the torrent is a seed or finished, this is -1.
int queue_position;
// the total rates for all peers for this
// torrent. These will usually have better precision than summing the rates from
// all peers. The rates are given as the number of bytes per second.
// the total rates for all peers for this torrent. These will usually
// have better precision than summing the rates from all peers. The rates
// are given as the number of bytes per second.
int download_rate;
int upload_rate;
// the total transfer rate of payload only, not counting protocol chatter. This might
// be slightly smaller than the other rates, but if projected over a long time
// (e.g. when calculating ETA:s) the difference may be noticeable.
// the total transfer rate of payload only, not counting protocol
// chatter. This might be slightly smaller than the other rates, but if
// projected over a long time (e.g. when calculating ETA:s) the
// difference may be noticeable.
int download_payload_rate;
int upload_payload_rate;
@ -1344,65 +1370,60 @@ namespace libtorrent
// currently connected to.
int num_seeds;
// the number of peers this torrent currently is connected to.
// Peer connections that are in the half-open state (is attempting to connect)
// or are queued for later connection attempt do not count. Although they are
// visible in the peer list when you call get_peer_info().
// the number of peers this torrent currently is connected to. Peer
// connections that are in the half-open state (is attempting to connect)
// or are queued for later connection attempt do not count. Although they
// are visible in the peer list when you call get_peer_info().
int num_peers;
// if the tracker sends scrape info in its
// announce reply, these fields will be
// set to the total number of peers that
// have the whole file and the total number
// of peers that are still downloading.
// set to -1 if the tracker did not
// send any scrape data in its announce reply.
// if the tracker sends scrape info in its announce reply, these fields
// will be set to the total number of peers that have the whole file and
// the total number of peers that are still downloading. set to -1 if the
// tracker did not send any scrape data in its announce reply.
int num_complete;
int num_incomplete;
// the number of seeds in our peer list
// and the total number of peers (including seeds). We are not
// necessarily connected to all the peers in our peer list. This is the number
// of peers we know of in total, including banned peers and peers that we have
// failed to connect to.
// the number of seeds in our peer list and the total number of peers
// (including seeds). We are not necessarily connected to all the peers
// in our peer list. This is the number of peers we know of in total,
// including banned peers and peers that we have failed to connect to.
int list_seeds;
int list_peers;
// the number of peers in this torrent's peer list
// that is a candidate to be connected to. i.e. It has fewer connect attempts
// than the max fail count, it is not a seed if we are a seed, it is not banned
// etc. If this is 0, it means we don't know of any more peers that we can try.
// the number of peers in this torrent's peer list that is a candidate to
// be connected to. i.e. It has fewer connect attempts than the max fail
// count, it is not a seed if we are a seed, it is not banned etc. If
// this is 0, it means we don't know of any more peers that we can try.
int connect_candidates;
// the number of pieces that has been downloaded. It is equivalent
// to: ``std::accumulate(pieces->begin(), pieces->end())``. So you don't have to
// count yourself. This can be used to see if anything has updated since last time
// if you want to keep a graph of the pieces up to date.
// the number of pieces that has been downloaded. It is equivalent to:
// ``std::accumulate(pieces->begin(), pieces->end())``. So you don't have
// to count yourself. This can be used to see if anything has updated
// since last time if you want to keep a graph of the pieces up to date.
int num_pieces;
// the number of distributed copies of the torrent.
// Note that one copy may be spread out among many peers. It tells how many copies
// there are currently of the rarest piece(s) among the peers this client is
// the number of distributed copies of the torrent. Note that one copy
// may be spread out among many peers. It tells how many copies there are
// currently of the rarest piece(s) among the peers this client is
// connected to.
int distributed_full_copies;
// tells the share of pieces that have more copies than
// the rarest piece(s). Divide this number by 1000 to get the fraction.
// tells the share of pieces that have more copies than the rarest
// piece(s). Divide this number by 1000 to get the fraction.
//
// For example, if ``distributed_full_copies`` is 2 and ``distrbuted_fraction``
// is 500, it means that the rarest pieces have only 2 copies among the peers
// this torrent is connected to, and that 50% of all the pieces have more than
// two copies.
// For example, if ``distributed_full_copies`` is 2 and
// ``distrbuted_fraction`` is 500, it means that the rarest pieces have
// only 2 copies among the peers this torrent is connected to, and that
// 50% of all the pieces have more than two copies.
//
// If we are a seed, the piece picker is deallocated as an optimization, and
// piece availability is no longer tracked. In this case the distributed
// copies members are set to -1.
// If we are a seed, the piece picker is deallocated as an optimization,
// and piece availability is no longer tracked. In this case the
// distributed copies members are set to -1.
int distributed_fraction;
// the number of distributed copies of the file.
// note that one copy may be spread out among many peers.
// This is a floating point representation of the
// distributed copies.
// the number of distributed copies of the file. note that one copy may
// be spread out among many peers. This is a floating point
// representation of the distributed copies.
//
// the integer part tells how many copies
// there are of the rarest piece(s)
@ -1411,8 +1432,8 @@ namespace libtorrent
// have more copies than the rarest piece(s).
float distributed_copies;
// the size of a block, in bytes. A block is a sub piece, it
// is the number of bytes that each piece request asks for and the number of
// the size of a block, in bytes. A block is a sub piece, it is the
// number of bytes that each piece request asks for and the number of
// bytes that each bit in the ``partial_piece_info``'s bitset represents,
// see get_download_queue(). This is typically 16 kB, but it may be
// larger if the pieces are larger.
@ -1421,9 +1442,9 @@ namespace libtorrent
// the number of unchoked peers in this torrent.
int num_uploads;
// the number of peer connections this torrent has, including
// half-open connections that hasn't completed the bittorrent handshake yet. This is
// always >= ``num_peers``.
// the number of peer connections this torrent has, including half-open
// connections that hasn't completed the bittorrent handshake yet. This
// is always >= ``num_peers``.
int num_connections;
// the set limit of upload slots (unchoked peers) for this torrent.
@ -1432,43 +1453,44 @@ namespace libtorrent
// the set limit of number of connections for this torrent.
int connections_limit;
// the number of peers in this
// torrent that are waiting for more bandwidth quota from the torrent rate limiter.
// This can determine if the rate you get from this torrent is bound by the torrents
// limit or not. If there is no limit set on this torrent, the peers might still be
// waiting for bandwidth quota from the global limiter, but then they are counted in
// the ``session_status`` object.
// the number of peers in this torrent that are waiting for more
// bandwidth quota from the torrent rate limiter. This can determine if
// the rate you get from this torrent is bound by the torrents limit or
// not. If there is no limit set on this torrent, the peers might still
// be waiting for bandwidth quota from the global limiter, but then they
// are counted in the ``session_status`` object.
int up_bandwidth_queue;
int down_bandwidth_queue;
// the number of
// seconds since any peer last uploaded from this torrent and the last
// time a downloaded piece passed the hash check, respectively.
// the number of seconds since any peer last uploaded from this torrent
// and the last time a downloaded piece passed the hash check,
// respectively.
int time_since_upload;
int time_since_download;
// These keep track of the number of seconds this torrent has been active (not
// paused) and the number of seconds it has been active while being finished and
// active while being a seed. ``seeding_time`` should be <= ``finished_time`` which
// should be <= ``active_time``. They are all saved in and restored from resume data,
// to keep totals across sessions.
int active_time;
// These keep track of the number of seconds this torrent has been active
// (not paused) and the number of seconds it has been active while being
// finished and active while being a seed. ``seeding_time`` should be <=
// ``finished_time`` which should be <= ``active_time``. They are all
// saved in and restored from resume data, to keep totals across
// sessions.
int active_time;
int finished_time;
int seeding_time;
// A rank of how important it is to seed the torrent, it is used
// to determine which torrents to seed and which to queue. It is based on the peer
// to seed ratio from the tracker scrape. For more information, see queuing_.
// Higher value means more important to seed
// A rank of how important it is to seed the torrent, it is used to
// determine which torrents to seed and which to queue. It is based on
// the peer to seed ratio from the tracker scrape. For more information,
// see queuing_. Higher value means more important to seed
int seed_rank;
// the number of seconds since this torrent acquired scrape data.
// If it has never done that, this value is -1.
int last_scrape;
// the number of regions of non-downloaded pieces in the
// torrent. This is an interesting metric on windows vista, since there is
// a limit on the number of sparse regions in a single file there.
// the number of regions of non-downloaded pieces in the torrent. This is
// an interesting metric on windows vista, since there is a limit on the
// number of sparse regions in a single file there.
int sparse_regions;
// the priority of this torrent
@ -1486,58 +1508,60 @@ namespace libtorrent
// to this torrent. This defaults to true.
bool ip_filter_applies;
// true if the torrent is blocked from downloading. This
// typically happens when a disk write operation fails. If the torrent is
// true if the torrent is blocked from downloading. This typically
// happens when a disk write operation fails. If the torrent is
// auto-managed, it will periodically be taken out of this state, in the
// hope that the disk condition (be it disk full or permission errors) has
// been resolved. If the torrent is not auto-managed, you have to explicitly
// take it out of the upload mode by calling set_upload_mode() on the
// torrent_handle.
// hope that the disk condition (be it disk full or permission errors)
// has been resolved. If the torrent is not auto-managed, you have to
// explicitly take it out of the upload mode by calling set_upload_mode()
// on the torrent_handle.
bool upload_mode;
// true if the torrent is currently in share-mode, i.e.
// not downloading the torrent, but just helping the swarm out.
// true if the torrent is currently in share-mode, i.e. not downloading
// the torrent, but just helping the swarm out.
bool share_mode;
// true if the torrent is in super seeding mode
bool super_seeding;
// set to true if the torrent is paused and false otherwise. It's only true
// if the torrent itself is paused. If the torrent is not running because the session is
// paused, this is still false. To know if a torrent is active or not, you need to inspect
// both ``torrent_status::paused`` and ``session::is_paused()``.
// set to true if the torrent is paused and false otherwise. It's only
// true if the torrent itself is paused. If the torrent is not running
// because the session is paused, this is still false. To know if a
// torrent is active or not, you need to inspect both
// ``torrent_status::paused`` and ``session::is_paused()``.
bool paused;
// set to true if the torrent is auto managed, i.e. libtorrent is
// responsible for determining whether it should be started or queued. For more info
// see queuing_
// responsible for determining whether it should be started or queued.
// For more info see queuing_
bool auto_managed;
// true when the torrent is in sequential download mode. In
// this mode pieces are downloaded in order rather than rarest first.
// true when the torrent is in sequential download mode. In this mode
// pieces are downloaded in order rather than rarest first.
bool sequential_download;
// true if all pieces have been downloaded.
bool is_seeding;
// true if all pieces that have a priority > 0 are downloaded. There is
// only a distinction between finished and seeding if some pieces or files have been
// set to priority 0, i.e. are not downloaded.
// only a distinction between finished and seeding if some pieces or
// files have been set to priority 0, i.e. are not downloaded.
bool is_finished;
// true if this torrent has metadata (either it was started from a
// .torrent file or the metadata has been downloaded). The only scenario where this can be
// false is when the torrent was started torrent-less (i.e. with just an info-hash and tracker
// ip, a magnet link for instance).
// .torrent file or the metadata has been downloaded). The only scenario
// where this can be false is when the torrent was started torrent-less
// (i.e. with just an info-hash and tracker ip, a magnet link for
// instance).
bool has_metadata;
// true if there has ever been an incoming connection attempt
// to this torrent.
// true if there has ever been an incoming connection attempt to this
// torrent.
bool has_incoming;
// true if the torrent is in seed_mode. If the torrent was
// started in seed mode, it will leave seed mode once all pieces have been
// checked or as soon as one piece fails the hash check.
// true if the torrent is in seed_mode. If the torrent was started in
// seed mode, it will leave seed mode once all pieces have been checked
// or as soon as one piece fails the hash check.
bool seed_mode;
// this is true if this torrent's storage is currently being moved from