| Version: | 2.0.11 |
|---|
Table of contents
torrent_status
Declared in "libtorrent/torrent_status.hpp"
holds a snapshot of the status of a torrent, as queried by torrent_handle::status().
struct torrent_status
{
bool operator== (torrent_status const& st) const;
enum state_t
{
checking_files,
downloading_metadata,
downloading,
finished,
seeding,
unused_enum_for_backwards_compatibility_allocating,
checking_resume_data,
};
torrent_handle handle;
error_code errc;
file_index_t error_file = torrent_status::error_file_none;
static constexpr file_index_t error_file_none {-1};
static constexpr file_index_t error_file_ssl_ctx {-3};
static constexpr file_index_t error_file_metadata {-4};
static constexpr file_index_t error_file_exception {-5};
static constexpr file_index_t error_file_partfile {-6};
std::string save_path;
std::string name;
std::weak_ptr<const torrent_info> torrent_file;
time_duration next_announce = seconds{0};
std::string current_tracker;
std::int64_t total_download = 0;
std::int64_t total_upload = 0;
std::int64_t total_payload_download = 0;
std::int64_t total_payload_upload = 0;
std::int64_t total_failed_bytes = 0;
std::int64_t total_redundant_bytes = 0;
typed_bitfield<piece_index_t> pieces;
typed_bitfield<piece_index_t> verified_pieces;
std::int64_t total_done = 0;
std::int64_t total = 0;
std::int64_t total_wanted_done = 0;
std::int64_t total_wanted = 0;
std::int64_t all_time_upload = 0;
std::int64_t all_time_download = 0;
std::time_t added_time = 0;
std::time_t completed_time = 0;
std::time_t last_seen_complete = 0;
storage_mode_t storage_mode = storage_mode_sparse;
float progress = 0.f;
int progress_ppm = 0;
queue_position_t queue_position {};
int download_rate = 0;
int upload_rate = 0;
int download_payload_rate = 0;
int upload_payload_rate = 0;
int num_seeds = 0;
int num_peers = 0;
int num_complete = -1;
int num_incomplete = -1;
int list_seeds = 0;
int list_peers = 0;
int connect_candidates = 0;
int num_pieces = 0;
int distributed_full_copies = 0;
int distributed_fraction = 0;
float distributed_copies = 0.f;
int block_size = 0;
int num_uploads = 0;
int num_connections = 0;
int uploads_limit = 0;
int connections_limit = 0;
int up_bandwidth_queue = 0;
int down_bandwidth_queue = 0;
int seed_rank = 0;
state_t state = checking_resume_data;
bool need_save_resume = false;
bool is_seeding = false;
bool is_finished = false;
bool has_metadata = false;
bool has_incoming = false;
bool moving_storage = false;
bool announcing_to_trackers = false;
bool announcing_to_lsd = false;
bool announcing_to_dht = false;
info_hash_t info_hashes;
time_point last_upload;
time_point last_download;
seconds active_duration;
seconds finished_duration;
seconds seeding_duration;
torrent_flags_t flags {};
};
[report issue]operator==()
bool operator== (torrent_status const& st) const;
compares if the torrent status objects come from the same torrent. i.e. only the torrent_handle field is compared.
[report issue]enum state_t
Declared in "libtorrent/torrent_status.hpp"
| name | value | description |
|---|---|---|
| checking_files | 1 | The torrent has not started its download yet, and is currently checking existing files. |
| downloading_metadata | 2 | The torrent is trying to download metadata from peers. This implies the ut_metadata extension is in use. |
| downloading | 3 | The torrent is being downloaded. This is the state most torrents will be in most of the time. The progress meter will tell how much of the files that has been downloaded. |
| finished | 4 | In this state the torrent has finished downloading but still doesn't have the entire torrent. i.e. some pieces are filtered and won't get downloaded. |
| seeding | 5 | In this state the torrent has finished downloading and is a pure seeder. |
| unused_enum_for_backwards_compatibility_allocating | 6 | If the torrent was started in full allocation mode, this indicates that the (disk) storage for the torrent is allocated. |
| checking_resume_data | 7 | The torrent is currently checking the fast resume data and comparing it to the files on disk. This is typically completed in a fraction of a second, but if you add a large number of torrents at once, they will queue up. |
- handle
- a handle to the torrent whose status the object represents.
- errc
- may be set to an error code describing why the torrent was paused, in case it was paused by an error. If the torrent is not paused or if it's paused but not because of an error, this error_code is not set. if the error is attributed specifically to a file, error_file is set to the index of that file in the .torrent file.
- error_file
- if the torrent is stopped because of an disk I/O error, this field contains the index of the file in the torrent that encountered the error. If the error did not originate in a file in the torrent, there are a few special values this can be set to: error_file_none, error_file_ssl_ctx, error_file_exception, error_file_partfile or error_file_metadata;
- error_file_none
- special values for error_file to describe which file or component encountered the error (errc). the error did not occur on a file
- error_file_ssl_ctx
- the error occurred setting up the SSL context
- error_file_metadata
- the error occurred while loading the metadata for the torrent
- error_file_exception
- there was a serious error reported in this torrent. The error code or a torrent log alert may provide more information.
- error_file_partfile
- the error occurred with the partfile
- save_path
- the path to the directory where this torrent's files are stored. It's typically the path as was given to async_add_torrent() or add_torrent() when this torrent was started. This field is only included if the torrent status is queried with torrent_handle::query_save_path.
- name
- the name of the torrent. Typically this is derived from the .torrent file. In case the torrent was started without metadata, and hasn't completely received it yet, it returns the name given to it when added to the session. See session::add_torrent. This field is only included if the torrent status is queried with torrent_handle::query_name.
- torrent_file
- set to point to the torrent_info object for this torrent. It's only included if the torrent status is queried with torrent_handle::query_torrent_file.
- next_announce
- the time until the torrent will announce itself to the tracker.
- current_tracker
- the URL of the last working tracker. If no tracker request has been successful yet, it's set to an empty string.
- total_download total_upload
- the number of bytes downloaded and uploaded to all peers, accumulated, this session only. The session is considered to restart when a torrent is paused and restarted again. When a torrent is paused, these counters are reset to 0. If you want complete, persistent, stats, see all_time_upload and all_time_download.
- total_payload_download total_payload_upload
- counts the amount of bytes send and received this session, but only the actual payload data (i.e the interesting data), these counters ignore any protocol overhead. The session is considered to restart when a torrent is paused and restarted again. When a torrent is paused, these counters are reset to 0.
- total_failed_bytes
- the number of bytes that has been downloaded and that has failed the piece hash test. In other words, this is just how much crap that has been downloaded since the torrent was last started. If a torrent is paused and then restarted again, this counter will be reset.
- total_redundant_bytes
- the number of bytes that has been downloaded even though that data already was downloaded. The reason for this is that in some situations the same data can be downloaded by mistake. When libtorrent sends requests to a peer, and the peer doesn't send a response within a certain timeout, libtorrent will re-request that block. Another situation when libtorrent may re-request blocks is when the requests it sends out are not replied in FIFO-order (it will re-request blocks that are skipped by an out of order block). This is supposed to be as low as possible. This only counts bytes since the torrent was last started. If a torrent is paused and then restarted again, this counter will be reset.
- pieces
- a bitmask that represents which pieces we have (set to true) and the pieces we don't have. It's a pointer and may be set to 0 if the torrent isn't downloading or seeding.
- verified_pieces
- a bitmask representing which pieces has had their hash checked. This only applies to torrents in seed mode. If the torrent is not in seed mode, this bitmask may be empty.
- total_done
- the total number of bytes of the file(s) that we have. All this does not necessarily has to be downloaded during this session (that's total_payload_download).
- total
- the total number of bytes to download for this torrent. This may be less than the size of the torrent in case there are pad files. This number only counts bytes that will actually be requested from peers.
- total_wanted_done
- the number of bytes we have downloaded, only counting the pieces that we actually want to download. i.e. excluding any pieces that we have but have priority 0 (i.e. not wanted). Once a torrent becomes seed, any piece- and file priorities are forgotten and all bytes are considered "wanted".
- total_wanted
- The total number of bytes we want to download. This may be smaller than the total torrent size in case any pieces are prioritized to 0, i.e. not wanted. Once a torrent becomes seed, any piece- and file priorities are forgotten and all bytes are considered "wanted".
- all_time_upload all_time_download
- are accumulated upload and download payload byte counters. They are saved in and restored from resume data to keep totals across sessions.
- added_time
- the posix-time when this torrent was added. i.e. what time(nullptr) returned at the time.
- completed_time
- the posix-time when this torrent was finished. If the torrent is not yet finished, this is 0.
- last_seen_complete
- the time when we, or one of our peers, last saw a complete copy of this torrent.
- storage_mode
- The allocation mode for the torrent. See storage_mode_t for the options. For more information, see storage allocation.
- progress
- a value in the range [0, 1], that represents the progress of the torrent's current task. It may be checking files or downloading.
- progress_ppm
progress parts per million (progress * 1000000) when disabling floating point operations, this is the only option to query progress
reflects the same value as progress, but instead in a range [0, 1000000] (ppm = parts per million). When floating point operations are disabled, this is the only alternative to the floating point value in progress.
- queue_position
- the position this torrent has in the download queue. If the torrent is a seed or finished, this is -1.
- download_rate upload_rate
- the total rates for all peers for this torrent. These will usually have better precision than summing the rates from all peers. The rates are given as the number of bytes per second.
- download_payload_rate upload_payload_rate
- the total transfer rate of payload only, not counting protocol chatter. This might be slightly smaller than the other rates, but if projected over a long time (e.g. when calculating ETA:s) the difference may be noticeable.
- num_seeds
- the number of peers that are seeding that this client is currently connected to.
- num_peers
- the number of peers this torrent currently is connected to. Peer connections that are in the half-open state (is attempting to connect) or are queued for later connection attempt do not count. Although they are visible in the peer list when you call get_peer_info().
- num_complete num_incomplete
- if the tracker sends scrape info in its announce reply, these fields will be set to the total number of peers that have the whole file and the total number of peers that are still downloading. set to -1 if the tracker did not send any scrape data in its announce reply.
- list_seeds list_peers
- the number of seeds in our peer list and the total number of peers (including seeds). We are not necessarily connected to all the peers in our peer list. This is the number of peers we know of in total, including banned peers and peers that we have failed to connect to.
- connect_candidates
- the number of peers in this torrent's peer list that is a candidate to be connected to. i.e. It has fewer connect attempts than the max fail count, it is not a seed if we are a seed, it is not banned etc. If this is 0, it means we don't know of any more peers that we can try.
- num_pieces
- the number of pieces that has been downloaded. It is equivalent to: std::accumulate(pieces->begin(), pieces->end()). So you don't have to count yourself. This can be used to see if anything has updated since last time if you want to keep a graph of the pieces up to date. Note that these pieces have not necessarily been written to disk yet, and there is a risk the write to disk will fail.
- distributed_full_copies
- the number of distributed copies of the torrent. Note that one copy may be spread out among many peers. It tells how many copies there are currently of the rarest piece(s) among the peers this client is connected to.
- distributed_fraction
tells the share of pieces that have more copies than the rarest piece(s). Divide this number by 1000 to get the fraction.
For example, if distributed_full_copies is 2 and distributed_fraction is 500, it means that the rarest pieces have only 2 copies among the peers this torrent is connected to, and that 50% of all the pieces have more than two copies.
If we are a seed, the piece picker is deallocated as an optimization, and piece availability is no longer tracked. In this case the distributed copies members are set to -1.
- distributed_copies
the number of distributed copies of the file. note that one copy may be spread out among many peers. This is a floating point representation of the distributed copies.
- the integer part tells how many copies
- there are of the rarest piece(s)
- the fractional part tells the fraction of pieces that
- have more copies than the rarest piece(s).
- block_size
- the size of a block, in bytes. A block is a sub piece, it is the number of bytes that each piece request asks for and the number of bytes that each bit in the partial_piece_info's bitset represents, see get_download_queue(). This is typically 16 kB, but it may be smaller, if the pieces are smaller.
- num_uploads
- the number of unchoked peers in this torrent.
- num_connections
- the number of peer connections this torrent has, including half-open connections that hasn't completed the bittorrent handshake yet. This is always >= num_peers.
- uploads_limit
- the set limit of upload slots (unchoked peers) for this torrent.
- connections_limit
- the set limit of number of connections for this torrent.
- up_bandwidth_queue down_bandwidth_queue
- the number of peers in this torrent that are waiting for more bandwidth quota from the torrent rate limiter. This can determine if the rate you get from this torrent is bound by the torrents limit or not. If there is no limit set on this torrent, the peers might still be waiting for bandwidth quota from the global limiter, but then they are counted in the session_status object.
- seed_rank
- A rank of how important it is to seed the torrent, it is used to determine which torrents to seed and which to queue. It is based on the peer to seed ratio from the tracker scrape. For more information, see queuing. Higher value means more important to seed
- state
- the main state the torrent is in. See torrent_status::state_t.
- need_save_resume
- true if this torrent has unsaved changes to its download state and statistics since the last resume data was saved.
- is_seeding
- true if all pieces have been downloaded.
- is_finished
- true if all pieces that have a priority > 0 are downloaded. There is only a distinction between finished and seeding if some pieces or files have been set to priority 0, i.e. are not downloaded.
- has_metadata
- true if this torrent has metadata (either it was started from a .torrent file or the metadata has been downloaded). The only scenario where this can be false is when the torrent was started torrent-less (i.e. with just an info-hash and tracker ip, a magnet link for instance).
- has_incoming
- true if there has ever been an incoming connection attempt to this torrent.
- moving_storage
- this is true if this torrent's storage is currently being moved from one location to another. This may potentially be a long operation if a large file ends up being copied from one drive to another.
- announcing_to_trackers announcing_to_lsd announcing_to_dht
- these are set to true if this torrent is allowed to announce to the respective peer source. Whether they are true or false is determined by the queue logic/auto manager. Torrents that are not auto managed will always be allowed to announce to all peer sources.
- info_hashes
- the info-hash for this torrent
- last_upload last_download
- the timestamps of the last time this torrent uploaded or downloaded payload to any peer.
- active_duration finished_duration seeding_duration
- these are cumulative counters of for how long the torrent has been in different states. active means not paused and added to session. Whether it has found any peers or not is not relevant. finished means all selected files/pieces were downloaded and available to other peers (this is always a subset of active time). seeding means all files/pieces were downloaded and available to peers. Being available to peers does not imply there are other peers asking for the payload.
- flags
- reflects several of the torrent's flags. For more information, see torrent_handle::flags().