diff --git a/docs/manual.rst b/docs/manual.rst index de1780679..825ee3d88 100644 --- a/docs/manual.rst +++ b/docs/manual.rst @@ -211,257 +211,6 @@ It contains the following fields:: tcp::endpoint local_endpoint; }; -The ``flags`` attribute tells you in which state the peer is. It is set to -any combination of the enums above. The following table describes each flag: - -+-------------------------+-------------------------------------------------------+ -| ``interesting`` | **we** are interested in pieces from this peer. | -+-------------------------+-------------------------------------------------------+ -| ``choked`` | **we** have choked this peer. | -+-------------------------+-------------------------------------------------------+ -| ``remote_interested`` | the peer is interested in **us** | -+-------------------------+-------------------------------------------------------+ -| ``remote_choked`` | the peer has choked **us**. | -+-------------------------+-------------------------------------------------------+ -| ``support_extensions`` | means that this peer supports the | -| | `extension protocol`__. | -+-------------------------+-------------------------------------------------------+ -| ``local_connection`` | The connection was initiated by us, the peer has a | -| | listen port open, and that port is the same as in the | -| | address of this peer. If this flag is not set, this | -| | peer connection was opened by this peer connecting to | -| | us. | -+-------------------------+-------------------------------------------------------+ -| ``handshake`` | The connection is opened, and waiting for the | -| | handshake. Until the handshake is done, the peer | -| | cannot be identified. | -+-------------------------+-------------------------------------------------------+ -| ``connecting`` | The connection is in a half-open state (i.e. it is | -| | being connected). | -+-------------------------+-------------------------------------------------------+ -| ``queued`` | The connection is currently queued for a connection | -| | attempt. This may happen if there is a limit set on | -| | the number of half-open TCP connections. | -+-------------------------+-------------------------------------------------------+ -| ``on_parole`` | The peer has participated in a piece that failed the | -| | hash check, and is now "on parole", which means we're | -| | only requesting whole pieces from this peer until | -| | it either fails that piece or proves that it doesn't | -| | send bad data. | -+-------------------------+-------------------------------------------------------+ -| ``seed`` | This peer is a seed (it has all the pieces). | -+-------------------------+-------------------------------------------------------+ -| ``optimistic_unchoke`` | This peer is subject to an optimistic unchoke. It has | -| | been unchoked for a while to see if it might unchoke | -| | us in return an earn an upload/unchoke slot. If it | -| | doesn't within some period of time, it will be choked | -| | and another peer will be optimistically unchoked. | -+-------------------------+-------------------------------------------------------+ -| ``snubbed`` | This peer has recently failed to send a block within | -| | the request timeout from when the request was sent. | -| | We're currently picking one block at a time from this | -| | peer. | -+-------------------------+-------------------------------------------------------+ -| ``upload_only`` | This peer has either explicitly (with an extension) | -| | or implicitly (by becoming a seed) told us that it | -| | will not downloading anything more, regardless of | -| | which pieces we have. | -+-------------------------+-------------------------------------------------------+ -| ``endgame_mode`` | This means the last time this peer picket a piece, | -| | it could not pick as many as it wanted because there | -| | were not enough free ones. i.e. all pieces this peer | -| | has were already requested from other peers. | -+-------------------------+-------------------------------------------------------+ -| ``holepunched`` | This flag is set if the peer was in holepunch mode | -| | when the connection succeeded. This typically only | -| | happens if both peers are behind a NAT and the peers | -| | connect via the NAT holepunch mechanism. | -+-------------------------+-------------------------------------------------------+ - -__ extension_protocol.html - -``source`` is a combination of flags describing from which sources this peer -was received. The flags are: - -+------------------------+--------------------------------------------------------+ -| ``tracker`` | The peer was received from the tracker. | -+------------------------+--------------------------------------------------------+ -| ``dht`` | The peer was received from the kademlia DHT. | -+------------------------+--------------------------------------------------------+ -| ``pex`` | The peer was received from the peer exchange | -| | extension. | -+------------------------+--------------------------------------------------------+ -| ``lsd`` | The peer was received from the local service | -| | discovery (The peer is on the local network). | -+------------------------+--------------------------------------------------------+ -| ``resume_data`` | The peer was added from the fast resume data. | -+------------------------+--------------------------------------------------------+ - -``read_state`` and ``write_state`` are bitmasks indicating what state this peer -is in with regards to sending and receiving data. The states are declared in the -``bw_state`` enum and defines as follows: - -+------------------------+--------------------------------------------------------+ -| ``bw_idle`` | The peer is not waiting for any external events to | -| | send or receive data. | -| | | -+------------------------+--------------------------------------------------------+ -| ``bw_limit`` | The peer is waiting for the rate limiter. | -| | | -+------------------------+--------------------------------------------------------+ -| ``bw_network`` | The peer has quota and is currently waiting for a | -| | network read or write operation to complete. This is | -| | the state all peers are in if there are no bandwidth | -| | limits. | -| | | -+------------------------+--------------------------------------------------------+ -| ``bw_disk`` | The peer is waiting for the disk I/O thread to catch | -| | up writing buffers to disk before downloading more. | -| | | -+------------------------+--------------------------------------------------------+ - -Note that ``read_state`` and ``write_state`` are bitmasks. A peer may be waiting -on disk and on the network at the same time. ``bw_idle`` does not represent a bit, -but is simply a name for no bit being set in the bitmask. - -The ``ip`` field is the IP-address to this peer. The type is an asio endpoint. For -more info, see the asio_ documentation. - -.. _asio: http://asio.sf.net - -``up_speed`` and ``down_speed`` contains the current upload and download speed -we have to and from this peer (including any protocol messages). The transfer rates -of payload data only are found in ``payload_up_speed`` and ``payload_down_speed``. -These figures are updated approximately once every second. - -``total_download`` and ``total_upload`` are the total number of bytes downloaded -from and uploaded to this peer. These numbers do not include the protocol chatter, but only -the payload data. - -``pid`` is the peer's id as used in the bit torrent protocol. This id can be used to -extract 'fingerprints' from the peer. Sometimes it can tell you which client the peer -is using. See identify_client()_ - -``pieces`` is a bitfield, with one bit per piece in the torrent. -Each bit tells you if the peer has that piece (if it's set to 1) -or if the peer miss that piece (set to 0). - -``seed`` is true if this peer is a seed. - -``upload_limit`` is the number of bytes per second we are allowed to send to this -peer every second. It may be -1 if there's no local limit on the peer. The global -limit and the torrent limit is always enforced anyway. - -``download_limit`` is the number of bytes per second this peer is allowed to -receive. -1 means it's unlimited. - -``last_request`` and ``last_active`` is the time since we last sent a request -to this peer and since any transfer occurred with this peer, respectively. - -``request_timeout`` is the number of seconds until the current front piece request -will time out. This timeout can be adjusted through ``session_settings::request_timeout``. --1 means that there is not outstanding request. - -``send_buffer_size`` and ``used_send_buffer`` is the number of bytes allocated -and used for the peer's send buffer, respectively. - -``receive_buffer_size`` and ``used_receive_buffer`` are the number of bytes -allocated and used as receive buffer, respectively. - -``num_hashfails`` is the number of pieces this peer has participated in -sending us that turned out to fail the hash check. - -``country`` is the two letter `ISO 3166 country code`__ for the country the peer -is connected from. If the country hasn't been resolved yet, both chars are set -to 0. If the resolution failed for some reason, the field is set to "--". If the -resolution service returns an invalid country code, it is set to "!!". -The ``countries.nerd.dk`` service is used to look up countries. This field will -remain set to 0 unless the torrent is set to resolve countries, see `resolve_countries()`_. - -__ http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html - -``inet_as_name`` is the name of the AS this peer is located in. This might be -an empty string if there is no name in the geo ip database. - -``inet_as`` is the AS number the peer is located in. - -``load_balancing`` is a measurement of the balancing of free download (that we get) -and free upload that we give. Every peer gets a certain amount of free upload, but -this member says how much *extra* free upload this peer has got. If it is a negative -number it means that this was a peer from which we have got this amount of free -download. - -``requests_in_buffer`` is the number of requests messages that are currently in the -send buffer waiting to be sent. - -``download_queue_length`` is the number of piece-requests we have sent to this peer -that hasn't been answered with a piece yet. - -``upload_queue_length`` is the number of piece-requests we have received from this peer -that we haven't answered with a piece yet. - -``failcount`` is the number of times this peer has "failed". i.e. failed to connect -or disconnected us. The failcount is decremented when we see this peer in a tracker -response or peer exchange message. - -You can know which piece, and which part of that piece, that is currently being -downloaded from a specific peer by looking at the next four members. -``downloading_piece_index`` is the index of the piece that is currently being downloaded. -This may be set to -1 if there's currently no piece downloading from this peer. If it is ->= 0, the other three members are valid. ``downloading_block_index`` is the index of the -block (or sub-piece) that is being downloaded. ``downloading_progress`` is the number -of bytes of this block we have received from the peer, and ``downloading_total`` is -the total number of bytes in this block. - -``client`` is a string describing the software at the other end of the connection. -In some cases this information is not available, then it will contain a string -that may give away something about which software is running in the other end. -In the case of a web seed, the server type and version will be a part of this -string. - -``connection_type`` can currently be one of: - -+---------------------------------------+-------------------------------------------------------+ -| type | meaning | -+=======================================+=======================================================+ -| ``peer_info::standard_bittorrent`` | Regular bittorrent connection over TCP | -+---------------------------------------+-------------------------------------------------------+ -| ``peer_info::bittorrent_utp`` | Bittorrent connection over uTP | -+---------------------------------------+-------------------------------------------------------+ -| ``peer_info::web_sesed`` | HTTP connection using the `BEP 19`_ protocol | -+---------------------------------------+-------------------------------------------------------+ -| ``peer_info::http_seed`` | HTTP connection using the `BEP 17`_ protocol | -+---------------------------------------+-------------------------------------------------------+ - -``remote_dl_rate`` is an estimate of the rate this peer is downloading at, in -bytes per second. - -``pending_disk_bytes`` is the number of bytes this peer has pending in the -disk-io thread. Downloaded and waiting to be written to disk. This is what -is capped by ``session_settings::max_queued_disk_bytes``. - -``send_quota`` and ``receive_quota`` are the number of bytes this peer has been -assigned to be allowed to send and receive until it has to request more quota -from the bandwidth manager. - -``rtt`` is an estimated round trip time to this peer, in milliseconds. It is -estimated by timing the the tcp ``connect()``. It may be 0 for incoming connections. - -``num_pieces`` is the number of pieces this peer has. - -``download_rate_peak`` and ``upload_rate_peak`` are the highest download and upload -rates seen on this connection. They are given in bytes per second. This number is -reset to 0 on reconnect. - -``progress`` is the progress of the peer in the range [0, 1]. This is always 0 when -floating point operations are diabled, instead use ``progress_ppm``. - -``progress_ppm`` indicates the download progress of the peer in the range [0, 1000000] -(parts per million). - -``local_endpoint`` is the IP and port pair the socket is bound to locally. i.e. the IP -address of the interface it's going out over. This may be useful for multi-homed -clients with multiple interfaces to the internet. feed_handle =========== diff --git a/include/libtorrent/peer_info.hpp b/include/libtorrent/peer_info.hpp index 705a762fc..dbc436a3b 100644 --- a/include/libtorrent/peer_info.hpp +++ b/include/libtorrent/peer_info.hpp @@ -44,73 +44,193 @@ namespace libtorrent { struct TORRENT_EXPORT peer_info { - enum + enum peer_flags_t { + // **we** are interested in pieces from this peer. interesting = 0x1, + + // **we** have choked this peer. choked = 0x2, + + // the peer is interested in **us** remote_interested = 0x4, + + // the peer has choked **us**. remote_choked = 0x8, + + // means that this peer supports the + // `extension protocol`__. + // + // __ extension_protocol.html supports_extensions = 0x10, + + // The connection was initiated by us, the peer has a + // listen port open, and that port is the same as in the + // address of this peer. If this flag is not set, this + // peer connection was opened by this peer connecting to + // us. local_connection = 0x20, + + // The connection is opened, and waiting for the + // handshake. Until the handshake is done, the peer + // cannot be identified. handshake = 0x40, + + // The connection is in a half-open state (i.e. it is + // being connected). connecting = 0x80, + + // The connection is currently queued for a connection + // attempt. This may happen if there is a limit set on + // the number of half-open TCP connections. queued = 0x100, + + // The peer has participated in a piece that failed the + // hash check, and is now "on parole", which means we're + // only requesting whole pieces from this peer until + // it either fails that piece or proves that it doesn't + // send bad data. on_parole = 0x200, + + // This peer is a seed (it has all the pieces). seed = 0x400, + + // This peer is subject to an optimistic unchoke. It has + // been unchoked for a while to see if it might unchoke + // us in return an earn an upload/unchoke slot. If it + // doesn't within some period of time, it will be choked + // and another peer will be optimistically unchoked. optimistic_unchoke = 0x800, + + // This peer has recently failed to send a block within + // the request timeout from when the request was sent. + // We're currently picking one block at a time from this + // peer. snubbed = 0x1000, + + // This peer has either explicitly (with an extension) + // or implicitly (by becoming a seed) told us that it + // will not downloading anything more, regardless of + // which pieces we have. upload_only = 0x2000, + + // This means the last time this peer picket a piece, + // it could not pick as many as it wanted because there + // were not enough free ones. i.e. all pieces this peer + // has were already requested from other peers. endgame_mode = 0x4000, + + // This flag is set if the peer was in holepunch mode + // when the connection succeeded. This typically only + // happens if both peers are behind a NAT and the peers + // connect via the NAT holepunch mechanism. holepunched = 0x8000, rc4_encrypted = 0x100000, plaintext_encrypted = 0x200000 }; + // tells you in which state the peer is in. It is set to + // any combination of the peer_flags_t enum. unsigned int flags; enum peer_source_flags { + // The peer was received from the tracker. tracker = 0x1, + + // The peer was received from the kademlia DHT. dht = 0x2, + + // The peer was received from the peer exchange + // extension. pex = 0x4, + + // The peer was received from the local service + // discovery (The peer is on the local network). lsd = 0x8, + + // The peer was added from the fast resume data. resume_data = 0x10, + + // we received an incoming connection from this peer incoming = 0x20 }; + // a combination of flags describing from which sources this peer + // was received. int source; - // bw_idle: the channel is not used - // bw_limit: the channel is waiting for quota - // bw_network: the channel is waiting for an async write - // or read operation to complete - // bw_disk: the peer is waiting for the disk io thread - // this is a bitmask, a peer can wait for network, rate-limiter - // and disk at the same time! - enum bw_state { bw_idle = 0, bw_limit = 1, bw_network = 2, bw_disk = 4 }; + // bits for the read_state and write_state + enum bw_state + { + // The peer is not waiting for any external events to + // send or receive data. + bw_idle = 0, + + // The peer is waiting for the rate limiter. + bw_limit = 1, + + // The peer has quota and is currently waiting for a + // network read or write operation to complete. This is + // the state all peers are in if there are no bandwidth + // limits. + bw_network = 2, + + // The peer is waiting for the disk I/O thread to catch + // up writing buffers to disk before downloading more. + bw_disk = 4 + }; #ifndef TORRENT_NO_DEPRECATE enum bw_state_deprecated { bw_torrent = bw_limit, bw_global = bw_limit }; #endif + // bitmasks indicating what state this peer + // is in with regards to sending and receiving data. The states are declared in the + // bw_state enum. char read_state; char write_state; + // the IP-address to this peer. The type is an asio endpoint. For + // more info, see the asio_ documentation. tcp::endpoint ip; + + // the current upload and download speed + // we have to and from this peer (including any protocol messages). + // updated about once per second int up_speed; int down_speed; + + // The transfer rates + // of payload data only + // updated about once per second int payload_up_speed; int payload_down_speed; + + // the total number of bytes downloaded + // from and uploaded to this peer. These numbers do not include the protocol chatter, but only + // the payload data. size_type total_download; size_type total_upload; + + // the peer's id as used in the bit torrent protocol. This id can be used to + // extract 'fingerprints' from the peer. Sometimes it can tell you which client the peer + // is using. See identify_client()_ peer_id pid; + + // a bitfield, with one bit per piece in the torrent. + // Each bit tells you if the peer has that piece (if it's set to 1) + // or if the peer miss that piece (set to 0). bitfield pieces; + + // the number of bytes per second we are allowed to send to or receive from this + // peer. It may be -1 if there's no local limit on the peer. The global + // limit and the torrent limit may also be enforced. int upload_limit; int download_limit; - // time since last request + // the time since we last sent a request + // to this peer and since any transfer occurred with this peer time_duration last_request; - - // time since last download or upload time_duration last_active; // the time until all blocks in the request @@ -118,33 +238,49 @@ namespace libtorrent time_duration download_queue_time; int queue_bytes; - // the number of seconds until the current - // pending request times out + // the number of seconds until the current front piece request + // will time out. This timeout can be adjusted through ``session_settings::request_timeout``. + // -1 means that there is not outstanding request. int request_timeout; - // the size of the send buffer for this peer, in bytes + // the number of bytes allocated + // and used for the peer's send buffer, respectively. int send_buffer_size; - // the number bytes that's actually used of the send buffer int used_send_buffer; + // the number of bytes + // allocated and used as receive buffer, respectively. int receive_buffer_size; int used_receive_buffer; - // the number of failed hashes for this peer + // the number of pieces this peer has participated in + // sending us that turned out to fail the hash check. int num_hashfails; - // in case the session settings is set - // to resolve countries, this is set to - // the two character country code this - // peer resides in. + // the two letter `ISO 3166 country code`__ for the country the peer + // is connected from. If the country hasn't been resolved yet, both chars are set + // to 0. If the resolution failed for some reason, the field is set to "--". If the + // resolution service returns an invalid country code, it is set to "!!". + // The ``countries.nerd.dk`` service is used to look up countries. This field will + // remain set to 0 unless the torrent is set to resolve countries, see `resolve_countries()`_. + // + // __ http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html char country[2]; #ifndef TORRENT_DISABLE_GEO_IP - // atonomous system this peer belongs to + // the name of the AS this peer is located in. This might be + // an empty string if there is no name in the geo ip database. std::string inet_as_name; + + // the AS number the peer is located in. int inet_as; #endif + // a measurement of the balancing of free download (that we get) + // and free upload that we give. Every peer gets a certain amount of free upload, but + // this member says how much *extra* free upload this peer has got. If it is a negative + // number it means that this was a peer from which we have got this amount of free + // download. size_type load_balancing; // this is the number of requests @@ -163,8 +299,8 @@ namespace libtorrent // we've also requested from a different peer int busy_requests; - // the number of request messages - // waiting to be sent inside the send buffer + // the number of requests messages that are currently in the + // send buffer waiting to be sent. int requests_in_buffer; // the number of requests that is @@ -172,61 +308,94 @@ namespace libtorrent // typically a function of download speed) int target_dl_queue_length; - // this is the number of requests - // the peer has sent to us - // that we haven't sent yet + // the number of piece-requests we have received from this peer + // that we haven't answered with a piece yet. int upload_queue_length; - // the number of times this IP - // has failed to connect + // the number of times this peer has "failed". i.e. failed to connect + // or disconnected us. The failcount is decremented when we see this peer in a tracker + // response or peer exchange message. int failcount; - // the currently downloading piece - // if piece index is -1 all associated - // members are just set to 0 + // You can know which piece, and which part of that piece, that is currently being + // downloaded from a specific peer by looking at these four members. + // ``downloading_piece_index`` is the index of the piece that is currently being downloaded. + // This may be set to -1 if there's currently no piece downloading from this peer. If it is + // >= 0, the other three members are valid. ``downloading_block_index`` is the index of the + // block (or sub-piece) that is being downloaded. ``downloading_progress`` is the number + // of bytes of this block we have received from the peer, and ``downloading_total`` is + // the total number of bytes in this block. int downloading_piece_index; int downloading_block_index; int downloading_progress; int downloading_total; - + + // a string describing the software at the other end of the connection. + // In some cases this information is not available, then it will contain a string + // that may give away something about which software is running in the other end. + // In the case of a web seed, the server type and version will be a part of this + // string. std::string client; - enum + enum connection_type_t { + // Regular bittorrent connection over TCP standard_bittorrent = 0, + + // Bittorrent connection over uTP web_seed = 1, + + // HTTP connection using the `BEP 19`_ protocol http_seed = 2, + + // HTTP connection using the `BEP 17`_ protocol bittorrent_utp = 3 }; + + // the kind of connection this peer uses. See connection_type_t. int connection_type; - // approximate peer download rate + // an estimate of the rate this peer is downloading at, in + // bytes per second. int remote_dl_rate; - // number of bytes this peer has in - // the disk write queue + // the number of bytes this peer has pending in the + // disk-io thread. Downloaded and waiting to be written to disk. This is what + // is capped by ``session_settings::max_queued_disk_bytes``. int pending_disk_bytes; - // numbers used for bandwidth limiting + // the number of bytes this peer has been + // assigned to be allowed to send and receive until it has to request more quota + // from the bandwidth manager. int send_quota; int receive_quota; - // estimated rtt to peer, in milliseconds + // an estimated round trip time to this peer, in milliseconds. It is + // estimated by timing the the tcp ``connect()``. It may be 0 for incoming connections. int rtt; - // the number of pieces this peer has + // the number of pieces this peer has. int num_pieces; - // the highest transfer rates seen for this peer + // the highest download and upload + // rates seen on this connection. They are given in bytes per second. This number is + // reset to 0 on reconnect. int download_rate_peak; int upload_rate_peak; - // the peer's progress + // the progress of the peer in the range [0, 1]. This is always 0 when + // floating point operations are diabled, instead use ``progress_ppm``. float progress; // [0, 1] - int progress_ppm; // [0, 1000000] + + // indicates the download progress of the peer in the range [0, 1000000] + // (parts per million). + int progress_ppm; int estimated_reciprocation_rate; + // the IP and port pair the socket is bound to locally. i.e. the IP + // address of the interface it's going out over. This may be useful for multi-homed + // clients with multiple interfaces to the internet. tcp::endpoint local_endpoint; };