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();