jiigen666/libtorrent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

moved more documentation into header files

Browse Source
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
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
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()
----------------------------------------