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

move more documentation into headers

This commit is contained in:
Arvid Norberg 2013-08-08 01:03:54 +00:00
parent 4c0caa4ba1
commit 28cdc639fa
12 changed files with 367 additions and 756 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

725
docs/manual.rst
View File

@ -1539,241 +1539,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.
pe_settings
===========
The ``pe_settings`` structure is used to control the settings related
to peer protocol encryption::
struct pe_settings
{
pe_settings();
enum enc_policy
{
forced,
enabled,
disabled
};
enum enc_level
{
plaintext,
rc4,
both
};
enc_policy out_enc_policy;
enc_policy in_enc_policy;
enc_level allowed_enc_level;
bool prefer_rc4;
};
``in_enc_policy`` and ``out_enc_policy`` control the settings for incoming
and outgoing connections respectively. The settings for these are:
* ``forced`` - Only encrypted connections are allowed. Incoming connections
that are not encrypted are closed and if the encrypted outgoing connection
fails, a non-encrypted retry will not be made.
* ``enabled`` - encrypted connections are enabled, but non-encrypted
connections are allowed. An incoming non-encrypted connection will
be accepted, and if an outgoing encrypted connection fails, a non-
encrypted connection will be tried.
* ``disabled`` - only non-encrypted connections are allowed.
``allowed_enc_level`` determines the encryption level of the
connections. This setting will adjust which encryption scheme is
offered to the other peer, as well as which encryption scheme is
selected by the client. The settings are:
* ``plaintext`` - only the handshake is encrypted, the bulk of the traffic
remains unchanged.
* ``rc4`` - the entire stream is encrypted with RC4
* ``both`` - both RC4 and plaintext connections are allowed.
``prefer_rc4`` can be set to true if you want to prefer the RC4 encrypted stream.
proxy_settings
==============
The ``proxy_settings`` structs contains the information needed to
direct certain traffic to a proxy.
::
struct proxy_settings
{
proxy_settings();
std::string hostname;
int port;
std::string username;
std::string password;
enum proxy_type
{
none,
socks4,
socks5,
socks5_pw,
http,
http_pw
};
proxy_type type;
bool proxy_hostnames;
bool proxy_peer_connections;
};
``hostname`` is the name or IP of the proxy server. ``port`` is the
port number the proxy listens to. If required, ``username`` and ``password``
can be set to authenticate with the proxy.
The ``type`` tells libtorrent what kind of proxy server it is. The following
options are available:
* ``none`` - This is the default, no proxy server is used, all other fields
are ignored.
* ``socks4`` - The server is assumed to be a `SOCKS4 server`_ that
requires a username.
* ``socks5`` - The server is assumed to be a SOCKS5 server (`RFC 1928`_) that
does not require any authentication. The username and password are ignored.
* ``socks5_pw`` - The server is assumed to be a SOCKS5 server that supports
plain text username and password authentication (`RFC 1929`_). The username
and password specified may be sent to the proxy if it requires.
* ``http`` - The server is assumed to be an HTTP proxy. If the transport used
for the connection is non-HTTP, the server is assumed to support the
CONNECT_ method. i.e. for web seeds and HTTP trackers, a plain proxy will
suffice. The proxy is assumed to not require authorization. The username
and password will not be used.
* ``http_pw`` - The server is assumed to be an HTTP proxy that requires
user authorization. The username and password will be sent to the proxy.
.. _`SOCKS4 server`: http://www.ufasoft.com/doc/socks4_protocol.htm
.. _`RFC 1928`: http://www.faqs.org/rfcs/rfc1928.html
.. _`RFC 1929`: http://www.faqs.org/rfcs/rfc1929.html
.. _CONNECT: draft-luotonen-web-proxy-tunneling-01.txt
``proxy_hostnames`` defaults to true. It means that hostnames should be
attempted to be resolved through the proxy instead of using the local DNS
service. This is only supported by SOCKS5 and HTTP.
``proxy_peer_connections`` determines whether or not to excempt peer and
web seed connections from using the proxy. This defaults to true, i.e. peer
connections are proxied by default.
ip_filter
=========
The ``ip_filter`` class is a set of rules that uniquely categorizes all
ip addresses as allowed or disallowed. The default constructor creates
a single rule that allows all addresses (0.0.0.0 - 255.255.255.255 for
the IPv4 range, and the equivalent range covering all addresses for the
IPv6 range).
::
template <class Addr>
struct ip_range
{
Addr first;
Addr last;
int flags;
};
class ip_filter
{
public:
enum access_flags { blocked = 1 };
ip_filter();
void add_rule(address first, address last, int flags);
int access(address const& addr) const;
typedef boost::tuple<std::vector<ip_range<address_v4> >
, std::vector<ip_range<address_v6> > > filter_tuple_t;
filter_tuple_t export_filter() const;
};
ip_filter()
-----------
::
ip_filter()
Creates a default filter that doesn't filter any address.
postcondition:
``access(x) == 0`` for every ``x``
add_rule()
----------
::
void add_rule(address first, address last, int flags);
Adds a rule to the filter. ``first`` and ``last`` defines a range of
ip addresses that will be marked with the given flags. The ``flags``
can currently be 0, which means allowed, or ``ip_filter::blocked``, which
means disallowed.
precondition:
``first.is_v4() == last.is_v4() && first.is_v6() == last.is_v6()``
postcondition:
``access(x) == flags`` for every ``x`` in the range [``first``, ``last``]
This means that in a case of overlapping ranges, the last one applied takes
precedence.
access()
--------
::
int access(address const& addr) const;
Returns the access permissions for the given address (``addr``). The permission
can currently be 0 or ``ip_filter::blocked``. The complexity of this operation
is O(``log`` n), where n is the minimum number of non-overlapping ranges to describe
the current filter.
export_filter()
---------------
::
boost::tuple<std::vector<ip_range<address_v4> >
, std::vector<ip_range<address_v6> > > export_filter() const;
This function will return the current state of the filter in the minimum number of
ranges possible. They are sorted from ranges in low addresses to high addresses. Each
entry in the returned vector is a range with the access control specified in its
``flags`` field.
The return value is a tuple containing two range-lists. One for IPv4 addresses
and one for IPv6 addresses.
big_number big_number
========== ==========
@ -1796,144 +1561,6 @@ Both the ``peer_id`` and ``sha1_hash`` types are typedefs of the class
The iterators gives you access to individual bytes. The iterators gives you access to individual bytes.
bitfield
========
The bitfiled type stores any number of bits as a bitfield in an array.
::
class bitfield
{
bitfield();
bitfield(int bits);
bitfield(int bits, bool val);
bitfield(char const* bytes, int bits);
bitfield(bitfield const& rhs);
void borrow_bytes(char* bytes, int bits);
~bitfield();
void assign(char const* bytes, int bits);
bool operator[](int index) const;
bool get_bit(int index) const;
void clear_bit(int index);
void set_bit(int index);
std::size_t size() const;
bool empty() const;
char const* bytes() const;
bitfield& operator=(bitfield const& rhs);
int count() const;
typedef const_iterator;
const_iterator begin() const;
const_iterator end() const;
void resize(int bits, bool val);
void set_all();
void clear_all();
void resize(int bits);
};
hasher
======
This class creates sha1-hashes. Its declaration looks like this::
class hasher
{
public:
hasher();
hasher(char const* data, unsigned int len);
void update(char const* data, unsigned int len);
sha1_hash final();
void reset();
};
You use it by first instantiating it, then call ``update()`` to feed it
with data. i.e. you don't have to keep the entire buffer of which you want to
create the hash in memory. You can feed the hasher parts of it at a time. When
You have fed the hasher with all the data, you call ``final()`` and it
will return the sha1-hash of the data.
The constructor that takes a ``char const*`` and an integer will construct the
sha1 context and feed it the data passed in.
If you want to reuse the hasher object once you have created a hash, you have to
call ``reset()`` to reinitialize it.
The sha1-algorithm used was implemented by Steve Reid and released as public domain.
For more info, see ``src/sha1.cpp``.
fingerprint
===========
The fingerprint class represents information about a client and its version. It is used
to encode this information into the client's peer id.
This is the class declaration::
struct fingerprint
{
fingerprint(const char* id_string, int major, int minor
, int revision, int tag);
std::string to_string() const;
char name[2];
char major_version;
char minor_version;
char revision_version;
char tag_version;
};
The constructor takes a ``char const*`` that should point to a string constant containing
exactly two characters. These are the characters that should be unique for your client. Make
sure not to clash with anybody else. Here are some taken id's:
+----------+-----------------------+
| id chars | client |
+==========+=======================+
| 'AZ' | Azureus |
+----------+-----------------------+
| 'LT' | libtorrent (default) |
+----------+-----------------------+
| 'BX' | BittorrentX |
+----------+-----------------------+
| 'MT' | Moonlight Torrent |
+----------+-----------------------+
| 'TS' | Torrent Storm |
+----------+-----------------------+
| 'SS' | Swarm Scope |
+----------+-----------------------+
| 'XT' | Xan Torrent |
+----------+-----------------------+
There's currently an informal directory of client id's here__.
__ http://wiki.theory.org/BitTorrentSpecification#peer_id
The ``major``, ``minor``, ``revision`` and ``tag`` parameters are used to identify the
version of your client. All these numbers must be within the range [0, 9].
``to_string()`` will generate the actual string put in the peer-id, and return it.
UPnP and NAT-PMP UPnP and NAT-PMP
================ ================
@ -2018,358 +1645,6 @@ This is only available for UPnP routers. If the model is advertized by
the router, it can be queried through this function. the router, it can be queried through this function.
free functions
==============
identify_client()
-----------------
::
std::string identify_client(peer_id const& id);
This function is declared in the header ``<libtorrent/identify_client.hpp>``. It can can be used
to extract a string describing a client version from its peer-id. It will recognize most clients
that have this kind of identification in the peer-id.
client_fingerprint()
--------------------
::
boost::optional<fingerprint> client_fingerprint(peer_id const& p);
Returns an optional fingerprint if any can be identified from the peer id. This can be used
to automate the identification of clients. It will not be able to identify peers with non-
standard encodings. Only Azureus style, Shadow's style and Mainline style. This function is
declared in the header ``<libtorrent/identify_client.hpp>``.
lazy_bdecode()
--------------
::
int lazy_bdecode(char const* start, char const* end, lazy_entry& ret
, error_code& ec, int* error_pos = 0, int depth_limit = 1000
, int item_limit = 1000000);
This function decodes bencoded_ data.
.. _bencoded: http://wiki.theory.org/index.php/BitTorrentSpecification
Whenever possible, ``lazy_bdecode()`` should be preferred over ``bdecode()``.
It is more efficient and more secure. It supports having constraints on the
amount of memory is consumed by the parser.
*lazy* refers to the fact that it doesn't copy any actual data out of the
bencoded buffer. It builds a tree of ``lazy_entry`` which has pointers into
the bencoded buffer. This makes it very fast and efficient. On top of that,
it is not recursive, which saves a lot of stack space when parsing deeply
nested trees. However, in order to protect against potential attacks, the
``depth_limit`` and ``item_limit`` control how many levels deep the tree is
allowed to get. With recursive parser, a few thousand levels would be enough
to exhaust the threads stack and terminate the process. The ``item_limit``
protects against very large structures, not necessarily deep. Each bencoded
item in the structure causes the parser to allocate some amount of memory,
this memory is constant regardless of how much data actually is stored in
the item. One potential attack is to create a bencoded list of hundreds of
thousands empty strings, which would cause the parser to allocate a significant
amount of memory, perhaps more than is available on the machine, and effectively
provide a denial of service. The default item limit is set as a reasonable
upper limit for desktop computers. Very few torrents have more items in them.
The limit corresponds to about 25 MB, which might be a bit much for embedded
systems.
``start`` and ``end`` defines the bencoded buffer to be decoded. ``ret`` is
the ``lazy_entry`` which is filled in with the whole decoded tree. ``ec``
is a reference to an ``error_code`` which is set to describe the error encountered
in case the function fails. ``error_pos`` is an optional pointer to an int,
which will be set to the byte offset into the buffer where an error occurred,
in case the function fails.
bdecode() bencode()
--------------------
::
template<class InIt> entry bdecode(InIt start, InIt end);
template<class OutIt> void bencode(OutIt out, const entry& e);
These functions will encode data to bencoded_ or decode bencoded_ data.
If possible, `lazy_bdecode()`_ should be preferred over ``bdecode()``.
The entry_ class is the internal representation of the bencoded data
and it can be used to retrieve information, an entry_ can also be build by
the program and given to ``bencode()`` to encode it into the ``OutIt``
iterator.
The ``OutIt`` and ``InIt`` are iterators
(InputIterator_ and OutputIterator_ respectively). They
are templates and are usually instantiated as ostream_iterator_,
back_insert_iterator_ or istream_iterator_. These
functions will assume that the iterator refers to a character
(``char``). So, if you want to encode entry ``e`` into a buffer
in memory, you can do it like this::
std::vector<char> buffer;
bencode(std::back_inserter(buf), e);
.. _InputIterator: http://www.sgi.com/tech/stl/InputIterator.html
.. _OutputIterator: http://www.sgi.com/tech/stl/OutputIterator.html
.. _ostream_iterator: http://www.sgi.com/tech/stl/ostream_iterator.html
.. _back_insert_iterator: http://www.sgi.com/tech/stl/back_insert_iterator.html
.. _istream_iterator: http://www.sgi.com/tech/stl/istream_iterator.html
If you want to decode a torrent file from a buffer in memory, you can do it like this::
std::vector<char> buffer;
// ...
entry e = bdecode(buf.begin(), buf.end());
Or, if you have a raw char buffer::
const char* buf;
// ...
entry e = bdecode(buf, buf + data_size);
Now we just need to know how to retrieve information from the entry_.
If ``bdecode()`` encounters invalid encoded data in the range given to it
it will throw libtorrent_exception_.
add_magnet_uri()
----------------
*deprecated*
::
torrent_handle add_magnet_uri(session& ses, std::string const& uri
add_torrent_params p);
torrent_handle add_magnet_uri(session& ses, std::string const& uri
add_torrent_params p, error_code& ec);
This function parses the magnet URI (``uri``) as a bittorrent magnet link,
and adds the torrent to the specified session (``ses``). It returns the
handle to the newly added torrent, or an invalid handle in case parsing
failed. To control some initial settings of the torrent, sepcify those in
the ``add_torrent_params``, ``p``. See `async_add_torrent() add_torrent()`_.
The overload that does not take an ``error_code`` throws an exception on
error and is not available when building without exception support.
A simpler way to add a magnet link to a session is to pass in the
link through ``add_torrent_params::url`` argument to ``session::add_torrent()``.
For more information about magnet links, see `magnet links`_.
parse_magnet_uri()
------------------
::
void parse_magnet_uri(std::string const& uri, add_torrent_params& p, error_code& ec);
This function parses out information from the magnet link and populates the
``add_torrent_params`` object.
make_magnet_uri()
-----------------
::
std::string make_magnet_uri(torrent_handle const& handle);
Generates a magnet URI from the specified torrent. If the torrent
handle is invalid, an empty string is returned.
For more information about magnet links, see `magnet links`_.
alerts
======
The ``pop_alert()`` function on session is the interface for retrieving
alerts, warnings, messages and errors from libtorrent. If no alerts have
been posted by libtorrent ``pop_alert()`` will return a default initialized
``auto_ptr`` object. If there is an alert in libtorrent's queue, the alert
from the front of the queue is popped and returned.
You can then use the alert object and query
By default, only errors are reported. `set_alert_mask()`_ can be
used to specify which kinds of events should be reported. The alert mask
is a bitmask with the following bits:
+--------------------------------+---------------------------------------------------------------------+
| ``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
alerts that belong to an enabled category are posted. Setting the alert bitmask to 0 will disable
all alerts
When you get an alert, you can use ``alert_cast<>`` to attempt to cast the pointer to a
more specific alert type, to be queried for more information about the alert. ``alert_cast``
has the followinf signature::
template <T> T* alert_cast(alert* a);
template <T> T const* alert_cast(alert const* a);
You can also use a `alert dispatcher`_ mechanism that's available in libtorrent.
All alert types are defined in the ``<libtorrent/alert_types.hpp>`` header file.
The ``alert`` class is the base class that specific messages are derived from. This
is its synopsis:
.. parsed-literal::
class alert
{
public:
enum category_t
{
error_notification = *implementation defined*,
peer_notification = *implementation defined*,
port_mapping_notification = *implementation defined*,
storage_notification = *implementation defined*,
tracker_notification = *implementation defined*,
debug_notification = *implementation defined*,
status_notification = *implementation defined*,
progress_notification = *implementation defined*,
ip_block_notification = *implementation defined*,
performance_warning = *implementation defined*,
dht_notification = *implementation defined*,
stats_notification = *implementation defined*,
rss_notification = *implementation defined*,
all_categories = *implementation defined*
};
ptime timestamp() const;
virtual ~alert();
virtual int type() const = 0;
virtual std::string message() const = 0;
virtual char const* what() const = 0;
virtual int category() const = 0;
virtual bool discardable() const;
virtual std::auto_ptr<alert> clone() const = 0;
};
``type()`` returns an integer that is unique to this alert type. It can be
compared against a specific alert by querying a static constant called ``alert_type``
in the alert. It can be used to determine the run-time type of an alert* in
order to cast to that alert type and access specific members.
e.g::
std::auto_ptr<alert> a = ses.pop_alert();
switch (a->type())
{
case read_piece_alert::alert_type:
{
read_piece_alert* p = (read_piece_alert*)a.get();
if (p->ec) {
// read_piece failed
break;
}
// use p
break;
}
case file_renamed_alert::alert_type:
{
// etc...
}
}
``what()`` returns a string literal describing the type of the alert. It does
not include any information that might be bundled with the alert.
``category()`` returns a bitmask specifying which categories this alert belong to.
``clone()`` returns a pointer to a copy of the alert.
``discardable()`` determines whether or not an alert is allowed to be discarded
when the alert queue is full. There are a few alerts which may not be discared,
since they would break the user contract, such as ``save_resume_data_alert``.
``message()`` generate a string describing the alert and the information bundled
with it. This is mainly intended for debug and development use. It is not suitable
to use this for applications that may be localized. Instead, handle each alert
type individually and extract and render the information from the alert depending
on the locale.
There's another alert base class that most alerts derives from, all the
alerts that are generated for a specific torrent are derived from::
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;
};
The specific alerts are:
torrent_added_alert torrent_added_alert
------------------- -------------------

133
include/libtorrent/alert.hpp
View File

@ -47,6 +47,91 @@ POSSIBILITY OF SUCH DAMAGE.
#include <boost/preprocessor/repetition/enum_shifted_params.hpp> #include <boost/preprocessor/repetition/enum_shifted_params.hpp>
#include <boost/preprocessor/repetition/enum_shifted_binary_params.hpp> #include <boost/preprocessor/repetition/enum_shifted_binary_params.hpp>
// OVERVIEW
//
// The pop_alert() function on session is the interface for retrieving
// alerts, warnings, messages and errors from libtorrent. If no alerts have
// been posted by libtorrent pop_alert() will return a default initialized
// ``std::auto_ptr`` object. If there is an alert in libtorrent's queue, the alert
// from the front of the queue is popped and returned.
// You can then use the alert object and query
//
// By default, only errors are reported. set_alert_mask() can be
// used to specify which kinds of events should be reported. The alert mask
// is a bitmask with the following bits:
//
// +--------------------------------+---------------------------------------------------------------------+
// | ``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
// alerts that belong to an enabled category are posted. Setting the alert bitmask to 0 will disable
// all alerts
//
// There's another alert base class that some alerts derive from, all the
// alerts that are generated for a specific torrent are derived from::
//
// 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
#pragma warning(pop) #pragma warning(pop)
#endif #endif
@ -64,6 +149,7 @@ POSSIBILITY OF SUCH DAMAGE.
namespace libtorrent { namespace libtorrent {
// The ``alert`` class is the base class that specific messages are derived from.
class TORRENT_EXPORT alert class TORRENT_EXPORT alert
{ {
public: public:
@ -102,10 +188,50 @@ namespace libtorrent {
// a timestamp is automatically created in the constructor // a timestamp is automatically created in the constructor
ptime timestamp() const; ptime timestamp() const;
// returns an integer that is unique to this alert type. It can be
// compared against a specific alert by querying a static constant called ``alert_type``
// in the alert. It can be used to determine the run-time type of an alert* in
// order to cast to that alert type and access specific members.
//
// e.g::
//
// std::auto_ptr<alert> a = ses.pop_alert();
// switch (a->type())
// {
// case read_piece_alert::alert_type:
// {
// read_piece_alert* p = (read_piece_alert*)a.get();
// if (p->ec) {
// // read_piece failed
// break;
// }
// // use p
// break;
// }
// case file_renamed_alert::alert_type:
// {
// // etc...
// }
// }
virtual int type() const = 0; virtual int type() const = 0;
// returns a string literal describing the type of the alert. It does
// not include any information that might be bundled with the alert.
virtual char const* what() const = 0; virtual char const* what() const = 0;
// generate a string describing the alert and the information bundled
// with it. This is mainly intended for debug and development use. It is not suitable
// to use this for applications that may be localized. Instead, handle each alert
// type individually and extract and render the information from the alert depending
// on the locale.
virtual std::string message() const = 0; virtual std::string message() const = 0;
// returns a bitmask specifying which categories this alert belong to.
virtual int category() const = 0; virtual int category() const = 0;
// determines whether or not an alert is allowed to be discarded
// when the alert queue is full. There are a few alerts which may not be discared,
// since they would break the user contract, such as save_resume_data_alert.
virtual bool discardable() const { return true; } virtual bool discardable() const { return true; }
#ifndef TORRENT_NO_DEPRECATE #ifndef TORRENT_NO_DEPRECATE
@ -113,6 +239,7 @@ namespace libtorrent {
severity_t severity() const TORRENT_DEPRECATED { return warning; } severity_t severity() const TORRENT_DEPRECATED { return warning; }
#endif #endif
// returns a pointer to a copy of the alert.
virtual std::auto_ptr<alert> clone() const = 0; virtual std::auto_ptr<alert> clone() const = 0;
private: private:
@ -176,6 +303,11 @@ namespace libtorrent {
#endif // BOOST_NO_TYPEID #endif // BOOST_NO_TYPEID
// 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.
//
// 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)
{ {
@ -183,7 +315,6 @@ T* alert_cast(alert* a)
if (a->type() == T::alert_type) return static_cast<T*>(a); if (a->type() == T::alert_type) return static_cast<T*>(a);
return 0; return 0;
} }
template <class T> template <class T>
T const* alert_cast(alert const* a) T const* alert_cast(alert const* a)
{ {

45
include/libtorrent/bencode.hpp
View File

@ -169,7 +169,6 @@ namespace libtorrent
} }
} }
// returns the number of bytes written
template<class OutIt> template<class OutIt>
int bencode_recursive(OutIt& out, const entry& e) int bencode_recursive(OutIt& out, const entry& e)
{ {
@ -379,12 +378,53 @@ namespace libtorrent
} }
} }
// These functions will encode data to bencoded_ or decode bencoded_ data.
//
// If possible, lazy_bdecode() should be preferred over ``bdecode()``.
//
// The entry_ class is the internal representation of the bencoded data
// and it can be used to retrieve information, an entry_ can also be build by
// the program and given to ``bencode()`` to encode it into the ``OutIt``
// iterator.
//
// The ``OutIt`` and ``InIt`` are iterators
// (InputIterator_ and OutputIterator_ respectively). They
// are templates and are usually instantiated as ostream_iterator_,
// back_insert_iterator_ or istream_iterator_. These
// functions will assume that the iterator refers to a character
// (``char``). So, if you want to encode entry ``e`` into a buffer
// in memory, you can do it like this::
//
// std::vector<char> buffer;
// bencode(std::back_inserter(buf), e);
//
// .. _InputIterator: http://www.sgi.com/tech/stl/InputIterator.html
// .. _OutputIterator: http://www.sgi.com/tech/stl/OutputIterator.html
// .. _ostream_iterator: http://www.sgi.com/tech/stl/ostream_iterator.html
// .. _back_insert_iterator: http://www.sgi.com/tech/stl/back_insert_iterator.html
// .. _istream_iterator: http://www.sgi.com/tech/stl/istream_iterator.html
//
// If you want to decode a torrent file from a buffer in memory, you can do it like this::
//
// std::vector<char> buffer;
// // ...
// entry e = bdecode(buf.begin(), buf.end());
//
// Or, if you have a raw char buffer::
//
// const char* buf;
// ...
// entry e = bdecode(buf, buf + data_size);
//
// Now we just need to know how to retrieve information from the entry.
//
// If ``bdecode()`` encounters invalid encoded data in the range given to it
// it will throw libtorrent_exception.
template<class OutIt> template<class OutIt>
int bencode(OutIt out, const entry& e) int bencode(OutIt out, const entry& e)
{ {
return detail::bencode_recursive(out, e); return detail::bencode_recursive(out, e);
} }
template<class InIt> template<class InIt>
entry bdecode(InIt start, InIt end) entry bdecode(InIt start, InIt end)
{ {
@ -397,7 +437,6 @@ namespace libtorrent
if (err) return entry(); if (err) return entry();
return e; return e;
} }
template<class InIt> template<class InIt>
entry bdecode(InIt start, InIt end, int& len) entry bdecode(InIt start, InIt end, int& len)
{ {

1
include/libtorrent/bitfield.hpp
View File

@ -41,6 +41,7 @@ POSSIBILITY OF SUCH DAMAGE.
namespace libtorrent namespace libtorrent
{ {
// The bitfiled type stores any number of bits as a bitfield in an array.
struct TORRENT_EXPORT bitfield struct TORRENT_EXPORT bitfield
{ {
bitfield(): m_bytes(0), m_size(0), m_own(false) {} bitfield(): m_bytes(0), m_size(0), m_own(false) {}

32
include/libtorrent/fingerprint.hpp
View File

@ -43,8 +43,39 @@ POSSIBILITY OF SUCH DAMAGE.
namespace libtorrent namespace libtorrent
{ {
// The fingerprint class represents information about a client and its version. It is used
// to encode this information into the client's peer id.
struct fingerprint struct fingerprint
{ {
// The constructor takes a ``char const*`` that should point to a string constant containing
// exactly two characters. These are the characters that should be unique for your client. Make
// sure not to clash with anybody else. Here are some taken id's:
//
// +----------+-----------------------+
// | id chars | client |
// +==========+=======================+
// | 'AZ' | Azureus |
// +----------+-----------------------+
// | 'LT' | libtorrent (default) |
// +----------+-----------------------+
// | 'BX' | BittorrentX |
// +----------+-----------------------+
// | 'MT' | Moonlight Torrent |
// +----------+-----------------------+
// | 'TS' | Torrent Storm |
// +----------+-----------------------+
// | 'SS' | Swarm Scope |
// +----------+-----------------------+
// | 'XT' | Xan Torrent |
// +----------+-----------------------+
//
// There's an informal directory of client id's here_.
//
// .. _here: http://wiki.theory.org/BitTorrentSpecification#peer_id
//
// The ``major``, ``minor``, ``revision`` and ``tag`` parameters are used to identify the
// version of your client.
fingerprint(const char* id_string, int major, int minor, int revision, int tag) fingerprint(const char* id_string, int major, int minor, int revision, int tag)
: major_version(major) : major_version(major)
, minor_version(minor) , minor_version(minor)
@ -61,6 +92,7 @@ namespace libtorrent
name[1] = id_string[1]; name[1] = id_string[1];
} }
// generates the actual string put in the peer-id, and return it.
std::string to_string() const std::string to_string() const
{ {
char s[100]; char s[100];

15
include/libtorrent/hasher.hpp
View File

@ -74,6 +74,21 @@ namespace libtorrent
namespace libtorrent namespace libtorrent
{ {
// You use it by first instantiating it, then call ``update()`` to feed it
// with data. i.e. you don't have to keep the entire buffer of which you want to
// create the hash in memory. You can feed the hasher parts of it at a time. When
// You have fed the hasher with all the data, you call ``final()`` and it
// will return the sha1-hash of the data.
//
// The constructor that takes a ``char const*`` and an integer will construct the
// sha1 context and feed it the data passed in.
//
// If you want to reuse the hasher object once you have created a hash, you have to
// call ``reset()`` to reinitialize it.
//
// The sha1-algorithm used was implemented by Steve Reid and released as public domain.
// For more info, see ``src/sha1.cpp``.
class TORRENT_EXTRA_EXPORT hasher class TORRENT_EXTRA_EXPORT hasher
{ {
public: public:

8
include/libtorrent/identify_client.hpp
View File

@ -50,7 +50,15 @@ POSSIBILITY OF SUCH DAMAGE.
namespace libtorrent namespace libtorrent
{ {
// This function is declared in the header ``<libtorrent/identify_client.hpp>``. It can can be used
// to extract a string describing a client version from its peer-id. It will recognize most clients
// that have this kind of identification in the peer-id.
TORRENT_EXPORT std::string identify_client(const peer_id& p); TORRENT_EXPORT std::string identify_client(const peer_id& p);
// Returns an optional fingerprint if any can be identified from the peer id. This can be used
// to automate the identification of clients. It will not be able to identify peers with non-
// standard encodings. Only Azureus style, Shadow's style and Mainline style. This function is
// declared in the header ``<libtorrent/identify_client.hpp>``.
TORRENT_EXPORT boost::optional<fingerprint> client_fingerprint(peer_id const& p); TORRENT_EXPORT boost::optional<fingerprint> client_fingerprint(peer_id const& p);
} }

34
include/libtorrent/ip_filter.hpp
View File

@ -260,6 +260,13 @@ namespace detail
} }
// The ``ip_filter`` class is a set of rules that uniquely categorizes all
// ip addresses as allowed or disallowed. The default constructor creates
// a single rule that allows all addresses (0.0.0.0 - 255.255.255.255 for
// the IPv4 range, and the equivalent range covering all addresses for the
// IPv6 range).
//
// A default constructed ip_filter does not filter any address.
struct TORRENT_EXPORT ip_filter struct TORRENT_EXPORT ip_filter
{ {
enum access_flags enum access_flags
@ -267,9 +274,25 @@ struct TORRENT_EXPORT ip_filter
blocked = 1 blocked = 1
}; };
// both addresses MUST be of the same type (i.e. both must // Adds a rule to the filter. ``first`` and ``last`` defines a range of
// be either IPv4 or both must be IPv6) // ip addresses that will be marked with the given flags. The ``flags``
// can currently be 0, which means allowed, or ``ip_filter::blocked``, which
// means disallowed.
//
// precondition:
// ``first.is_v4() == last.is_v4() && first.is_v6() == last.is_v6()``
//
// postcondition:
// ``access(x) == flags`` for every ``x`` in the range [``first``, ``last``]
//
// This means that in a case of overlapping ranges, the last one applied takes
// precedence.
void add_rule(address first, address last, int flags); void add_rule(address first, address last, int flags);
// Returns the access permissions for the given address (``addr``). The permission
// can currently be 0 or ``ip_filter::blocked``. The complexity of this operation
// is O(``log`` n), where n is the minimum number of non-overlapping ranges to describe
// the current filter.
int access(address const& addr) const; int access(address const& addr) const;
#if TORRENT_USE_IPV6 #if TORRENT_USE_IPV6
@ -279,6 +302,13 @@ struct TORRENT_EXPORT ip_filter
typedef std::vector<ip_range<address_v4> > filter_tuple_t; typedef std::vector<ip_range<address_v4> > filter_tuple_t;
#endif #endif
// This function will return the current state of the filter in the minimum number of
// ranges possible. They are sorted from ranges in low addresses to high addresses. Each
// entry in the returned vector is a range with the access control specified in its
// ``flags`` field.
//
// The return value is a tuple containing two range-lists. One for IPv4 addresses
// and one for IPv6 addresses.
filter_tuple_t export_filter() const; filter_tuple_t export_filter() const;
// void print() const; // void print() const;

34
include/libtorrent/lazy_entry.hpp
View File

@ -50,7 +50,39 @@ namespace libtorrent
{ {
struct lazy_entry; struct lazy_entry;
// return 0 = success // This function decodes bencoded_ data.
//
// .. _bencoded: http://wiki.theory.org/index.php/BitTorrentSpecification
//
// Whenever possible, ``lazy_bdecode()`` should be preferred over ``bdecode()``.
// It is more efficient and more secure. It supports having constraints on the
// amount of memory is consumed by the parser.
//
// *lazy* refers to the fact that it doesn't copy any actual data out of the
// bencoded buffer. It builds a tree of ``lazy_entry`` which has pointers into
// the bencoded buffer. This makes it very fast and efficient. On top of that,
// it is not recursive, which saves a lot of stack space when parsing deeply
// nested trees. However, in order to protect against potential attacks, the
// ``depth_limit`` and ``item_limit`` control how many levels deep the tree is
// allowed to get. With recursive parser, a few thousand levels would be enough
// to exhaust the threads stack and terminate the process. The ``item_limit``
// protects against very large structures, not necessarily deep. Each bencoded
// item in the structure causes the parser to allocate some amount of memory,
// this memory is constant regardless of how much data actually is stored in
// the item. One potential attack is to create a bencoded list of hundreds of
// thousands empty strings, which would cause the parser to allocate a significant
// amount of memory, perhaps more than is available on the machine, and effectively
// provide a denial of service. The default item limit is set as a reasonable
// upper limit for desktop computers. Very few torrents have more items in them.
// The limit corresponds to about 25 MB, which might be a bit much for embedded
// systems.
//
// ``start`` and ``end`` defines the bencoded buffer to be decoded. ``ret`` is
// the ``lazy_entry`` which is filled in with the whole decoded tree. ``ec``
// is a reference to an ``error_code`` which is set to describe the error encountered
// in case the function fails. ``error_pos`` is an optional pointer to an int,
// which will be set to the byte offset into the buffer where an error occurred,
// in case the function fails.
TORRENT_EXPORT int lazy_bdecode(char const* start, char const* end TORRENT_EXPORT int lazy_bdecode(char const* start, char const* end
, lazy_entry& ret, error_code& ec, int* error_pos = 0 , lazy_entry& ret, error_code& ec, int* error_pos = 0
, int depth_limit = 1000, int item_limit = 1000000); , int depth_limit = 1000, int item_limit = 1000000);

7
include/libtorrent/magnet_uri.hpp
View File

@ -43,6 +43,11 @@ namespace libtorrent
struct torrent_handle; struct torrent_handle;
class session; class session;
// Generates a magnet URI from the specified torrent. If the torrent
// handle is invalid, an empty string is returned.
//
// For more information about magnet links, see `magnet links`_.
//
std::string TORRENT_EXPORT make_magnet_uri(torrent_handle const& handle); std::string TORRENT_EXPORT make_magnet_uri(torrent_handle const& handle);
std::string TORRENT_EXPORT make_magnet_uri(torrent_info const& info); std::string TORRENT_EXPORT make_magnet_uri(torrent_info const& info);
@ -70,6 +75,8 @@ namespace libtorrent
#endif #endif
// This function parses out information from the magnet link and populates the
// add_torrent_params object.
TORRENT_EXPORT void parse_magnet_uri(std::string const& uri, add_torrent_params& p, error_code& ec); TORRENT_EXPORT void parse_magnet_uri(std::string const& uri, add_torrent_params& p, error_code& ec);
} }

4
include/libtorrent/session.hpp
View File

@ -134,7 +134,7 @@ namespace libtorrent
// (ut_metadata, ut_pex and smart_ban). The default is to start those things. If you do not want // (ut_metadata, ut_pex and smart_ban). The default is to start those things. If you do not want
// them to start, pass 0 as the flags parameter. // them to start, pass 0 as the flags parameter.
// //
// The ``alert_mask`` is the same mask that you would send to `set_alert_mask()`_. // The ``alert_mask`` is the same mask that you would send to set_alert_mask().
session(fingerprint const& print = fingerprint("LT" session(fingerprint const& print = fingerprint("LT"
, LIBTORRENT_VERSION_MAJOR, LIBTORRENT_VERSION_MINOR, 0, 0) , LIBTORRENT_VERSION_MAJOR, LIBTORRENT_VERSION_MINOR, 0, 0)
, int flags = start_default_features | add_default_plugins , int flags = start_default_features | add_default_plugins
@ -810,7 +810,7 @@ namespace libtorrent
// Changes the mask of which alerts to receive. By default only errors are reported. // Changes the mask of which alerts to receive. By default only errors are reported.
// ``m`` is a bitmask where each bit represents a category of alerts. // ``m`` is a bitmask where each bit represents a category of alerts.
// //
// See alerts_ for mor information on the alert categories. // See category_t enum for options.
void set_alert_mask(boost::uint32_t m); void set_alert_mask(boost::uint32_t m);
// This sets a function to be called (from within libtorrent's netowrk thread) every time an alert // This sets a function to be called (from within libtorrent's netowrk thread) every time an alert

83
include/libtorrent/session_settings.hpp
View File

@ -42,6 +42,8 @@ POSSIBILITY OF SUCH DAMAGE.
namespace libtorrent namespace libtorrent
{ {
// The ``proxy_settings`` structs contains the information needed to
// direct certain traffic to a proxy.
struct TORRENT_EXPORT proxy_settings struct TORRENT_EXPORT proxy_settings
{ {
proxy_settings() : port(0), type(none) proxy_settings() : port(0), type(none)
@ -49,6 +51,9 @@ namespace libtorrent
, proxy_peer_connections(true) , proxy_peer_connections(true)
{} {}
// the name or IP of the proxy server. ``port`` is the
// port number the proxy listens to. If required, ``username`` and ``password``
// can be set to authenticate with the proxy.
std::string hostname; std::string hostname;
int port; int port;
@ -57,38 +62,54 @@ namespace libtorrent
enum proxy_type enum proxy_type
{ {
// a plain tcp socket is used, and // This is the default, no proxy server is used, all other fields
// the other settings are ignored. // are ignored.
none, none,
// socks4 server, requires username.
// The server is assumed to be a `SOCKS4 server`_ that
// requires a username.
//
// .. _`SOCKS4 server`: http://www.ufasoft.com/doc/socks4_protocol.htm
socks4, socks4,
// the hostname and port settings are // The server is assumed to be a SOCKS5 server (`RFC 1928`_) that
// used to connect to the proxy. No // does not require any authentication. The username and password are ignored.
// username or password is sent. //
// .. _`RFC 1928`: http://www.faqs.org/rfcs/rfc1928.html
socks5, socks5,
// the hostname and port are used to
// connect to the proxy. the username // The server is assumed to be a SOCKS5 server that supports
// and password are used to authenticate // plain text username and password authentication (`RFC 1929`_). The username
// with the proxy server. // and password specified may be sent to the proxy if it requires.
//
// .. _`RFC 1929`: http://www.faqs.org/rfcs/rfc1929.html
socks5_pw, socks5_pw,
// the http proxy is only available for // The server is assumed to be an HTTP proxy. If the transport used
// tracker and web seed traffic // for the connection is non-HTTP, the server is assumed to support the
// assumes anonymous access to proxy // CONNECT_ method. i.e. for web seeds and HTTP trackers, a plain proxy will
// suffice. The proxy is assumed to not require authorization. The username
// and password will not be used.
//
// .. _CONNECT: http://tools.ietf.org/html/draft-luotonen-web-proxy-tunneling-01
http, http,
// http proxy with basic authentication // The server is assumed to be an HTTP proxy that requires
// uses username and password // user authorization. The username and password will be sent to the proxy.
http_pw, http_pw,
// route through a i2p SAM proxy // route through a i2p SAM proxy
i2p_proxy i2p_proxy
}; };
// tells libtorrent what kind of proxy server it is. See proxy_type
// enum for options
proxy_type type; proxy_type type;
// when set to true, hostname are resolved // defaults to true. It means that hostnames should be
// through the proxy (if supported) // attempted to be resolved through the proxy instead of using the local DNS
// service. This is only supported by SOCKS5 and HTTP.
bool proxy_hostnames; bool proxy_hostnames;
// if true, use this proxy for peers too // determines whether or not to excempt peer and
// web seed connections from using the proxy. This defaults to true, i.e. peer
// connections are proxied by default.
bool proxy_peer_connections; bool proxy_peer_connections;
}; };
@ -1065,6 +1086,8 @@ namespace libtorrent
#ifndef TORRENT_DISABLE_ENCRYPTION #ifndef TORRENT_DISABLE_ENCRYPTION
// The ``pe_settings`` structure is used to control the settings related
// to peer protocol encryption.
struct pe_settings struct pe_settings
{ {
pe_settings() pe_settings()
@ -1076,9 +1099,19 @@ namespace libtorrent
enum enc_policy enum enc_policy
{ {
forced, // disallow non encrypted connections // Only encrypted connections are allowed. Incoming connections
enabled, // allow encrypted and non encrypted connections // that are not encrypted are closed and if the encrypted outgoing connection
disabled // disallow encrypted connections // fails, a non-encrypted retry will not be made.
forced,
// encrypted connections are enabled, but non-encrypted
// connections are allowed. An incoming non-encrypted connection will
// be accepted, and if an outgoing encrypted connection fails, a non-
// encrypted connection will be tried.
enabled,
// only non-encrypted connections are allowed.
disabled
}; };
enum enc_level enum enc_level
@ -1088,10 +1121,18 @@ namespace libtorrent
both = 3 // allow both both = 3 // allow both
}; };
// control the settings for incoming
// and outgoing connections respectively.
// see enc_policy enum for the available options.
enc_policy out_enc_policy; enc_policy out_enc_policy;
enc_policy in_enc_policy; enc_policy in_enc_policy;
// determines the encryption level of the
// connections. This setting will adjust which encryption scheme is
// offered to the other peer, as well as which encryption scheme is
// selected by the client. See enc_level enum for options.
enc_level allowed_enc_level; enc_level allowed_enc_level;
// if the allowed encryption level is both, setting this to // if the allowed encryption level is both, setting this to
// true will prefer rc4 if both methods are offered, plaintext // true will prefer rc4 if both methods are offered, plaintext
// otherwise // otherwise