From 28cdc639fa0932fa8c45bd6d4393b947bc8b0dd2 Mon Sep 17 00:00:00 2001 From: Arvid Norberg Date: Thu, 8 Aug 2013 01:03:54 +0000 Subject: [PATCH] move more documentation into headers --- docs/manual.rst | 725 ------------------------ include/libtorrent/alert.hpp | 133 ++++- include/libtorrent/bencode.hpp | 47 +- include/libtorrent/bitfield.hpp | 1 + include/libtorrent/fingerprint.hpp | 32 ++ include/libtorrent/hasher.hpp | 15 + include/libtorrent/identify_client.hpp | 8 + include/libtorrent/ip_filter.hpp | 34 +- include/libtorrent/lazy_entry.hpp | 34 +- include/libtorrent/magnet_uri.hpp | 7 + include/libtorrent/session.hpp | 4 +- include/libtorrent/session_settings.hpp | 83 ++- 12 files changed, 367 insertions(+), 756 deletions(-) diff --git a/docs/manual.rst b/docs/manual.rst index 825ee3d88..b77c576b8 100644 --- a/docs/manual.rst +++ b/docs/manual.rst @@ -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 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 - 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 > > 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 > > 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 ========== @@ -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. - -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 ================ @@ -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. -free functions -============== - -identify_client() ------------------ - - :: - - std::string identify_client(peer_id const& id); - -This function is declared in the header ````. 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 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 ````. - - -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 entry bdecode(InIt start, InIt end); - template 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 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 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* alert_cast(alert* a); - template 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 ```` 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 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 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 ------------------- diff --git a/include/libtorrent/alert.hpp b/include/libtorrent/alert.hpp index 0d1f6a136..76bc976e2 100644 --- a/include/libtorrent/alert.hpp +++ b/include/libtorrent/alert.hpp @@ -47,6 +47,91 @@ POSSIBILITY OF SUCH DAMAGE. #include #include +// 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 #pragma warning(pop) #endif @@ -64,6 +149,7 @@ POSSIBILITY OF SUCH DAMAGE. namespace libtorrent { + // The ``alert`` class is the base class that specific messages are derived from. class TORRENT_EXPORT alert { public: @@ -102,10 +188,50 @@ namespace libtorrent { // a timestamp is automatically created in the constructor 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 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; + + // 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; + + // 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; + + // returns a bitmask specifying which categories this alert belong to. 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; } #ifndef TORRENT_NO_DEPRECATE @@ -113,6 +239,7 @@ namespace libtorrent { severity_t severity() const TORRENT_DEPRECATED { return warning; } #endif + // returns a pointer to a copy of the alert. virtual std::auto_ptr clone() const = 0; private: @@ -176,6 +303,11 @@ namespace libtorrent { #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 T* alert_cast(alert* a) { @@ -183,7 +315,6 @@ T* alert_cast(alert* a) if (a->type() == T::alert_type) return static_cast(a); return 0; } - template T const* alert_cast(alert const* a) { diff --git a/include/libtorrent/bencode.hpp b/include/libtorrent/bencode.hpp index 5312f7f36..444beb8ce 100644 --- a/include/libtorrent/bencode.hpp +++ b/include/libtorrent/bencode.hpp @@ -169,7 +169,6 @@ namespace libtorrent } } - // returns the number of bytes written template int bencode_recursive(OutIt& out, const entry& e) { @@ -378,13 +377,54 @@ 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 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 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 int bencode(OutIt out, const entry& e) { return detail::bencode_recursive(out, e); } - template entry bdecode(InIt start, InIt end) { @@ -397,7 +437,6 @@ namespace libtorrent if (err) return entry(); return e; } - template entry bdecode(InIt start, InIt end, int& len) { diff --git a/include/libtorrent/bitfield.hpp b/include/libtorrent/bitfield.hpp index 950c675b8..a3864d1a5 100644 --- a/include/libtorrent/bitfield.hpp +++ b/include/libtorrent/bitfield.hpp @@ -41,6 +41,7 @@ POSSIBILITY OF SUCH DAMAGE. namespace libtorrent { + // The bitfiled type stores any number of bits as a bitfield in an array. struct TORRENT_EXPORT bitfield { bitfield(): m_bytes(0), m_size(0), m_own(false) {} diff --git a/include/libtorrent/fingerprint.hpp b/include/libtorrent/fingerprint.hpp index 394b35c65..c9d4efecb 100644 --- a/include/libtorrent/fingerprint.hpp +++ b/include/libtorrent/fingerprint.hpp @@ -43,8 +43,39 @@ POSSIBILITY OF SUCH DAMAGE. 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 { + + // 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) : major_version(major) , minor_version(minor) @@ -61,6 +92,7 @@ namespace libtorrent name[1] = id_string[1]; } + // generates the actual string put in the peer-id, and return it. std::string to_string() const { char s[100]; diff --git a/include/libtorrent/hasher.hpp b/include/libtorrent/hasher.hpp index e76617a40..c234a7160 100644 --- a/include/libtorrent/hasher.hpp +++ b/include/libtorrent/hasher.hpp @@ -74,6 +74,21 @@ 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 { public: diff --git a/include/libtorrent/identify_client.hpp b/include/libtorrent/identify_client.hpp index 14e9db908..648542bb9 100644 --- a/include/libtorrent/identify_client.hpp +++ b/include/libtorrent/identify_client.hpp @@ -50,7 +50,15 @@ POSSIBILITY OF SUCH DAMAGE. namespace libtorrent { + // This function is declared in the header ````. 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); + + // 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 ````. TORRENT_EXPORT boost::optional client_fingerprint(peer_id const& p); } diff --git a/include/libtorrent/ip_filter.hpp b/include/libtorrent/ip_filter.hpp index 7ce2ffc22..18b15dfd3 100644 --- a/include/libtorrent/ip_filter.hpp +++ b/include/libtorrent/ip_filter.hpp @@ -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 { enum access_flags @@ -267,9 +274,25 @@ struct TORRENT_EXPORT ip_filter blocked = 1 }; - // both addresses MUST be of the same type (i.e. both must - // be either IPv4 or both must be IPv6) + // 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. 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; #if TORRENT_USE_IPV6 @@ -279,6 +302,13 @@ struct TORRENT_EXPORT ip_filter typedef std::vector > filter_tuple_t; #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; // void print() const; diff --git a/include/libtorrent/lazy_entry.hpp b/include/libtorrent/lazy_entry.hpp index f1bb47eaf..57970d753 100644 --- a/include/libtorrent/lazy_entry.hpp +++ b/include/libtorrent/lazy_entry.hpp @@ -50,7 +50,39 @@ namespace libtorrent { 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 , lazy_entry& ret, error_code& ec, int* error_pos = 0 , int depth_limit = 1000, int item_limit = 1000000); diff --git a/include/libtorrent/magnet_uri.hpp b/include/libtorrent/magnet_uri.hpp index 5df2b3ac6..42a0fca48 100644 --- a/include/libtorrent/magnet_uri.hpp +++ b/include/libtorrent/magnet_uri.hpp @@ -43,6 +43,11 @@ namespace libtorrent struct torrent_handle; 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_info const& info); @@ -70,6 +75,8 @@ namespace libtorrent #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); } diff --git a/include/libtorrent/session.hpp b/include/libtorrent/session.hpp index c9c34fbb6..7e4104939 100644 --- a/include/libtorrent/session.hpp +++ b/include/libtorrent/session.hpp @@ -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 // them to start, pass 0 as the flags parameter. // - // The ``alert_mask`` is the same mask that you would send to `set_alert_mask()`_. + // The ``alert_mask`` is the same mask that you would send to set_alert_mask(). session(fingerprint const& print = fingerprint("LT" , LIBTORRENT_VERSION_MAJOR, LIBTORRENT_VERSION_MINOR, 0, 0) , int flags = start_default_features | add_default_plugins @@ -810,7 +810,7 @@ namespace libtorrent // Changes the mask of which alerts to receive. By default only errors are reported. // ``m`` is a bitmask where each bit represents a category of alerts. // - // See alerts_ for mor information on the alert categories. + // See category_t enum for options. void set_alert_mask(boost::uint32_t m); // This sets a function to be called (from within libtorrent's netowrk thread) every time an alert diff --git a/include/libtorrent/session_settings.hpp b/include/libtorrent/session_settings.hpp index 95aea987d..fa90c1155 100644 --- a/include/libtorrent/session_settings.hpp +++ b/include/libtorrent/session_settings.hpp @@ -42,6 +42,8 @@ POSSIBILITY OF SUCH DAMAGE. namespace libtorrent { + // The ``proxy_settings`` structs contains the information needed to + // direct certain traffic to a proxy. struct TORRENT_EXPORT proxy_settings { proxy_settings() : port(0), type(none) @@ -49,6 +51,9 @@ namespace libtorrent , 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; int port; @@ -57,38 +62,54 @@ namespace libtorrent enum proxy_type { - // a plain tcp socket is used, and - // the other settings are ignored. + // This is the default, no proxy server is used, all other fields + // are ignored. 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, - // the hostname and port settings are - // used to connect to the proxy. No - // username or password is sent. + // The server is assumed to be a SOCKS5 server (`RFC 1928`_) that + // does not require any authentication. The username and password are ignored. + // + // .. _`RFC 1928`: http://www.faqs.org/rfcs/rfc1928.html socks5, - // the hostname and port are used to - // connect to the proxy. the username - // and password are used to authenticate - // with the proxy server. + + // 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. + // + // .. _`RFC 1929`: http://www.faqs.org/rfcs/rfc1929.html socks5_pw, - // the http proxy is only available for - // tracker and web seed traffic - // assumes anonymous access to proxy + // 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. + // + // .. _CONNECT: http://tools.ietf.org/html/draft-luotonen-web-proxy-tunneling-01 http, - // http proxy with basic authentication - // uses username and password + // The server is assumed to be an HTTP proxy that requires + // user authorization. The username and password will be sent to the proxy. http_pw, // route through a i2p SAM proxy i2p_proxy }; + // tells libtorrent what kind of proxy server it is. See proxy_type + // enum for options proxy_type type; - // when set to true, hostname are resolved - // through the proxy (if supported) + // 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. 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; }; @@ -1065,6 +1086,8 @@ namespace libtorrent #ifndef TORRENT_DISABLE_ENCRYPTION + // The ``pe_settings`` structure is used to control the settings related + // to peer protocol encryption. struct pe_settings { pe_settings() @@ -1076,9 +1099,19 @@ namespace libtorrent enum enc_policy { - forced, // disallow non encrypted connections - enabled, // allow encrypted and non encrypted connections - disabled // disallow encrypted connections + // 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. + 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 @@ -1088,10 +1121,18 @@ namespace libtorrent 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 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; + // if the allowed encryption level is both, setting this to // true will prefer rc4 if both methods are offered, plaintext // otherwise