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. |
[report issue]
- handle
- a handle to the torrent whose status the object represents.
[report issue]
- 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.
[report issue]
- 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;
[report issue]
- 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
[report issue]
- error_file_ssl_ctx
- the error occurred setting up the SSL context
[report issue]
- error_file_metadata
- the error occurred while loading the metadata for the torrent
[report issue]
- error_file_exception
- there was a serious error reported in this torrent. The error code
or a torrent log alert may provide more information.
[report issue]
- error_file_partfile
- the error occurred with the partfile
[report issue]
- 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.
[report issue]
- 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.
[report issue]
- 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.
[report issue]
- next_announce
- the time until the torrent will announce itself to the tracker.
[report issue]
- current_tracker
- the URL of the last working tracker. If no tracker request has
been successful yet, it's set to an empty string.
[report issue]
- 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.
[report issue]
- 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.
[report issue]
- 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.
[report issue]
- 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.
[report issue]
- 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.
[report issue]
- 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.
[report issue]
- 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).
[report issue]
- 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.
[report issue]
- 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".
[report issue]
- 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".
[report issue]
- 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.
[report issue]
- added_time
- the posix-time when this torrent was added. i.e. what time(nullptr)
returned at the time.
[report issue]
- completed_time
- the posix-time when this torrent was finished. If the torrent is not
yet finished, this is 0.
[report issue]
- last_seen_complete
- the time when we, or one of our peers, last saw a complete copy of
this torrent.
[report issue]
- storage_mode
- The allocation mode for the torrent. See storage_mode_t for the
options. For more information, see storage allocation.
[report issue]
- 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.
[report issue]
- 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.
[report issue]
- queue_position
- the position this torrent has in the download
queue. If the torrent is a seed or finished, this is -1.
[report issue]
- 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.
[report issue]
- 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.
[report issue]
- num_seeds
- the number of peers that are seeding that this client is
currently connected to.
[report issue]
- 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().
[report issue]
- 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.
[report issue]
- 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.
[report issue]
- 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.
[report issue]
- 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.
[report issue]
- 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.
[report issue]
- 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.
[report issue]
- 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).
[report issue]
- 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.
[report issue]
- num_uploads
- the number of unchoked peers in this torrent.
[report issue]
- 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.
[report issue]
- uploads_limit
- the set limit of upload slots (unchoked peers) for this torrent.
[report issue]
- connections_limit
- the set limit of number of connections for this torrent.
[report issue]
- 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.
[report issue]
- 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
[report issue]
- state
- the main state the torrent is in. See torrent_status::state_t.
[report issue]
- need_save_resume
- true if this torrent has unsaved changes
to its download state and statistics since the last resume data
was saved.
[report issue]
- is_seeding
- true if all pieces have been downloaded.
[report issue]
- 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.
[report issue]
- 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).
[report issue]
- has_incoming
- true if there has ever been an incoming connection attempt to this
torrent.
[report issue]
- 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.
[report issue]
- 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.
[report issue]
- info_hashes
- the info-hash for this torrent
[report issue]
- last_upload last_download
- the timestamps of the last time this torrent uploaded or downloaded
payload to any peer.
[report issue]
- 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.
[report issue]
- flags
- reflects several of the torrent's flags. For more
information, see torrent_handle::flags().