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

moved more documentation into header files

This commit is contained in:
Arvid Norberg 2013-07-21 05:05:21 +00:00
parent 329ed1bdde
commit eb6a964463
6 changed files with 212 additions and 522 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

497
docs/manual.rst
View File

@ -93,503 +93,6 @@ For documentation on these types, please refer to the `asio documentation`_.
.. _`asio documentation`: http://asio.sourceforge.net/asio-0.3.8/doc/asio/reference.html .. _`asio documentation`: http://asio.sourceforge.net/asio-0.3.8/doc/asio/reference.html
async_add_torrent() add_torrent()
---------------------------------
::
typedef boost::function<storage_interface*(file_storage const&
, file_storage const*, std::string const&, file_pool&
, std::vector<boost::uint8_t> const&) storage_constructor_type;
struct add_torrent_params
{
add_torrent_params(storage_constructor_type s);
enum flags_t
{
flag_seed_mode = 0x001,
flag_override_resume_data = 0x002,
flag_upload_mode = 0x004,
flag_share_mode = 0x008,
flag_apply_ip_filter = 0x010,
flag_paused = 0x020,
flag_auto_managed = 0x040.
flag_duplicate_is_error = 0x080,
flag_merge_resume_trackers = 0x100,
flag_update_subscribe = 0x200,
flag_super_seeding = 0x400,
flag_sequential_download = 0x800
};
int version;
boost::intrusive_ptr<torrent_info> ti;
#ifndef TORRENT_NO_DEPRECATE
char const* tracker_url;
#endif
std::vector<std::string> trackers;
std::vector<std::pair<std::string, int> > dht_nodes;
sha1_hash info_hash;
std::string name;
std::string save_path;
std::vector<char> resume_data;
storage_mode_t storage_mode;
storage_constructor_type storage;
void* userdata;
std::vector<boost::uint8_t> file_priorities;
std::string trackerid;
std::string url;
std::string uuid;
std::string source_feed_url;
boost::uint64_t flags;
int max_uploads;
int max_connections;
int upload_limit;
int download_limit;
};
torrent_handle add_torrent(add_torrent_params const& params);
torrent_handle add_torrent(add_torrent_params const& params
, error_code& ec);
void async_add_torrent(add_torrent_params const& params);
The ``storage_mode`` parameter refers to the layout of the storage for this torrent.
There are 3 different modes:
storage_mode_sparse
All pieces will be written to the place where they belong and sparse files
will be used. This is the recommended, and default mode.
storage_mode_allocate
All pieces will be written to their final position, all files will be
allocated in full when the torrent is first started. This is done with
``fallocate()`` and similar calls. This mode minimizes fragmentation.
storage_mode_compact
**this mode is deprecated and will be removed in future versions of libtorrent**
The storage will grow as more pieces are downloaded, and pieces
are rearranged to finally be in their correct places once the entire torrent has been
downloaded.
For more information, see `storage allocation`_.
remove_torrent()
----------------
::
void remove_torrent(torrent_handle const& h, int options = none);
``remove_torrent()`` will close all peer connections associated with the torrent and tell
the tracker that we've stopped participating in the swarm. The optional second argument
``options`` can be used to delete all the files downloaded by this torrent. To do this, 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.
find_torrent() get_torrents()
-----------------------------
::
torrent_handle find_torrent(sha_hash const& ih);
std::vector<torrent_handle> get_torrents() const;
``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.
``get_torrents()`` returns a vector of torrent_handles to all the torrents
currently in the session.
get_torrent_status() refresh_torrent_status()
---------------------------------------------
::
void get_torrent_status(std::vector<torrent_status>* ret
, boost::function<bool(torrent_status const&)> const& pred
, boost::uint32_t flags = 0) const;
void refresh_torrent_status(std::vector<torrent_status>* ret
, boost::uint32_t flags = 0) const;
.. note::
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.
``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.
post_torrent_updates()
----------------------
::
void post_torrent_updates();
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`` under `async_add_torrent() add_torrent()`_.
load_asnum_db() load_country_db() as_for_ip()
---------------------------------------------
::
void load_asnum_db(char const* file);
void load_asnum_db(wchar_t const* file);
void load_country_db(char const* file);
void load_country_db(wchar_t const* file);
int as_for_ip(address const& adr);
These functions are not available if ``TORRENT_DISABLE_GEO_IP`` is defined. They
expects a path to the `MaxMind ASN database`_ and `MaxMind GeoIP database`_
respectively. This will be used to look up which AS and country peers belong to.
``as_for_ip`` returns the AS number for the IP address specified. If the IP is not
in the database or the ASN database is not loaded, 0 is returned.
The ``wchar_t`` overloads are for wide character paths.
.. _`MaxMind ASN database`: http://www.maxmind.com/app/asnum
.. _`MaxMind GeoIP database`: http://www.maxmind.com/app/geolitecountry
set_ip_filter()
---------------
::
void set_ip_filter(ip_filter const& 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()
---------------
::
ip_filter get_ip_filter() const;
Returns the ip_filter currently in the session. See ip_filter_.
status()
--------
::
session_status status() const;
``status()`` returns session wide-statistics and status. The ``session_status``
struct has the following members::
struct dht_lookup
{
char const* type;
int outstanding_requests;
int timeouts;
int responses;
int branch_factor;
int nodes_left;
int last_sent;
int first_timeout;
};
struct dht_routing_bucket
{
int num_nodes;
int num_replacements;
int last_active;
};
struct utp_status
{
int num_idle;
int num_syn_sent;
int num_connected;
int num_fin_sent;
int num_close_wait;
};
struct session_status
{
bool has_incoming_connections;
int upload_rate;
int download_rate;
size_type total_download;
size_type total_upload;
int payload_upload_rate;
int payload_download_rate;
size_type total_payload_download;
size_type total_payload_upload;
int ip_overhead_upload_rate;
int ip_overhead_download_rate;
size_type total_ip_overhead_download;
size_type total_ip_overhead_upload;
int dht_upload_rate;
int dht_download_rate;
size_type total_dht_download;
size_type total_dht_upload;
int tracker_upload_rate;
int tracker_download_rate;
size_type total_tracker_download;
size_type total_tracker_upload;
size_type total_redundant_bytes;
size_type total_failed_bytes;
int num_peers;
int num_unchoked;
int allowed_upload_slots;
int up_bandwidth_queue;
int down_bandwidth_queue;
int up_bandwidth_bytes_queue;
int down_bandwidth_bytes_queue;
int optimistic_unchoke_counter;
int unchoke_counter;
int disk_write_queue;
int disk_read_queue;
int dht_nodes;
int dht_node_cache;
int dht_torrents;
size_type dht_global_nodes;
std::vector<dht_lookup> active_requests;
std::vector<dht_routing_table> dht_routing_table;
int dht_total_allocations;
utp_status utp_stats;
};
``has_incoming_connections`` is false as long as no incoming connections have been
established on the listening socket. Every time you change the listen port, this will
be reset to false.
``upload_rate``, ``download_rate`` are the total download and upload rates accumulated
from all torrents. This includes bittorrent protocol, DHT and an estimated TCP/IP
protocol overhead.
``total_download`` and ``total_upload`` are the total number of bytes downloaded and
uploaded to and from all torrents. This also includes all the protocol overhead.
``payload_download_rate`` and ``payload_upload_rate`` is the rate of the payload
down- and upload only.
``total_payload_download`` and ``total_payload_upload`` is the total transfers of payload
only. The payload does not include the bittorrent protocol overhead, but only parts of the
actual files to be downloaded.
``ip_overhead_upload_rate``, ``ip_overhead_download_rate``, ``total_ip_overhead_download``
and ``total_ip_overhead_upload`` is the estimated TCP/IP overhead in each direction.
``dht_upload_rate``, ``dht_download_rate``, ``total_dht_download`` and ``total_dht_upload``
is the DHT bandwidth usage.
``total_redundant_bytes`` is the number of bytes that has been received more than once.
This can happen if a request from a peer times out and is requested from a different
peer, and then received again from the first one. To make this lower, increase the
``request_timeout`` and the ``piece_timeout`` in the session settings.
``total_failed_bytes`` is the number of bytes that was downloaded which later failed
the hash-check.
``num_peers`` is the total number of peer connections this session has. This includes
incoming connections that still hasn't sent their handshake or outgoing connections
that still hasn't completed the TCP connection. This number may be slightly higher
than the sum of all peers of all torrents because the incoming connections may not
be assigned a torrent yet.
``num_unchoked`` is the current number of unchoked peers.
``allowed_upload_slots`` is the current allowed number of unchoked peers.
``up_bandwidth_queue`` and ``down_bandwidth_queue`` are the number of peers that are
waiting for more bandwidth quota from the torrent rate limiter.
``up_bandwidth_bytes_queue`` and ``down_bandwidth_bytes_queue`` count the number of
bytes the connections are waiting for to be able to send and receive.
``optimistic_unchoke_counter`` and ``unchoke_counter`` tells the number of
seconds until the next optimistic unchoke change and the start of the next
unchoke interval. These numbers may be reset prematurely if a peer that is
unchoked disconnects or becomes notinterested.
``disk_write_queue`` and ``disk_read_queue`` are the number of peers currently
waiting on a disk write or disk read to complete before it receives or sends
any more data on the socket. It'a a metric of how disk bound you are.
``dht_nodes``, ``dht_node_cache`` and ``dht_torrents`` are only available when
built with DHT support. They are all set to 0 if the DHT isn't running. When
the DHT is running, ``dht_nodes`` is set to the number of nodes in the routing
table. This number only includes *active* nodes, not cache nodes. The
``dht_node_cache`` is set to the number of nodes in the node cache. These nodes
are used to replace the regular nodes in the routing table in case any of them
becomes unresponsive.
``dht_torrents`` are the number of torrents tracked by the DHT at the moment.
``dht_global_nodes`` is an estimation of the total number of nodes in the DHT
network.
``active_requests`` is a vector of the currently running DHT lookups.
``dht_routing_table`` contains information about every bucket in the DHT routing
table.
``dht_total_allocations`` is the number of nodes allocated dynamically for a
particular DHT lookup. This represents roughly the amount of memory used
by the DHT.
``utp_stats`` contains statistics on the uTP sockets.
get_cache_status()
------------------
::
cache_status get_cache_status() const;
Returns status of the disk cache for this session.
::
struct cache_status
{
size_type blocks_written;
size_type writes;
size_type blocks_read;
size_type blocks_read_hit;
size_type reads;
int cache_size;
int read_cache_size;
int total_used_buffers;
int average_queue_time;
int average_read_time;
int average_write_time;
int average_hash_time;
int average_cache_time;
int job_queue_length;
};
``blocks_written`` is the total number of 16 KiB blocks written to disk
since this session was started.
``writes`` is the total number of write operations performed since this
session was started.
The ratio (``blocks_written`` - ``writes``) / ``blocks_written`` represents
the number of saved write operations per total write operations. i.e. a kind
of cache hit ratio for the write cahe.
``blocks_read`` is the number of blocks that were requested from the
bittorrent engine (from peers), that were served from disk or cache.
``blocks_read_hit`` is the number of blocks that were served from cache.
The ratio ``blocks_read_hit`` / ``blocks_read`` is the cache hit ratio
for the read cache.
``cache_size`` is the number of 16 KiB blocks currently in the disk cache.
This includes both read and write cache.
``read_cache_size`` is the number of 16KiB blocks in the read cache.
``total_used_buffers`` is the total number of buffers currently in use.
This includes the read/write disk cache as well as send and receive buffers
used in peer connections.
``average_queue_time`` is the number of microseconds an average disk I/O job
has to wait in the job queue before it get processed.
``average_read_time`` is the time read jobs takes on average to complete
(not including the time in the queue), in microseconds. This only measures
read cache misses.
``average_write_time`` is the time write jobs takes to complete, on average,
in microseconds. This does not include the time the job sits in the disk job
queue or in the write cache, only blocks that are flushed to disk.
``average_hash_time`` is the time hash jobs takes to complete on average, in
microseconds. Hash jobs include running SHA-1 on the data (which for the most
part is done incrementally) and sometimes reading back parts of the piece. It
also includes checking files without valid resume data.
``average_cache_time`` is the average amuount of time spent evicting cached
blocks that have expired from the disk cache.
``job_queue_length`` is the number of jobs in the job queue.
get_cache_info()
----------------
::
void get_cache_info(sha1_hash const& ih
, std::vector<cached_piece_info>& ret) const;
``get_cache_info()`` fills out the supplied vector with information for
each piece that is currently in the disk cache for the torrent with the
specified info-hash (``ih``).
::
struct cached_piece_info
{
int piece;
std::vector<bool> blocks;
ptime last_use;
enum kind_t { read_cache = 0, write_cache = 1 };
kind_t kind;
};
``piece`` is the piece index for this cache entry.
``blocks`` has one entry for each block in this piece. ``true`` represents
the data for that block being in the disk cache and ``false`` means it's not.
``last_use`` is the time when a block was last written to this piece. The older
a piece is, the more likely it is to be flushed to disk.
``kind`` specifies if this piece is part of the read cache or the write cache.
is_listening() listen_port() listen_on() is_listening() listen_port() listen_on()
---------------------------------------- ----------------------------------------

16
include/libtorrent/add_torrent_params.hpp
View File

@ -177,7 +177,7 @@ namespace libtorrent
// an auto-update torrent for instance. // an auto-update torrent for instance.
flag_apply_ip_filter = 0x010, flag_apply_ip_filter = 0x010,
// ``flag_paused`` specifies whether or not the torrent is to be started in a paused // specifies whether or not the torrent is to be started in a paused
// state. I.e. it won't connect to the tracker or any of the peers until it's // state. I.e. it won't connect to the tracker or any of the peers until it's
// resumed. This is typically a good way of avoiding race conditions when setting // resumed. This is typically a good way of avoiding race conditions when setting
// configuration options on torrents before starting them. // configuration options on torrents before starting them.
@ -223,7 +223,7 @@ namespace libtorrent
#endif #endif
}; };
// ``version`` is filled in by the constructor and should be left untouched. It // filled in by the constructor and should be left untouched. It
// is used for forward binary compatibility. // is used for forward binary compatibility.
int version; int version;
boost::intrusive_ptr<torrent_info> ti; boost::intrusive_ptr<torrent_info> ti;
@ -234,7 +234,7 @@ namespace libtorrent
// ``trackers`` can specify tracker URLs for the torrent. // ``trackers`` can specify tracker URLs for the torrent.
std::vector<std::string> trackers; std::vector<std::string> trackers;
// ``dht_nodes`` is a list of hostname and port pairs, representing DHT nodes to be // a list of hostname and port pairs, representing DHT nodes to be
// added to the session (if DHT is enabled). The hostname may be an IP address. // added to the session (if DHT is enabled). The hostname may be an IP address.
std::vector<std::pair<std::string, int> > dht_nodes; std::vector<std::pair<std::string, int> > dht_nodes;
sha1_hash info_hash; sha1_hash info_hash;
@ -246,9 +246,11 @@ namespace libtorrent
// `save_resume_data()`_ on `torrent_handle`_. See `fast resume`_. The ``vector`` that is // `save_resume_data()`_ on `torrent_handle`_. See `fast resume`_. The ``vector`` that is
// passed in will be swapped into the running torrent instance with ``std::vector::swap()``. // passed in will be swapped into the running torrent instance with ``std::vector::swap()``.
std::vector<char> resume_data; std::vector<char> resume_data;
// One of the values from storage_mode_t. For more information, see `storage allocation`_.
storage_mode_t storage_mode; storage_mode_t storage_mode;
// ``storage`` can be used to customize how the data is stored. The default // can be used to customize how the data is stored. The default
// storage will simply write the data to the files it belongs to, but it could be // storage will simply write the data to the files it belongs to, but it could be
// overridden to save everything to a single file at a specific location or encrypt the // overridden to save everything to a single file at a specific location or encrypt the
// content on disk for instance. For more information about the ``storage_interface`` // content on disk for instance. For more information about the ``storage_interface``
@ -259,11 +261,11 @@ namespace libtorrent
// constructor functions, if any (see `add_extension()`_). // constructor functions, if any (see `add_extension()`_).
void* userdata; void* userdata;
// ``file_priorities`` can be set to control the initial file priorities when adding // can be set to control the initial file priorities when adding
// a torrent. The semantics are the same as for ``torrent_handle::prioritize_files()``. // a torrent. The semantics are the same as for ``torrent_handle::prioritize_files()``.
std::vector<boost::uint8_t> file_priorities; std::vector<boost::uint8_t> file_priorities;
// ``trackerid`` is the default tracker id to be used when announcing to trackers. By default // the default tracker id to be used when announcing to trackers. By default
// this is empty, and no tracker ID is used, since this is an optional argument. If // this is empty, and no tracker ID is used, since this is an optional argument. If
// a tracker returns a tracker ID, that ID is used instead of this. // a tracker returns a tracker ID, that ID is used instead of this.
std::string trackerid; std::string trackerid;
@ -286,7 +288,7 @@ namespace libtorrent
// is mainly useful for RSS feed items which has UUIDs specified. // is mainly useful for RSS feed items which has UUIDs specified.
std::string uuid; std::string uuid;
// ``source_feed_url`` should point to the URL of the RSS feed this torrent comes from, // should point to the URL of the RSS feed this torrent comes from,
// if it comes from an RSS feed. // if it comes from an RSS feed.
std::string source_feed_url; std::string source_feed_url;

68
include/libtorrent/disk_io_thread.hpp
View File

@ -63,11 +63,26 @@ namespace libtorrent
struct cached_piece_info struct cached_piece_info
{ {
// the piece index for this cache entry.
int piece; int piece;
// holds one entry for each block in this piece. ``true`` represents
// the data for that block being in the disk cache and ``false`` means it's not.
std::vector<bool> blocks; std::vector<bool> blocks;
// the time when a block was last written to this piece. The older
// a piece is, the more likely it is to be flushed to disk.
ptime last_use; ptime last_use;
// The index of the next block that needs to be hashed.
// Blocks are hashed as they are downloaded in order to not
// have to re-read them from disk once the piece is complete, to
// compare its hash against the hashes in the .torrent file.
int next_to_hash; int next_to_hash;
enum kind_t { read_cache = 0, write_cache = 1 }; enum kind_t { read_cache = 0, write_cache = 1 };
// specifies if this piece is part of the read cache or the write cache.
kind_t kind; kind_t kind;
}; };
@ -180,40 +195,69 @@ namespace libtorrent
, read_queue_size(0) , read_queue_size(0)
{} {}
// the number of 16kB blocks written // the total number of 16 KiB blocks written to disk
// since this session was started.
size_type blocks_written; size_type blocks_written;
// the number of write operations used
size_type writes;
// (blocks_written - writes) / blocks_written represents the
// "cache hit" ratio in the write cache
// the number of blocks read
// the number of blocks passed back to the bittorrent engine // the total number of write operations performed since this
// session was started.
//
// The ratio (``blocks_written`` - ``writes``) / ``blocks_written`` represents
// the number of saved write operations per total write operations. i.e. a kind
// of cache hit ratio for the write cahe.
size_type writes;
// the number of blocks that were requested from the
// bittorrent engine (from peers), that were served from disk or cache.
size_type blocks_read; size_type blocks_read;
// the number of blocks that was just copied from the read cache // the number of blocks that was just copied from the read cache
//
// The ratio ``blocks_read_hit`` / ``blocks_read`` is the cache hit ratio
// for the read cache.
size_type blocks_read_hit; size_type blocks_read_hit;
// the number of read operations used // the number of read operations used
size_type reads; size_type reads;
mutable size_type queued_bytes; mutable size_type queued_bytes;
// the number of blocks in the cache (both read and write) // the number of 16 KiB blocks currently in the disk cache (both read and write).
// This includes both read and write cache.
int cache_size; int cache_size;
// the number of blocks in the cache used for read cache // the number of 16KiB blocks in the read cache.
int read_cache_size; int read_cache_size;
// the total number of blocks that are currently in use // the total number of buffers currently in use.
// this includes send and receive buffers // This includes the read/write disk cache as well as send and receive buffers
// used in peer connections.
mutable int total_used_buffers; mutable int total_used_buffers;
// times in microseconds // the number of microseconds an average disk I/O job
// has to wait in the job queue before it get processed.
int average_queue_time; int average_queue_time;
// the time read jobs takes on average to complete
// (not including the time in the queue), in microseconds. This only measures
// read cache misses.
int average_read_time; int average_read_time;
// the time write jobs takes to complete, on average,
// in microseconds. This does not include the time the job sits in the disk job
// queue or in the write cache, only blocks that are flushed to disk.
int average_write_time; int average_write_time;
// the time hash jobs takes to complete on average, in
// microseconds. Hash jobs include running SHA-1 on the data (which for the most
// part is done incrementally) and sometimes reading back parts of the piece. It
// also includes checking files without valid resume data.
int average_hash_time; int average_hash_time;
int average_job_time; int average_job_time;
int average_sort_time; int average_sort_time;
// the number of jobs in the job queue.
int job_queue_length; int job_queue_length;
boost::uint32_t cumulative_job_time; boost::uint32_t cumulative_job_time;

78
include/libtorrent/session.hpp
View File

@ -205,20 +205,55 @@ namespace libtorrent
void save_state(entry& e, boost::uint32_t flags = 0xffffffff) const; void save_state(entry& e, boost::uint32_t flags = 0xffffffff) const;
void load_state(lazy_entry const& e); 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
// 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.
//
// ``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.
void get_torrent_status(std::vector<torrent_status>* ret void get_torrent_status(std::vector<torrent_status>* ret
, boost::function<bool(torrent_status const&)> const& pred , boost::function<bool(torrent_status const&)> const& pred
, boost::uint32_t flags = 0) const; , boost::uint32_t flags = 0) const;
void refresh_torrent_status(std::vector<torrent_status>* ret void refresh_torrent_status(std::vector<torrent_status>* ret
, boost::uint32_t flags = 0) const; , 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.
//
// Only torrents who has the state subscription flag set will be included. This flag
// is on by default. See ``add_torrent_params`` under `async_add_torrent() add_torrent()`_
void post_torrent_updates(); void post_torrent_updates();
// returns a list of all torrents in this session
std::vector<torrent_handle> get_torrents() const;
io_service& get_io_service(); io_service& get_io_service();
// returns an invalid handle in case the torrent doesn't exist // ``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.
//
// ``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; torrent_handle find_torrent(sha1_hash const& info_hash) const;
std::vector<torrent_handle> get_torrents() const;
// You add torrents through the ``add_torrent()`` function where you give an // You add torrents through the ``add_torrent()`` function where you give an
// object with all the parameters. The ``add_torrent()`` overloads will block // object with all the parameters. The ``add_torrent()`` overloads will block
@ -311,9 +346,16 @@ namespace libtorrent
void resume(); void resume();
bool is_paused() const; bool is_paused() const;
// returns session wide-statistics and status. For more information, see the ``session_status`` struct.
session_status status() const; session_status status() const;
// Returns status of the disk cache for this session.
// For more information, see the cache_status type.
cache_status get_cache_status() const; cache_status get_cache_status() const;
// fills out the supplied vector with information for
// each piece that is currently in the disk cache for the torrent with the
// specified info-hash (``ih``).
void get_cache_info(sha1_hash const& ih void get_cache_info(sha1_hash const& ih
, std::vector<cached_piece_info>& ret) const; , std::vector<cached_piece_info>& ret) const;
@ -344,10 +386,21 @@ namespace libtorrent
void add_extension(boost::function<boost::shared_ptr<torrent_plugin>(torrent*, void*)> ext); void add_extension(boost::function<boost::shared_ptr<torrent_plugin>(torrent*, void*)> ext);
void add_extension(boost::shared_ptr<plugin> ext); void add_extension(boost::shared_ptr<plugin> ext);
// These functions are not available if ``TORRENT_DISABLE_GEO_IP`` is defined. They
// expects a path to the `MaxMind ASN database`_ and `MaxMind GeoIP database`_
// respectively. This will be used to look up which AS and country peers belong to.
//
// ``as_for_ip`` returns the AS number for the IP address specified. If the IP is not
// in the database or the ASN database is not loaded, 0 is returned.
//
// The ``wchar_t`` overloads are for wide character paths.
//
// .. _`MaxMind ASN database`: http://www.maxmind.com/app/asnum
// .. _`MaxMind GeoIP database`: http://www.maxmind.com/app/geolitecountry
#ifndef TORRENT_DISABLE_GEO_IP #ifndef TORRENT_DISABLE_GEO_IP
int as_for_ip(address const& addr);
void load_asnum_db(char const* file); void load_asnum_db(char const* file);
void load_country_db(char const* file); void load_country_db(char const* file);
int as_for_ip(address const& addr);
#if TORRENT_USE_WSTRING #if TORRENT_USE_WSTRING
void load_country_db(wchar_t const* file); void load_country_db(wchar_t const* file);
void load_asnum_db(wchar_t const* file); void load_asnum_db(wchar_t const* file);
@ -363,6 +416,14 @@ namespace libtorrent
entry state() const TORRENT_DEPRECATED; entry state() const TORRENT_DEPRECATED;
#endif #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_.
//
// 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); void set_ip_filter(ip_filter const& f);
ip_filter get_ip_filter() const; ip_filter get_ip_filter() const;
@ -423,6 +484,13 @@ namespace libtorrent
start_default_features = 2 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. The optional second argument
` // `options`` can be used to delete all the files downloaded by this torrent. To do this, 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 = none); void remove_torrent(const torrent_handle& h, int options = none);
void set_settings(session_settings const& s); void set_settings(session_settings const& s);

66
include/libtorrent/session_status.hpp
View File

@ -79,23 +79,40 @@ namespace libtorrent
struct TORRENT_EXPORT session_status struct TORRENT_EXPORT session_status
{ {
// false as long as no incoming connections have been
// established on the listening socket. Every time you change the listen port, this will
// be reset to false.
bool has_incoming_connections; bool has_incoming_connections;
// the total download and upload rates accumulated
// from all torrents. This includes bittorrent protocol, DHT and an estimated TCP/IP
// protocol overhead.
int upload_rate; int upload_rate;
int download_rate; int download_rate;
// the total number of bytes downloaded and
// uploaded to and from all torrents. This also includes all the protocol overhead.
size_type total_download; size_type total_download;
size_type total_upload; size_type total_upload;
// the rate of the payload
// down- and upload only.
int payload_upload_rate; int payload_upload_rate;
int payload_download_rate; int payload_download_rate;
// the total transfers of payload
// only. The payload does not include the bittorrent protocol overhead, but only parts of the
// actual files to be downloaded.
size_type total_payload_download; size_type total_payload_download;
size_type total_payload_upload; size_type total_payload_upload;
// the estimated TCP/IP overhead in each direction.
int ip_overhead_upload_rate; int ip_overhead_upload_rate;
int ip_overhead_download_rate; int ip_overhead_download_rate;
size_type total_ip_overhead_download; size_type total_ip_overhead_download;
size_type total_ip_overhead_upload; size_type total_ip_overhead_upload;
// the DHT bandwidth usage.
int dht_upload_rate; int dht_upload_rate;
int dht_download_rate; int dht_download_rate;
size_type total_dht_download; size_type total_dht_download;
@ -106,33 +123,82 @@ namespace libtorrent
size_type total_tracker_download; size_type total_tracker_download;
size_type total_tracker_upload; size_type total_tracker_upload;
// the number of bytes that has been received more than once.
// This can happen if a request from a peer times out and is requested from a different
// peer, and then received again from the first one. To make this lower, increase the
// ``request_timeout`` and the ``piece_timeout`` in the session settings.
size_type total_redundant_bytes; size_type total_redundant_bytes;
// the number of bytes that was downloaded which later failed
// the hash-check.
size_type total_failed_bytes; size_type total_failed_bytes;
// the total number of peer connections this session has. This includes
// incoming connections that still hasn't sent their handshake or outgoing connections
// that still hasn't completed the TCP connection. This number may be slightly higher
// than the sum of all peers of all torrents because the incoming connections may not
// be assigned a torrent yet.
int num_peers; int num_peers;
// the current number of unchoked peers.
int num_unchoked; int num_unchoked;
// the current allowed number of unchoked peers.
int allowed_upload_slots; int allowed_upload_slots;
// the number of peers that are
// waiting for more bandwidth quota from the torrent rate limiter.
int up_bandwidth_queue; int up_bandwidth_queue;
int down_bandwidth_queue; int down_bandwidth_queue;
// count the number of
// bytes the connections are waiting for to be able to send and receive.
int up_bandwidth_bytes_queue; int up_bandwidth_bytes_queue;
int down_bandwidth_bytes_queue; int down_bandwidth_bytes_queue;
// tells the number of
// seconds until the next optimistic unchoke change and the start of the next
// unchoke interval. These numbers may be reset prematurely if a peer that is
// unchoked disconnects or becomes notinterested.
int optimistic_unchoke_counter; int optimistic_unchoke_counter;
int unchoke_counter; int unchoke_counter;
// the number of peers currently
// waiting on a disk write or disk read to complete before it receives or sends
// any more data on the socket. It'a a metric of how disk bound you are.
int disk_write_queue; int disk_write_queue;
int disk_read_queue; int disk_read_queue;
// only available when
// built with DHT support. They are all set to 0 if the DHT isn't running. When
// the DHT is running, ``dht_nodes`` is set to the number of nodes in the routing
// table. This number only includes *active* nodes, not cache nodes. The
// ``dht_node_cache`` is set to the number of nodes in the node cache. These nodes
// are used to replace the regular nodes in the routing table in case any of them
// becomes unresponsive.
int dht_nodes; int dht_nodes;
int dht_node_cache; int dht_node_cache;
// the number of torrents tracked by the DHT at the moment.
int dht_torrents; int dht_torrents;
// an estimation of the total number of nodes in the DHT
// network.
size_type dht_global_nodes; size_type dht_global_nodes;
// a vector of the currently running DHT lookups.
std::vector<dht_lookup> active_requests; std::vector<dht_lookup> active_requests;
// contains information about every bucket in the DHT routing
// table.
std::vector<dht_routing_bucket> dht_routing_table; std::vector<dht_routing_bucket> dht_routing_table;
// the number of nodes allocated dynamically for a
// particular DHT lookup. This represents roughly the amount of memory used
// by the DHT.
int dht_total_allocations; int dht_total_allocations;
// statistics on the uTP sockets.
utp_status utp_stats; utp_status utp_stats;
int peerlist_size; int peerlist_size;

9
include/libtorrent/storage_defs.hpp
View File

@ -45,9 +45,16 @@ namespace libtorrent
enum storage_mode_t enum storage_mode_t
{ {
// All pieces will be written to their final position, all files will be
// allocated in full when the torrent is first started. This is done with
// ``fallocate()`` and similar calls. This mode minimizes fragmentation.
storage_mode_allocate = 0, storage_mode_allocate = 0,
// All pieces will be written to the place where they belong and sparse files
// will be used. This is the recommended, and default mode.
storage_mode_sparse, storage_mode_sparse,
// this is here for internal use
// internal use only
internal_storage_mode_compact_deprecated, internal_storage_mode_compact_deprecated,
#ifndef TORRENT_NO_DEPRECATE #ifndef TORRENT_NO_DEPRECATE
storage_mode_compact = internal_storage_mode_compact_deprecated storage_mode_compact = internal_storage_mode_compact_deprecated