added some documentation

This commit is contained in:
Arvid Norberg 2013-09-01 17:34:05 +00:00
parent d04748f1db
commit f3684db153
11 changed files with 229 additions and 21 deletions

View File

@ -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('''<html><head>
<table width="100%%" border="1" style="border-collapse: collapse;">''' % \
(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:

View File

@ -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 {

View File

@ -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<char> 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<entry> 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)

View File

@ -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<torrent_plugin> new_torrent(torrent*, void*)
{ return boost::shared_ptr<torrent_plugin>(); }
@ -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

View File

@ -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

View File

@ -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

View File

@ -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;
};

View File

@ -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); }

View File

@ -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:

View File

@ -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<std::string, int> 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

View File

@ -2627,7 +2627,7 @@ namespace libtorrent
{
ae->trackerid = trackerid;
if (m_ses.m_alerts.should_post<trackerid_alert>())
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();