swap()
void swap (torrent_info& ti);
diff --git a/docs/reference.html b/docs/reference.html
index df18544c9..868ec1786 100644
--- a/docs/reference.html
+++ b/docs/reference.html
@@ -57,7 +57,6 @@
-
diff --git a/include/libtorrent/peer_info.hpp b/include/libtorrent/peer_info.hpp
index a7c6b7121..3bf8f5b21 100644
--- a/include/libtorrent/peer_info.hpp
+++ b/include/libtorrent/peer_info.hpp
@@ -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
diff --git a/include/libtorrent/session.hpp b/include/libtorrent/session.hpp
index c27bdc3b9..6d9d33892 100644
--- a/include/libtorrent/session.hpp
+++ b/include/libtorrent/session.hpp
@@ -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
* ret
, boost::function const& pred
, boost::uint32_t flags = 0) const;
void refresh_torrent_status(std::vector* 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 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& 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 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`` 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`` 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 pop_alert();
void pop_alerts(std::deque* 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)> 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();
diff --git a/include/libtorrent/torrent_handle.hpp b/include/libtorrent/torrent_handle.hpp
index b6c52c833..2e01111b8 100644
--- a/include/libtorrent/torrent_handle.hpp
+++ b/include/libtorrent/torrent_handle.hpp
@@ -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(torrent*, void*)> const& ext
+ void add_extension(
+ boost::function(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`` 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`` 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& 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 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 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