moved more documentation over from manual to headers
This commit is contained in:
Arvid Norberg
parent
28cdc639fa
commit
fc68f28848
431
docs/manual.rst
431
docs/manual.rst
|
|
@ -93,248 +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
|
||||||
|
|
||||||
peer_info
|
|
||||||
=========
|
|
||||||
|
|
||||||
It contains the following fields::
|
|
||||||
|
|
||||||
struct peer_info
|
|
||||||
{
|
|
||||||
enum
|
|
||||||
{
|
|
||||||
interesting = 0x1,
|
|
||||||
choked = 0x2,
|
|
||||||
remote_interested = 0x4,
|
|
||||||
remote_choked = 0x8,
|
|
||||||
supports_extensions = 0x10,
|
|
||||||
local_connection = 0x20,
|
|
||||||
handshake = 0x40,
|
|
||||||
connecting = 0x80,
|
|
||||||
queued = 0x100,
|
|
||||||
on_parole = 0x200,
|
|
||||||
seed = 0x400,
|
|
||||||
optimistic_unchoke = 0x800,
|
|
||||||
snubbed = 0x1000,
|
|
||||||
upload_only = 0x2000,
|
|
||||||
endgame_mode = 0x4000,
|
|
||||||
holepunched = 0x8000,
|
|
||||||
rc4_encrypted = 0x100000,
|
|
||||||
plaintext_encrypted = 0x200000
|
|
||||||
};
|
|
||||||
|
|
||||||
unsigned int flags;
|
|
||||||
|
|
||||||
enum peer_source_flags
|
|
||||||
{
|
|
||||||
tracker = 0x1,
|
|
||||||
dht = 0x2,
|
|
||||||
pex = 0x4,
|
|
||||||
lsd = 0x8
|
|
||||||
};
|
|
||||||
|
|
||||||
int source;
|
|
||||||
|
|
||||||
// bitmask representing socket state
|
|
||||||
enum bw_state { bw_idle = 0, bw_limit = 1, bw_network = 2, bw_disk = 4 };
|
|
||||||
|
|
||||||
char read_state;
|
|
||||||
char write_state;
|
|
||||||
|
|
||||||
asio::ip::tcp::endpoint ip;
|
|
||||||
int up_speed;
|
|
||||||
int down_speed;
|
|
||||||
int payload_up_speed;
|
|
||||||
int payload_down_speed;
|
|
||||||
size_type total_download;
|
|
||||||
size_type total_upload;
|
|
||||||
peer_id pid;
|
|
||||||
bitfield pieces;
|
|
||||||
int upload_limit;
|
|
||||||
int download_limit;
|
|
||||||
|
|
||||||
time_duration last_request;
|
|
||||||
time_duration last_active;
|
|
||||||
int request_timeout;
|
|
||||||
|
|
||||||
int send_buffer_size;
|
|
||||||
int used_send_buffer;
|
|
||||||
|
|
||||||
int receive_buffer_size;
|
|
||||||
int used_receive_buffer;
|
|
||||||
|
|
||||||
int num_hashfails;
|
|
||||||
|
|
||||||
char country[2];
|
|
||||||
|
|
||||||
std::string inet_as_name;
|
|
||||||
int inet_as;
|
|
||||||
|
|
||||||
size_type load_balancing;
|
|
||||||
|
|
||||||
int requests_in_buffer;
|
|
||||||
int download_queue_length;
|
|
||||||
int upload_queue_length;
|
|
||||||
|
|
||||||
int failcount;
|
|
||||||
|
|
||||||
int downloading_piece_index;
|
|
||||||
int downloading_block_index;
|
|
||||||
int downloading_progress;
|
|
||||||
int downloading_total;
|
|
||||||
|
|
||||||
std::string client;
|
|
||||||
|
|
||||||
enum
|
|
||||||
{
|
|
||||||
standard_bittorrent = 0,
|
|
||||||
web_seed = 1
|
|
||||||
};
|
|
||||||
int connection_type;
|
|
||||||
|
|
||||||
int remote_dl_rate;
|
|
||||||
|
|
||||||
int pending_disk_bytes;
|
|
||||||
|
|
||||||
int send_quota;
|
|
||||||
int receive_quota;
|
|
||||||
|
|
||||||
int rtt;
|
|
||||||
|
|
||||||
int num_pieces;
|
|
||||||
|
|
||||||
int download_rate_peak;
|
|
||||||
int upload_rate_peak;
|
|
||||||
|
|
||||||
float progress;
|
|
||||||
int progress_ppm;
|
|
||||||
|
|
||||||
tcp::endpoint local_endpoint;
|
|
||||||
};
|
|
||||||
|
|
||||||
|
|
||||||
feed_handle
|
|
||||||
===========
|
|
||||||
|
|
||||||
The ``feed_handle`` refers to a specific RSS feed which is watched by the session.
|
|
||||||
The ``feed_item`` struct is defined in ``<libtorrent/rss.hpp>``. It has the following
|
|
||||||
functions::
|
|
||||||
|
|
||||||
struct feed_handle
|
|
||||||
{
|
|
||||||
feed_handle();
|
|
||||||
void update_feed();
|
|
||||||
feed_status get_feed_status() const;
|
|
||||||
void set_settings(feed_settings const& s);
|
|
||||||
feed_settings settings() const;
|
|
||||||
};
|
|
||||||
|
|
||||||
update_feed()
|
|
||||||
-------------
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
void update_feed();
|
|
||||||
|
|
||||||
Forces an update/refresh of the feed. Regular updates of the feed is managed
|
|
||||||
by libtorrent, be careful to not call this too frequently since it may
|
|
||||||
overload the RSS server.
|
|
||||||
|
|
||||||
get_feed_status()
|
|
||||||
-----------------
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
feed_status get_feed_status() const;
|
|
||||||
|
|
||||||
Queries the RSS feed for information, including all the items in the feed.
|
|
||||||
The ``feed_status`` object has the following fields::
|
|
||||||
|
|
||||||
struct feed_status
|
|
||||||
{
|
|
||||||
std::string url;
|
|
||||||
std::string title;
|
|
||||||
std::string description;
|
|
||||||
time_t last_update;
|
|
||||||
int next_update;
|
|
||||||
bool updating;
|
|
||||||
std::vector<feed_item> items;
|
|
||||||
error_code error;
|
|
||||||
int ttl;
|
|
||||||
};
|
|
||||||
|
|
||||||
``url`` is the URL of the feed.
|
|
||||||
|
|
||||||
``title`` is the name of the feed (as specified by the feed itself). This
|
|
||||||
may be empty if we have not recevied a response from the RSS server yet,
|
|
||||||
or if the feed does not specify a title.
|
|
||||||
|
|
||||||
``description`` is the feed description (as specified by the feed itself).
|
|
||||||
This may be empty if we have not received a response from the RSS server
|
|
||||||
yet, or if the feed does not specify a description.
|
|
||||||
|
|
||||||
``last_update`` is the posix time of the last successful response from the feed.
|
|
||||||
|
|
||||||
``next_update`` is the number of seconds, from now, when the feed will be
|
|
||||||
updated again.
|
|
||||||
|
|
||||||
``updating`` is true if the feed is currently being updated (i.e. waiting for
|
|
||||||
DNS resolution, connecting to the server or waiting for the response to the
|
|
||||||
HTTP request, or receiving the response).
|
|
||||||
|
|
||||||
``items`` is a vector of all items that we have received from the feed. See
|
|
||||||
feed_item_ for more information.
|
|
||||||
|
|
||||||
``error`` is set to the appropriate error code if the feed encountered an
|
|
||||||
error.
|
|
||||||
|
|
||||||
``ttl`` is the current refresh time (in minutes). It's either the configured
|
|
||||||
default ttl, or the ttl specified by the feed.
|
|
||||||
|
|
||||||
|
|
||||||
set_settings() settings()
|
|
||||||
-------------------------
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
void set_settings(feed_settings const& s);
|
|
||||||
feed_settings settings() const;
|
|
||||||
|
|
||||||
Sets and gets settings for this feed. For more information on the
|
|
||||||
available settings, see `add_feed()`_.
|
|
||||||
|
|
||||||
feed_item
|
|
||||||
=========
|
|
||||||
|
|
||||||
The ``feed_item`` struct is defined in ``<libtorrent/rss.hpp>``.
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
struct feed_item
|
|
||||||
{
|
|
||||||
feed_item();
|
|
||||||
std::string url;
|
|
||||||
std::string uuid;
|
|
||||||
std::string title;
|
|
||||||
std::string description;
|
|
||||||
std::string comment;
|
|
||||||
std::string category;
|
|
||||||
size_type size;
|
|
||||||
torrent_handle handle;
|
|
||||||
sha1_hash info_hash;
|
|
||||||
};
|
|
||||||
|
|
||||||
``size`` is the total size of the content the torrent refers to, or -1
|
|
||||||
if no size was specified by the feed.
|
|
||||||
|
|
||||||
``handle`` is the handle to the torrent, if the session is already downloading
|
|
||||||
this torrent.
|
|
||||||
|
|
||||||
``info_hash`` is the info-hash of the torrent, or cleared (i.e. all zeroes) if
|
|
||||||
the feed does not specify the info-hash.
|
|
||||||
|
|
||||||
All the strings are self explanatory and may be empty if the feed does not specify
|
|
||||||
those fields.
|
|
||||||
|
|
||||||
session customization
|
session customization
|
||||||
=====================
|
=====================
|
||||||
|
|
||||||
|
|
@ -346,35 +104,6 @@ You have control over proxy and authorization settings and also the user-agent
|
||||||
that will be sent to the tracker. The user-agent will also be used to identify the
|
that will be sent to the tracker. The user-agent will also be used to identify the
|
||||||
client with other peers.
|
client with other peers.
|
||||||
|
|
||||||
presets
|
|
||||||
-------
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
session_settings min_memory_usage();
|
|
||||||
session_settings high_performance_seed();
|
|
||||||
|
|
||||||
``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.
|
|
||||||
|
|
||||||
``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.
|
|
||||||
|
|
||||||
|
|
||||||
session_settings
|
session_settings
|
||||||
----------------
|
----------------
|
||||||
|
|
||||||
|
|
@ -1539,112 +1268,6 @@ disabled by default. Enabling it makes the cache perform better at high throughp
|
||||||
It also makes the cache less likely and slower at returning memory back to the system
|
It also makes the cache less likely and slower at returning memory back to the system
|
||||||
once allocated.
|
once allocated.
|
||||||
|
|
||||||
big_number
|
|
||||||
==========
|
|
||||||
|
|
||||||
Both the ``peer_id`` and ``sha1_hash`` types are typedefs of the class
|
|
||||||
``big_number``. It represents 20 bytes of data. Its synopsis follows::
|
|
||||||
|
|
||||||
class big_number
|
|
||||||
{
|
|
||||||
public:
|
|
||||||
bool operator==(const big_number& n) const;
|
|
||||||
bool operator!=(const big_number& n) const;
|
|
||||||
bool operator<(const big_number& n) const;
|
|
||||||
|
|
||||||
const unsigned char* begin() const;
|
|
||||||
const unsigned char* end() const;
|
|
||||||
|
|
||||||
unsigned char* begin();
|
|
||||||
unsigned char* end();
|
|
||||||
};
|
|
||||||
|
|
||||||
The iterators gives you access to individual bytes.
|
|
||||||
|
|
||||||
UPnP and NAT-PMP
|
|
||||||
================
|
|
||||||
|
|
||||||
The ``upnp`` and ``natpmp`` classes contains the state for all UPnP and NAT-PMP mappings,
|
|
||||||
by default 1 or two mappings are made by libtorrent, one for the listen port and one
|
|
||||||
for the DHT port (UDP).
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
class upnp
|
|
||||||
{
|
|
||||||
public:
|
|
||||||
|
|
||||||
enum protocol_type { none = 0, udp = 1, tcp = 2 };
|
|
||||||
int add_mapping(protocol_type p, int external_port, int local_port);
|
|
||||||
void delete_mapping(int mapping_index);
|
|
||||||
|
|
||||||
void discover_device();
|
|
||||||
void close();
|
|
||||||
|
|
||||||
std::string router_model();
|
|
||||||
};
|
|
||||||
|
|
||||||
class natpmp
|
|
||||||
{
|
|
||||||
public:
|
|
||||||
|
|
||||||
enum protocol_type { none = 0, udp = 1, tcp = 2 };
|
|
||||||
int add_mapping(protocol_type p, int external_port, int local_port);
|
|
||||||
void delete_mapping(int mapping_index);
|
|
||||||
|
|
||||||
void close();
|
|
||||||
void rebind(address const& listen_interface);
|
|
||||||
};
|
|
||||||
|
|
||||||
``discover_device()``, ``close()`` and ``rebind()`` are for internal uses and should
|
|
||||||
not be called directly by clients.
|
|
||||||
|
|
||||||
add_mapping()
|
|
||||||
-------------
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
int add_mapping(protocol_type p, int external_port, int local_port);
|
|
||||||
|
|
||||||
Attempts to add a port mapping for the specified protocol. Valid protocols are
|
|
||||||
``upnp::tcp`` and ``upnp::udp`` for the UPnP class and ``natpmp::tcp`` and
|
|
||||||
``natpmp::udp`` for the NAT-PMP class.
|
|
||||||
|
|
||||||
``external_port`` is the port on the external address that will be mapped. This
|
|
||||||
is a hint, you are not guaranteed that this port will be available, and it may
|
|
||||||
end up being something else. In the portmap_alert_ notification, the actual
|
|
||||||
external port is reported.
|
|
||||||
|
|
||||||
``local_port`` is the port in the local machine that the mapping should forward
|
|
||||||
to.
|
|
||||||
|
|
||||||
The return value is an index that identifies this port mapping. This is used
|
|
||||||
to refer to mappings that fails or succeeds in the portmap_error_alert_ and
|
|
||||||
portmap_alert_ respectively. If The mapping fails immediately, the return value
|
|
||||||
is -1, which means failure. There will not be any error alert notification for
|
|
||||||
mappings that fail with a -1 return value.
|
|
||||||
|
|
||||||
delete_mapping()
|
|
||||||
----------------
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
void delete_mapping(int mapping_index);
|
|
||||||
|
|
||||||
This function removes a port mapping. ``mapping_index`` is the index that refers
|
|
||||||
to the mapping you want to remove, which was returned from `add_mapping()`_.
|
|
||||||
|
|
||||||
router_model()
|
|
||||||
--------------
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
std::string router_model();
|
|
||||||
|
|
||||||
This is only available for UPnP routers. If the model is advertized by
|
|
||||||
the router, it can be queried through this function.
|
|
||||||
|
|
||||||
|
|
||||||
torrent_added_alert
|
torrent_added_alert
|
||||||
-------------------
|
-------------------
|
||||||
|
|
||||||
|
|
@ -2954,55 +2577,6 @@ of the info-hash changing.
|
||||||
|
|
||||||
``old_ih`` and ``new_ih`` are the previous and new info-hash for the torrent, respectively.
|
``old_ih`` and ``new_ih`` are the previous and new info-hash for the torrent, respectively.
|
||||||
|
|
||||||
alert dispatcher
|
|
||||||
================
|
|
||||||
|
|
||||||
The ``handle_alert`` class is defined in ``<libtorrent/alert.hpp>``.
|
|
||||||
|
|
||||||
Examples usage::
|
|
||||||
|
|
||||||
struct my_handler
|
|
||||||
{
|
|
||||||
void operator()(portmap_error_alert const& a) const
|
|
||||||
{
|
|
||||||
std::cout << "Portmapper: " << a.msg << std::endl;
|
|
||||||
}
|
|
||||||
|
|
||||||
void operator()(tracker_warning_alert const& a) const
|
|
||||||
{
|
|
||||||
std::cout << "Tracker warning: " << a.msg << std::endl;
|
|
||||||
}
|
|
||||||
|
|
||||||
void operator()(torrent_finished_alert const& a) const
|
|
||||||
{
|
|
||||||
// write fast resume data
|
|
||||||
// ...
|
|
||||||
|
|
||||||
std::cout << a.handle.torrent_file()->name() << "completed"
|
|
||||||
<< std::endl;
|
|
||||||
}
|
|
||||||
};
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
std::auto_ptr<alert> a;
|
|
||||||
a = ses.pop_alert();
|
|
||||||
my_handler h;
|
|
||||||
while (a.get())
|
|
||||||
{
|
|
||||||
handle_alert<portmap_error_alert
|
|
||||||
, tracker_warning_alert
|
|
||||||
, torrent_finished_alert
|
|
||||||
>::handle_alert(h, a);
|
|
||||||
a = ses.pop_alert();
|
|
||||||
}
|
|
||||||
|
|
||||||
In this example 3 alert types are used. You can use any number of template
|
|
||||||
parameters to select between more types. If the number of types are more than
|
|
||||||
15, you can define ``TORRENT_MAX_ALERT_TYPES`` to a greater number before
|
|
||||||
including ``<libtorrent/alert.hpp>``.
|
|
||||||
|
|
||||||
|
|
||||||
exceptions
|
exceptions
|
||||||
==========
|
==========
|
||||||
|
|
||||||
|
|
@ -3810,8 +3384,9 @@ The benefits of this mode are:
|
||||||
compact allocation
|
compact allocation
|
||||||
------------------
|
------------------
|
||||||
|
|
||||||
Note that support for compact allocation is deprecated in libttorrent, and will
|
.. note::
|
||||||
be removed in future versions.
|
Note that support for compact allocation is deprecated in libttorrent, and will
|
||||||
|
be removed in future versions.
|
||||||
|
|
||||||
The compact allocation will only allocate as much storage as it needs to keep the
|
The compact allocation will only allocate as much storage as it needs to keep the
|
||||||
pieces downloaded so far. This means that pieces will be moved around to be placed
|
pieces downloaded so far. This means that pieces will be moved around to be placed
|
||||||
|
|
|
||||||
|
|
@ -58,78 +58,15 @@ POSSIBILITY OF SUCH DAMAGE.
|
||||||
//
|
//
|
||||||
// By default, only errors are reported. set_alert_mask() can be
|
// By default, only errors are reported. set_alert_mask() can be
|
||||||
// used to specify which kinds of events should be reported. The alert mask
|
// used to specify which kinds of events should be reported. The alert mask
|
||||||
// is a bitmask with the following bits:
|
// is comprised by bits from the category_t enum.
|
||||||
//
|
|
||||||
// +--------------------------------+---------------------------------------------------------------------+
|
|
||||||
// | ``error_notification`` | Enables alerts that report an error. This includes: |
|
|
||||||
// | | |
|
|
||||||
// | | * tracker errors |
|
|
||||||
// | | * tracker warnings |
|
|
||||||
// | | * file errors |
|
|
||||||
// | | * resume data failures |
|
|
||||||
// | | * web seed errors |
|
|
||||||
// | | * .torrent files errors |
|
|
||||||
// | | * listen socket errors |
|
|
||||||
// | | * port mapping errors |
|
|
||||||
// +--------------------------------+---------------------------------------------------------------------+
|
|
||||||
// | ``peer_notification`` | Enables alerts when peers send invalid requests, get banned or |
|
|
||||||
// | | snubbed. |
|
|
||||||
// +--------------------------------+---------------------------------------------------------------------+
|
|
||||||
// | ``port_mapping_notification`` | Enables alerts for port mapping events. For NAT-PMP and UPnP. |
|
|
||||||
// +--------------------------------+---------------------------------------------------------------------+
|
|
||||||
// | ``storage_notification`` | Enables alerts for events related to the storage. File errors and |
|
|
||||||
// | | synchronization events for moving the storage, renaming files etc. |
|
|
||||||
// +--------------------------------+---------------------------------------------------------------------+
|
|
||||||
// | ``tracker_notification`` | Enables all tracker events. Includes announcing to trackers, |
|
|
||||||
// | | receiving responses, warnings and errors. |
|
|
||||||
// +--------------------------------+---------------------------------------------------------------------+
|
|
||||||
// | ``debug_notification`` | Low level alerts for when peers are connected and disconnected. |
|
|
||||||
// +--------------------------------+---------------------------------------------------------------------+
|
|
||||||
// | ``status_notification`` | Enables alerts for when a torrent or the session changes state. |
|
|
||||||
// +--------------------------------+---------------------------------------------------------------------+
|
|
||||||
// | ``progress_notification`` | Alerts for when blocks are requested and completed. Also when |
|
|
||||||
// | | pieces are completed. |
|
|
||||||
// +--------------------------------+---------------------------------------------------------------------+
|
|
||||||
// | ``ip_block_notification`` | Alerts when a peer is blocked by the ip blocker or port blocker. |
|
|
||||||
// +--------------------------------+---------------------------------------------------------------------+
|
|
||||||
// | ``performance_warning`` | Alerts when some limit is reached that might limit the download |
|
|
||||||
// | | or upload rate. |
|
|
||||||
// +--------------------------------+---------------------------------------------------------------------+
|
|
||||||
// | ``stats_notification`` | If you enable these alerts, you will receive a stats_alert |
|
|
||||||
// | | approximately once every second, for every active torrent. |
|
|
||||||
// | | These alerts contain all statistics counters for the interval since |
|
|
||||||
// | | the lasts stats alert. |
|
|
||||||
// +--------------------------------+---------------------------------------------------------------------+
|
|
||||||
// | ``dht_notification`` | Alerts on events in the DHT node. For incoming searches or |
|
|
||||||
// | | bootstrapping being done etc. |
|
|
||||||
// +--------------------------------+---------------------------------------------------------------------+
|
|
||||||
// | ``rss_notification`` | Alerts on RSS related events, like feeds being updated, feed error |
|
|
||||||
// | | conditions and successful RSS feed updates. Enabling this categoty |
|
|
||||||
// | | will make you receive rss_alert alerts. |
|
|
||||||
// +--------------------------------+---------------------------------------------------------------------+
|
|
||||||
// | ``all_categories`` | The full bitmask, representing all available categories. |
|
|
||||||
// +--------------------------------+---------------------------------------------------------------------+
|
|
||||||
//
|
//
|
||||||
// Every alert belongs to one or more category. There is a small cost involved in posting alerts. Only
|
// Every alert belongs to one or more category. There is a small cost involved in posting alerts. Only
|
||||||
// alerts that belong to an enabled category are posted. Setting the alert bitmask to 0 will disable
|
// alerts that belong to an enabled category are posted. Setting the alert bitmask to 0 will disable
|
||||||
// all alerts
|
// all alerts (except those that are non-discardable).
|
||||||
//
|
//
|
||||||
// There's another alert base class that some alerts derive from, all the
|
// There are other alert base classes that some alerts derive from, all the
|
||||||
// alerts that are generated for a specific torrent are derived from::
|
// alerts that are generated for a specific torrent are derived from torrent_alert,
|
||||||
//
|
// and tracker events derive from tracker_alert.
|
||||||
// struct torrent_alert: alert
|
|
||||||
// {
|
|
||||||
// // ...
|
|
||||||
// torrent_handle handle;
|
|
||||||
// };
|
|
||||||
//
|
|
||||||
// There's also a base class for all alerts referring to tracker events::
|
|
||||||
//
|
|
||||||
// struct tracker_alert: torrent_alert
|
|
||||||
// {
|
|
||||||
// // ...
|
|
||||||
// std::string url;
|
|
||||||
// };
|
|
||||||
//
|
//
|
||||||
|
|
||||||
#ifdef _MSC_VER
|
#ifdef _MSC_VER
|
||||||
|
|
@ -161,20 +98,67 @@ namespace libtorrent {
|
||||||
|
|
||||||
enum category_t
|
enum category_t
|
||||||
{
|
{
|
||||||
|
// Enables alerts that report an error. This includes:
|
||||||
|
//
|
||||||
|
// * tracker errors
|
||||||
|
// * tracker warnings
|
||||||
|
// * file errors
|
||||||
|
// * resume data failures
|
||||||
|
// * web seed errors
|
||||||
|
// * .torrent files errors
|
||||||
|
// * listen socket errors
|
||||||
|
// * port mapping errors
|
||||||
error_notification = 0x1,
|
error_notification = 0x1,
|
||||||
|
|
||||||
|
// Enables alerts when peers send invalid requests, get banned or
|
||||||
|
// snubbed.
|
||||||
peer_notification = 0x2,
|
peer_notification = 0x2,
|
||||||
|
|
||||||
|
// Enables alerts for port mapping events. For NAT-PMP and UPnP.
|
||||||
port_mapping_notification = 0x4,
|
port_mapping_notification = 0x4,
|
||||||
|
|
||||||
|
// Enables alerts for events related to the storage. File errors and
|
||||||
|
// synchronization events for moving the storage, renaming files etc.
|
||||||
storage_notification = 0x8,
|
storage_notification = 0x8,
|
||||||
|
|
||||||
|
// Enables all tracker events. Includes announcing to trackers,
|
||||||
|
// receiving responses, warnings and errors.
|
||||||
tracker_notification = 0x10,
|
tracker_notification = 0x10,
|
||||||
|
|
||||||
|
// Low level alerts for when peers are connected and disconnected.
|
||||||
debug_notification = 0x20,
|
debug_notification = 0x20,
|
||||||
|
|
||||||
|
// Enables alerts for when a torrent or the session changes state.
|
||||||
status_notification = 0x40,
|
status_notification = 0x40,
|
||||||
|
|
||||||
|
// Alerts for when blocks are requested and completed. Also when
|
||||||
|
// pieces are completed.
|
||||||
progress_notification = 0x80,
|
progress_notification = 0x80,
|
||||||
|
|
||||||
|
// Alerts when a peer is blocked by the ip blocker or port blocker.
|
||||||
ip_block_notification = 0x100,
|
ip_block_notification = 0x100,
|
||||||
|
|
||||||
|
// Alerts when some limit is reached that might limit the download
|
||||||
|
// or upload rate.
|
||||||
performance_warning = 0x200,
|
performance_warning = 0x200,
|
||||||
|
|
||||||
|
// Alerts on events in the DHT node. For incoming searches or
|
||||||
|
// bootstrapping being done etc.
|
||||||
dht_notification = 0x400,
|
dht_notification = 0x400,
|
||||||
|
|
||||||
|
// If you enable these alerts, you will receive a stats_alert
|
||||||
|
// approximately once every second, for every active torrent.
|
||||||
|
// These alerts contain all statistics counters for the interval since
|
||||||
|
// the lasts stats alert.
|
||||||
stats_notification = 0x800,
|
stats_notification = 0x800,
|
||||||
|
|
||||||
|
// Alerts on RSS related events, like feeds being updated, feed error
|
||||||
|
// conditions and successful RSS feed updates. Enabling this categoty
|
||||||
|
// will make you receive rss_alert alerts.
|
||||||
rss_notification = 0x1000,
|
rss_notification = 0x1000,
|
||||||
|
|
||||||
|
// The full bitmask, representing all available categories.
|
||||||
|
//
|
||||||
// since the enum is signed, make sure this isn't
|
// since the enum is signed, make sure this isn't
|
||||||
// interpreted as -1. For instance, boost.python
|
// interpreted as -1. For instance, boost.python
|
||||||
// does that and fails when assigning it to an
|
// does that and fails when assigning it to an
|
||||||
|
|
@ -251,6 +235,7 @@ namespace libtorrent {
|
||||||
unhandled_alert() {}
|
unhandled_alert() {}
|
||||||
};
|
};
|
||||||
|
|
||||||
|
#ifndef TORRENT_NO_DEPRECATE
|
||||||
#ifndef BOOST_NO_TYPEID
|
#ifndef BOOST_NO_TYPEID
|
||||||
|
|
||||||
namespace detail {
|
namespace detail {
|
||||||
|
|
@ -302,12 +287,10 @@ namespace libtorrent {
|
||||||
};
|
};
|
||||||
|
|
||||||
#endif // BOOST_NO_TYPEID
|
#endif // BOOST_NO_TYPEID
|
||||||
|
#endif // TORRENT_NO_DEPRECATE
|
||||||
|
|
||||||
// When you get an alert, you can use ``alert_cast<>`` to attempt to cast the pointer to a
|
// When you get an alert, you can use ``alert_cast<>`` to attempt to cast the pointer to a
|
||||||
// more specific alert type, in order to query it for more information.
|
// more specific alert type, in order to query it for more information.
|
||||||
//
|
|
||||||
// You can also use a `alert dispatcher`_ mechanism that's available in libtorrent.
|
|
||||||
|
|
||||||
template <class T>
|
template <class T>
|
||||||
T* alert_cast(alert* a)
|
T* alert_cast(alert* a)
|
||||||
{
|
{
|
||||||
|
|
|
||||||
|
|
@ -45,18 +45,33 @@ namespace libtorrent
|
||||||
namespace aux
|
namespace aux
|
||||||
{ struct session_impl; }
|
{ struct session_impl; }
|
||||||
|
|
||||||
|
// represents one item from an RSS feed. Specifically
|
||||||
|
// a feed of torrents.
|
||||||
|
//
|
||||||
struct TORRENT_EXPORT feed_item
|
struct TORRENT_EXPORT feed_item
|
||||||
{
|
{
|
||||||
feed_item();
|
feed_item();
|
||||||
~feed_item();
|
~feed_item();
|
||||||
|
|
||||||
|
// these are self explanatory and may be empty if the feed does not specify
|
||||||
|
// those fields.
|
||||||
std::string url;
|
std::string url;
|
||||||
std::string uuid;
|
std::string uuid;
|
||||||
std::string title;
|
std::string title;
|
||||||
std::string description;
|
std::string description;
|
||||||
std::string comment;
|
std::string comment;
|
||||||
std::string category;
|
std::string category;
|
||||||
|
|
||||||
|
// the total size of the content the torrent refers to, or -1
|
||||||
|
// if no size was specified by the feed.
|
||||||
size_type size;
|
size_type size;
|
||||||
|
|
||||||
|
// the handle to the torrent, if the session is already downloading
|
||||||
|
// this torrent.
|
||||||
torrent_handle handle;
|
torrent_handle handle;
|
||||||
|
|
||||||
|
// the info-hash of the torrent, or cleared (i.e. all zeroes) if
|
||||||
|
// the feed does not specify the info-hash.
|
||||||
sha1_hash info_hash;
|
sha1_hash info_hash;
|
||||||
};
|
};
|
||||||
|
|
||||||
|
|
@ -114,28 +129,69 @@ namespace libtorrent
|
||||||
add_torrent_params add_args;
|
add_torrent_params add_args;
|
||||||
};
|
};
|
||||||
|
|
||||||
|
// holds information about the status of an RSS feed. Retrieved by
|
||||||
|
// calling get_feed_status() on feed_handle.
|
||||||
struct TORRENT_EXPORT feed_status
|
struct TORRENT_EXPORT feed_status
|
||||||
{
|
{
|
||||||
feed_status(): last_update(0), next_update(0)
|
feed_status(): last_update(0), next_update(0)
|
||||||
, updating(false), ttl(0) {}
|
, updating(false), ttl(0) {}
|
||||||
|
|
||||||
|
// the URL of the feed.
|
||||||
std::string url;
|
std::string url;
|
||||||
|
|
||||||
|
// the name of the feed (as specified by the feed itself). This
|
||||||
|
// may be empty if we have not recevied a response from the RSS server yet,
|
||||||
|
// or if the feed does not specify a title.
|
||||||
std::string title;
|
std::string title;
|
||||||
|
|
||||||
|
// the feed description (as specified by the feed itself).
|
||||||
|
// This may be empty if we have not received a response from the RSS server
|
||||||
|
// yet, or if the feed does not specify a description.
|
||||||
std::string description;
|
std::string description;
|
||||||
|
|
||||||
|
// the posix time of the last successful response from the feed.
|
||||||
time_t last_update;
|
time_t last_update;
|
||||||
|
|
||||||
|
// the number of seconds, from now, when the feed will be
|
||||||
|
// updated again.
|
||||||
int next_update;
|
int next_update;
|
||||||
|
|
||||||
|
// true if the feed is currently being updated (i.e. waiting for
|
||||||
|
// DNS resolution, connecting to the server or waiting for the response to the
|
||||||
|
// HTTP request, or receiving the response).
|
||||||
bool updating;
|
bool updating;
|
||||||
|
|
||||||
|
// a vector of all items that we have received from the feed. See
|
||||||
|
// feed_item for more information.
|
||||||
std::vector<feed_item> items;
|
std::vector<feed_item> items;
|
||||||
|
|
||||||
|
// set to the appropriate error code if the feed encountered an
|
||||||
|
// error. See error_code for more info.
|
||||||
error_code error;
|
error_code error;
|
||||||
|
|
||||||
|
// the current refresh time (in minutes). It's either the configured
|
||||||
|
// default ttl, or the ttl specified by the feed.
|
||||||
int ttl;
|
int ttl;
|
||||||
};
|
};
|
||||||
|
|
||||||
struct feed;
|
struct feed;
|
||||||
|
|
||||||
|
// The ``feed_handle`` refers to a specific RSS feed that is watched by the session.
|
||||||
struct TORRENT_EXPORT feed_handle
|
struct TORRENT_EXPORT feed_handle
|
||||||
{
|
{
|
||||||
feed_handle() {}
|
feed_handle() {}
|
||||||
|
|
||||||
|
// Forces an update/refresh of the feed. Regular updates of the feed is managed
|
||||||
|
// by libtorrent, be careful to not call this too frequently since it may
|
||||||
|
// overload the RSS server.
|
||||||
void update_feed();
|
void update_feed();
|
||||||
|
|
||||||
|
// Queries the RSS feed for information, including all the items in the feed.
|
||||||
|
// see feed_status.
|
||||||
feed_status get_feed_status() const;
|
feed_status get_feed_status() const;
|
||||||
|
|
||||||
|
// Sets and gets settings for this feed. For more information on the
|
||||||
|
// available settings, see add_feed().
|
||||||
void set_settings(feed_settings const& s);
|
void set_settings(feed_settings const& s);
|
||||||
feed_settings settings() const;
|
feed_settings settings() const;
|
||||||
private:
|
private:
|
||||||
|
|
|
||||||
|
|
@ -82,6 +82,25 @@ namespace libtorrent
|
||||||
class connection_queue;
|
class connection_queue;
|
||||||
class alert;
|
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.
|
||||||
|
//
|
||||||
|
// ``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.
|
||||||
|
//
|
||||||
|
// ``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 min_memory_usage();
|
||||||
TORRENT_EXPORT session_settings high_performance_seed();
|
TORRENT_EXPORT session_settings high_performance_seed();
|
||||||
|
|
||||||
|
|
@ -498,8 +517,6 @@ namespace libtorrent
|
||||||
// ``as_for_ip`` returns the AS number for the IP address specified. If the IP is not
|
// ``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.
|
// 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 ASN database`: http://www.maxmind.com/app/asnum
|
||||||
// .. _`MaxMind GeoIP database`: http://www.maxmind.com/app/geolitecountry
|
// .. _`MaxMind GeoIP database`: http://www.maxmind.com/app/geolitecountry
|
||||||
#ifndef TORRENT_DISABLE_GEO_IP
|
#ifndef TORRENT_DISABLE_GEO_IP
|
||||||
|
|
|
||||||
|
|
@ -118,8 +118,8 @@ namespace libtorrent
|
||||||
typedef boost::function<void(int, address, int, error_code const&)> portmap_callback_t;
|
typedef boost::function<void(int, address, int, error_code const&)> portmap_callback_t;
|
||||||
typedef boost::function<void(char const*)> log_callback_t;
|
typedef boost::function<void(char const*)> log_callback_t;
|
||||||
|
|
||||||
// TODO: 2 make this a shared_ptr instead
|
|
||||||
class TORRENT_EXTRA_EXPORT upnp : public intrusive_ptr_base<upnp>
|
class TORRENT_EXTRA_EXPORT upnp : public intrusive_ptr_base<upnp>
|
||||||
|
// TODO: 2 make this a shared_ptr instead
|
||||||
{
|
{
|
||||||
public:
|
public:
|
||||||
upnp(io_service& ios, connection_queue& cc
|
upnp(io_service& ios, connection_queue& cc
|
||||||
|
|
@ -131,13 +131,37 @@ public:
|
||||||
void* drain_state();
|
void* drain_state();
|
||||||
|
|
||||||
enum protocol_type { none = 0, udp = 1, tcp = 2 };
|
enum protocol_type { none = 0, udp = 1, tcp = 2 };
|
||||||
|
|
||||||
|
// Attempts to add a port mapping for the specified protocol. Valid protocols are
|
||||||
|
// ``upnp::tcp`` and ``upnp::udp`` for the UPnP class and ``natpmp::tcp`` and
|
||||||
|
// ``natpmp::udp`` for the NAT-PMP class.
|
||||||
|
//
|
||||||
|
// ``external_port`` is the port on the external address that will be mapped. This
|
||||||
|
// is a hint, you are not guaranteed that this port will be available, and it may
|
||||||
|
// end up being something else. In the portmap_alert_ notification, the actual
|
||||||
|
// external port is reported.
|
||||||
|
//
|
||||||
|
// ``local_port`` is the port in the local machine that the mapping should forward
|
||||||
|
// to.
|
||||||
|
//
|
||||||
|
// The return value is an index that identifies this port mapping. This is used
|
||||||
|
// to refer to mappings that fails or succeeds in the portmap_error_alert_ and
|
||||||
|
// portmap_alert_ respectively. If The mapping fails immediately, the return value
|
||||||
|
// is -1, which means failure. There will not be any error alert notification for
|
||||||
|
// mappings that fail with a -1 return value.
|
||||||
int add_mapping(protocol_type p, int external_port, int local_port);
|
int add_mapping(protocol_type p, int external_port, int local_port);
|
||||||
|
|
||||||
|
// This function removes a port mapping. ``mapping_index`` is the index that refers
|
||||||
|
// to the mapping you want to remove, which was returned from add_mapping().
|
||||||
void delete_mapping(int mapping_index);
|
void delete_mapping(int mapping_index);
|
||||||
|
|
||||||
bool get_mapping(int mapping_index, int& local_port, int& external_port, int& protocol) const;
|
bool get_mapping(int mapping_index, int& local_port, int& external_port, int& protocol) const;
|
||||||
|
|
||||||
void discover_device();
|
void discover_device();
|
||||||
void close();
|
void close();
|
||||||
|
|
||||||
|
// This is only available for UPnP routers. If the model is advertized by
|
||||||
|
// the router, it can be queried through this function.
|
||||||
std::string router_model()
|
std::string router_model()
|
||||||
{
|
{
|
||||||
mutex::scoped_lock l(m_mutex);
|
mutex::scoped_lock l(m_mutex);
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue