libtorrent
Description: A feature complete BitTorrent protocol implementation as a C++ library

Version: | 2.0.8

home

Table of contents

- torrent_status
  - operator==()
  - enum state_t

[report issue]

# 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()`.