diff --git a/docs/gen_todo.py b/docs/gen_todo.py index c939a23a9..4ac480b9e 100644 --- a/docs/gen_todo.py +++ b/docs/gen_todo.py @@ -16,7 +16,7 @@ items = [] # todo-items context = [] -priority_count = [0, 0, 0, 0] +priority_count = [0, 0, 0, 0, 0] def html_sanitize(s): ret = '' @@ -119,7 +119,7 @@ out.write(''' ''' % \ (priority_count[3], priority_count[2], priority_count[1], priority_count[0])) -prio_colors = [ '#ccc', '#ccf', '#cfc', '#fcc'] +prio_colors = [ '#ccc', '#ccf', '#cfc', '#fcc', '#fdd'] index = 0 for i in items: diff --git a/include/libtorrent/alert.hpp b/include/libtorrent/alert.hpp index 191c73372..0e266c282 100644 --- a/include/libtorrent/alert.hpp +++ b/include/libtorrent/alert.hpp @@ -167,7 +167,9 @@ namespace libtorrent { all_categories = 0x7fffffff }; + // hidden alert(); + // hidden virtual ~alert(); // a timestamp is automatically created in the constructor @@ -231,12 +233,12 @@ namespace libtorrent { ptime m_timestamp; }; +#ifndef TORRENT_NO_DEPRECATE struct TORRENT_EXPORT unhandled_alert : std::exception { unhandled_alert() {} }; -#ifndef TORRENT_NO_DEPRECATE #ifndef BOOST_NO_TYPEID namespace detail { diff --git a/include/libtorrent/alert_types.hpp b/include/libtorrent/alert_types.hpp index 1a34e8960..24595a4e2 100644 --- a/include/libtorrent/alert_types.hpp +++ b/include/libtorrent/alert_types.hpp @@ -57,15 +57,21 @@ namespace libtorrent // user defined alerts should use IDs greater than this const static int user_alert_id = 10000; + // This is a base class for alerts that are associated with a + // specific torrent. It contains a handle to the torrent. struct TORRENT_EXPORT torrent_alert: alert { + // internal torrent_alert(torrent_handle const& h) : handle(h) {} + // internal const static int alert_type = 1; virtual std::string message() const; + // The torrent_handle pointing to the torrent this + // alert is associated with. torrent_handle handle; }; @@ -73,6 +79,7 @@ namespace libtorrent // the information to identify the peer. i.e. ``ip`` and ``peer-id``. struct TORRENT_EXPORT peer_alert: torrent_alert { + // internal peer_alert(torrent_handle const& h, tcp::endpoint const& i , peer_id const& pi) : torrent_alert(h) @@ -85,12 +92,19 @@ namespace libtorrent virtual int category() const { return static_category; } virtual std::string message() const; + // The peer's IP address and port. tcp::endpoint ip; + + // the peer ID, if known. peer_id pid; }; + // This is a base class used for alerts that are associated with a + // specific tracker. It derives from torrent_alert since a tracker + // is also associated with a specific torrent. struct TORRENT_EXPORT tracker_alert: torrent_alert { + // internal tracker_alert(torrent_handle const& h , std::string const& u) : torrent_alert(h) @@ -102,6 +116,7 @@ namespace libtorrent virtual int category() const { return static_category; } virtual std::string message() const; + // The tracker URL std::string url; }; @@ -119,6 +134,7 @@ namespace libtorrent // It's posted when the ``status_notification`` bit is set in the alert_mask. struct TORRENT_EXPORT torrent_added_alert: torrent_alert { + // internal torrent_added_alert(torrent_handle const& h) : torrent_alert(h) {} @@ -142,6 +158,7 @@ namespace libtorrent // points to the same non-existent object. struct TORRENT_EXPORT torrent_removed_alert: torrent_alert { + // internal torrent_removed_alert(torrent_handle const& h, sha1_hash const& ih) : torrent_alert(h) , info_hash(ih) @@ -163,6 +180,7 @@ namespace libtorrent // If the operation fails, ec will indicat what went wrong. struct TORRENT_EXPORT read_piece_alert: torrent_alert { + // internal read_piece_alert(torrent_handle const& h , int p, boost::shared_array d, int s) : torrent_alert(h) @@ -170,7 +188,6 @@ namespace libtorrent , piece(p) , size(s) {} - read_piece_alert(torrent_handle h, int p, error_code e) : torrent_alert(h) , ec(e) @@ -194,6 +211,7 @@ namespace libtorrent // All pieces overlapping this file have passed their hash check. struct TORRENT_EXPORT file_completed_alert: torrent_alert { + // internal file_completed_alert(torrent_handle const& h , int idx) : torrent_alert(h) @@ -213,6 +231,7 @@ namespace libtorrent // operation succeeds. struct TORRENT_EXPORT file_renamed_alert: torrent_alert { + // internal file_renamed_alert(torrent_handle const& h , std::string const& n , int idx) @@ -238,6 +257,7 @@ namespace libtorrent // operation failed. struct TORRENT_EXPORT file_rename_failed_alert: torrent_alert { + // internal file_rename_failed_alert(torrent_handle const& h , int idx , error_code ec) @@ -343,6 +363,7 @@ namespace libtorrent num_warnings }; + // internal performance_alert(torrent_handle const& h , performance_warning_t w) : torrent_alert(h) @@ -361,6 +382,7 @@ namespace libtorrent // Generated whenever a torrent changes its state. struct TORRENT_EXPORT state_changed_alert: torrent_alert { + // internal state_changed_alert(torrent_handle const& h , torrent_status::state_t st , torrent_status::state_t prev_st) @@ -392,6 +414,7 @@ namespace libtorrent // to 0. struct TORRENT_EXPORT tracker_error_alert: tracker_alert { + // internal tracker_error_alert(torrent_handle const& h , int times , int status @@ -423,6 +446,7 @@ namespace libtorrent // the client. struct TORRENT_EXPORT tracker_warning_alert: tracker_alert { + // internal tracker_warning_alert(torrent_handle const& h , std::string const& u , std::string const& m) @@ -442,6 +466,7 @@ namespace libtorrent // This alert is generated when a scrape request succeeds. struct TORRENT_EXPORT scrape_reply_alert: tracker_alert { + // internal scrape_reply_alert(torrent_handle const& h , int incomp , int comp @@ -466,6 +491,7 @@ namespace libtorrent // code indicating an error. struct TORRENT_EXPORT scrape_failed_alert: tracker_alert { + // internal scrape_failed_alert(torrent_handle const& h , std::string const& u , error_code const& e) @@ -494,6 +520,7 @@ namespace libtorrent // the DHT. struct TORRENT_EXPORT tracker_reply_alert: tracker_alert { + // internal tracker_reply_alert(torrent_handle const& h , int np , std::string const& u) @@ -517,6 +544,7 @@ namespace libtorrent // a few at a time. struct TORRENT_EXPORT dht_reply_alert: tracker_alert { + // internal dht_reply_alert(torrent_handle const& h , int np) : tracker_alert(h, "") @@ -535,6 +563,7 @@ namespace libtorrent // however. struct TORRENT_EXPORT tracker_announce_alert: tracker_alert { + // internal tracker_announce_alert(torrent_handle const& h , std::string const& u, int e) : tracker_alert(h, u) @@ -558,6 +587,7 @@ namespace libtorrent // to the torrent which got the failed piece and the index of the piece itself from the alert. struct TORRENT_EXPORT hash_failed_alert: torrent_alert { + // internal hash_failed_alert( torrent_handle const& h , int index) @@ -577,6 +607,7 @@ namespace libtorrent // to us. ``ip`` is the endpoint to the peer that was banned. struct TORRENT_EXPORT peer_ban_alert: peer_alert { + // internal peer_ban_alert(torrent_handle h, tcp::endpoint const& ep , peer_id const& peer_id) : peer_alert(h, ep, peer_id) @@ -591,6 +622,7 @@ namespace libtorrent // sending data, and now it started sending data again. struct TORRENT_EXPORT peer_unsnubbed_alert: peer_alert { + // internal peer_unsnubbed_alert(torrent_handle h, tcp::endpoint const& ep , peer_id const& peer_id) : peer_alert(h, ep, peer_id) @@ -605,6 +637,7 @@ namespace libtorrent // it. struct TORRENT_EXPORT peer_snubbed_alert: peer_alert { + // internal peer_snubbed_alert(torrent_handle h, tcp::endpoint const& ep , peer_id const& peer_id) : peer_alert(h, ep, peer_id) @@ -619,6 +652,7 @@ namespace libtorrent // will be disconnected, but you get its ip address from the alert, to identify it. struct TORRENT_EXPORT peer_error_alert: peer_alert { + // internal peer_error_alert(torrent_handle const& h, tcp::endpoint const& ep , peer_id const& peer_id, error_code const& e) : peer_alert(h, ep, peer_id) @@ -648,6 +682,7 @@ namespace libtorrent // This alert is posted every time an outgoing peer connect attempts succeeds. struct TORRENT_EXPORT peer_connect_alert: peer_alert { + // internal peer_connect_alert(torrent_handle h, tcp::endpoint const& ep , peer_id const& peer_id, int type) : peer_alert(h, ep, peer_id) @@ -666,6 +701,7 @@ namespace libtorrent // covered by peer_error_alert ). struct TORRENT_EXPORT peer_disconnected_alert: peer_alert { + // internal peer_disconnected_alert(torrent_handle const& h, tcp::endpoint const& ep , peer_id const& peer_id, error_code const& e) : peer_alert(h, ep, peer_id) @@ -694,6 +730,7 @@ namespace libtorrent // request from the peer. See peer_request for more info. struct TORRENT_EXPORT invalid_request_alert: peer_alert { + // internal invalid_request_alert(torrent_handle const& h, tcp::endpoint const& ep , peer_id const& peer_id, peer_request const& r) : peer_alert(h, ep, peer_id) @@ -712,6 +749,7 @@ namespace libtorrent // torrent in question. struct TORRENT_EXPORT torrent_finished_alert: torrent_alert { + // internal torrent_finished_alert( const torrent_handle& h) : torrent_alert(h) @@ -724,8 +762,12 @@ namespace libtorrent { return torrent_alert::message() + " torrent finished downloading"; } }; + // this alert is posted every time a piece completes downloading + // and passes the hash check. This alert derives from torrent_alert + // which contains the torrent_handle to the torrent the piece belongs to. struct TORRENT_EXPORT piece_finished_alert: torrent_alert { + // internal piece_finished_alert( const torrent_handle& h , int piece_num) @@ -738,12 +780,14 @@ namespace libtorrent const static int static_category = alert::progress_notification; virtual std::string message() const; + // the index of the piece that finished int piece_index; }; // This alert is generated when a peer rejects or ignores a piece request. struct TORRENT_EXPORT request_dropped_alert: peer_alert { + // internal request_dropped_alert(const torrent_handle& h, tcp::endpoint const& ep , peer_id const& peer_id, int block_num, int piece_num) : peer_alert(h, ep, peer_id) @@ -764,6 +808,7 @@ namespace libtorrent // This alert is generated when a block request times out. struct TORRENT_EXPORT block_timeout_alert: peer_alert { + // internal block_timeout_alert(const torrent_handle& h, tcp::endpoint const& ep , peer_id const& peer_id, int block_num, int piece_num) : peer_alert(h, ep, peer_id) @@ -784,6 +829,7 @@ namespace libtorrent // This alert is generated when a block request receives a response. struct TORRENT_EXPORT block_finished_alert: peer_alert { + // internal block_finished_alert(const torrent_handle& h, tcp::endpoint const& ep , peer_id const& peer_id, int block_num, int piece_num) : peer_alert(h, ep, peer_id) @@ -803,6 +849,7 @@ namespace libtorrent // This alert is generated when a block request is sent to a peer. struct TORRENT_EXPORT block_downloading_alert: peer_alert { + // internal block_downloading_alert(const torrent_handle& h, tcp::endpoint const& ep , peer_id const& peer_id, char const* speedmsg, int block_num, int piece_num) : peer_alert(h, ep, peer_id) @@ -825,6 +872,7 @@ namespace libtorrent // whose request timed out. struct TORRENT_EXPORT unwanted_block_alert: peer_alert { + // internal unwanted_block_alert(const torrent_handle& h, tcp::endpoint const& ep , peer_id const& peer_id, int block_num, int piece_num) : peer_alert(h, ep, peer_id) @@ -846,6 +894,7 @@ namespace libtorrent // the storage. struct TORRENT_EXPORT storage_moved_alert: torrent_alert { + // internal storage_moved_alert(torrent_handle const& h, std::string const& p) : torrent_alert(h) , path(p) @@ -867,6 +916,7 @@ namespace libtorrent // via torrent_handle::move_storage(), fails. struct TORRENT_EXPORT storage_moved_failed_alert: torrent_alert { + // internal storage_moved_failed_alert(torrent_handle const& h, error_code const& e) : torrent_alert(h) , error(e) @@ -895,6 +945,7 @@ namespace libtorrent // needs to be set in the alert_mask. struct TORRENT_EXPORT torrent_deleted_alert: torrent_alert { + // internal torrent_deleted_alert(torrent_handle const& h, sha1_hash const& ih) : torrent_alert(h) { info_hash = ih; } @@ -912,6 +963,7 @@ namespace libtorrent // This alert is generated when a request to delete the files of a torrent fails. struct TORRENT_EXPORT torrent_delete_failed_alert: torrent_alert { + // internal torrent_delete_failed_alert(torrent_handle const& h, error_code const& e) : torrent_alert(h) , error(e) @@ -942,9 +994,9 @@ namespace libtorrent // This alert is generated as a response to a ``torrent_handle::save_resume_data`` request. // It is generated once the disk IO thread is done writing the state for this torrent. - struct TORRENT_EXPORT save_resume_data_alert: torrent_alert { + // internal save_resume_data_alert(boost::shared_ptr const& rd , torrent_handle const& h) : torrent_alert(h) @@ -966,6 +1018,7 @@ namespace libtorrent // generating the resume data. ``error`` describes what went wrong. struct TORRENT_EXPORT save_resume_data_failed_alert: torrent_alert { + // internal save_resume_data_failed_alert(torrent_handle const& h , error_code const& e) : torrent_alert(h) @@ -999,6 +1052,7 @@ namespace libtorrent // This is useful for synchronizing with the disk. struct TORRENT_EXPORT torrent_paused_alert: torrent_alert { + // internal torrent_paused_alert(torrent_handle const& h) : torrent_alert(h) {} @@ -1014,6 +1068,7 @@ namespace libtorrent // generated when a torrent goes from a paused state to an active state. struct TORRENT_EXPORT torrent_resumed_alert: torrent_alert { + // internal torrent_resumed_alert(torrent_handle const& h) : torrent_alert(h) {} @@ -1024,8 +1079,11 @@ namespace libtorrent { return torrent_alert::message() + " resumed"; } }; + // This alert is posted when a torrent completes checking. i.e. when it transitions + // out of the ``checking files`` state into a state where it is ready to start downloading struct TORRENT_EXPORT torrent_checked_alert: torrent_alert { + // internal torrent_checked_alert(torrent_handle const& h) : torrent_alert(h) {} @@ -1040,6 +1098,7 @@ namespace libtorrent // This alert is generated when a HTTP seed name lookup fails. struct TORRENT_EXPORT url_seed_alert: torrent_alert { + // internal url_seed_alert( torrent_handle const& h , std::string const& u @@ -1048,7 +1107,6 @@ namespace libtorrent , url(u) , msg(convert_from_native(e.message())) {} - url_seed_alert( torrent_handle const& h , std::string const& u @@ -1078,6 +1136,7 @@ namespace libtorrent // generated and the torrent is paused. struct TORRENT_EXPORT file_error_alert: torrent_alert { + // internal file_error_alert( std::string const& f , torrent_handle const& h @@ -1119,6 +1178,7 @@ namespace libtorrent // torrent-less download, with the metadata extension provided by libtorrent. struct TORRENT_EXPORT metadata_failed_alert: torrent_alert { + // internal metadata_failed_alert(const torrent_handle& h) : torrent_alert(h) {} @@ -1156,6 +1216,7 @@ namespace libtorrent // struct TORRENT_EXPORT metadata_received_alert: torrent_alert { + // internal metadata_received_alert( const torrent_handle& h) : torrent_alert(h) @@ -1168,8 +1229,12 @@ namespace libtorrent { return torrent_alert::message() + " metadata successfully received"; } }; + // This alert is posted when there is an error on the UDP socket. The + // UDP socket is used for all uTP, DHT and UDP tracker traffic. It's + // global to the session. struct TORRENT_EXPORT udp_error_alert: alert { + // internal udp_error_alert( udp::endpoint const& ep , error_code const& ec) @@ -1186,7 +1251,10 @@ namespace libtorrent return "UDP error: " + convert_from_native(error.message()) + " from: " + endpoint.address().to_string(ec); } + // the source address associated with the error (if any) udp::endpoint endpoint; + + // the error code describing the error error_code error; }; @@ -1196,6 +1264,7 @@ namespace libtorrent // The address can be accessed through the ``external_address`` member. struct TORRENT_EXPORT external_ip_alert: alert { + // internal external_ip_alert(address const& ip) : external_address(ip) {} @@ -1209,6 +1278,7 @@ namespace libtorrent return "external IP received: " + external_address.to_string(ec); } + // the IP address that is believed to be our external IP address external_address; }; @@ -1223,6 +1293,7 @@ namespace libtorrent // listen on it. struct TORRENT_EXPORT listen_failed_alert: alert { + // internal listen_failed_alert( tcp::endpoint const& ep , int op @@ -1252,6 +1323,7 @@ namespace libtorrent // was opened for listening. struct TORRENT_EXPORT listen_succeeded_alert: alert { + // internal listen_succeeded_alert(tcp::endpoint const& ep) : endpoint(ep) {} @@ -1273,6 +1345,7 @@ namespace libtorrent // mappings. struct TORRENT_EXPORT portmap_error_alert: alert { + // internal portmap_error_alert(int i, int t, error_code const& e) : mapping(i), map_type(t), error(e) { @@ -1307,6 +1380,7 @@ namespace libtorrent // port and, if DHT is enabled, when the UDP port is mapped. struct TORRENT_EXPORT portmap_alert: alert { + // internal portmap_alert(int i, int port, int t) : mapping(i), external_port(port), map_type(t) {} @@ -1333,6 +1407,7 @@ namespace libtorrent // for debugging the UPnP or NAT-PMP implementation. struct TORRENT_EXPORT portmap_log_alert: alert { + // internal portmap_log_alert(int t, std::string const& m) : map_type(t), msg(m) {} @@ -1351,6 +1426,7 @@ namespace libtorrent // resume file was rejected. struct TORRENT_EXPORT fastresume_rejected_alert: torrent_alert { + // internal fastresume_rejected_alert(torrent_handle const& h , error_code const& e) : torrent_alert(h) @@ -1385,6 +1461,7 @@ namespace libtorrent // * the protocol of the peer is blocked (uTP/TCP blocking) struct TORRENT_EXPORT peer_blocked_alert: torrent_alert { + // internal peer_blocked_alert(torrent_handle const& h, address const& i) : torrent_alert(h) , ip(i) @@ -1407,6 +1484,7 @@ namespace libtorrent // to the ``dht_notification`` category. struct TORRENT_EXPORT dht_announce_alert: alert { + // internal dht_announce_alert(address const& i, int p , sha1_hash const& ih) : ip(i) @@ -1428,6 +1506,7 @@ namespace libtorrent // It belongs to the ``dht_notification`` category. struct TORRENT_EXPORT dht_get_peers_alert: alert { + // internal dht_get_peers_alert(sha1_hash const& ih) : info_hash(ih) {} @@ -1445,6 +1524,7 @@ namespace libtorrent // torrent posts these alerts regularly. struct TORRENT_EXPORT stats_alert: torrent_alert { + // internal stats_alert(torrent_handle const& h, int interval , stat const& s); @@ -1487,6 +1567,7 @@ namespace libtorrent // cache flush is complete and the torrent does no longer have any files open. struct TORRENT_EXPORT cache_flushed_alert: torrent_alert { + // internal cache_flushed_alert(torrent_handle const& h); TORRENT_DEFINE_ALERT(cache_flushed_alert); @@ -1500,6 +1581,7 @@ namespace libtorrent // when in anonymous mode. struct TORRENT_EXPORT anonymous_mode_alert: torrent_alert { + // internal anonymous_mode_alert(torrent_handle const& h , int k, std::string const& s) : torrent_alert(h) @@ -1529,6 +1611,7 @@ namespace libtorrent // for a torrent we're currently participating in. struct TORRENT_EXPORT lsd_peer_alert: peer_alert { + // internal lsd_peer_alert(torrent_handle const& h , tcp::endpoint const& i) : peer_alert(h, i, peer_id(0)) @@ -1540,8 +1623,12 @@ namespace libtorrent virtual std::string message() const; }; + // This alert is posted whenever a tracker responds with a ``trackerid``. The tracker ID + // is like a cookie. The libtorrent will store the tracker ID for this tracker and + // repeat it in subsequent announces. struct TORRENT_EXPORT trackerid_alert: tracker_alert { + // internal trackerid_alert(torrent_handle const& h , std::string const& u , const std::string& id) @@ -1554,12 +1641,14 @@ namespace libtorrent const static int static_category = alert::status_notification; virtual std::string message() const; + // The tracker ID returned by the tracker std::string trackerid; }; // This alert is posted when the initial DHT bootstrap is done. struct TORRENT_EXPORT dht_bootstrap_alert: alert { + // internal dht_bootstrap_alert() {} TORRENT_DEFINE_ALERT(dht_bootstrap_alert); @@ -1575,6 +1664,7 @@ namespace libtorrent // in the alert_mask. struct TORRENT_EXPORT rss_alert: alert { + // internal rss_alert(feed_handle h, std::string const& u, int s, error_code const& ec) : handle(h), url(u), state(s), error(ec) {} @@ -1617,6 +1707,7 @@ namespace libtorrent // This is posted whenever a torrent is transitioned into the error state. struct TORRENT_EXPORT torrent_error_alert: torrent_alert { + // internal torrent_error_alert(torrent_handle const& h , error_code const& e) : torrent_alert(h) @@ -1638,6 +1729,7 @@ namespace libtorrent // in the .torrent file. struct TORRENT_EXPORT torrent_need_cert_alert: torrent_alert { + // internal torrent_need_cert_alert(torrent_handle const& h) : torrent_alert(h) {} @@ -1659,6 +1751,7 @@ namespace libtorrent // listen socket for SSL torrents. struct TORRENT_EXPORT incoming_connection_alert: alert { + // internal incoming_connection_alert(int t, tcp::endpoint const& i) : socket_type(t) , ip(i) @@ -1695,6 +1788,7 @@ namespace libtorrent // the torrent failed, ``error`` contains the error code. struct TORRENT_EXPORT add_torrent_alert : torrent_alert { + // internal add_torrent_alert(torrent_handle h, add_torrent_params const& p, error_code ec) : torrent_alert(h) , params(p) @@ -1742,6 +1836,7 @@ namespace libtorrent // of the info-hash changing. struct TORRENT_EXPORT torrent_update_alert : torrent_alert { + // internal torrent_update_alert(torrent_handle h, sha1_hash const& old_hash, sha1_hash const& new_hash) : torrent_alert(h) , old_ih(old_hash) @@ -1766,6 +1861,7 @@ namespace libtorrent // alert_mask. struct TORRENT_EXPORT rss_item_alert : alert { + // internal rss_item_alert(feed_handle h, feed_item const& item) : handle(h) , item(item) diff --git a/include/libtorrent/extensions.hpp b/include/libtorrent/extensions.hpp index 89da2aa73..b30694547 100644 --- a/include/libtorrent/extensions.hpp +++ b/include/libtorrent/extensions.hpp @@ -69,8 +69,17 @@ namespace libtorrent struct TORRENT_EXPORT plugin { + // hidden virtual ~plugin() {} + // this is called by the session every time a new torrent is added. + // The ``torrent*`` points to the internal torrent object created + // for the new torrent. The ``void*`` is the userdata pointer as + // passed in via add_torrent_params. + // + // If the plugin returns a torrent_plugin instance, it will be added + // to the new torrent. Otherwise, return an empty shared_ptr to a + // torrent_plugin (the default). virtual boost::shared_ptr new_torrent(torrent*, void*) { return boost::shared_ptr(); } @@ -92,9 +101,14 @@ namespace libtorrent virtual void load_state(lazy_entry const&) {} }; + // Torrent plugins are associated with a single torrent and have a number + // of functions called at certain events. Many of its functions have the + // ability to change or override the default libtorrent behavior. struct TORRENT_EXPORT torrent_plugin { + // hidden virtual ~torrent_plugin() {} + // throwing an exception closes the connection // returning a 0 pointer is valid and will not add // the peer_plugin to the peer_connection @@ -136,12 +150,19 @@ namespace libtorrent filtered = 2 }; + // called every time a new peer is added to the peer list. + // This is before the peer is connected to. For ``flags``, see + // torrent_plugin::flags_t. The ``source`` argument refers to + // the source where we learned about this peer from. It's a + // bitmask, because many sources may have told us about the same + // peer. For peer source flags, see peer_info::peer_source_flags. virtual void on_add_peer(tcp::endpoint const&, int /*src*/, int /*flags*/) {} }; struct TORRENT_EXPORT peer_plugin { + // hidden virtual ~peer_plugin() {} // This function is expected to return the name of diff --git a/include/libtorrent/file_storage.hpp b/include/libtorrent/file_storage.hpp index 53a1865df..58df818dd 100644 --- a/include/libtorrent/file_storage.hpp +++ b/include/libtorrent/file_storage.hpp @@ -51,6 +51,7 @@ namespace libtorrent { // hidden file_entry(); + // hidden ~file_entry(); // the full path of this file. The paths are unicode strings @@ -223,6 +224,7 @@ namespace libtorrent public: // hidden file_storage(); + // hidden ~file_storage() {} // returns true if the piece length has been initialized diff --git a/include/libtorrent/lazy_entry.hpp b/include/libtorrent/lazy_entry.hpp index 25040109b..62ec528dc 100644 --- a/include/libtorrent/lazy_entry.hpp +++ b/include/libtorrent/lazy_entry.hpp @@ -104,8 +104,16 @@ namespace libtorrent // see lazy_entry::string_pstr(). struct TORRENT_EXPORT pascal_string { + // construct a string pointing to the characters at ``p`` + // of length ``l`` characters. No NULL termination is required. pascal_string(char const* p, int l): len(l), ptr(p) {} + + // the number of characters in the string. int len; + + // the pointer to the first character in the string. This is + // not NULL terminated, but instead consult the ``len`` field + // to know how many characters follow. char const* ptr; // lexicographical comparison of strings. Order is consisten diff --git a/include/libtorrent/session_status.hpp b/include/libtorrent/session_status.hpp index 74bb0efe1..66420dd4f 100644 --- a/include/libtorrent/session_status.hpp +++ b/include/libtorrent/session_status.hpp @@ -112,12 +112,15 @@ namespace libtorrent size_type total_ip_overhead_download; size_type total_ip_overhead_upload; - // the DHT bandwidth usage. + // the upload and download rate used by DHT traffic. Also the total number + // of bytes sent and received to and from the DHT. int dht_upload_rate; int dht_download_rate; size_type total_dht_download; size_type total_dht_upload; + // the upload and download rate used by tracker traffic. Also the total number + // of bytes sent and received to and from trackers. int tracker_upload_rate; int tracker_download_rate; size_type total_tracker_download; @@ -201,6 +204,8 @@ namespace libtorrent // statistics on the uTP sockets. utp_status utp_stats; + // the number of known peers across all torrents. These are not necessarily + // connected peers, just peers we know of. int peerlist_size; }; diff --git a/include/libtorrent/sha1_hash.hpp b/include/libtorrent/sha1_hash.hpp index e12a9c9c0..0d6cc5db3 100644 --- a/include/libtorrent/sha1_hash.hpp +++ b/include/libtorrent/sha1_hash.hpp @@ -71,8 +71,12 @@ namespace libtorrent public: enum { size = number_size }; + // constructs an all-sero sha1-hash sha1_hash() { clear(); } + // returns an all-F sha1-hash. i.e. the maximum value + // representable by a 160 bit number (20 bytes). This is + // a static member function. static sha1_hash max() { sha1_hash ret; @@ -80,6 +84,9 @@ namespace libtorrent return ret; } + // returns an all-zero sha1-hash. i.e. the minimum value + // representable by a 160 bit number (20 bytes). This is + // a static member function. static sha1_hash min() { sha1_hash ret; @@ -87,29 +94,32 @@ namespace libtorrent return ret; } + // copies 20 bytes from the pointer provided, into the sha1-hash. + // The passed in string MUST be at least 20 bytes. NULL terminators + // are ignored, ``s`` is treated like a raw memory buffer. explicit sha1_hash(char const* s) { if (s == 0) clear(); else std::memcpy(m_number, s, size); } - explicit sha1_hash(std::string const& s) { TORRENT_ASSERT(s.size() >= 20); int sl = int(s.size()) < size ? int(s.size()) : size; std::memcpy(m_number, s.c_str(), sl); } - void assign(std::string const& s) { TORRENT_ASSERT(s.size() >= 20); int sl = int(s.size()) < size ? int(s.size()) : size; std::memcpy(m_number, s.c_str(), sl); } - void assign(char const* str) { std::memcpy(m_number, str, size); } + + // set the sha1-hash to all zeroes. void clear() { std::memset(m_number, 0, number_size); } + // return true if the sha1-hash is all zero. bool is_all_zeros() const { for (const unsigned char* i = m_number; i < m_number+number_size; ++i) @@ -117,6 +127,7 @@ namespace libtorrent return true; } + // shift left ``n`` bits. sha1_hash& operator<<=(int n) { TORRENT_ASSERT(n >= 0); @@ -145,6 +156,7 @@ namespace libtorrent return *this; } + // shift r ``n`` bits. sha1_hash& operator>>=(int n) { TORRENT_ASSERT(n >= 0); @@ -172,6 +184,7 @@ namespace libtorrent return *this; } + // standard comparison operators bool operator==(sha1_hash const& n) const { return std::equal(n.m_number, n.m_number+number_size, m_number); @@ -181,7 +194,6 @@ namespace libtorrent { return !std::equal(n.m_number, n.m_number+number_size, m_number); } - bool operator<(sha1_hash const& n) const { for (int i = 0; i < number_size; ++i) @@ -192,6 +204,7 @@ namespace libtorrent return false; } + // negate every bit in the sha1-hash sha1_hash operator~() { sha1_hash ret; @@ -200,20 +213,27 @@ namespace libtorrent return ret; } + // bit-wise XOR of the two sha1-hash. sha1_hash operator^(sha1_hash const& n) const { sha1_hash ret = *this; ret ^= n; return ret; } + sha1_hash& operator^=(sha1_hash const& n) + { + for (int i = 0; i< number_size; ++i) + m_number[i] ^= n.m_number[i]; + return *this; + } + // bit-wise AND of the two sha1-hash. sha1_hash operator&(sha1_hash const& n) const { sha1_hash ret = *this; ret &= n; return ret; } - sha1_hash& operator&=(sha1_hash const& n) { for (int i = 0; i< number_size; ++i) @@ -221,6 +241,7 @@ namespace libtorrent return *this; } + // bit-wise OR of the two sha1-hash. sha1_hash& operator|=(sha1_hash const& n) { for (int i = 0; i< number_size; ++i) @@ -228,16 +249,9 @@ namespace libtorrent return *this; } - sha1_hash& operator^=(sha1_hash const& n) - { - for (int i = 0; i< number_size; ++i) - m_number[i] ^= n.m_number[i]; - return *this; - } - + // accessors for specific bytes unsigned char& operator[](int i) { TORRENT_ASSERT(i >= 0 && i < number_size); return m_number[i]; } - unsigned char const& operator[](int i) const { TORRENT_ASSERT(i >= 0 && i < number_size); return m_number[i]; } @@ -250,6 +264,8 @@ namespace libtorrent iterator begin() { return m_number; } iterator end() { return m_number+number_size; } + // return a copy of the 20 bytes representing the sha1-hash as a std::string. + // It's still a binary string with 20 binary characters. std::string to_string() const { return std::string((char const*)&m_number[0], number_size); } diff --git a/include/libtorrent/storage.hpp b/include/libtorrent/storage.hpp index 18a18863e..95b6d274c 100644 --- a/include/libtorrent/storage.hpp +++ b/include/libtorrent/storage.hpp @@ -355,25 +355,41 @@ namespace libtorrent virtual void finalize_file(int) {} #endif + // access global disk_buffer_pool, for allocating and freeing disk buffers disk_buffer_pool* disk_pool() { return m_disk_pool; } + + // access global session_settings session_settings const& settings() const { return *m_settings; } + // called by the storage implementation to set it into an + // error state. Typically whenever a critical file operation + // fails. void set_error(std::string const& file, error_code const& ec) const; + // returns the currently set error code and file path associated with it, + // if set. error_code const& error() const { return m_error; } std::string const& error_file() const { return m_error_file; } + + // reset the error state to allow continuing reading and writing + // to the storage virtual void clear_error() { m_error = error_code(); m_error_file.resize(0); } + // hidden mutable error_code m_error; mutable std::string m_error_file; // hidden virtual ~storage_interface() {} + // hidden disk_buffer_pool* m_disk_pool; session_settings* m_settings; }; + // The default implementation of storage_interface. Behaves as a normal bittorrent client. + // It is possible to derive from this class in order to override some of its behavior, when + // implementing a custom storage. class TORRENT_EXPORT default_storage : public storage_interface, boost::noncopyable { public: diff --git a/include/libtorrent/torrent_info.hpp b/include/libtorrent/torrent_info.hpp index 694ef9a82..88716becc 100644 --- a/include/libtorrent/torrent_info.hpp +++ b/include/libtorrent/torrent_info.hpp @@ -84,6 +84,7 @@ namespace libtorrent // relates to a specific torrent. struct TORRENT_EXPORT announce_entry { + // constructs a tracker announce entry with ``u`` as the URL. announce_entry(std::string const& u); announce_entry(); ~announce_entry(); @@ -180,6 +181,9 @@ namespace libtorrent // this is false the stats sent to this tracker will be 0 bool send_stats:1; + // reset announce counters and clears the started sent flag. + // The announce_entry will look like we've never talked to + // the tracker. void reset() { start_sent = false; @@ -187,23 +191,38 @@ namespace libtorrent min_announce = min_time(); } + // updates the failure counter and time-outs for re-trying. + // This is called when the tracker announce fails. void failed(session_settings const& sett, int retry_interval = 0); +/* bool will_announce(ptime now) const { return now <= next_announce && (fails < fail_limit || fail_limit == 0) && !updating; } +*/ + // returns true if we can announec to this tracker now. + // The current time is passed in as ``now``. The ``is_seed`` + // argument is necessary because once we become a seed, we + // need to announce right away, even if the re-announce timer + // hasn't expired yet. bool can_announce(ptime now, bool is_seed) const; + // returns true if the last time we tried to announce to this + // tracker succeeded, or if we haven't tried yet. bool is_working() const { return fails == 0; } + // trims whitespace characters from the beginning of the URL. void trim(); }; + // the web_seed_entry holds information about a web seed (also known + // as URL seed or HTTP seed). It is essentially a URL with some state + // associated with it. For more information, see `BEP 17`_ and `BEP 19`_. struct web_seed_entry { // http seeds are different from url seeds in the @@ -217,9 +236,11 @@ namespace libtorrent , std::string const& auth_ = std::string() , headers_t const& extra_headers_ = headers_t()); + // URL and type comparison bool operator==(web_seed_entry const& e) const { return url == e.url && type == e.type; } + // URL and type less-than comparison bool operator<(web_seed_entry const& e) const { if (url < e.url) return true; @@ -439,6 +460,7 @@ namespace libtorrent int piece_length() const { return m_files.piece_length(); } int num_pieces() const { return m_files.num_pieces(); } + // returns the info-hash of the torrent const sha1_hash& info_hash() const { return m_info_hash; } #ifndef TORRENT_NO_DEPRECATE @@ -499,6 +521,9 @@ namespace libtorrent // ------- end deprecation ------- #endif + // Returns the SSL root certificate for the torrent, if it is an SSL + // torrent. Otherwise returns an empty string. The certificate is + // the the public certificate in x509 format. #ifdef TORRENT_USE_OPENSSL std::string const& ssl_cert() const { return m_ssl_root_cert; } #else @@ -509,12 +534,19 @@ namespace libtorrent } #endif + // returns true if this torrent_info object has a torrent loaded. + // This is primarily used to determine if a magnet link has had its + // metadata resolved yet or not. bool is_valid() const { return m_files.is_valid(); } // returns true if this torrent is private. i.e., it should not be // distributed on the trackerless network (the kademlia DHT). bool priv() const { return m_private; } + // returns true if this is an i2p torrent. This is determined by whether + // or not it has a tracker whose URL domain name ends with ".i2p". i2p + // torrents disable the DHT and local peer discovery as well as talking + // to peers over anything other than the i2p network. bool is_i2p() const { return m_i2p; } // ``hash_for_piece()`` takes a piece-index and returns the 20-bytes sha1-hash for that @@ -589,8 +621,16 @@ namespace libtorrent void add_node(std::pair const& node) { m_nodes.push_back(node); } + // populates the torrent_info by providing just the info-dict buffer. This is used when + // loading a torrent from a magnet link for instance, where we only have the info-dict. + // The lazy_entry ``e`` points to a parsed info-dictionary. ``ec`` returns an error code + // if something fails (typically if the info dictionary is malformed). ``flags`` are currently + // unused. bool parse_info_section(lazy_entry const& e, error_code& ec, int flags); + // This function looks up keys from the info-dictionary of the loaded torrent file. + // It can be used to access extension values put in the .torrent file. If the specified + // key cannot be found, it returns NULL. lazy_entry const* info(char const* key) const { if (m_info_dict.type() == lazy_entry::none_t) @@ -598,10 +638,12 @@ namespace libtorrent error_code ec; lazy_bdecode(m_info_section.get(), m_info_section.get() + m_info_section_size, m_info_dict, ec); + if (ec) return NULL; } return m_info_dict.dict_find(key); } + // swap the content of this and ``ti```. void swap(torrent_info& ti); // ``metadata()`` returns a the raw info section of the torrent file. The size diff --git a/src/torrent.cpp b/src/torrent.cpp index d76b7b47d..3e61b66f9 100644 --- a/src/torrent.cpp +++ b/src/torrent.cpp @@ -2627,7 +2627,7 @@ namespace libtorrent { ae->trackerid = trackerid; if (m_ses.m_alerts.should_post()) - m_ses.m_alerts.post_alert(trackerid_alert(get_handle(), r.url, trackerid)); + m_ses.m_alerts.post_alert(trackerid_alert(get_handle(), r.url, trackerid)); } update_scrape_state();