│ │ │ │ -
torrent_handle
│ │ │ │ -
Declared in "libtorrent/torrent_handle.hpp"
│ │ │ │ -
You will usually have to store your torrent handles somewhere, since it's
│ │ │ │ -the object through which you retrieve information about the torrent and
│ │ │ │ -aborts the torrent.
│ │ │ │ -
│ │ │ │ -
Warning
│ │ │ │ -
Any member function that returns a value or fills in a value has to be
│ │ │ │ -made synchronously. This means it has to wait for the main thread to
│ │ │ │ -complete the query before it can return. This might potentially be
│ │ │ │ -expensive if done from within a GUI thread that needs to stay
│ │ │ │ -responsive. Try to avoid querying for information you don't need, and
│ │ │ │ -try to do it in as few calls as possible. You can get most of the
│ │ │ │ -interesting information about a torrent from the
│ │ │ │ -torrent_handle::status() call.
│ │ │ │ -
│ │ │ │ -
The default constructor will initialize the handle to an invalid state.
│ │ │ │ -Which means you cannot perform any operation on it, unless you first
│ │ │ │ -assign it a valid handle. If you try to perform any operation on an
│ │ │ │ -uninitialized handle, it will throw invalid_handle.
│ │ │ │ -
│ │ │ │ -
Warning
│ │ │ │ -
All operations on a torrent_handle may throw system_error
│ │ │ │ -exception, in case the handle is no longer referring to a torrent.
│ │ │ │ -There is one exception is_valid() will never throw. Since the torrents
│ │ │ │ -are processed by a background thread, there is no guarantee that a
│ │ │ │ -handle will remain valid between two calls.
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -struct torrent_handle
│ │ │ │ -{
│ │ │ │ - friend std::size_t hash_value (torrent_handle const& th);
│ │ │ │ - torrent_handle () noexcept = default;
│ │ │ │ - void add_piece (piece_index_t piece, std::vector<char> data, add_piece_flags_t flags = {}) const;
│ │ │ │ - void add_piece (piece_index_t piece, char const* data, add_piece_flags_t flags = {}) const;
│ │ │ │ - void read_piece (piece_index_t piece) const;
│ │ │ │ - bool have_piece (piece_index_t piece) const;
│ │ │ │ - void post_peer_info () const;
│ │ │ │ - void get_peer_info (std::vector<peer_info>& v) const;
│ │ │ │ - torrent_status status (status_flags_t flags = status_flags_t::all()) const;
│ │ │ │ - void post_status (status_flags_t flags = status_flags_t::all()) const;
│ │ │ │ - void get_download_queue (std::vector<partial_piece_info>& queue) const;
│ │ │ │ - void post_download_queue () const;
│ │ │ │ - std::vector<partial_piece_info> get_download_queue () const;
│ │ │ │ - void clear_piece_deadlines () const;
│ │ │ │ - void reset_piece_deadline (piece_index_t index) const;
│ │ │ │ - void set_piece_deadline (piece_index_t index, int deadline, deadline_flags_t flags = {}) const;
│ │ │ │ - void file_progress (std::vector<std::int64_t>& progress, file_progress_flags_t flags = {}) const;
│ │ │ │ - std::vector<std::int64_t> file_progress (file_progress_flags_t flags = {}) const;
│ │ │ │ - void post_file_progress (file_progress_flags_t flags) const;
│ │ │ │ - std::vector<open_file_state> file_status () const;
│ │ │ │ - void clear_error () const;
│ │ │ │ - void post_trackers () const;
│ │ │ │ - void replace_trackers (std::vector<announce_entry> const&) const;
│ │ │ │ - std::vector<announce_entry> trackers () const;
│ │ │ │ - void add_tracker (announce_entry const&) const;
│ │ │ │ - std::set<std::string> url_seeds () const;
│ │ │ │ - void add_url_seed (std::string const& url) const;
│ │ │ │ - void remove_url_seed (std::string const& url) const;
│ │ │ │ - std::set<std::string> http_seeds () const;
│ │ │ │ - void add_http_seed (std::string const& url) const;
│ │ │ │ - void remove_http_seed (std::string const& url) const;
│ │ │ │ - void add_extension (
│ │ │ │ - std::function<std::shared_ptr<torrent_plugin>(torrent_handle const&, client_data_t)> const& ext
│ │ │ │ - , client_data_t userdata = client_data_t{});
│ │ │ │ - bool set_metadata (span<char const> metadata) const;
│ │ │ │ - bool is_valid () const;
│ │ │ │ - void resume () const;
│ │ │ │ - void pause (pause_flags_t flags = {}) const;
│ │ │ │ - void unset_flags (torrent_flags_t flags) const;
│ │ │ │ - void set_flags (torrent_flags_t flags, torrent_flags_t mask) const;
│ │ │ │ - void set_flags (torrent_flags_t flags) const;
│ │ │ │ - torrent_flags_t flags () const;
│ │ │ │ - void flush_cache () const;
│ │ │ │ - void force_recheck () const;
│ │ │ │ - void save_resume_data (resume_data_flags_t flags = {}) const;
│ │ │ │ - bool need_save_resume_data (resume_data_flags_t flags) const;
│ │ │ │ - bool need_save_resume_data () const;
│ │ │ │ - queue_position_t queue_position () const;
│ │ │ │ - void queue_position_bottom () const;
│ │ │ │ - void queue_position_top () const;
│ │ │ │ - void queue_position_down () const;
│ │ │ │ - void queue_position_up () const;
│ │ │ │ - void queue_position_set (queue_position_t p) const;
│ │ │ │ - void set_ssl_certificate_buffer (std::string const& certificate
│ │ │ │ - , std::string const& private_key
│ │ │ │ - , std::string const& dh_params);
│ │ │ │ - void set_ssl_certificate (std::string const& certificate
│ │ │ │ - , std::string const& private_key
│ │ │ │ - , std::string const& dh_params
│ │ │ │ - , std::string const& passphrase = "");
│ │ │ │ - std::shared_ptr<torrent_info> torrent_file_with_hashes () const;
│ │ │ │ - std::shared_ptr<const torrent_info> torrent_file () const;
│ │ │ │ - std::vector<std::vector<sha256_hash>> piece_layers () const;
│ │ │ │ - void post_piece_availability () const;
│ │ │ │ - void piece_availability (std::vector<int>& avail) const;
│ │ │ │ - void prioritize_pieces (std::vector<download_priority_t> const& pieces) const;
│ │ │ │ - void prioritize_pieces (std::vector<std::pair<piece_index_t, download_priority_t>> const& pieces) const;
│ │ │ │ - std::vector<download_priority_t> get_piece_priorities () const;
│ │ │ │ - download_priority_t piece_priority (piece_index_t index) const;
│ │ │ │ - void piece_priority (piece_index_t index, download_priority_t priority) const;
│ │ │ │ - std::vector<download_priority_t> get_file_priorities () const;
│ │ │ │ - download_priority_t file_priority (file_index_t index) const;
│ │ │ │ - void file_priority (file_index_t index, download_priority_t priority) const;
│ │ │ │ - void prioritize_files (std::vector<download_priority_t> const& files) const;
│ │ │ │ - void force_reannounce (int seconds = 0, int idx = -1, reannounce_flags_t = {}) const;
│ │ │ │ - void force_dht_announce () const;
│ │ │ │ - void force_lsd_announce () const;
│ │ │ │ - void scrape_tracker (int idx = -1) const;
│ │ │ │ - int upload_limit () const;
│ │ │ │ - int download_limit () const;
│ │ │ │ - void set_upload_limit (int limit) const;
│ │ │ │ - void set_download_limit (int limit) const;
│ │ │ │ - void connect_peer (tcp::endpoint const& adr, peer_source_flags_t source = {}
│ │ │ │ - , pex_flags_t flags = pex_encryption | pex_utp | pex_holepunch) const;
│ │ │ │ - void clear_peers ();
│ │ │ │ - int max_uploads () const;
│ │ │ │ - void set_max_uploads (int max_uploads) const;
│ │ │ │ - int max_connections () const;
│ │ │ │ - void set_max_connections (int max_connections) const;
│ │ │ │ - void move_storage (std::string const& save_path
│ │ │ │ - , move_flags_t flags = move_flags_t::always_replace_files
│ │ │ │ - ) const;
│ │ │ │ - void rename_file (file_index_t index, std::string const& new_name) const;
│ │ │ │ - sha1_hash info_hash () const;
│ │ │ │ - info_hash_t info_hashes () const;
│ │ │ │ - bool operator< (const torrent_handle& h) const;
│ │ │ │ - bool operator== (const torrent_handle& h) const;
│ │ │ │ - bool operator!= (const torrent_handle& h) const;
│ │ │ │ - std::uint32_t id () const;
│ │ │ │ - std::shared_ptr<torrent> native_handle () const;
│ │ │ │ - client_data_t userdata () const;
│ │ │ │ - bool in_session () const;
│ │ │ │ -
│ │ │ │ - static constexpr add_piece_flags_t overwrite_existing = 0_bit;
│ │ │ │ - static constexpr status_flags_t query_distributed_copies = 0_bit;
│ │ │ │ - static constexpr status_flags_t query_accurate_download_counters = 1_bit;
│ │ │ │ - static constexpr status_flags_t query_last_seen_complete = 2_bit;
│ │ │ │ - static constexpr status_flags_t query_pieces = 3_bit;
│ │ │ │ - static constexpr status_flags_t query_verified_pieces = 4_bit;
│ │ │ │ - static constexpr status_flags_t query_torrent_file = 5_bit;
│ │ │ │ - static constexpr status_flags_t query_name = 6_bit;
│ │ │ │ - static constexpr status_flags_t query_save_path = 7_bit;
│ │ │ │ - static constexpr deadline_flags_t alert_when_available = 0_bit;
│ │ │ │ - static constexpr file_progress_flags_t piece_granularity = 0_bit;
│ │ │ │ - static constexpr pause_flags_t graceful_pause = 0_bit;
│ │ │ │ - static constexpr resume_data_flags_t flush_disk_cache = 0_bit;
│ │ │ │ - static constexpr resume_data_flags_t save_info_dict = 1_bit;
│ │ │ │ - static constexpr resume_data_flags_t only_if_modified = 2_bit;
│ │ │ │ - static constexpr resume_data_flags_t if_counters_changed = 3_bit;
│ │ │ │ - static constexpr resume_data_flags_t if_download_progress = 4_bit;
│ │ │ │ - static constexpr resume_data_flags_t if_config_changed = 5_bit;
│ │ │ │ - static constexpr resume_data_flags_t if_state_changed = 6_bit;
│ │ │ │ - static constexpr resume_data_flags_t if_metadata_changed = 7_bit;
│ │ │ │ - static constexpr reannounce_flags_t ignore_min_interval = 0_bit;
│ │ │ │ -};
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
torrent_handle()
│ │ │ │ -
│ │ │ │ -torrent_handle () noexcept = default;
│ │ │ │ -
│ │ │ │ -
constructs a torrent handle that does not refer to a torrent.
│ │ │ │ -i.e. is_valid() will return false.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
add_piece()
│ │ │ │ -
│ │ │ │ -void add_piece (piece_index_t piece, std::vector<char> data, add_piece_flags_t flags = {}) const;
│ │ │ │ -void add_piece (piece_index_t piece, char const* data, add_piece_flags_t flags = {}) const;
│ │ │ │ -
│ │ │ │ -
This function will write data to the storage as piece piece,
│ │ │ │ -as if it had been downloaded from a peer.
│ │ │ │ -
By default, data that's already been downloaded is not overwritten by
│ │ │ │ -this buffer. If you trust this data to be correct (and pass the piece
│ │ │ │ -hash check) you may pass the overwrite_existing flag. This will
│ │ │ │ -instruct libtorrent to overwrite any data that may already have been
│ │ │ │ -downloaded with this data.
│ │ │ │ -
Since the data is written asynchronously, you may know that is passed
│ │ │ │ -or failed the hash check by waiting for piece_finished_alert or
│ │ │ │ -hash_failed_alert.
│ │ │ │ -
Adding pieces while the torrent is being checked (i.e. in
│ │ │ │ -torrent_status::checking_files state) is not supported.
│ │ │ │ -
The overload taking a raw pointer to the data is a blocking call. It
│ │ │ │ -won't return until the libtorrent thread has copied the data into its
│ │ │ │ -disk write buffer. data is expected to point to a buffer of as
│ │ │ │ -many bytes as the size of the specified piece. See
│ │ │ │ -file_storage::piece_size().
│ │ │ │ -
The data in the buffer is copied and passed on to the disk IO thread
│ │ │ │ -to be written at a later point.
│ │ │ │ -
The overload taking a std::vector<char> is not blocking, it will
│ │ │ │ -send the buffer to the main thread and return immediately.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
read_piece()
│ │ │ │ -
│ │ │ │ -void read_piece (piece_index_t piece) const;
│ │ │ │ -
│ │ │ │ -
This function starts an asynchronous read operation of the specified
│ │ │ │ -piece from this torrent. You must have completed the download of the
│ │ │ │ -specified piece before calling this function.
│ │ │ │ -
When the read operation is completed, it is passed back through an
│ │ │ │ -alert, read_piece_alert. Since this alert is a response to an explicit
│ │ │ │ -call, it will always be posted, regardless of the alert mask.
│ │ │ │ -
Note that if you read multiple pieces, the read operations are not
│ │ │ │ -guaranteed to finish in the same order as you initiated them.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
have_piece()
│ │ │ │ -
│ │ │ │ -bool have_piece (piece_index_t piece) const;
│ │ │ │ -
│ │ │ │ -
Returns true if this piece has been completely downloaded and written
│ │ │ │ -to disk, and false otherwise.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
post_peer_info() get_peer_info()
│ │ │ │ -
│ │ │ │ -void post_peer_info () const;
│ │ │ │ -void get_peer_info (std::vector<peer_info>& v) const;
│ │ │ │ -
│ │ │ │ -
Query information about connected peers for this torrent. If the
│ │ │ │ -torrent_handle is invalid, it will throw a system_error exception.
│ │ │ │ -
post_peer_info() is asynchronous and will trigger the posting of
│ │ │ │ -a peer_info_alert. The alert contain a list of peer_info objects, one
│ │ │ │ -for each connected peer.
│ │ │ │ -
get_peer_info() is synchronous and takes a reference to a vector
│ │ │ │ -that will be cleared and filled with one entry for each peer
│ │ │ │ -connected to this torrent, given the handle is valid. Each entry in
│ │ │ │ -the vector contains information about that particular peer. See
│ │ │ │ -peer_info.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
status() post_status()
│ │ │ │ -
│ │ │ │ -torrent_status status (status_flags_t flags = status_flags_t::all()) const;
│ │ │ │ -void post_status (status_flags_t flags = status_flags_t::all()) const;
│ │ │ │ -
│ │ │ │ -
status() will return a structure with information about the status
│ │ │ │ -of this torrent. If the torrent_handle is invalid, it will throw
│ │ │ │ -system_error exception. See torrent_status. The flags
│ │ │ │ -argument filters what information is returned in the torrent_status.
│ │ │ │ -Some information in there is relatively expensive to calculate, and if
│ │ │ │ -you're not interested in it (and see performance issues), you can
│ │ │ │ -filter them out.
│ │ │ │ -
The status() function will block until the internal libtorrent
│ │ │ │ -thread responds with the torrent_status object. To avoid blocking,
│ │ │ │ -instead call post_status(). It will trigger posting of a
│ │ │ │ -state_update_alert with a single torrent_status object for this
│ │ │ │ -torrent.
│ │ │ │ -
In order to get regular updates for torrents whose status changes,
│ │ │ │ -consider calling session::post_torrent_updates()`` instead.
│ │ │ │ -
By default everything is included. The flags you can use to decide
│ │ │ │ -what to include are defined in this class.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
get_download_queue() post_download_queue()
│ │ │ │ -
│ │ │ │ -void get_download_queue (std::vector<partial_piece_info>& queue) const;
│ │ │ │ -void post_download_queue () const;
│ │ │ │ -std::vector<partial_piece_info> get_download_queue () const;
│ │ │ │ -
│ │ │ │ -
post_download_queue() triggers a download_queue_alert to be
│ │ │ │ -posted.
│ │ │ │ -get_download_queue() is a synchronous call and returns a vector
│ │ │ │ -with information about pieces that are partially downloaded or not
│ │ │ │ -downloaded but partially requested. See partial_piece_info for the
│ │ │ │ -fields in the returned vector.
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
set_piece_deadline() clear_piece_deadlines() reset_piece_deadline()
│ │ │ │ -
│ │ │ │ -void clear_piece_deadlines () const;
│ │ │ │ -void reset_piece_deadline (piece_index_t index) const;
│ │ │ │ -void set_piece_deadline (piece_index_t index, int deadline, deadline_flags_t flags = {}) const;
│ │ │ │ -
│ │ │ │ -
This function sets or resets the deadline associated with a specific
│ │ │ │ -piece index (index). libtorrent will attempt to download this
│ │ │ │ -entire piece before the deadline expires. This is not necessarily
│ │ │ │ -possible, but pieces with a more recent deadline will always be
│ │ │ │ -prioritized over pieces with a deadline further ahead in time. The
│ │ │ │ -deadline (and flags) of a piece can be changed by calling this
│ │ │ │ -function again.
│ │ │ │ -
If the piece is already downloaded when this call is made, nothing
│ │ │ │ -happens, unless the alert_when_available flag is set, in which case it
│ │ │ │ -will have the same effect as calling read_piece() for index.
│ │ │ │ -
deadline is the number of milliseconds until this piece should be
│ │ │ │ -completed.
│ │ │ │ -
reset_piece_deadline removes the deadline from the piece. If it
│ │ │ │ -hasn't already been downloaded, it will no longer be considered a
│ │ │ │ -priority.
│ │ │ │ -
clear_piece_deadlines() removes deadlines on all pieces in
│ │ │ │ -the torrent. As if reset_piece_deadline() was called on all pieces.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
file_progress() post_file_progress()
│ │ │ │ -
│ │ │ │ -void file_progress (std::vector<std::int64_t>& progress, file_progress_flags_t flags = {}) const;
│ │ │ │ -std::vector<std::int64_t> file_progress (file_progress_flags_t flags = {}) const;
│ │ │ │ -void post_file_progress (file_progress_flags_t flags) const;
│ │ │ │ -
│ │ │ │ -
This function fills in the supplied vector, or returns a vector, with
│ │ │ │ -the number of bytes downloaded of each file in this torrent. The
│ │ │ │ -progress values are ordered the same as the files in the
│ │ │ │ -torrent_info.
│ │ │ │ -
This operation is not very cheap. Its complexity is O(n + mj).
│ │ │ │ -Where n is the number of files, m is the number of currently
│ │ │ │ -downloading pieces and j is the number of blocks in a piece.
│ │ │ │ -
The flags parameter can be used to specify the granularity of the
│ │ │ │ -file progress. If left at the default value of 0, the progress will be
│ │ │ │ -as accurate as possible, but also more expensive to calculate. If
│ │ │ │ -torrent_handle::piece_granularity is specified, the progress will
│ │ │ │ -be specified in piece granularity. i.e. only pieces that have been
│ │ │ │ -fully downloaded and passed the hash check count. When specifying
│ │ │ │ -piece granularity, the operation is a lot cheaper, since libtorrent
│ │ │ │ -already keeps track of this internally and no calculation is required.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
file_status()
│ │ │ │ -
│ │ │ │ -std::vector<open_file_state> file_status () const;
│ │ │ │ -
│ │ │ │ -
This function returns a vector with status about files
│ │ │ │ -that are open for this torrent. Any file that is not open
│ │ │ │ -will not be reported in the vector, i.e. it's possible that
│ │ │ │ -the vector is empty when returning, if none of the files in the
│ │ │ │ -torrent are currently open.
│ │ │ │ -
See open_file_state
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
clear_error()
│ │ │ │ -
│ │ │ │ -void clear_error () const;
│ │ │ │ -
│ │ │ │ -
If the torrent is in an error state (i.e. torrent_status::error is
│ │ │ │ -non-empty), this will clear the error and start the torrent again.
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
trackers() add_tracker() replace_trackers() post_trackers()
│ │ │ │ -
│ │ │ │ -void post_trackers () const;
│ │ │ │ -void replace_trackers (std::vector<announce_entry> const&) const;
│ │ │ │ -std::vector<announce_entry> trackers () const;
│ │ │ │ -void add_tracker (announce_entry const&) const;
│ │ │ │ -
│ │ │ │ -
trackers() returns the list of trackers for this torrent. The
│ │ │ │ -announce entry contains both a string url which specify the
│ │ │ │ -announce url for the tracker as well as an int tier, which is
│ │ │ │ -specifies the order in which this tracker is tried. If you want
│ │ │ │ -libtorrent to use another list of trackers for this torrent, you can
│ │ │ │ -use replace_trackers() which takes a list of the same form as the
│ │ │ │ -one returned from trackers() and will replace it. If you want an
│ │ │ │ -immediate effect, you have to call force_reannounce(). See
│ │ │ │ -announce_entry.
│ │ │ │ -
post_trackers() is the asynchronous version of trackers(). It
│ │ │ │ -will trigger a tracker_list_alert to be posted.
│ │ │ │ -
add_tracker() will look if the specified tracker is already in the
│ │ │ │ -set. If it is, it doesn't do anything. If it's not in the current set
│ │ │ │ -of trackers, it will insert it in the tier specified in the
│ │ │ │ -announce_entry.
│ │ │ │ -
The updated set of trackers will be saved in the resume data, and when
│ │ │ │ -a torrent is started with resume data, the trackers from the resume
│ │ │ │ -data will replace the original ones.
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
add_url_seed() remove_url_seed() url_seeds()
│ │ │ │ -
│ │ │ │ -std::set<std::string> url_seeds () const;
│ │ │ │ -void add_url_seed (std::string const& url) const;
│ │ │ │ -void remove_url_seed (std::string const& url) const;
│ │ │ │ -
│ │ │ │ -
add_url_seed() adds another url to the torrent's list of url
│ │ │ │ -seeds. If the given url already exists in that list, the call has no
│ │ │ │ -effect. The torrent will connect to the server and try to download
│ │ │ │ -pieces from it, unless it's paused, queued, checking or seeding.
│ │ │ │ -remove_url_seed() removes the given url if it exists already.
│ │ │ │ -url_seeds() return a set of the url seeds currently in this
│ │ │ │ -torrent. Note that URLs that fails may be removed automatically from
│ │ │ │ -the list.
│ │ │ │ -
See http seeding for more information.
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
remove_http_seed() add_http_seed() http_seeds()
│ │ │ │ -
│ │ │ │ -std::set<std::string> http_seeds () const;
│ │ │ │ -void add_http_seed (std::string const& url) const;
│ │ │ │ -void remove_http_seed (std::string const& url) const;
│ │ │ │ -
│ │ │ │ -
These functions are identical as the *_url_seed() variants, but
│ │ │ │ -they operate on BEP 17 web seeds instead of BEP 19.
│ │ │ │ -
See http seeding for more information.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
add_extension()
│ │ │ │ -
│ │ │ │ -void add_extension (
│ │ │ │ - std::function<std::shared_ptr<torrent_plugin>(torrent_handle const&, client_data_t)> const& ext
│ │ │ │ - , client_data_t userdata = client_data_t{});
│ │ │ │ -
│ │ │ │ -
add the specified extension to this torrent. The ext argument is
│ │ │ │ -a function that will be called from within libtorrent's context
│ │ │ │ -passing in the internal torrent object and the specified userdata
│ │ │ │ -pointer. The function is expected to return a shared pointer to
│ │ │ │ -a torrent_plugin instance.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
is_valid()
│ │ │ │ -
│ │ │ │ -bool is_valid () const;
│ │ │ │ -
│ │ │ │ -
Returns true if this handle refers to a valid torrent and false if it
│ │ │ │ -hasn't been initialized or if the torrent it refers to has been
│ │ │ │ -removed from the session AND destructed.
│ │ │ │ -
To tell if the torrent_handle is in the session, use
│ │ │ │ -torrent_handle::in_session(). This will return true before
│ │ │ │ -session_handle::remove_torrent() is called, and false
│ │ │ │ -afterward.
│ │ │ │ -
Clients should only use is_valid() to determine if the result of
│ │ │ │ -session::find_torrent() was successful.
│ │ │ │ -
Unlike other member functions which return a value, is_valid()
│ │ │ │ -completes immediately, without blocking on a result from the
│ │ │ │ -network thread. Also unlike other functions, it never throws
│ │ │ │ -the system_error exception.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
pause() resume()
│ │ │ │ -
│ │ │ │ -void resume () const;
│ │ │ │ -void pause (pause_flags_t flags = {}) const;
│ │ │ │ -
│ │ │ │ -
pause(), and resume() will disconnect all peers and reconnect
│ │ │ │ -all peers respectively. When a torrent is paused, it will however
│ │ │ │ -remember all share ratios to all peers and remember all potential (not
│ │ │ │ -connected) peers. Torrents may be paused automatically if there is a
│ │ │ │ -file error (e.g. disk full) or something similar. See
│ │ │ │ -file_error_alert.
│ │ │ │ -
For possible values of the flags parameter, see pause_flags_t.
│ │ │ │ -
To know if a torrent is paused or not, call
│ │ │ │ -torrent_handle::flags() and check for the
│ │ │ │ -torrent_status::paused flag.
│ │ │ │ -
│ │ │ │ -
Note
│ │ │ │ -
Torrents that are auto-managed may be automatically resumed again. It
│ │ │ │ -does not make sense to pause an auto-managed torrent without making it
│ │ │ │ -not auto-managed first. Torrents are auto-managed by default when added
│ │ │ │ -to the session. For more information, see queuing.
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
unset_flags() set_flags() flags()
│ │ │ │ -
│ │ │ │ -void unset_flags (torrent_flags_t flags) const;
│ │ │ │ -void set_flags (torrent_flags_t flags, torrent_flags_t mask) const;
│ │ │ │ -void set_flags (torrent_flags_t flags) const;
│ │ │ │ -torrent_flags_t flags () const;
│ │ │ │ -
│ │ │ │ -
sets and gets the torrent state flags. See torrent_flags_t.
│ │ │ │ -The set_flags overload that take a mask will affect all
│ │ │ │ -flags part of the mask, and set their values to what the
│ │ │ │ -flags argument is set to. This allows clearing and
│ │ │ │ -setting flags in a single function call.
│ │ │ │ -The set_flags overload that just takes flags, sets all
│ │ │ │ -the specified flags and leave any other flags unchanged.
│ │ │ │ -unset_flags clears the specified flags, while leaving
│ │ │ │ -any other flags unchanged.
│ │ │ │ -
The seed_mode flag is special, it can only be cleared once the
│ │ │ │ -torrent has been added, and it can only be set as part of the
│ │ │ │ -add_torrent_params flags, when adding the torrent.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
flush_cache()
│ │ │ │ -
│ │ │ │ -void flush_cache () const;
│ │ │ │ -
│ │ │ │ -
Instructs libtorrent to flush all the disk caches for this torrent and
│ │ │ │ -close all file handles. This is done asynchronously and you will be
│ │ │ │ -notified that it's complete through cache_flushed_alert.
│ │ │ │ -
Note that by the time you get the alert, libtorrent may have cached
│ │ │ │ -more data for the torrent, but you are guaranteed that whatever cached
│ │ │ │ -data libtorrent had by the time you called
│ │ │ │ -torrent_handle::flush_cache() has been written to disk.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
force_recheck()
│ │ │ │ -
│ │ │ │ -void force_recheck () const;
│ │ │ │ -
│ │ │ │ -
force_recheck puts the torrent back in a state where it assumes to
│ │ │ │ -have no resume data. All peers will be disconnected and the torrent
│ │ │ │ -will stop announcing to the tracker. The torrent will be added to the
│ │ │ │ -checking queue, and will be checked (all the files will be read and
│ │ │ │ -compared to the piece hashes). Once the check is complete, the torrent
│ │ │ │ -will start connecting to peers again, as normal.
│ │ │ │ -The torrent will be placed last in queue, i.e. its queue position
│ │ │ │ -will be the highest of all torrents in the session.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
save_resume_data()
│ │ │ │ -
│ │ │ │ -void save_resume_data (resume_data_flags_t flags = {}) const;
│ │ │ │ -
│ │ │ │ -
save_resume_data() asks libtorrent to generate fast-resume data for
│ │ │ │ -this torrent. The fast resume data (stored in an add_torrent_params
│ │ │ │ -object) can be used to resume a torrent in the next session without
│ │ │ │ -having to check all files for which pieces have been downloaded. It
│ │ │ │ -can also be used to save a .torrent file for a torrent_handle.
│ │ │ │ -
This operation is asynchronous, save_resume_data will return
│ │ │ │ -immediately. The resume data is delivered when it's done through a
│ │ │ │ -save_resume_data_alert.
│ │ │ │ -
The operation will fail, and post a save_resume_data_failed_alert
│ │ │ │ -instead, in the following cases:
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -- The torrent is in the process of being removed.
│ │ │ │ -- No torrent state has changed since the last saving of resume
│ │ │ │ -data, and the only_if_modified flag is set.
│ │ │ │ -metadata (see libtorrent's metadata from peers extension)
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
Note that some counters may be outdated by the time you receive the fast resume data
│ │ │ │ -
When saving resume data because of shutting down, make sure not to
│ │ │ │ -remove_torrent() before you receive the save_resume_data_alert.
│ │ │ │ -There's no need to pause the session or torrent when saving resume
│ │ │ │ -data.
│ │ │ │ -
The paused state of a torrent is saved in the resume data, so pausing
│ │ │ │ -all torrents before saving resume data will all torrents be restored
│ │ │ │ -in a paused state.
│ │ │ │ -
│ │ │ │ -
Note
│ │ │ │ -
It is typically a good idea to save resume data whenever a torrent
│ │ │ │ -is completed or paused. If you save resume data for torrents when they are
│ │ │ │ -paused, you can accelerate the shutdown process by not saving resume
│ │ │ │ -data again for those torrents. Completed torrents should have their
│ │ │ │ -resume data saved when they complete and on exit, since their
│ │ │ │ -statistics might be updated.
│ │ │ │ -
│ │ │ │ -
Example code to pause and save resume data for all torrents and wait
│ │ │ │ -for the alerts:
│ │ │ │ -
│ │ │ │ -extern int outstanding_resume_data; std::vector<torrent_handle> handles = ses.get_torrents();
│ │ │ │ -for (torrent_handle const& h : handles) try
│ │ │ │ -{
│ │ │ │ - h.save_resume_data(torrent_handle::only_if_modified);
│ │ │ │ - ++outstanding_resume_data;
│ │ │ │ -}
│ │ │ │ -catch (lt::system_error const& e)
│ │ │ │ -{
│ │ │ │ - }
│ │ │ │ -
│ │ │ │ -while (outstanding_resume_data > 0)
│ │ │ │ -{
│ │ │ │ - alert const* a = ses.wait_for_alert(seconds(30));
│ │ │ │ -
│ │ │ │ - if (a == nullptr) break;
│ │ │ │ -
│ │ │ │ - std::vector<alert*> alerts;
│ │ │ │ - ses.pop_alerts(&alerts);
│ │ │ │ -
│ │ │ │ - for (alert* i : alerts)
│ │ │ │ - {
│ │ │ │ - if (alert_cast<save_resume_data_failed_alert>(i))
│ │ │ │ - {
│ │ │ │ - process_alert(i);
│ │ │ │ - --outstanding_resume_data;
│ │ │ │ - continue;
│ │ │ │ - }
│ │ │ │ -
│ │ │ │ - save_resume_data_alert const* rd = alert_cast<save_resume_data_alert>(i);
│ │ │ │ - if (rd == nullptr)
│ │ │ │ - {
│ │ │ │ - process_alert(i);
│ │ │ │ - continue;
│ │ │ │ - }
│ │ │ │ -
│ │ │ │ - std::ofstream out((rd->params.save_path
│ │ │ │ - + "/" + rd->params.name + ".fastresume").c_str()
│ │ │ │ - , std::ios_base::binary);
│ │ │ │ - std::vector<char> buf = write_resume_data_buf(rd->params);
│ │ │ │ - out.write(buf.data(), buf.size());
│ │ │ │ - --outstanding_resume_data;
│ │ │ │ - }
│ │ │ │ -}
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
Note
│ │ │ │ -
Note how outstanding_resume_data is a global counter in this
│ │ │ │ -example. This is deliberate, otherwise there is a race condition for
│ │ │ │ -torrents that was just asked to save their resume data, they posted
│ │ │ │ -the alert, but it has not been received yet. Those torrents would
│ │ │ │ -report that they don't need to save resume data again, and skipped by
│ │ │ │ -the initial loop, and thwart the counter otherwise.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
need_save_resume_data()
│ │ │ │ -
│ │ │ │ -bool need_save_resume_data (resume_data_flags_t flags) const;
│ │ │ │ -bool need_save_resume_data () const;
│ │ │ │ -
│ │ │ │ -
This function returns true if anything that is stored in the resume
│ │ │ │ -data has changed since the last time resume data was saved.
│ │ │ │ -The overload that takes flags let you ask if specific categories
│ │ │ │ -of properties have changed. These flags have the same behavior as in
│ │ │ │ -the save_resume_data() call.
│ │ │ │ -
This is a blocking call. It will wait for a response from
│ │ │ │ -libtorrent's main thread. A way to avoid blocking is to instead
│ │ │ │ -call save_resume_data() directly, specifying the conditions under
│ │ │ │ -which resume data should be saved.
│ │ │ │ -
│ │ │ │ -
Note
│ │ │ │ -
A torrent's resume data is considered saved as soon as the
│ │ │ │ -save_resume_data_alert is posted. It is important to make sure this
│ │ │ │ -alert is received and handled in order for this function to be
│ │ │ │ -meaningful.
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
queue_position_top() queue_position_up() queue_position() queue_position_down() queue_position_bottom()
│ │ │ │ -
│ │ │ │ -queue_position_t queue_position () const;
│ │ │ │ -void queue_position_bottom () const;
│ │ │ │ -void queue_position_top () const;
│ │ │ │ -void queue_position_down () const;
│ │ │ │ -void queue_position_up () const;
│ │ │ │ -
│ │ │ │ -
Every torrent that is added is assigned a queue position exactly one
│ │ │ │ -greater than the greatest queue position of all existing torrents.
│ │ │ │ -Torrents that are being seeded have -1 as their queue position, since
│ │ │ │ -they're no longer in line to be downloaded.
│ │ │ │ -
When a torrent is removed or turns into a seed, all torrents with
│ │ │ │ -greater queue positions have their positions decreased to fill in the
│ │ │ │ -space in the sequence.
│ │ │ │ -
queue_position() returns the torrent's position in the download
│ │ │ │ -queue. The torrents with the smallest numbers are the ones that are
│ │ │ │ -being downloaded. The smaller number, the closer the torrent is to the
│ │ │ │ -front of the line to be started.
│ │ │ │ -
The queue position is also available in the torrent_status.
│ │ │ │ -
The queue_position_*() functions adjust the torrents position in
│ │ │ │ -the queue. Up means closer to the front and down means closer to the
│ │ │ │ -back of the queue. Top and bottom refers to the front and the back of
│ │ │ │ -the queue respectively.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
queue_position_set()
│ │ │ │ -
│ │ │ │ -void queue_position_set (queue_position_t p) const;
│ │ │ │ -
│ │ │ │ -
updates the position in the queue for this torrent. The relative order
│ │ │ │ -of all other torrents remain intact but their numerical queue position
│ │ │ │ -shifts to make space for this torrent's new position
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
set_ssl_certificate_buffer() set_ssl_certificate()
│ │ │ │ -
│ │ │ │ -void set_ssl_certificate_buffer (std::string const& certificate
│ │ │ │ - , std::string const& private_key
│ │ │ │ - , std::string const& dh_params);
│ │ │ │ -void set_ssl_certificate (std::string const& certificate
│ │ │ │ - , std::string const& private_key
│ │ │ │ - , std::string const& dh_params
│ │ │ │ - , std::string const& passphrase = "");
│ │ │ │ -
│ │ │ │ -
For SSL torrents, use this to specify a path to a .pem file to use as
│ │ │ │ -this client's certificate. The certificate must be signed by the
│ │ │ │ -certificate in the .torrent file to be valid.
│ │ │ │ -
The set_ssl_certificate_buffer() overload takes the actual certificate,
│ │ │ │ -private key and DH params as strings, rather than paths to files.
│ │ │ │ -
cert is a path to the (signed) certificate in .pem format
│ │ │ │ -corresponding to this torrent.
│ │ │ │ -
private_key is a path to the private key for the specified
│ │ │ │ -certificate. This must be in .pem format.
│ │ │ │ -
dh_params is a path to the Diffie-Hellman parameter file, which
│ │ │ │ -needs to be in .pem format. You can generate this file using the
│ │ │ │ -openssl command like this: openssl dhparam -outform PEM -out
│ │ │ │ -dhparams.pem 512.
│ │ │ │ -
passphrase may be specified if the private key is encrypted and
│ │ │ │ -requires a passphrase to be decrypted.
│ │ │ │ -
Note that when a torrent first starts up, and it needs a certificate,
│ │ │ │ -it will suspend connecting to any peers until it has one. It's
│ │ │ │ -typically desirable to resume the torrent after setting the SSL
│ │ │ │ -certificate.
│ │ │ │ -
If you receive a torrent_need_cert_alert, you need to call this to
│ │ │ │ -provide a valid cert. If you don't have a cert you won't be allowed to
│ │ │ │ -connect to any peers.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
torrent_file_with_hashes() torrent_file()
│ │ │ │ -
│ │ │ │ -std::shared_ptr<torrent_info> torrent_file_with_hashes () const;
│ │ │ │ -std::shared_ptr<const torrent_info> torrent_file () const;
│ │ │ │ -
│ │ │ │ -
torrent_file() returns a pointer to the torrent_info object
│ │ │ │ -associated with this torrent. The torrent_info object may be a copy
│ │ │ │ -of the internal object. If the torrent doesn't have metadata, the
│ │ │ │ -pointer will not be initialized (i.e. a nullptr). The torrent may be
│ │ │ │ -in a state without metadata only if it was started without a .torrent
│ │ │ │ -file, e.g. by being added by magnet link.
│ │ │ │ -
Note that the torrent_info object returned here may be a different
│ │ │ │ -instance than the one added to the session, with different attributes
│ │ │ │ -like piece layers, dht nodes and trackers. A torrent_info object does
│ │ │ │ -not round-trip cleanly when added to a session.
│ │ │ │ -
If you want to save a .torrent file from the torrent_handle, instead
│ │ │ │ -call save_resume_data() and write_torrent_file() the
│ │ │ │ -add_torrent_params object passed back in the alert.
│ │ │ │ -
torrent_file_with_hashes() returns a copy of the internal
│ │ │ │ -torrent_info and piece layer hashes (if it's a v2 torrent). The piece
│ │ │ │ -layers will only be included if they are available. If this torrent
│ │ │ │ -was added from a .torrent file with piece layers or if it's seeding,
│ │ │ │ -the piece layers are available. This function is more expensive than
│ │ │ │ -torrent_file() since it needs to make copies of this information.
│ │ │ │ -
The torrent_file_with_hashes() is here for backwards compatibility
│ │ │ │ -when constructing a create_torrent object from a torrent_info that's
│ │ │ │ -in a session. Prefer save_resume_data() + write_torrent_file().
│ │ │ │ -
Note that a torrent added from a magnet link may not have the full
│ │ │ │ -merkle trees for all files, and hence not have the complete piece
│ │ │ │ -layers. In that state, you cannot create a .torrent file even from
│ │ │ │ -the torrent_info returned from torrent_file_with_hashes(). Once the
│ │ │ │ -torrent completes downloading all files, becoming a seed, you can
│ │ │ │ -make a .torrent file from it.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
piece_layers()
│ │ │ │ -
│ │ │ │ -std::vector<std::vector<sha256_hash>> piece_layers () const;
│ │ │ │ -
│ │ │ │ -
returns the piece layers for all files in the torrent. If this is a
│ │ │ │ -v1 torrent (and doesn't have any piece layers) it returns an empty
│ │ │ │ -vector. This is a blocking call that will synchronize with the
│ │ │ │ -libtorrent network thread.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
piece_availability() post_piece_availability()
│ │ │ │ -
│ │ │ │ -void post_piece_availability () const;
│ │ │ │ -void piece_availability (std::vector<int>& avail) const;
│ │ │ │ -
│ │ │ │ -
The piece availability is the number of peers that we are connected
│ │ │ │ -that has advertised having a particular piece. This is the information
│ │ │ │ -that libtorrent uses in order to prefer picking rare pieces.
│ │ │ │ -
post_piece_availability() will trigger a piece_availability_alert
│ │ │ │ -to be posted.
│ │ │ │ -
piece_availability() fills the specified std::vector<int>
│ │ │ │ -with the availability for each piece in this torrent. libtorrent does
│ │ │ │ -not keep track of availability for seeds, so if the torrent is
│ │ │ │ -seeding the availability for all pieces is reported as 0.
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
prioritize_pieces() piece_priority() get_piece_priorities()
│ │ │ │ -
│ │ │ │ -void prioritize_pieces (std::vector<download_priority_t> const& pieces) const;
│ │ │ │ -void prioritize_pieces (std::vector<std::pair<piece_index_t, download_priority_t>> const& pieces) const;
│ │ │ │ -std::vector<download_priority_t> get_piece_priorities () const;
│ │ │ │ -download_priority_t piece_priority (piece_index_t index) const;
│ │ │ │ -void piece_priority (piece_index_t index, download_priority_t priority) const;
│ │ │ │ -
│ │ │ │ -
These functions are used to set and get the priority of individual
│ │ │ │ -pieces. By default all pieces have priority 4. That means that the
│ │ │ │ -random rarest first algorithm is effectively active for all pieces.
│ │ │ │ -You may however change the priority of individual pieces. There are 8
│ │ │ │ -priority levels. 0 means not to download the piece at all. Otherwise,
│ │ │ │ -lower priority values means less likely to be picked. Piece priority
│ │ │ │ -takes precedence over piece availability. Every piece with priority 7
│ │ │ │ -will be attempted to be picked before a priority 6 piece and so on.
│ │ │ │ -
The default priority of pieces is 4.
│ │ │ │ -
Piece priorities can not be changed for torrents that have not
│ │ │ │ -downloaded the metadata yet. Magnet links won't have metadata
│ │ │ │ -immediately. see the metadata_received_alert.
│ │ │ │ -
piece_priority sets or gets the priority for an individual piece,
│ │ │ │ -specified by index.
│ │ │ │ -
prioritize_pieces takes a vector of integers, one integer per
│ │ │ │ -piece in the torrent. All the piece priorities will be updated with
│ │ │ │ -the priorities in the vector.
│ │ │ │ -The second overload of prioritize_pieces that takes a vector of pairs
│ │ │ │ -will update the priorities of only select pieces, and leave all other
│ │ │ │ -unaffected. Each pair is (piece, priority). That is, the first item is
│ │ │ │ -the piece index and the second item is the priority of that piece.
│ │ │ │ -Invalid entries, where the piece index or priority is out of range, are
│ │ │ │ -not allowed.
│ │ │ │ -
get_piece_priorities returns a vector with one element for each piece
│ │ │ │ -in the torrent. Each element is the current priority of that piece.
│ │ │ │ -
It's possible to cancel the effect of file priorities by setting the
│ │ │ │ -priorities for the affected pieces. Care has to be taken when mixing
│ │ │ │ -usage of file- and piece priorities.
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
file_priority() get_file_priorities() prioritize_files()
│ │ │ │ -
│ │ │ │ -std::vector<download_priority_t> get_file_priorities () const;
│ │ │ │ -download_priority_t file_priority (file_index_t index) const;
│ │ │ │ -void file_priority (file_index_t index, download_priority_t priority) const;
│ │ │ │ -void prioritize_files (std::vector<download_priority_t> const& files) const;
│ │ │ │ -
│ │ │ │ -
index must be in the range [0, number_of_files).
│ │ │ │ -
file_priority() queries or sets the priority of file index.
│ │ │ │ -
prioritize_files() takes a vector that has at as many elements as
│ │ │ │ -there are files in the torrent. Each entry is the priority of that
│ │ │ │ -file. The function sets the priorities of all the pieces in the
│ │ │ │ -torrent based on the vector.
│ │ │ │ -
get_file_priorities() returns a vector with the priorities of all
│ │ │ │ -files.
│ │ │ │ -
The priority values are the same as for piece_priority(). See
│ │ │ │ -download_priority_t.
│ │ │ │ -
Whenever a file priority is changed, all other piece priorities are
│ │ │ │ -reset to match the file priorities. In order to maintain special
│ │ │ │ -priorities for particular pieces, piece_priority() has to be called
│ │ │ │ -again for those pieces.
│ │ │ │ -
You cannot set the file priorities on a torrent that does not yet have
│ │ │ │ -metadata or a torrent that is a seed. file_priority(int, int) and
│ │ │ │ -prioritize_files() are both no-ops for such torrents.
│ │ │ │ -
Since changing file priorities may involve disk operations (of moving
│ │ │ │ -files in- and out of the part file), the internal accounting of file
│ │ │ │ -priorities happen asynchronously. i.e. setting file priorities and then
│ │ │ │ -immediately querying them may not yield the same priorities just set.
│ │ │ │ -To synchronize with the priorities taking effect, wait for the
│ │ │ │ -file_prio_alert.
│ │ │ │ -
When combining file- and piece priorities, the resume file will record
│ │ │ │ -both. When loading the resume data, the file priorities will be applied
│ │ │ │ -first, then the piece priorities.
│ │ │ │ -
Moving data from a file into the part file is currently not
│ │ │ │ -supported. If a file has its priority set to 0 after it has already
│ │ │ │ -been created, it will not be moved into the partfile.
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
force_dht_announce() force_reannounce() force_lsd_announce()
│ │ │ │ -
│ │ │ │ -void force_reannounce (int seconds = 0, int idx = -1, reannounce_flags_t = {}) const;
│ │ │ │ -void force_dht_announce () const;
│ │ │ │ -void force_lsd_announce () const;
│ │ │ │ -
│ │ │ │ -
force_reannounce() will force this torrent to do another tracker
│ │ │ │ -request, to receive new peers. The seconds argument specifies how
│ │ │ │ -many seconds from now to issue the tracker announces.
│ │ │ │ -
If the tracker's min_interval has not passed since the last
│ │ │ │ -announce, the forced announce will be scheduled to happen immediately
│ │ │ │ -as the min_interval expires. This is to honor trackers minimum
│ │ │ │ -re-announce interval settings.
│ │ │ │ -
The tracker_index argument specifies which tracker to re-announce.
│ │ │ │ -If set to -1 (which is the default), all trackers are re-announce.
│ │ │ │ -
The flags argument can be used to affect the re-announce. See
│ │ │ │ -ignore_min_interval.
│ │ │ │ -
force_dht_announce will announce the torrent to the DHT
│ │ │ │ -immediately.
│ │ │ │ -
force_lsd_announce will announce the torrent on LSD
│ │ │ │ -immediately.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
scrape_tracker()
│ │ │ │ -
│ │ │ │ -void scrape_tracker (int idx = -1) const;
│ │ │ │ -
│ │ │ │ -
scrape_tracker() will send a scrape request to a tracker. By
│ │ │ │ -default (idx = -1) it will scrape the last working tracker. If
│ │ │ │ -idx is >= 0, the tracker with the specified index will scraped.
│ │ │ │ -
A scrape request queries the tracker for statistics such as total
│ │ │ │ -number of incomplete peers, complete peers, number of downloads etc.
│ │ │ │ -
This request will specifically update the num_complete and
│ │ │ │ -num_incomplete fields in the torrent_status struct once it
│ │ │ │ -completes. When it completes, it will generate a scrape_reply_alert.
│ │ │ │ -If it fails, it will generate a scrape_failed_alert.
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
download_limit() set_download_limit() upload_limit() set_upload_limit()
│ │ │ │ -
│ │ │ │ -int upload_limit () const;
│ │ │ │ -int download_limit () const;
│ │ │ │ -void set_upload_limit (int limit) const;
│ │ │ │ -void set_download_limit (int limit) const;
│ │ │ │ -
│ │ │ │ -
set_upload_limit will limit the upload bandwidth used by this
│ │ │ │ -particular torrent to the limit you set. It is given as the number of
│ │ │ │ -bytes per second the torrent is allowed to upload.
│ │ │ │ -set_download_limit works the same way but for download bandwidth
│ │ │ │ -instead of upload bandwidth. Note that setting a higher limit on a
│ │ │ │ -torrent then the global limit
│ │ │ │ -(settings_pack::upload_rate_limit) will not override the global
│ │ │ │ -rate limit. The torrent can never upload more than the global rate
│ │ │ │ -limit.
│ │ │ │ -
upload_limit and download_limit will return the current limit
│ │ │ │ -setting, for upload and download, respectively.
│ │ │ │ -
Local peers are not rate limited by default. see peer classes.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
connect_peer()
│ │ │ │ -
│ │ │ │ -void connect_peer (tcp::endpoint const& adr, peer_source_flags_t source = {}
│ │ │ │ - , pex_flags_t flags = pex_encryption | pex_utp | pex_holepunch) const;
│ │ │ │ -
│ │ │ │ -
connect_peer() is a way to manually connect to peers that one
│ │ │ │ -believe is a part of the torrent. If the peer does not respond, or is
│ │ │ │ -not a member of this torrent, it will simply be disconnected. No harm
│ │ │ │ -can be done by using this other than an unnecessary connection attempt
│ │ │ │ -is made. If the torrent is uninitialized or in queued or checking
│ │ │ │ -mode, this will throw system_error. The second (optional)
│ │ │ │ -argument will be bitwise ORed into the source mask of this peer.
│ │ │ │ -Typically this is one of the source flags in peer_info. i.e.
│ │ │ │ -tracker, pex, dht etc.
│ │ │ │ -
For possible values of flags, see pex_flags_t.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
clear_peers()
│ │ │ │ -
│ │ │ │ -void clear_peers ();
│ │ │ │ -
│ │ │ │ -
This will disconnect all peers and clear the peer list for this
│ │ │ │ -torrent. New peers will have to be acquired before resuming, from
│ │ │ │ -trackers, DHT or local service discovery, for example.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
max_uploads() set_max_uploads()
│ │ │ │ -
│ │ │ │ -int max_uploads () const;
│ │ │ │ -void set_max_uploads (int max_uploads) const;
│ │ │ │ -
│ │ │ │ -
set_max_uploads() sets the maximum number of peers that's unchoked
│ │ │ │ -at the same time on this torrent. If you set this to -1, there will be
│ │ │ │ -no limit. This defaults to infinite. The primary setting controlling
│ │ │ │ -this is the global unchoke slots limit, set by unchoke_slots_limit in
│ │ │ │ -settings_pack.
│ │ │ │ -
max_uploads() returns the current settings.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
set_max_connections() max_connections()
│ │ │ │ -
│ │ │ │ -int max_connections () const;
│ │ │ │ -void set_max_connections (int max_connections) const;
│ │ │ │ -
│ │ │ │ -
set_max_connections() sets the maximum number of connection this
│ │ │ │ -torrent will open. If all connections are used up, incoming
│ │ │ │ -connections may be refused or poor connections may be closed. This
│ │ │ │ -must be at least 2. The default is unlimited number of connections. If
│ │ │ │ --1 is given to the function, it means unlimited. There is also a
│ │ │ │ -global limit of the number of connections, set by
│ │ │ │ -connections_limit in settings_pack.
│ │ │ │ -
max_connections() returns the current settings.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
move_storage()
│ │ │ │ -
│ │ │ │ -void move_storage (std::string const& save_path
│ │ │ │ - , move_flags_t flags = move_flags_t::always_replace_files
│ │ │ │ - ) const;
│ │ │ │ -
│ │ │ │ -
Moves the file(s) that this torrent are currently seeding from or
│ │ │ │ -downloading to. If the given save_path is not located on the same
│ │ │ │ -drive as the original save path, the files will be copied to the new
│ │ │ │ -drive and removed from their original location. This will block all
│ │ │ │ -other disk IO, and other torrents download and upload rates may drop
│ │ │ │ -while copying the file.
│ │ │ │ -
Since disk IO is performed in a separate thread, this operation is
│ │ │ │ -also asynchronous. Once the operation completes, the
│ │ │ │ -storage_moved_alert is generated, with the new path as the
│ │ │ │ -message. If the move fails for some reason,
│ │ │ │ -storage_moved_failed_alert is generated instead, containing the
│ │ │ │ -error message.
│ │ │ │ -
The flags argument determines the behavior of the copying/moving
│ │ │ │ -of the files in the torrent. see move_flags_t.
│ │ │ │ -
always_replace_files is the default and replaces any file that
│ │ │ │ -exist in both the source directory and the target directory.
│ │ │ │ -
fail_if_exist first check to see that none of the copy operations
│ │ │ │ -would cause an overwrite. If it would, it will fail. Otherwise it will
│ │ │ │ -proceed as if it was in always_replace_files mode. Note that there
│ │ │ │ -is an inherent race condition here. If the files in the target
│ │ │ │ -directory appear after the check but before the copy or move
│ │ │ │ -completes, they will be overwritten. When failing because of files
│ │ │ │ -already existing in the target path, the error of
│ │ │ │ -move_storage_failed_alert is set to
│ │ │ │ -boost::system::errc::file_exists.
│ │ │ │ -
The intention is that a client may use this as a probe, and if it
│ │ │ │ -fails, ask the user which mode to use. The client may then re-issue
│ │ │ │ -the move_storage call with one of the other modes.
│ │ │ │ -
dont_replace always keeps the existing file in the target
│ │ │ │ -directory, if there is one. The source files will still be removed in
│ │ │ │ -that case. Note that it won't automatically re-check files. If an
│ │ │ │ -incomplete torrent is moved into a directory with the complete files,
│ │ │ │ -pause, move, force-recheck and resume. Without the re-checking, the
│ │ │ │ -torrent will keep downloading and files in the new download directory
│ │ │ │ -will be overwritten.
│ │ │ │ -
Files that have been renamed to have absolute paths are not moved by
│ │ │ │ -this function. Keep in mind that files that don't belong to the
│ │ │ │ -torrent but are stored in the torrent's directory may be moved as
│ │ │ │ -well. This goes for files that have been renamed to absolute paths
│ │ │ │ -that still end up inside the save path.
│ │ │ │ -
When copying files, sparse regions are not likely to be preserved.
│ │ │ │ -This makes it proportionally more expensive to move a large torrent
│ │ │ │ -when only few pieces have been downloaded, since the files are then
│ │ │ │ -allocated with zeros in the destination directory.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
rename_file()
│ │ │ │ -
│ │ │ │ -void rename_file (file_index_t index, std::string const& new_name) const;
│ │ │ │ -
│ │ │ │ -
Renames the file with the given index asynchronously. The rename
│ │ │ │ -operation is complete when either a file_renamed_alert or
│ │ │ │ -file_rename_failed_alert is posted.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
info_hash() info_hashes()
│ │ │ │ -
│ │ │ │ -sha1_hash info_hash () const;
│ │ │ │ -info_hash_t info_hashes () const;
│ │ │ │ -
│ │ │ │ -
returns the info-hash(es) of the torrent. If this handle is to a
│ │ │ │ -torrent that hasn't loaded yet (for instance by being added) by a
│ │ │ │ -URL, the returned value is undefined.
│ │ │ │ -The info_hash() returns the SHA-1 info-hash for v1 torrents and a
│ │ │ │ -truncated hash for v2 torrents. For the full v2 info-hash, use
│ │ │ │ -info_hashes() instead.
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
operator!=() operator<() operator==()
│ │ │ │ -
│ │ │ │ -bool operator< (const torrent_handle& h) const;
│ │ │ │ -bool operator== (const torrent_handle& h) const;
│ │ │ │ -bool operator!= (const torrent_handle& h) const;
│ │ │ │ -
│ │ │ │ -
comparison operators. The order of the torrents is unspecified
│ │ │ │ -but stable.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
id()
│ │ │ │ -
│ │ │ │ -std::uint32_t id () const;
│ │ │ │ -
│ │ │ │ -
returns a unique identifier for this torrent. It's not a dense index.
│ │ │ │ -It's not preserved across sessions.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
native_handle()
│ │ │ │ -
│ │ │ │ -std::shared_ptr<torrent> native_handle () const;
│ │ │ │ -
│ │ │ │ -
This function is intended only for use by plugins and the alert
│ │ │ │ -dispatch function. This type does not have a stable ABI and should
│ │ │ │ -be relied on as little as possible. Accessing the handle returned by
│ │ │ │ -this function is not thread safe outside of libtorrent's internal
│ │ │ │ -thread (which is used to invoke plugin callbacks).
│ │ │ │ -The torrent class is not only eligible for changing ABI across
│ │ │ │ -minor versions of libtorrent, its layout is also dependent on build
│ │ │ │ -configuration. This adds additional requirements on a client to be
│ │ │ │ -built with the exact same build configuration as libtorrent itself.
│ │ │ │ -i.e. the TORRENT_ macros must match between libtorrent and the
│ │ │ │ -client builds.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
userdata()
│ │ │ │ -
│ │ │ │ -client_data_t userdata () const;
│ │ │ │ -
│ │ │ │ -
returns the userdata pointer as set in add_torrent_params
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
in_session()
│ │ │ │ -
│ │ │ │ -bool in_session () const;
│ │ │ │ -
│ │ │ │ -
Returns true if the torrent is in the session. It returns true before
│ │ │ │ -session::remove_torrent() is called, and false afterward.
│ │ │ │ -
Note that this is a blocking function, unlike torrent_handle::is_valid()
│ │ │ │ -which returns immediately.
│ │ │ │ -
[report issue]
│ │ │ │ -- overwrite_existing
│ │ │ │ -- instruct libtorrent to overwrite any data that may already have been
│ │ │ │ -downloaded with the data of the new piece being added. Using this
│ │ │ │ -flag when adding a piece that is actively being downloaded from other
│ │ │ │ -peers may have some unexpected consequences, as blocks currently
│ │ │ │ -being downloaded from peers may not be replaced.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -- query_distributed_copies
│ │ │ │ -- calculates distributed_copies, distributed_full_copies and
│ │ │ │ -distributed_fraction.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -- query_accurate_download_counters
│ │ │ │ -- includes partial downloaded blocks in total_done and
│ │ │ │ -total_wanted_done.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -- query_last_seen_complete
│ │ │ │ -- includes last_seen_complete.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -- query_pieces
│ │ │ │ -- populate the pieces field in torrent_status.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -- query_verified_pieces
│ │ │ │ -- includes verified_pieces (only applies to torrents in seed
│ │ │ │ -mode).
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -- query_torrent_file
│ │ │ │ -- includes torrent_file, which is all the static information from
│ │ │ │ -the .torrent file.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -- query_name
│ │ │ │ -- includes name, the name of the torrent. This is either derived
│ │ │ │ -from the .torrent file, or from the &dn= magnet link argument
│ │ │ │ -or possibly some other source. If the name of the torrent is not
│ │ │ │ -known, this is an empty string.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -- query_save_path
│ │ │ │ -- includes save_path, the path to the directory the files of the
│ │ │ │ -torrent are saved to.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -- alert_when_available
│ │ │ │ -- used to ask libtorrent to send an alert once the piece has been
│ │ │ │ -downloaded, by passing alert_when_available. When set, the
│ │ │ │ -read_piece_alert alert will be delivered, with the piece data, when
│ │ │ │ -it's downloaded.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -- piece_granularity
│ │ │ │ -- only calculate file progress at piece granularity. This makes
│ │ │ │ -the file_progress() call cheaper and also only takes bytes that
│ │ │ │ -have passed the hash check into account, so progress cannot
│ │ │ │ -regress in this mode.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -- graceful_pause
│ │ │ │ -- will delay the disconnect of peers that we're still downloading
│ │ │ │ -outstanding requests from. The torrent will not accept any more
│ │ │ │ -requests and will disconnect all idle peers. As soon as a peer is done
│ │ │ │ -transferring the blocks that were requested from it, it is
│ │ │ │ -disconnected. This is a graceful shut down of the torrent in the sense
│ │ │ │ -that no downloaded bytes are wasted.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -- flush_disk_cache
│ │ │ │ -- the disk cache will be flushed before creating the resume data.
│ │ │ │ -This avoids a problem with file timestamps in the resume data in
│ │ │ │ -case the cache hasn't been flushed yet.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -- save_info_dict
│ │ │ │ -- the resume data will contain the metadata from the torrent file as
│ │ │ │ -well. This is useful for clients that don't keep .torrent files
│ │ │ │ -around separately, or for torrents that were added via a magnet link.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -- only_if_modified
│ │ │ │ -- this flag has the same behavior as the combination of:
│ │ │ │ -if_counters_changed | if_download_progress | if_config_changed |
│ │ │ │ -if_state_changed | if_metadata_changed
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -- if_counters_changed
│ │ │ │ -- save resume data if any counters has changed since the last time
│ │ │ │ -resume data was saved. This includes upload/download counters, active
│ │ │ │ -time counters and scrape data. A torrent that is not paused will have
│ │ │ │ -its active time counters incremented continuously.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -- if_download_progress
│ │ │ │ -- save the resume data if any blocks have been downloaded since the
│ │ │ │ -last time resume data was saved. This includes:
│ │ │ │ -* checking existing files on disk
│ │ │ │ -* downloading a block from a peer
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -- if_config_changed
│ │ │ │ -- save the resume data if configuration options changed since last time
│ │ │ │ -the resume data was saved. This includes:
│ │ │ │ -* file- or piece priorities
│ │ │ │ -* upload- and download rate limits
│ │ │ │ -* change max-uploads (unchoke slots)
│ │ │ │ -* change max connection limit
│ │ │ │ -* enable/disable peer-exchange, local service discovery or DHT
│ │ │ │ -* enable/disable apply IP-filter
│ │ │ │ -* enable/disable auto-managed
│ │ │ │ -* enable/disable share-mode
│ │ │ │ -* enable/disable sequential-mode
│ │ │ │ -* files renamed
│ │ │ │ -* storage moved (save_path changed)
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -- if_state_changed
│ │ │ │ -- save the resume data if torrent state has changed since last time the
│ │ │ │ -resume data was saved. This includes:
│ │ │ │ -* upload mode
│ │ │ │ -* paused state
│ │ │ │ -* super-seeding
│ │ │ │ -* seed-mode
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -- if_metadata_changed
│ │ │ │ -- save the resume data if any metadata changed since the last time
│ │ │ │ -resume data was saved. This includes:
│ │ │ │ -* add/remove web seeds
│ │ │ │ -* add/remove trackers
│ │ │ │ -* receiving metadata for a magnet link
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -- ignore_min_interval
│ │ │ │ -- by default, force-reannounce will still honor the min-interval
│ │ │ │ -published by the tracker. If this flag is set, it will be ignored
│ │ │ │ -and the tracker is announced immediately.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
session_handle
│ │ │ │ -
Declared in "libtorrent/session_handle.hpp"
│ │ │ │ -
this class provides a non-owning handle to a session and a subset of the
│ │ │ │ -interface of the session class. If the underlying session is destructed
│ │ │ │ -any handle to it will no longer be valid. is_valid() will return false and
│ │ │ │ -any operation on it will throw a system_error exception, with error code
│ │ │ │ -invalid_session_handle.
│ │ │ │ -
│ │ │ │ -struct session_handle
│ │ │ │ -{
│ │ │ │ - bool is_valid () const;
│ │ │ │ - session_params session_state (save_state_flags_t flags = save_state_flags_t::all()) const;
│ │ │ │ - std::vector<torrent_status> get_torrent_status (
│ │ │ │ - std::function<bool(torrent_status const&)> const& pred
│ │ │ │ - , status_flags_t flags = {}) const;
│ │ │ │ - void refresh_torrent_status (std::vector<torrent_status>* ret
│ │ │ │ - , status_flags_t flags = {}) const;
│ │ │ │ - void post_torrent_updates (status_flags_t flags = status_flags_t::all());
│ │ │ │ - void post_session_stats ();
│ │ │ │ - void post_dht_stats ();
│ │ │ │ - void set_dht_state (dht::dht_state const& st);
│ │ │ │ - void set_dht_state (dht::dht_state&& st);
│ │ │ │ - std::vector<torrent_handle> get_torrents () const;
│ │ │ │ - torrent_handle find_torrent (sha1_hash const& info_hash) const;
│ │ │ │ - void async_add_torrent (add_torrent_params const& params);
│ │ │ │ - torrent_handle add_torrent (add_torrent_params const& params);
│ │ │ │ - void async_add_torrent (add_torrent_params&& params);
│ │ │ │ - torrent_handle add_torrent (add_torrent_params&& params, error_code& ec);
│ │ │ │ - torrent_handle add_torrent (add_torrent_params&& params);
│ │ │ │ - torrent_handle add_torrent (add_torrent_params const& params, error_code& ec);
│ │ │ │ - void pause ();
│ │ │ │ - bool is_paused () const;
│ │ │ │ - void resume ();
│ │ │ │ - bool is_dht_running () const;
│ │ │ │ - void set_dht_storage (dht::dht_storage_constructor_type sc);
│ │ │ │ - void add_dht_node (std::pair<std::string, int> const& node);
│ │ │ │ - void dht_get_item (sha1_hash const& target);
│ │ │ │ - void dht_get_item (std::array<char, 32> key
│ │ │ │ - , std::string salt = std::string());
│ │ │ │ - sha1_hash dht_put_item (entry data);
│ │ │ │ - void dht_put_item (std::array<char, 32> key
│ │ │ │ - , std::function<void(entry&, std::array<char, 64>&
│ │ │ │ - , std::int64_t&, std::string const&)> cb
│ │ │ │ - , std::string salt = std::string());
│ │ │ │ - void dht_announce (sha1_hash const& info_hash, int port = 0, dht::announce_flags_t flags = {});
│ │ │ │ - void dht_get_peers (sha1_hash const& info_hash);
│ │ │ │ - void dht_live_nodes (sha1_hash const& nid);
│ │ │ │ - void dht_sample_infohashes (udp::endpoint const& ep, sha1_hash const& target);
│ │ │ │ - void dht_direct_request (udp::endpoint const& ep, entry const& e, client_data_t userdata = {});
│ │ │ │ - void add_extension (std::function<std::shared_ptr<torrent_plugin>(
│ │ │ │ - torrent_handle const&, client_data_t)> ext);
│ │ │ │ - void add_extension (std::shared_ptr<plugin> ext);
│ │ │ │ - ip_filter get_ip_filter () const;
│ │ │ │ - void set_ip_filter (ip_filter f);
│ │ │ │ - void set_port_filter (port_filter const& f);
│ │ │ │ - bool is_listening () const;
│ │ │ │ - unsigned short ssl_listen_port () const;
│ │ │ │ - unsigned short listen_port () const;
│ │ │ │ - ip_filter get_peer_class_filter () const;
│ │ │ │ - void set_peer_class_filter (ip_filter const& f);
│ │ │ │ - void set_peer_class_type_filter (peer_class_type_filter const& f);
│ │ │ │ - peer_class_type_filter get_peer_class_type_filter () const;
│ │ │ │ - peer_class_t create_peer_class (char const* name);
│ │ │ │ - void delete_peer_class (peer_class_t cid);
│ │ │ │ - void set_peer_class (peer_class_t cid, peer_class_info const& pci);
│ │ │ │ - peer_class_info get_peer_class (peer_class_t cid) const;
│ │ │ │ - void remove_torrent (const torrent_handle&, remove_flags_t = {});
│ │ │ │ - void apply_settings (settings_pack&&);
│ │ │ │ - settings_pack get_settings () const;
│ │ │ │ - void apply_settings (settings_pack const&);
│ │ │ │ - void pop_alerts (std::vector<alert*>* alerts);
│ │ │ │ - alert* wait_for_alert (time_duration max_wait);
│ │ │ │ - void set_alert_notify (std::function<void()> const& fun);
│ │ │ │ - void delete_port_mapping (port_mapping_t handle);
│ │ │ │ - std::vector<port_mapping_t> add_port_mapping (portmap_protocol t, int external_port, int local_port);
│ │ │ │ - void reopen_network_sockets (reopen_network_flags_t options = reopen_map_ports);
│ │ │ │ - std::shared_ptr<aux::session_impl> native_handle () const;
│ │ │ │ -
│ │ │ │ - static constexpr save_state_flags_t save_settings = 0_bit;
│ │ │ │ - static constexpr save_state_flags_t save_dht_state = 2_bit;
│ │ │ │ - static constexpr save_state_flags_t save_extension_state = 11_bit;
│ │ │ │ - static constexpr save_state_flags_t save_ip_filter = 12_bit;
│ │ │ │ - static constexpr peer_class_t global_peer_class_id {0};
│ │ │ │ - static constexpr peer_class_t tcp_peer_class_id {1};
│ │ │ │ - static constexpr peer_class_t local_peer_class_id {2};
│ │ │ │ - static constexpr remove_flags_t delete_files = 0_bit;
│ │ │ │ - static constexpr remove_flags_t delete_partfile = 1_bit;
│ │ │ │ - static constexpr session_flags_t paused = 2_bit;
│ │ │ │ - static constexpr portmap_protocol udp = portmap_protocol::udp;
│ │ │ │ - static constexpr portmap_protocol tcp = portmap_protocol::tcp;
│ │ │ │ - static constexpr reopen_network_flags_t reopen_map_ports = 0_bit;
│ │ │ │ -};
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
is_valid()
│ │ │ │ -
│ │ │ │ -bool is_valid () const;
│ │ │ │ -
│ │ │ │ -
returns true if this handle refers to a valid session object. If the
│ │ │ │ -session has been destroyed, all session_handle objects will expire and
│ │ │ │ -not be valid.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
session_state()
│ │ │ │ -
│ │ │ │ -session_params session_state (save_state_flags_t flags = save_state_flags_t::all()) const;
│ │ │ │ -
│ │ │ │ -
returns the current session state. This can be passed to
│ │ │ │ -write_session_params() to save the state to disk and restored using
│ │ │ │ -read_session_params() when constructing a new session. The kind of
│ │ │ │ -state that's included is all settings, the DHT routing table, possibly
│ │ │ │ -plugin-specific state.
│ │ │ │ -the flags parameter can be used to only save certain parts of the
│ │ │ │ -session state
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
get_torrent_status() refresh_torrent_status()
│ │ │ │ -
│ │ │ │ -std::vector<torrent_status> get_torrent_status (
│ │ │ │ - std::function<bool(torrent_status const&)> const& pred
│ │ │ │ - , status_flags_t flags = {}) const;
│ │ │ │ -void refresh_torrent_status (std::vector<torrent_status>* ret
│ │ │ │ - , status_flags_t flags = {}) const;
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
Note
│ │ │ │ -
these calls are potentially expensive and won't scale well with
│ │ │ │ -lots of torrents. If you're concerned about performance, consider
│ │ │ │ -using post_torrent_updates() instead.
│ │ │ │ -
│ │ │ │ -
get_torrent_status returns a vector of the torrent_status for
│ │ │ │ -every torrent which satisfies pred, which is a predicate function
│ │ │ │ -which determines if a torrent should be included in the returned set
│ │ │ │ -or not. Returning true means it should be included and false means
│ │ │ │ -excluded. The flags argument is the same as to
│ │ │ │ -torrent_handle::status(). Since pred is guaranteed to be
│ │ │ │ -called for every torrent, it may be used to count the number of
│ │ │ │ -torrents of different categories as well.
│ │ │ │ -
refresh_torrent_status takes a vector of torrent_status structs
│ │ │ │ -(for instance the same vector that was returned by
│ │ │ │ -get_torrent_status() ) and refreshes the status based on the
│ │ │ │ -handle member. It is possible to use this function by first
│ │ │ │ -setting up a vector of default constructed torrent_status objects,
│ │ │ │ -only initializing the handle member, in order to request the
│ │ │ │ -torrent status for multiple torrents in a single call. This can save a
│ │ │ │ -significant amount of time if you have a lot of torrents.
│ │ │ │ -
Any torrent_status object whose handle member is not referring to
│ │ │ │ -a valid torrent are ignored.
│ │ │ │ -
The intended use of these functions is to start off by calling
│ │ │ │ -get_torrent_status() to get a list of all torrents that match your
│ │ │ │ -criteria. Then call refresh_torrent_status() on that list. This
│ │ │ │ -will only refresh the status for the torrents in your list, and thus
│ │ │ │ -ignore all other torrents you might be running. This may save a
│ │ │ │ -significant amount of time, especially if the number of torrents you're
│ │ │ │ -interested in is small. In order to keep your list of interested
│ │ │ │ -torrents up to date, you can either call get_torrent_status() from
│ │ │ │ -time to time, to include torrents you might have become interested in
│ │ │ │ -since the last time. In order to stop refreshing a certain torrent,
│ │ │ │ -simply remove it from the list.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
post_torrent_updates()
│ │ │ │ -
│ │ │ │ -void post_torrent_updates (status_flags_t flags = status_flags_t::all());
│ │ │ │ -
│ │ │ │ -
This functions instructs the session to post the state_update_alert,
│ │ │ │ -containing the status of all torrents whose state changed since the
│ │ │ │ -last time this function was called.
│ │ │ │ -
Only torrents who has the state subscription flag set will be
│ │ │ │ -included. This flag is on by default. See add_torrent_params.
│ │ │ │ -the flags argument is the same as for torrent_handle::status().
│ │ │ │ -see status_flags_t in torrent_handle.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
post_session_stats()
│ │ │ │ -
│ │ │ │ -void post_session_stats ();
│ │ │ │ -
│ │ │ │ -
This function will post a session_stats_alert object, containing a
│ │ │ │ -snapshot of the performance counters from the internals of libtorrent.
│ │ │ │ -To interpret these counters, query the session via
│ │ │ │ -session_stats_metrics().
│ │ │ │ -
For more information, see the session statistics section.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
post_dht_stats()
│ │ │ │ -
│ │ │ │ -void post_dht_stats ();
│ │ │ │ -
│ │ │ │ -
This will cause a dht_stats_alert to be posted.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
set_dht_state()
│ │ │ │ -
│ │ │ │ -void set_dht_state (dht::dht_state const& st);
│ │ │ │ -void set_dht_state (dht::dht_state&& st);
│ │ │ │ -
│ │ │ │ -
set the DHT state for the session. This will be taken into account the
│ │ │ │ -next time the DHT is started, as if it had been passed in via the
│ │ │ │ -session_params on startup.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
get_torrents() find_torrent()
│ │ │ │ -
│ │ │ │ -std::vector<torrent_handle> get_torrents () const;
│ │ │ │ -torrent_handle find_torrent (sha1_hash const& info_hash) const;
│ │ │ │ -
│ │ │ │ -
find_torrent() looks for a torrent with the given info-hash. In
│ │ │ │ -case there is such a torrent in the session, a torrent_handle to that
│ │ │ │ -torrent is returned. In case the torrent cannot be found, an invalid
│ │ │ │ -torrent_handle is returned.
│ │ │ │ -
See torrent_handle::is_valid() to know if the torrent was found or
│ │ │ │ -not.
│ │ │ │ -
get_torrents() returns a vector of torrent_handles to all the
│ │ │ │ -torrents currently in the session.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
async_add_torrent() add_torrent()
│ │ │ │ -
│ │ │ │ -void async_add_torrent (add_torrent_params const& params);
│ │ │ │ -torrent_handle add_torrent (add_torrent_params const& params);
│ │ │ │ -void async_add_torrent (add_torrent_params&& params);
│ │ │ │ -torrent_handle add_torrent (add_torrent_params&& params, error_code& ec);
│ │ │ │ -torrent_handle add_torrent (add_torrent_params&& params);
│ │ │ │ -torrent_handle add_torrent (add_torrent_params const& params, error_code& ec);
│ │ │ │ -
│ │ │ │ -
You add torrents through the add_torrent() function where you give an
│ │ │ │ -object with all the parameters. The add_torrent() overloads will block
│ │ │ │ -until the torrent has been added (or failed to be added) and returns
│ │ │ │ -an error code and a torrent_handle. In order to add torrents more
│ │ │ │ -efficiently, consider using async_add_torrent() which returns
│ │ │ │ -immediately, without waiting for the torrent to add. Notification of
│ │ │ │ -the torrent being added is sent as add_torrent_alert.
│ │ │ │ -
The save_path field in add_torrent_params must be set to a valid
│ │ │ │ -path where the files for the torrent will be saved. Even when using a
│ │ │ │ -custom storage, this needs to be set to something. If the save_path
│ │ │ │ -is empty, the call to add_torrent() will throw a system_error
│ │ │ │ -exception.
│ │ │ │ -
The overload that does not take an error_code throws an exception on
│ │ │ │ -error and is not available when building without exception support.
│ │ │ │ -The torrent_handle returned by add_torrent() can be used to retrieve
│ │ │ │ -information about the torrent's progress, its peers etc. It is also
│ │ │ │ -used to abort a torrent.
│ │ │ │ -
If the torrent you are trying to add already exists in the session (is
│ │ │ │ -either queued for checking, being checked or downloading)
│ │ │ │ -add_torrent() will throw system_error which derives from
│ │ │ │ -std::exception unless duplicate_is_error is set to false. In that
│ │ │ │ -case, add_torrent() will return the handle to the existing torrent.
│ │ │ │ -
The add_torrent_params class has a flags field. It can be used to
│ │ │ │ -control what state the new torrent will be added in. Common flags to
│ │ │ │ -want to control are torrent_flags::paused and
│ │ │ │ -torrent_flags::auto_managed. In order to add a magnet link that will
│ │ │ │ -just download the metadata, but no payload, set the
│ │ │ │ -torrent_flags::upload_mode flag.
│ │ │ │ -
Special consideration has to be taken when adding hybrid torrents
│ │ │ │ -(i.e. torrents that are BitTorrent v2 torrents that are backwards
│ │ │ │ -compatible with v1). For more details, see BitTorrent v2 torrents.
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
pause() resume() is_paused()
│ │ │ │ -
│ │ │ │ -void pause ();
│ │ │ │ -bool is_paused () const;
│ │ │ │ -void resume ();
│ │ │ │ -
│ │ │ │ -
Pausing the session has the same effect as pausing every torrent in
│ │ │ │ -it, except that torrents will not be resumed by the auto-manage
│ │ │ │ -mechanism. Resuming will restore the torrents to their previous paused
│ │ │ │ -state. i.e. the session pause state is separate from the torrent pause
│ │ │ │ -state. A torrent is inactive if it is paused or if the session is
│ │ │ │ -paused.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
is_dht_running()
│ │ │ │ -
│ │ │ │ -bool is_dht_running () const;
│ │ │ │ -
│ │ │ │ -
is_dht_running() returns true if the DHT support has been started
│ │ │ │ -and false otherwise.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
set_dht_storage()
│ │ │ │ -
│ │ │ │ -void set_dht_storage (dht::dht_storage_constructor_type sc);
│ │ │ │ -
│ │ │ │ -
set_dht_storage set a dht custom storage constructor function
│ │ │ │ -to be used internally when the dht is created.
│ │ │ │ -
Since the dht storage is a critical component for the dht behavior,
│ │ │ │ -this function will only be effective the next time the dht is started.
│ │ │ │ -If you never touch this feature, a default map-memory based storage
│ │ │ │ -is used.
│ │ │ │ -
If you want to make sure the dht is initially created with your
│ │ │ │ -custom storage, create a session with the setting
│ │ │ │ -settings_pack::enable_dht to false, set your constructor function
│ │ │ │ -and call apply_settings with settings_pack::enable_dht to true.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
add_dht_node()
│ │ │ │ -
│ │ │ │ -void add_dht_node (std::pair<std::string, int> const& node);
│ │ │ │ -
│ │ │ │ -
add_dht_node takes a host name and port pair. That endpoint will be
│ │ │ │ -pinged, and if a valid DHT reply is received, the node will be added to
│ │ │ │ -the routing table.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
dht_get_item()
│ │ │ │ -
│ │ │ │ -void dht_get_item (sha1_hash const& target);
│ │ │ │ -
│ │ │ │ -
query the DHT for an immutable item at the target hash.
│ │ │ │ -the result is posted as a dht_immutable_item_alert.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
dht_get_item()
│ │ │ │ -
│ │ │ │ -void dht_get_item (std::array<char, 32> key
│ │ │ │ - , std::string salt = std::string());
│ │ │ │ -
│ │ │ │ -
query the DHT for a mutable item under the public key key.
│ │ │ │ -this is an ed25519 key. salt is optional and may be left
│ │ │ │ -as an empty string if no salt is to be used.
│ │ │ │ -if the item is found in the DHT, a dht_mutable_item_alert is
│ │ │ │ -posted.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
dht_put_item()
│ │ │ │ -
│ │ │ │ -sha1_hash dht_put_item (entry data);
│ │ │ │ -
│ │ │ │ -
store the given bencoded data as an immutable item in the DHT.
│ │ │ │ -the returned hash is the key that is to be used to look the item
│ │ │ │ -up again. It's just the SHA-1 hash of the bencoded form of the
│ │ │ │ -structure.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
dht_put_item()
│ │ │ │ -
│ │ │ │ -void dht_put_item (std::array<char, 32> key
│ │ │ │ - , std::function<void(entry&, std::array<char, 64>&
│ │ │ │ - , std::int64_t&, std::string const&)> cb
│ │ │ │ - , std::string salt = std::string());
│ │ │ │ -
│ │ │ │ -
store a mutable item. The key is the public key the blob is
│ │ │ │ -to be stored under. The optional salt argument is a string that
│ │ │ │ -is to be mixed in with the key when determining where in the DHT
│ │ │ │ -the value is to be stored. The callback function is called from within
│ │ │ │ -the libtorrent network thread once we've found where to store the blob,
│ │ │ │ -possibly with the current value stored under the key.
│ │ │ │ -The values passed to the callback functions are:
│ │ │ │ -
│ │ │ │ -- entry& value
│ │ │ │ -- the current value stored under the key (may be empty). Also expected
│ │ │ │ -to be set to the value to be stored by the function.
│ │ │ │ -- std::array<char,64>& signature
│ │ │ │ -- the signature authenticating the current value. This may be zeros
│ │ │ │ -if there is currently no value stored. The function is expected to
│ │ │ │ -fill in this buffer with the signature of the new value to store.
│ │ │ │ -To generate the signature, you may want to use the
│ │ │ │ -sign_mutable_item function.
│ │ │ │ -- std::int64_t& seq
│ │ │ │ -- current sequence number. May be zero if there is no current value.
│ │ │ │ -The function is expected to set this to the new sequence number of
│ │ │ │ -the value that is to be stored. Sequence numbers must be monotonically
│ │ │ │ -increasing. Attempting to overwrite a value with a lower or equal
│ │ │ │ -sequence number will fail, even if the signature is correct.
│ │ │ │ -- std::string const& salt
│ │ │ │ -- this is the salt that was used for this put call.
│ │ │ │ -
│ │ │ │ -
Since the callback function cb is called from within libtorrent,
│ │ │ │ -it is critical to not perform any blocking operations. Ideally not
│ │ │ │ -even locking a mutex. Pass any data required for this function along
│ │ │ │ -with the function object's context and make the function entirely
│ │ │ │ -self-contained. The only reason data blob's value is computed
│ │ │ │ -via a function instead of just passing in the new value is to avoid
│ │ │ │ -race conditions. If you want to update the value in the DHT, you
│ │ │ │ -must first retrieve it, then modify it, then write it back. The way
│ │ │ │ -the DHT works, it is natural to always do a lookup before storing and
│ │ │ │ -calling the callback in between is convenient.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
dht_announce() dht_get_peers()
│ │ │ │ -
│ │ │ │ -void dht_announce (sha1_hash const& info_hash, int port = 0, dht::announce_flags_t flags = {});
│ │ │ │ -void dht_get_peers (sha1_hash const& info_hash);
│ │ │ │ -
│ │ │ │ -
dht_get_peers() will issue a DHT get_peer request to the DHT for the
│ │ │ │ -specified info-hash. The response (the peers) will be posted back in a
│ │ │ │ -dht_get_peers_reply_alert.
│ │ │ │ -
dht_announce() will issue a DHT announce request to the DHT to the
│ │ │ │ -specified info-hash, advertising the specified port. If the port is
│ │ │ │ -left at its default, 0, the port will be implied by the DHT message's
│ │ │ │ -source port (which may improve connectivity through a NAT).
│ │ │ │ -dht_announce() is not affected by the announce_port override setting.
│ │ │ │ -
Both these functions are exposed for advanced custom use of the DHT.
│ │ │ │ -All torrents eligible to be announce to the DHT will be automatically,
│ │ │ │ -by libtorrent.
│ │ │ │ -
For possible flags, see announce_flags_t.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
dht_live_nodes()
│ │ │ │ -
│ │ │ │ -void dht_live_nodes (sha1_hash const& nid);
│ │ │ │ -
│ │ │ │ -
Retrieve all the live DHT (identified by nid) nodes. All the
│ │ │ │ -nodes id and endpoint will be returned in the list of nodes in the
│ │ │ │ -alert dht_live_nodes_alert.
│ │ │ │ -Since this alert is a response to an explicit call, it will always be
│ │ │ │ -posted, regardless of the alert mask.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
dht_sample_infohashes()
│ │ │ │ -
│ │ │ │ -void dht_sample_infohashes (udp::endpoint const& ep, sha1_hash const& target);
│ │ │ │ -
│ │ │ │ -
Query the DHT node specified by ep to retrieve a sample of the
│ │ │ │ -info-hashes that the node currently have in their storage.
│ │ │ │ -The target is included for iterative lookups so that indexing nodes
│ │ │ │ -can perform a key space traversal with a single RPC per node by adjusting
│ │ │ │ -the target value for each RPC. It has no effect on the returned sample value.
│ │ │ │ -The result is posted as a dht_sample_infohashes_alert.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
dht_direct_request()
│ │ │ │ -
│ │ │ │ -void dht_direct_request (udp::endpoint const& ep, entry const& e, client_data_t userdata = {});
│ │ │ │ -
│ │ │ │ -
Send an arbitrary DHT request directly to the specified endpoint. This
│ │ │ │ -function is intended for use by plugins. When a response is received
│ │ │ │ -or the request times out, a dht_direct_response_alert will be posted
│ │ │ │ -with the response (if any) and the userdata pointer passed in here.
│ │ │ │ -Since this alert is a response to an explicit call, it will always be
│ │ │ │ -posted, regardless of the alert mask.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
add_extension()
│ │ │ │ -
│ │ │ │ -void add_extension (std::function<std::shared_ptr<torrent_plugin>(
│ │ │ │ - torrent_handle const&, client_data_t)> ext);
│ │ │ │ -void add_extension (std::shared_ptr<plugin> ext);
│ │ │ │ -
│ │ │ │ -
This function adds an extension to this session. The argument is a
│ │ │ │ -function object that is called with a torrent_handle and which should
│ │ │ │ -return a std::shared_ptr<torrent_plugin>. To write custom
│ │ │ │ -plugins, see libtorrent plugins. For the typical bittorrent client
│ │ │ │ -all of these extensions should be added. The main plugins implemented
│ │ │ │ -in libtorrent are:
│ │ │ │ -
│ │ │ │ -- uTorrent metadata
│ │ │ │ -- Allows peers to download the metadata (.torrent files) from the swarm
│ │ │ │ -directly. Makes it possible to join a swarm with just a tracker and
│ │ │ │ -info-hash.
│ │ │ │ -
│ │ │ │ -
│ │ │ │ - ses.add_extension(<::create_ut_metadata_plugin);
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -- uTorrent peer exchange
│ │ │ │ -- Exchanges peers between clients.
│ │ │ │ -
│ │ │ │ -
│ │ │ │ - ses.add_extension(<::create_ut_pex_plugin);
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -- smart ban plugin
│ │ │ │ -- A plugin that, with a small overhead, can ban peers
│ │ │ │ -that sends bad data with very high accuracy. Should
│ │ │ │ -eliminate most problems on poisoned torrents.
│ │ │ │ -
│ │ │ │ -
│ │ │ │ - ses.add_extension(<::create_smart_ban_plugin);
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
set_ip_filter() get_ip_filter()
│ │ │ │ -
│ │ │ │ -ip_filter get_ip_filter () const;
│ │ │ │ -void set_ip_filter (ip_filter f);
│ │ │ │ -
│ │ │ │ -
Sets a filter that will be used to reject and accept incoming as well
│ │ │ │ -as outgoing connections based on their originating ip address. The
│ │ │ │ -default filter will allow connections to any ip address. To build a
│ │ │ │ -set of rules for which addresses are accepted and not, see ip_filter.
│ │ │ │ -
Each time a peer is blocked because of the IP filter, a
│ │ │ │ -peer_blocked_alert is generated. get_ip_filter() Returns the
│ │ │ │ -ip_filter currently in the session. See ip_filter.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
set_port_filter()
│ │ │ │ -
│ │ │ │ -void set_port_filter (port_filter const& f);
│ │ │ │ -
│ │ │ │ -
apply port_filter f to incoming and outgoing peers. a port filter
│ │ │ │ -will reject making outgoing peer connections to certain remote ports.
│ │ │ │ -The main intention is to be able to avoid triggering certain
│ │ │ │ -anti-virus software by connecting to SMTP, FTP ports.
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
ssl_listen_port() listen_port() is_listening()
│ │ │ │ -
│ │ │ │ -bool is_listening () const;
│ │ │ │ -unsigned short ssl_listen_port () const;
│ │ │ │ -unsigned short listen_port () const;
│ │ │ │ -
│ │ │ │ -
is_listening() will tell you whether or not the session has
│ │ │ │ -successfully opened a listening port. If it hasn't, this function will
│ │ │ │ -return false, and then you can set a new
│ │ │ │ -settings_pack::listen_interfaces to try another interface and port to
│ │ │ │ -bind to.
│ │ │ │ -
listen_port() returns the port we ended up listening on.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
get_peer_class_filter() set_peer_class_filter()
│ │ │ │ -
│ │ │ │ -ip_filter get_peer_class_filter () const;
│ │ │ │ -void set_peer_class_filter (ip_filter const& f);
│ │ │ │ -
│ │ │ │ -
Sets the peer class filter for this session. All new peer connections
│ │ │ │ -will take this into account and be added to the peer classes specified
│ │ │ │ -by this filter, based on the peer's IP address.
│ │ │ │ -
The ip-filter essentially maps an IP -> uint32. Each bit in that 32
│ │ │ │ -bit integer represents a peer class. The least significant bit
│ │ │ │ -represents class 0, the next bit class 1 and so on.
│ │ │ │ -
For more info, see ip_filter.
│ │ │ │ -
For example, to make all peers in the range 200.1.1.0 - 200.1.255.255
│ │ │ │ -belong to their own peer class, apply the following filter:
│ │ │ │ -
│ │ │ │ -ip_filter f = ses.get_peer_class_filter();
│ │ │ │ -peer_class_t my_class = ses.create_peer_class("200.1.x.x IP range");
│ │ │ │ -f.add_rule(make_address("200.1.1.0"), make_address("200.1.255.255")
│ │ │ │ - , 1 << static_cast<std::uint32_t>(my_class));
│ │ │ │ -ses.set_peer_class_filter(f);
│ │ │ │ -
│ │ │ │ -
This setting only applies to new connections, it won't affect existing
│ │ │ │ -peer connections.
│ │ │ │ -
This function is limited to only peer class 0-31, since there are only
│ │ │ │ -32 bits in the IP range mapping. Only the set bits matter; no peer
│ │ │ │ -class will be removed from a peer as a result of this call, peer
│ │ │ │ -classes are only added.
│ │ │ │ -
The peer_class argument cannot be greater than 31. The bitmasks
│ │ │ │ -representing peer classes in the peer_class_filter are 32 bits.
│ │ │ │ -
The get_peer_class_filter() function returns the current filter.
│ │ │ │ -
For more information, see peer classes.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
set_peer_class_type_filter() get_peer_class_type_filter()
│ │ │ │ -
│ │ │ │ -void set_peer_class_type_filter (peer_class_type_filter const& f);
│ │ │ │ -peer_class_type_filter get_peer_class_type_filter () const;
│ │ │ │ -
│ │ │ │ -
Sets and gets the peer class type filter. This is controls automatic
│ │ │ │ -peer class assignments to peers based on what kind of socket it is.
│ │ │ │ -
It does not only support assigning peer classes, it also supports
│ │ │ │ -removing peer classes based on socket type.
│ │ │ │ -
The order of these rules being applied are:
│ │ │ │ -
│ │ │ │ -- peer-class IP filter
│ │ │ │ -- peer-class type filter, removing classes
│ │ │ │ -- peer-class type filter, adding classes
│ │ │ │ -
│ │ │ │ -
For more information, see peer classes.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
create_peer_class()
│ │ │ │ -
│ │ │ │ -peer_class_t create_peer_class (char const* name);
│ │ │ │ -
│ │ │ │ -
Creates a new peer class (see peer classes) with the given name. The
│ │ │ │ -returned integer is the new peer class identifier. Peer classes may
│ │ │ │ -have the same name, so each invocation of this function creates a new
│ │ │ │ -class and returns a unique identifier.
│ │ │ │ -
Identifiers are assigned from low numbers to higher. So if you plan on
│ │ │ │ -using certain peer classes in a call to set_peer_class_filter(),
│ │ │ │ -make sure to create those early on, to get low identifiers.
│ │ │ │ -
For more information on peer classes, see peer classes.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
delete_peer_class()
│ │ │ │ -
│ │ │ │ -void delete_peer_class (peer_class_t cid);
│ │ │ │ -
│ │ │ │ -
This call dereferences the reference count of the specified peer
│ │ │ │ -class. When creating a peer class it's automatically referenced by 1.
│ │ │ │ -If you want to recycle a peer class, you may call this function. You
│ │ │ │ -may only call this function once per peer class you create.
│ │ │ │ -Calling it more than once for the same class will lead to memory
│ │ │ │ -corruption.
│ │ │ │ -
Since peer classes are reference counted, this function will not
│ │ │ │ -remove the peer class if it's still assigned to torrents or peers. It
│ │ │ │ -will however remove it once the last peer and torrent drops their
│ │ │ │ -references to it.
│ │ │ │ -
There is no need to call this function for custom peer classes. All
│ │ │ │ -peer classes will be properly destructed when the session object
│ │ │ │ -destructs.
│ │ │ │ -
For more information on peer classes, see peer classes.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
set_peer_class() get_peer_class()
│ │ │ │ -
│ │ │ │ -void set_peer_class (peer_class_t cid, peer_class_info const& pci);
│ │ │ │ -peer_class_info get_peer_class (peer_class_t cid) const;
│ │ │ │ -
│ │ │ │ -
These functions queries information from a peer class and updates the
│ │ │ │ -configuration of a peer class, respectively.
│ │ │ │ -
cid must refer to an existing peer class. If it does not, the
│ │ │ │ -return value of get_peer_class() is undefined.
│ │ │ │ -
set_peer_class() sets all the information in the
│ │ │ │ -peer_class_info object in the specified peer class. There is no
│ │ │ │ -option to only update a single property.
│ │ │ │ -
A peer or torrent belonging to more than one class, the highest
│ │ │ │ -priority among any of its classes is the one that is taken into
│ │ │ │ -account.
│ │ │ │ -
For more information, see peer classes.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
remove_torrent()
│ │ │ │ -
│ │ │ │ -void remove_torrent (const torrent_handle&, remove_flags_t = {});
│ │ │ │ -
│ │ │ │ -
remove_torrent() will close all peer connections associated with
│ │ │ │ -the torrent and tell the tracker that we've stopped participating in
│ │ │ │ -the swarm. This operation cannot fail. When it completes, you will
│ │ │ │ -receive a torrent_removed_alert.
│ │ │ │ -
remove_torrent() is non-blocking, but will remove the torrent from the
│ │ │ │ -session synchronously. Calling session_handle::add_torrent() immediately
│ │ │ │ -afterward with the same torrent will succeed. Note that this creates a
│ │ │ │ -new handle which is not equal to the removed one.
│ │ │ │ -
The optional second argument options can be used to delete all the
│ │ │ │ -files downloaded by this torrent. To do so, pass in the value
│ │ │ │ -session_handle::delete_files. Once the torrent is deleted, a
│ │ │ │ -torrent_deleted_alert is posted.
│ │ │ │ -
The torrent_handle remains valid for some time after remove_torrent() is
│ │ │ │ -called. It will become invalid only after all libtorrent tasks (such as
│ │ │ │ -I/O tasks) release their references to the torrent. Until this happens,
│ │ │ │ -torrent_handle::is_valid() will return true, and other calls such
│ │ │ │ -as torrent_handle::status() will succeed. Because of this, and because
│ │ │ │ -remove_torrent() is non-blocking, the following sequence usually
│ │ │ │ -succeeds (does not throw system_error):
│ │ │ │ -.. code:: c++
│ │ │ │ -
│ │ │ │ -session.remove_handle(handle);
│ │ │ │ -handle.save_resume_data();
│ │ │ │ -
Note that when a queued or downloading torrent is removed, its position
│ │ │ │ -in the download queue is vacated and every subsequent torrent in the
│ │ │ │ -queue has their queue positions updated. This can potentially cause a
│ │ │ │ -large state_update to be posted. When removing all torrents, it is
│ │ │ │ -advised to remove them from the back of the queue, to minimize the
│ │ │ │ -shifting.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
apply_settings() get_settings()
│ │ │ │ -
│ │ │ │ -void apply_settings (settings_pack&&);
│ │ │ │ -settings_pack get_settings () const;
│ │ │ │ -void apply_settings (settings_pack const&);
│ │ │ │ -
│ │ │ │ -
Applies the settings specified by the settings_pack s. This is an
│ │ │ │ -asynchronous operation that will return immediately and actually apply
│ │ │ │ -the settings to the main thread of libtorrent some time later.
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
pop_alerts() wait_for_alert() set_alert_notify()
│ │ │ │ -
│ │ │ │ -void pop_alerts (std::vector<alert*>* alerts);
│ │ │ │ -alert* wait_for_alert (time_duration max_wait);
│ │ │ │ -void set_alert_notify (std::function<void()> const& fun);
│ │ │ │ -
│ │ │ │ -
Alerts is the main mechanism for libtorrent to report errors and
│ │ │ │ -events. pop_alerts fills in the vector passed to it with pointers
│ │ │ │ -to new alerts. The session still owns these alerts and they will stay
│ │ │ │ -valid until the next time pop_alerts is called. You may not delete
│ │ │ │ -the alert objects.
│ │ │ │ -
It is safe to call pop_alerts from multiple different threads, as
│ │ │ │ -long as the alerts themselves are not accessed once another thread
│ │ │ │ -calls pop_alerts. Doing this requires manual synchronization
│ │ │ │ -between the popping threads.
│ │ │ │ -
wait_for_alert will block the current thread for max_wait time
│ │ │ │ -duration, or until another alert is posted. If an alert is available
│ │ │ │ -at the time of the call, it returns immediately. The returned alert
│ │ │ │ -pointer is the head of the alert queue. wait_for_alert does not
│ │ │ │ -pop alerts from the queue, it merely peeks at it. The returned alert
│ │ │ │ -will stay valid until pop_alerts is called twice. The first time
│ │ │ │ -will pop it and the second will free it.
│ │ │ │ -
If there is no alert in the queue and no alert arrives within the
│ │ │ │ -specified timeout, wait_for_alert returns nullptr.
│ │ │ │ -
In the python binding, wait_for_alert takes the number of
│ │ │ │ -milliseconds to wait as an integer.
│ │ │ │ -
The alert queue in the session will not grow indefinitely. Make sure
│ │ │ │ -to pop periodically to not miss notifications. To control the max
│ │ │ │ -number of alerts that's queued by the session, see
│ │ │ │ -settings_pack::alert_queue_size.
│ │ │ │ -
Some alerts are considered so important that they are posted even when
│ │ │ │ -the alert queue is full. Some alerts are considered mandatory and cannot
│ │ │ │ -be disabled by the alert_mask. For instance,
│ │ │ │ -save_resume_data_alert and save_resume_data_failed_alert are always
│ │ │ │ -posted, regardless of the alert mask.
│ │ │ │ -
To control which alerts are posted, set the alert_mask
│ │ │ │ -(settings_pack::alert_mask).
│ │ │ │ -
If the alert queue fills up to the point where alerts are dropped, this
│ │ │ │ -will be indicated by a alerts_dropped_alert, which contains a bitmask
│ │ │ │ -of which types of alerts were dropped. Generally it is a good idea to
│ │ │ │ -make sure the alert queue is large enough, the alert_mask doesn't have
│ │ │ │ -unnecessary categories enabled and to call pop_alert() frequently, to
│ │ │ │ -avoid alerts being dropped.
│ │ │ │ -
the set_alert_notify function lets the client set a function object
│ │ │ │ -to be invoked every time the alert queue goes from having 0 alerts to
│ │ │ │ -1 alert. This function is called from within libtorrent, it may be the
│ │ │ │ -main thread, or it may be from within a user call. The intention of
│ │ │ │ -of the function is that the client wakes up its main thread, to poll
│ │ │ │ -for more alerts using pop_alerts(). If the notify function fails
│ │ │ │ -to do so, it won't be called again, until pop_alerts is called for
│ │ │ │ -some other reason. For instance, it could signal an eventfd, post a
│ │ │ │ -message to an HWND or some other main message pump. The actual
│ │ │ │ -retrieval of alerts should not be done in the callback. In fact, the
│ │ │ │ -callback should not block. It should not perform any expensive work.
│ │ │ │ -It really should just notify the main application thread.
│ │ │ │ -
The type of an alert is returned by the polymorphic function
│ │ │ │ -alert::type() but can also be queries from a concrete type via
│ │ │ │ -T::alert_type, as a static constant.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
add_port_mapping() delete_port_mapping()
│ │ │ │ -
│ │ │ │ -void delete_port_mapping (port_mapping_t handle);
│ │ │ │ -std::vector<port_mapping_t> add_port_mapping (portmap_protocol t, int external_port, int local_port);
│ │ │ │ -
│ │ │ │ -
add_port_mapping adds one or more port forwards on UPnP and/or NAT-PMP,
│ │ │ │ -whichever is enabled. A mapping is created for each listen socket
│ │ │ │ -in the session. The return values are all handles referring to the
│ │ │ │ -port mappings that were just created. Pass them to delete_port_mapping()
│ │ │ │ -to remove them.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
reopen_network_sockets()
│ │ │ │ -
│ │ │ │ -void reopen_network_sockets (reopen_network_flags_t options = reopen_map_ports);
│ │ │ │ -
│ │ │ │ -
Instructs the session to reopen all listen and outgoing sockets.
│ │ │ │ -
It's useful in the case your platform doesn't support the built in
│ │ │ │ -IP notifier mechanism, or if you have a better more reliable way to
│ │ │ │ -detect changes in the IP routing table.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
native_handle()
│ │ │ │ -
│ │ │ │ -std::shared_ptr<aux::session_impl> native_handle () const;
│ │ │ │ -
│ │ │ │ -
This function is intended only for use by plugins. This type does
│ │ │ │ -not have a stable API and should be relied on as little as possible.
│ │ │ │ -
[report issue]
│ │ │ │ -- save_settings
│ │ │ │ -- saves settings (i.e. the settings_pack)
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -- save_dht_state
│ │ │ │ -- saves dht state such as nodes and node-id, possibly accelerating
│ │ │ │ -joining the DHT if provided at next session startup.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -- save_extension_state
│ │ │ │ -- load or save state from plugins
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -- save_ip_filter
│ │ │ │ -- load or save the IP filter set on the session
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -- global_peer_class_id tcp_peer_class_id local_peer_class_id
│ │ │ │ -- built-in peer classes
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -- delete_files
│ │ │ │ -- delete the files belonging to the torrent from disk.
│ │ │ │ -including the part-file, if there is one
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -- delete_partfile
│ │ │ │ -- delete just the part-file associated with this torrent
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -- paused
│ │ │ │ -- when set, the session will start paused. Call
│ │ │ │ -session_handle::resume() to start
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -- udp tcp
│ │ │ │ -- protocols used by add_port_mapping()
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -- reopen_map_ports
│ │ │ │ -- This option indicates if the ports are mapped using natpmp
│ │ │ │ -and upnp. If mapping was already made, they are deleted and added
│ │ │ │ -again. This only works if natpmp and/or upnp are configured to be
│ │ │ │ -enable.
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │
stats_metric
│ │ │ │
Declared in "libtorrent/session_stats.hpp"
│ │ │ │
describes one statistics metric from the session. For more information,
│ │ │ │ see the session statistics section.
│ │ │ │
│ │ │ │ @@ -5460,26 +3416,26 @@
│ │ │ │ Declared in "libtorrent/performance_counters.hpp"
│ │ │ │
│ │ │ │ struct counters
│ │ │ │ {
│ │ │ │ counters () ;
│ │ │ │ counters (counters const&) ;
│ │ │ │ counters& operator= (counters const&) & ;
│ │ │ │ - std::int64_t operator[] (int i) const ;
│ │ │ │ std::int64_t inc_stats_counter (int c, std::int64_t value = 1) ;
│ │ │ │ - void blend_stats_counter (int c, std::int64_t value, int ratio) ;
│ │ │ │ + std::int64_t operator[] (int i) const ;
│ │ │ │ void set_value (int c, std::int64_t value) ;
│ │ │ │ + void blend_stats_counter (int c, std::int64_t value, int ratio) ;
│ │ │ │ };
│ │ │ │
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
inc_stats_counter() operator[]()
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
operator[]() inc_stats_counter()
│ │ │ │
│ │ │ │ -std::int64_t operator[] (int i) const ;
│ │ │ │ std::int64_t inc_stats_counter (int c, std::int64_t value = 1) ;
│ │ │ │ +std::int64_t operator[] (int i) const ;
│ │ │ │
│ │ │ │
returns the new value
│ │ │ │
[report issue]
│ │ │ │
│ │ │ │
session_stats_metrics()
│ │ │ │
Declared in "libtorrent/session_stats.hpp"
│ │ │ │ @@ -5524,198 +3480,31 @@
│ │ │ │
│ │ │ │
| gauge |
│ │ │ │ 1 |
│ │ │ │ |
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │ -
[report issue]
│ │ │ │ -
ip_filter
│ │ │ │ -
Declared in "libtorrent/ip_filter.hpp"
│ │ │ │ -
The ip_filter class is a set of rules that uniquely categorizes all
│ │ │ │ -ip addresses as allowed or disallowed. The default constructor creates
│ │ │ │ -a single rule that allows all addresses (0.0.0.0 - 255.255.255.255 for
│ │ │ │ -the IPv4 range, and the equivalent range covering all addresses for the
│ │ │ │ -IPv6 range).
│ │ │ │ -
A default constructed ip_filter does not filter any address.
│ │ │ │ -
│ │ │ │ -struct ip_filter
│ │ │ │ -{
│ │ │ │ - ip_filter (ip_filter const&);
│ │ │ │ - ip_filter& operator= (ip_filter&&);
│ │ │ │ - ~ip_filter ();
│ │ │ │ - ip_filter& operator= (ip_filter const&);
│ │ │ │ - ip_filter (ip_filter&&);
│ │ │ │ - ip_filter ();
│ │ │ │ - bool empty () const;
│ │ │ │ - void add_rule (address const& first, address const& last, std::uint32_t flags);
│ │ │ │ - std::uint32_t access (address const& addr) const;
│ │ │ │ - filter_tuple_t export_filter () const;
│ │ │ │ -
│ │ │ │ - enum access_flags
│ │ │ │ - {
│ │ │ │ - blocked,
│ │ │ │ - };
│ │ │ │ -};
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
empty()
│ │ │ │ -
│ │ │ │ -bool empty () const;
│ │ │ │ -
│ │ │ │ -
returns true if the filter does not contain any rules
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
add_rule()
│ │ │ │ -
│ │ │ │ -void add_rule (address const& first, address const& last, std::uint32_t flags);
│ │ │ │ -
│ │ │ │ -
Adds a rule to the filter. first and last defines a range of
│ │ │ │ -ip addresses that will be marked with the given flags. The flags
│ │ │ │ -can currently be 0, which means allowed, or ip_filter::blocked, which
│ │ │ │ -means disallowed.
│ │ │ │ -
precondition:
│ │ │ │ -first.is_v4() == last.is_v4() && first.is_v6() == last.is_v6()
│ │ │ │ -
postcondition:
│ │ │ │ -access(x) == flags for every x in the range [first, last]
│ │ │ │ -
This means that in a case of overlapping ranges, the last one applied takes
│ │ │ │ -precedence.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
access()
│ │ │ │ -
│ │ │ │ -std::uint32_t access (address const& addr) const;
│ │ │ │ -
│ │ │ │ -
Returns the access permissions for the given address (addr). The permission
│ │ │ │ -can currently be 0 or ip_filter::blocked. The complexity of this operation
│ │ │ │ -is O(log n), where n is the minimum number of non-overlapping ranges to describe
│ │ │ │ -the current filter.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
export_filter()
│ │ │ │ -
│ │ │ │ -filter_tuple_t export_filter () const;
│ │ │ │ -
│ │ │ │ -
This function will return the current state of the filter in the minimum number of
│ │ │ │ -ranges possible. They are sorted from ranges in low addresses to high addresses. Each
│ │ │ │ -entry in the returned vector is a range with the access control specified in its
│ │ │ │ -flags field.
│ │ │ │ -
The return value is a tuple containing two range-lists. One for IPv4 addresses
│ │ │ │ -and one for IPv6 addresses.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
enum access_flags
│ │ │ │ -
Declared in "libtorrent/ip_filter.hpp"
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -| name |
│ │ │ │ -value |
│ │ │ │ -description |
│ │ │ │ -
|---|
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -| blocked |
│ │ │ │ -1 |
│ │ │ │ -indicates that IPs in this range should not be connected
│ │ │ │ -to nor accepted as incoming connections |
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
port_filter
│ │ │ │ -
Declared in "libtorrent/ip_filter.hpp"
│ │ │ │ -
the port filter maps non-overlapping port ranges to flags. This
│ │ │ │ -is primarily used to indicate whether a range of ports should
│ │ │ │ -be connected to or not. The default is to have the full port
│ │ │ │ -range (0-65535) set to flag 0.
│ │ │ │ -
│ │ │ │ -class port_filter
│ │ │ │ -{
│ │ │ │ - port_filter (port_filter&&);
│ │ │ │ - port_filter (port_filter const&);
│ │ │ │ - port_filter ();
│ │ │ │ - ~port_filter ();
│ │ │ │ - port_filter& operator= (port_filter const&);
│ │ │ │ - port_filter& operator= (port_filter&&);
│ │ │ │ - void add_rule (std::uint16_t first, std::uint16_t last, std::uint32_t flags);
│ │ │ │ - std::uint32_t access (std::uint16_t port) const;
│ │ │ │ -
│ │ │ │ - enum access_flags
│ │ │ │ - {
│ │ │ │ - blocked,
│ │ │ │ - };
│ │ │ │ -};
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
add_rule()
│ │ │ │ -
│ │ │ │ -void add_rule (std::uint16_t first, std::uint16_t last, std::uint32_t flags);
│ │ │ │ -
│ │ │ │ -
set the flags for the specified port range (first, last) to
│ │ │ │ -flags overwriting any existing rule for those ports. The range
│ │ │ │ -is inclusive, i.e. the port last also has the flag set on it.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
access()
│ │ │ │ -
│ │ │ │ -std::uint32_t access (std::uint16_t port) const;
│ │ │ │ -
│ │ │ │ -
test the specified port (port) for whether it is blocked
│ │ │ │ -or not. The returned value is the flags set for this port.
│ │ │ │ -see access_flags.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
enum access_flags
│ │ │ │ -
Declared in "libtorrent/ip_filter.hpp"
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -| name |
│ │ │ │ -value |
│ │ │ │ -description |
│ │ │ │ -
|---|
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -| blocked |
│ │ │ │ -1 |
│ │ │ │ -this flag indicates that destination ports in the
│ │ │ │ -range should not be connected to |
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
│ │ │ │
[report issue]
│ │ │ │ -
│ │ │ │
client_data_t
│ │ │ │
Declared in "libtorrent/client_data.hpp"
│ │ │ │
A thin wrapper around a void pointer used as "user data". i.e. an opaque
│ │ │ │ cookie passed in to libtorrent and returned on demand. It adds type-safety by
│ │ │ │ requiring the same type be requested out of it as was assigned to it.
│ │ │ │
│ │ │ │ struct client_data_t
│ │ │ │ {
│ │ │ │ client_data_t () = default;
│ │ │ │ explicit client_data_t (T* v);
│ │ │ │ client_data_t& operator= (T* v);
│ │ │ │ T* get () const;
│ │ │ │ explicit operator T () const;
│ │ │ │ - operator void* () const = delete;
│ │ │ │ client_data_t& operator= (void*) = delete;
│ │ │ │ + operator void* () const = delete;
│ │ │ │ client_data_t& operator= (void const*) = delete;
│ │ │ │ operator void const* () const = delete;
│ │ │ │
│ │ │ │ template <typename T, typename U = typename std::enable_if<std::is_pointer<T>::value>::type>
│ │ │ │ };
│ │ │ │
│ │ │ │
[report issue]
│ │ │ │ @@ -5726,16 +3515,16 @@
│ │ │ │
construct a nullptr client data
│ │ │ │
│ │ │ │
│ │ │ │
[report issue]
│ │ │ │
│ │ │ │
const*() operator=() void*()
│ │ │ │
│ │ │ │ -operator void* () const = delete;
│ │ │ │ client_data_t& operator= (void*) = delete;
│ │ │ │ +operator void* () const = delete;
│ │ │ │ client_data_t& operator= (void const*) = delete;
│ │ │ │ operator void const* () const = delete;
│ │ │ │
│ │ │ │
we don't allow type-unsafe operations
│ │ │ │
[report issue]
│ │ │ │
│ │ │ │ @@ -6150,19 +3939,19 @@
│ │ │ │
announce_entry
│ │ │ │
Declared in "libtorrent/announce_entry.hpp"
│ │ │ │
this class holds information about one bittorrent tracker, as it
│ │ │ │ relates to a specific torrent.
│ │ │ │
│ │ │ │ struct announce_entry
│ │ │ │ {
│ │ │ │ + announce_entry ();
│ │ │ │ explicit announce_entry (string_view u);
│ │ │ │ announce_entry (announce_entry const&);
│ │ │ │ ~announce_entry ();
│ │ │ │ announce_entry& operator= (announce_entry const&) &;
│ │ │ │ - announce_entry ();
│ │ │ │
│ │ │ │ enum tracker_source
│ │ │ │ {
│ │ │ │ source_torrent,
│ │ │ │ source_client,
│ │ │ │ source_magnet_link,
│ │ │ │ source_tex,
│ │ │ │ @@ -6178,19 +3967,19 @@
│ │ │ │ };
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │
[report issue]
│ │ │ │
announce_entry() operator=() ~announce_entry()
│ │ │ │
│ │ │ │ +announce_entry ();
│ │ │ │ explicit announce_entry (string_view u);
│ │ │ │ announce_entry (announce_entry const&);
│ │ │ │ ~announce_entry ();
│ │ │ │ announce_entry& operator= (announce_entry const&) &;
│ │ │ │ -announce_entry ();
│ │ │ │
│ │ │ │
constructs a tracker announce entry with u as the URL.
│ │ │ │
[report issue]
│ │ │ │
│ │ │ │
enum tracker_source
│ │ │ │
Declared in "libtorrent/announce_entry.hpp"
│ │ │ │
│ │ │ │ @@ -6208,15 +3997,15 @@
│ │ │ │
│ │ │ │ | source_torrent |
│ │ │ │ 1 |
│ │ │ │ the tracker was part of the .torrent file |
│ │ │ │
│ │ │ │ | source_client |
│ │ │ │ 2 |
│ │ │ │ -the tracker was added programmatically via the add_tracker() function |
│ │ │ │ +the tracker was added programmatically via the add_tracker() function |
│ │ │ │
│ │ │ │ | source_magnet_link |
│ │ │ │ 4 |
│ │ │ │ the tracker was part of a magnet link |
│ │ │ │
│ │ │ │ | source_tex |
│ │ │ │ 8 |
│ │ │ │ @@ -7315,26 +5104,26 @@
│ │ │ │ torrent_handle::move_storage. This is useful to synchronize with the
│ │ │ │ actual disk. The storage_path() member return the new path of the
│ │ │ │ storage.
│ │ │ │
│ │ │ │ struct storage_moved_alert final : torrent_alert
│ │ │ │ {
│ │ │ │ std::string message () const override;
│ │ │ │ - char const* storage_path () const;
│ │ │ │ char const* old_path () const;
│ │ │ │ + char const* storage_path () const;
│ │ │ │
│ │ │ │ static constexpr alert_category_t static_category = alert_category::storage;
│ │ │ │ };
│ │ │ │
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -
old_path() storage_path()
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
storage_path() old_path()
│ │ │ │
│ │ │ │ -char const* storage_path () const;
│ │ │ │ char const* old_path () const;
│ │ │ │ +char const* storage_path () const;
│ │ │ │
│ │ │ │
the path the torrent was moved to and from, respectively.
│ │ │ │
[report issue]
│ │ │ │
│ │ │ │
storage_moved_failed_alert
│ │ │ │
Declared in "libtorrent/alert_types.hpp"
│ │ │ │ @@ -9021,45 +6810,45 @@
│ │ │ │
Declared in "libtorrent/alert_types.hpp"
│ │ │ │
posted as a response to a call to session::dht_sample_infohashes() with
│ │ │ │ the information from the DHT response message.
│ │ │ │
│ │ │ │ struct dht_sample_infohashes_alert final : alert
│ │ │ │ {
│ │ │ │ std::string message () const override;
│ │ │ │ - int num_samples () const;
│ │ │ │ std::vector<sha1_hash> samples () const;
│ │ │ │ + int num_samples () const;
│ │ │ │ int num_nodes () const;
│ │ │ │ std::vector<std::pair<sha1_hash, udp::endpoint>> nodes () const;
│ │ │ │
│ │ │ │ static constexpr alert_category_t static_category = alert_category::dht_operation;
│ │ │ │ sha1_hash node_id;
│ │ │ │ aux::noexcept_movable<udp::endpoint> endpoint;
│ │ │ │ time_duration const interval;
│ │ │ │ int const num_infohashes;
│ │ │ │ };
│ │ │ │
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
samples() num_samples()
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
num_samples() samples()
│ │ │ │
│ │ │ │ -int num_samples () const;
│ │ │ │ std::vector<sha1_hash> samples () const;
│ │ │ │ +int num_samples () const;
│ │ │ │
│ │ │ │
returns the number of info-hashes returned by the node, as well as the
│ │ │ │ actual info-hashes. num_samples() is more efficient than
│ │ │ │ samples().size().
│ │ │ │
[report issue]
│ │ │ │
│ │ │ │
num_nodes()
│ │ │ │
│ │ │ │ int num_nodes () const;
│ │ │ │
│ │ │ │
The total number of nodes returned by nodes().
│ │ │ │
[report issue]
│ │ │ │ -
│ │ │ │ +
│ │ │ │
nodes()
│ │ │ │
│ │ │ │ std::vector<std::pair<sha1_hash, udp::endpoint>> nodes () const;
│ │ │ │
│ │ │ │
This is the set of more DHT nodes returned by the request.
│ │ │ │
The information is included so that indexing nodes can perform a key
│ │ │ │ space traversal with a single RPC per node by adjusting the target
│ │ │ │ @@ -9322,14 +7111,23 @@
│ │ │ │ std::vector<announce_entry> trackers;
│ │ │ │ };
│ │ │ │
│ │ │ │ [report issue]
│ │ │ │ - trackers
│ │ │ │ - list of trackers and their status for the torrent
│ │ │ │
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │
│ │ │ │
alert_cast()
│ │ │ │
Declared in "libtorrent/alert.hpp"
│ │ │ │
│ │ │ │ template <typename T> T* alert_cast (alert* a);
│ │ │ │ template <typename T> T const* alert_cast (alert const* a);
│ │ │ │ @@ -9337,23 +7135,14 @@
│ │ │ │ When you get an alert, you can use alert_cast<> to attempt to cast the
│ │ │ │ pointer to a specific alert type, in order to query it for more
│ │ │ │ information.
│ │ │ │
│ │ │ │
Note
│ │ │ │
alert_cast<> can only cast to an exact alert type, not a base class
│ │ │ │
│ │ │ │ -
│ │ │ │
│ │ │ │
enum operation_t
│ │ │ │
Declared in "libtorrent/operations.hpp"
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │ @@ -9684,34 +7473,623 @@
│ │ │ │
│ │ │ │
│ │ │ │ - block_progress
│ │ │ │ - alerts on individual blocks being requested, downloading, finished,
│ │ │ │ rejected, time-out and cancelled. This is likely to post alerts at a
│ │ │ │ high rate.
│ │ │ │
│ │ │ │ -
│ │ │ │ -- all
│ │ │ │ -The full bitmask, representing all available categories.
│ │ │ │ -since the enum is signed, make sure this isn't
│ │ │ │ -interpreted as -1. For instance, boost.python
│ │ │ │ -does that and fails when assigning it to an
│ │ │ │ -unsigned parameter.
│ │ │ │ -
│ │ │ │ +- all
│ │ │ │ +The full bitmask, representing all available categories.
│ │ │ │ +since the enum is signed, make sure this isn't
│ │ │ │ +interpreted as -1. For instance, boost.python
│ │ │ │ +does that and fails when assigning it to an
│ │ │ │ +unsigned parameter.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +
int
│ │ │ │ +
Declared in "libtorrent/alert_types.hpp"
│ │ │ │ +
│ │ │ │ +- user_alert_id
│ │ │ │ +- user defined alerts should use IDs greater than this
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +- num_alert_types
│ │ │ │ +- this constant represents "max_alert_index" + 1
│ │ │ │ +
│ │ │ │ +
You have some control over session configuration through the session::apply_settings()
│ │ │ │ +member function. To change one or more configuration options, create a settings_pack
│ │ │ │ +object and fill it with the settings to be set and pass it in to session::apply_settings().
│ │ │ │ +
The settings_pack object is a collection of settings updates that are applied
│ │ │ │ +to the session when passed to session::apply_settings(). It's empty when
│ │ │ │ +constructed.
│ │ │ │ +
You have control over proxy and authorization settings and also the user-agent
│ │ │ │ +that will be sent to the tracker. The user-agent will also be used to identify the
│ │ │ │ +client with other peers.
│ │ │ │ +
Each configuration option is named with an enum value inside the
│ │ │ │ +settings_pack class. These are the available settings:
│ │ │ │ +
[report issue]
│ │ │ │ +
disk_observer
│ │ │ │ +
Declared in "libtorrent/disk_observer.hpp"
│ │ │ │ +
│ │ │ │ +struct disk_observer
│ │ │ │ +{
│ │ │ │ + virtual void on_disk () = 0;
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
on_disk()
│ │ │ │ +
│ │ │ │ +virtual void on_disk () = 0;
│ │ │ │ +
│ │ │ │ +
called when the disk cache size has dropped
│ │ │ │ +below the low watermark again and we can
│ │ │ │ +resume downloading from peers
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
open_file_state
│ │ │ │ +
Declared in "libtorrent/disk_interface.hpp"
│ │ │ │ +
this contains information about a file that's currently open by the
│ │ │ │ +libtorrent disk I/O subsystem. It's associated with a single torrent.
│ │ │ │ +
│ │ │ │ +struct open_file_state
│ │ │ │ +{
│ │ │ │ + file_index_t file_index;
│ │ │ │ + file_open_mode_t open_mode;
│ │ │ │ + time_point last_use;
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- file_index
│ │ │ │ +- the index of the file this entry refers to into the file_storage
│ │ │ │ +file list of this torrent. This starts indexing at 0.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- open_mode
│ │ │ │ +open_mode is a bitmask of the file flags this file is currently
│ │ │ │ +opened with. For possible flags, see file_open_mode_t.
│ │ │ │ +Note that the read/write mode is not a bitmask. The two least significant bits are used
│ │ │ │ +to represent the read/write mode. Those bits can be masked out using the rw_mask constant.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- last_use
│ │ │ │ +- a (high precision) timestamp of when the file was last used.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
disk_interface
│ │ │ │ +
Declared in "libtorrent/disk_interface.hpp"
│ │ │ │ +
The disk_interface is the customization point for disk I/O in libtorrent.
│ │ │ │ +implement this interface and provide a factory function to the session constructor
│ │ │ │ +use custom disk I/O. All functions on the disk subsystem (implementing
│ │ │ │ +disk_interface) are called from within libtorrent's network thread. For
│ │ │ │ +disk I/O to be performed in a separate thread, the disk subsystem has to
│ │ │ │ +manage that itself.
│ │ │ │ +
Although the functions are called async_*, they do not technically
│ │ │ │ +have to be asynchronous, but they support being asynchronous, by
│ │ │ │ +expecting the result passed back into a callback. The callbacks must be
│ │ │ │ +posted back onto the network thread via the io_context object passed into
│ │ │ │ +the constructor. The callbacks will be run in the network thread.
│ │ │ │ +
│ │ │ │ +struct disk_interface
│ │ │ │ +{
│ │ │ │ + virtual storage_holder new_torrent (storage_params const& p
│ │ │ │ + , std::shared_ptr<void> const& torrent) = 0;
│ │ │ │ + virtual void remove_torrent (storage_index_t) = 0;
│ │ │ │ + virtual bool async_write (storage_index_t storage, peer_request const& r
│ │ │ │ + , char const* buf, std::shared_ptr<disk_observer> o
│ │ │ │ + , std::function<void(storage_error const&)> handler
│ │ │ │ + , disk_job_flags_t flags = {}) = 0;
│ │ │ │ + virtual void async_read (storage_index_t storage, peer_request const& r
│ │ │ │ + , std::function<void(disk_buffer_holder, storage_error const&)> handler
│ │ │ │ + , disk_job_flags_t flags = {}) = 0;
│ │ │ │ + virtual void async_hash (storage_index_t storage, piece_index_t piece, span<sha256_hash> v2
│ │ │ │ + , disk_job_flags_t flags
│ │ │ │ + , std::function<void(piece_index_t, sha1_hash const&, storage_error const&)> handler) = 0;
│ │ │ │ + virtual void async_hash2 (storage_index_t storage, piece_index_t piece, int offset, disk_job_flags_t flags
│ │ │ │ + , std::function<void(piece_index_t, sha256_hash const&, storage_error const&)> handler) = 0;
│ │ │ │ + virtual void async_move_storage (storage_index_t storage, std::string p, move_flags_t flags
│ │ │ │ + , std::function<void(status_t, std::string const&, storage_error const&)> handler) = 0;
│ │ │ │ + virtual void async_release_files (storage_index_t storage
│ │ │ │ + , std::function<void()> handler = std::function<void()>()) = 0;
│ │ │ │ + virtual void async_check_files (storage_index_t storage
│ │ │ │ + , add_torrent_params const* resume_data
│ │ │ │ + , aux::vector<std::string, file_index_t> links
│ │ │ │ + , std::function<void(status_t, storage_error const&)> handler) = 0;
│ │ │ │ + virtual void async_stop_torrent (storage_index_t storage
│ │ │ │ + , std::function<void()> handler = std::function<void()>()) = 0;
│ │ │ │ + virtual void async_rename_file (storage_index_t storage
│ │ │ │ + , file_index_t index, std::string name
│ │ │ │ + , std::function<void(std::string const&, file_index_t, storage_error const&)> handler) = 0;
│ │ │ │ + virtual void async_delete_files (storage_index_t storage, remove_flags_t options
│ │ │ │ + , std::function<void(storage_error const&)> handler) = 0;
│ │ │ │ + virtual void async_set_file_priority (storage_index_t storage
│ │ │ │ + , aux::vector<download_priority_t, file_index_t> prio
│ │ │ │ + , std::function<void(storage_error const&
│ │ │ │ + , aux::vector<download_priority_t, file_index_t>)> handler) = 0;
│ │ │ │ + virtual void async_clear_piece (storage_index_t storage, piece_index_t index
│ │ │ │ + , std::function<void(piece_index_t)> handler) = 0;
│ │ │ │ + virtual void update_stats_counters (counters& c) const = 0;
│ │ │ │ + virtual std::vector<open_file_state> get_status (storage_index_t) const = 0;
│ │ │ │ + virtual void abort (bool wait) = 0;
│ │ │ │ + virtual void submit_jobs () = 0;
│ │ │ │ + virtual void settings_updated () = 0;
│ │ │ │ +
│ │ │ │ + static constexpr disk_job_flags_t force_copy = 0_bit;
│ │ │ │ + static constexpr disk_job_flags_t sequential_access = 3_bit;
│ │ │ │ + static constexpr disk_job_flags_t volatile_read = 4_bit;
│ │ │ │ + static constexpr disk_job_flags_t v1_hash = 5_bit;
│ │ │ │ + static constexpr disk_job_flags_t flush_piece = 7_bit;
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
new_torrent()
│ │ │ │ +
│ │ │ │ +virtual storage_holder new_torrent (storage_params const& p
│ │ │ │ + , std::shared_ptr<void> const& torrent) = 0;
│ │ │ │ +
│ │ │ │ +
this is called when a new torrent is added. The shared_ptr can be
│ │ │ │ +used to hold the internal torrent object alive as long as there are
│ │ │ │ +outstanding disk operations on the storage.
│ │ │ │ +The returned storage_holder is an owning reference to the underlying
│ │ │ │ +storage that was just created. It is fundamentally a storage_index_t
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
remove_torrent()
│ │ │ │ +
│ │ │ │ +virtual void remove_torrent (storage_index_t) = 0;
│ │ │ │ +
│ │ │ │ +
remove the storage with the specified index. This is not expected to
│ │ │ │ +delete any files from disk, just to clean up any resources associated
│ │ │ │ +with the specified storage.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
async_write() async_read()
│ │ │ │ +
│ │ │ │ +virtual bool async_write (storage_index_t storage, peer_request const& r
│ │ │ │ + , char const* buf, std::shared_ptr<disk_observer> o
│ │ │ │ + , std::function<void(storage_error const&)> handler
│ │ │ │ + , disk_job_flags_t flags = {}) = 0;
│ │ │ │ +virtual void async_read (storage_index_t storage, peer_request const& r
│ │ │ │ + , std::function<void(disk_buffer_holder, storage_error const&)> handler
│ │ │ │ + , disk_job_flags_t flags = {}) = 0;
│ │ │ │ +
│ │ │ │ +
perform a read or write operation from/to the specified storage
│ │ │ │ +index and the specified request. When the operation completes, call
│ │ │ │ +handler possibly with a disk_buffer_holder, holding the buffer with
│ │ │ │ +the result. Flags may be set to affect the read operation. See
│ │ │ │ +disk_job_flags_t.
│ │ │ │ +
The disk_observer is a callback to indicate that
│ │ │ │ +the store buffer/disk write queue is below the watermark to let peers
│ │ │ │ +start writing buffers to disk again. When async_write() returns
│ │ │ │ +true, indicating the write queue is full, the peer will stop
│ │ │ │ +further writes and wait for the passed-in disk_observer to be
│ │ │ │ +notified before resuming.
│ │ │ │ +
Note that for async_read, the peer_request (r) is not
│ │ │ │ +necessarily aligned to blocks (but it is most of the time). However,
│ │ │ │ +all writes (passed to async_write) are guaranteed to be block
│ │ │ │ +aligned.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
async_hash()
│ │ │ │ +
│ │ │ │ +virtual void async_hash (storage_index_t storage, piece_index_t piece, span<sha256_hash> v2
│ │ │ │ + , disk_job_flags_t flags
│ │ │ │ + , std::function<void(piece_index_t, sha1_hash const&, storage_error const&)> handler) = 0;
│ │ │ │ +
│ │ │ │ +
Compute hash(es) for the specified piece. Unless the v1_hash flag is
│ │ │ │ +set (in flags), the SHA-1 hash of the whole piece does not need
│ │ │ │ +to be computed.
│ │ │ │ +
The v2 span is optional and can be empty, which means v2 hashes
│ │ │ │ +should not be computed. If v2 is non-empty it must be at least large
│ │ │ │ +enough to hold all v2 blocks in the piece, and this function will
│ │ │ │ +fill in the span with the SHA-256 block hashes of the piece.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
async_hash2()
│ │ │ │ +
│ │ │ │ +virtual void async_hash2 (storage_index_t storage, piece_index_t piece, int offset, disk_job_flags_t flags
│ │ │ │ + , std::function<void(piece_index_t, sha256_hash const&, storage_error const&)> handler) = 0;
│ │ │ │ +
│ │ │ │ +
computes the v2 hash (SHA-256) of a single block. The block at
│ │ │ │ +offset in piece piece.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
async_move_storage()
│ │ │ │ +
│ │ │ │ +virtual void async_move_storage (storage_index_t storage, std::string p, move_flags_t flags
│ │ │ │ + , std::function<void(status_t, std::string const&, storage_error const&)> handler) = 0;
│ │ │ │ +
│ │ │ │ +
called to request the files for the specified storage/torrent be
│ │ │ │ +moved to a new location. It is the disk I/O object's responsibility
│ │ │ │ +to synchronize this with any currently outstanding disk operations to
│ │ │ │ +the storage. Whether files are replaced at the destination path or
│ │ │ │ +not is controlled by flags (see move_flags_t).
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
async_release_files()
│ │ │ │ +
│ │ │ │ +virtual void async_release_files (storage_index_t storage
│ │ │ │ + , std::function<void()> handler = std::function<void()>()) = 0;
│ │ │ │ +
│ │ │ │ +
This is called on disk I/O objects to request they close all open
│ │ │ │ +files for the specified storage/torrent. If file handles are not
│ │ │ │ +pooled/cached, it can be a no-op. For truly asynchronous disk I/O,
│ │ │ │ +this should provide at least one point in time when all files are
│ │ │ │ +closed. It is possible that later asynchronous operations will
│ │ │ │ +re-open some of the files, by the time this completion handler is
│ │ │ │ +called, that's fine.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
async_check_files()
│ │ │ │ +
│ │ │ │ +virtual void async_check_files (storage_index_t storage
│ │ │ │ + , add_torrent_params const* resume_data
│ │ │ │ + , aux::vector<std::string, file_index_t> links
│ │ │ │ + , std::function<void(status_t, storage_error const&)> handler) = 0;
│ │ │ │ +
│ │ │ │ +
this is called when torrents are added to validate their resume data
│ │ │ │ +against the files on disk. This function is expected to do a few things:
│ │ │ │ +
if links is non-empty, it contains a string for each file in the
│ │ │ │ +torrent. The string being a path to an existing identical file. The
│ │ │ │ +default behavior is to create hard links of those files into the
│ │ │ │ +storage of the new torrent (specified by storage). An empty
│ │ │ │ +string indicates that there is no known identical file. This is part
│ │ │ │ +of the "mutable torrent" feature, where files can be reused from
│ │ │ │ +other torrents.
│ │ │ │ +
The resume_data points the resume data passed in by the client.
│ │ │ │ +
If the resume_data->flags field has the seed_mode flag set, all
│ │ │ │ +files/pieces are expected to be on disk already. This should be
│ │ │ │ +verified. Not just the existence of the file, but also that it has
│ │ │ │ +the correct size.
│ │ │ │ +
Any file with a piece set in the resume_data->have_pieces bitmask
│ │ │ │ +should exist on disk, this should be verified. Pad files and files
│ │ │ │ +with zero priority may be skipped.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
async_stop_torrent()
│ │ │ │ +
│ │ │ │ +virtual void async_stop_torrent (storage_index_t storage
│ │ │ │ + , std::function<void()> handler = std::function<void()>()) = 0;
│ │ │ │ +
│ │ │ │ +
This is called when a torrent is stopped. It gives the disk I/O
│ │ │ │ +object an opportunity to flush any data to disk that's currently kept
│ │ │ │ +cached. This function should at least do the same thing as
│ │ │ │ +async_release_files().
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
async_rename_file()
│ │ │ │ +
│ │ │ │ +virtual void async_rename_file (storage_index_t storage
│ │ │ │ + , file_index_t index, std::string name
│ │ │ │ + , std::function<void(std::string const&, file_index_t, storage_error const&)> handler) = 0;
│ │ │ │ +
│ │ │ │ +
This function is called when the name of a file in the specified
│ │ │ │ +storage has been requested to be renamed. The disk I/O object is
│ │ │ │ +responsible for renaming the file without racing with other
│ │ │ │ +potentially outstanding operations against the file (such as read,
│ │ │ │ +write, move, etc.).
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
async_delete_files()
│ │ │ │ +
│ │ │ │ +virtual void async_delete_files (storage_index_t storage, remove_flags_t options
│ │ │ │ + , std::function<void(storage_error const&)> handler) = 0;
│ │ │ │ +
│ │ │ │ +
This function is called when some file(s) on disk have been requested
│ │ │ │ +to be removed by the client. storage indicates which torrent is
│ │ │ │ +referred to. See session_handle for remove_flags_t flags
│ │ │ │ +indicating which files are to be removed.
│ │ │ │ +e.g. session_handle::delete_files - delete all files
│ │ │ │ +session_handle::delete_partfile - only delete part file.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
async_set_file_priority()
│ │ │ │ +
│ │ │ │ +virtual void async_set_file_priority (storage_index_t storage
│ │ │ │ + , aux::vector<download_priority_t, file_index_t> prio
│ │ │ │ + , std::function<void(storage_error const&
│ │ │ │ + , aux::vector<download_priority_t, file_index_t>)> handler) = 0;
│ │ │ │ +
│ │ │ │ +
This is called to set the priority of some or all files. Changing the
│ │ │ │ +priority from or to 0 may involve moving data to and from the
│ │ │ │ +partfile. The disk I/O object is responsible for correctly
│ │ │ │ +synchronizing this work to not race with any potentially outstanding
│ │ │ │ +asynchronous operations affecting these files.
│ │ │ │ +
prio is a vector of the file priority for all files. If it's
│ │ │ │ +shorter than the total number of files in the torrent, they are
│ │ │ │ +assumed to be set to the default priority.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
async_clear_piece()
│ │ │ │ +
│ │ │ │ +virtual void async_clear_piece (storage_index_t storage, piece_index_t index
│ │ │ │ + , std::function<void(piece_index_t)> handler) = 0;
│ │ │ │ +
│ │ │ │ +
This is called when a piece fails the hash check, to ensure there are
│ │ │ │ +no outstanding disk operations to the piece before blocks are
│ │ │ │ +re-requested from peers to overwrite the existing blocks. The disk I/O
│ │ │ │ +object does not need to perform any action other than synchronize
│ │ │ │ +with all outstanding disk operations to the specified piece before
│ │ │ │ +posting the result back.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
update_stats_counters()
│ │ │ │ +
│ │ │ │ +virtual void update_stats_counters (counters& c) const = 0;
│ │ │ │ +
│ │ │ │ +
update_stats_counters() is called to give the disk storage an
│ │ │ │ +opportunity to update gauges in the c stats counters, that aren't
│ │ │ │ +updated continuously as operations are performed. This is called
│ │ │ │ +before a snapshot of the counters are passed to the client.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
get_status()
│ │ │ │ +
│ │ │ │ +virtual std::vector<open_file_state> get_status (storage_index_t) const = 0;
│ │ │ │ +
│ │ │ │ +
Return a list of all the files that are currently open for the
│ │ │ │ +specified storage/torrent. This is is just used for the client to
│ │ │ │ +query the currently open files, and which modes those files are open
│ │ │ │ +in.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
abort()
│ │ │ │ +
│ │ │ │ +virtual void abort (bool wait) = 0;
│ │ │ │ +
│ │ │ │ +
this is called when the session is starting to shut down. The disk
│ │ │ │ +I/O object is expected to flush any outstanding write jobs, cancel
│ │ │ │ +hash jobs and initiate tearing down of any internal threads. If
│ │ │ │ +wait is true, this should be asynchronous. i.e. this call should
│ │ │ │ +not return until all threads have stopped and all jobs have either
│ │ │ │ +been aborted or completed and the disk I/O object is ready to be
│ │ │ │ +destructed.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
submit_jobs()
│ │ │ │ +
│ │ │ │ +virtual void submit_jobs () = 0;
│ │ │ │ +
│ │ │ │ +
This will be called after a batch of disk jobs has been issues (via
│ │ │ │ +the async_* ). It gives the disk I/O object an opportunity to
│ │ │ │ +notify any potential condition variables to wake up the disk
│ │ │ │ +thread(s). The async_* calls can of course also notify condition
│ │ │ │ +variables, but doing it in this call allows for batching jobs, by
│ │ │ │ +issuing the notification once for a collection of jobs.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
settings_updated()
│ │ │ │ +
│ │ │ │ +virtual void settings_updated () = 0;
│ │ │ │ +
│ │ │ │ +
This is called to notify the disk I/O object that the settings have
│ │ │ │ +been updated. In the disk io constructor, a settings_interface
│ │ │ │ +reference is passed in. Whenever these settings are updated, this
│ │ │ │ +function is called to allow the disk I/O object to react to any
│ │ │ │ +changed settings relevant to its operations.
│ │ │ │ +
[report issue]
│ │ │ │ +- force_copy
│ │ │ │ +- force making a copy of the cached block, rather than getting a
│ │ │ │ +reference to a block already in the cache. This is used the block is
│ │ │ │ +expected to be overwritten very soon, by async_write()`, and we need
│ │ │ │ +access to the previous content.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- sequential_access
│ │ │ │ +- hint that there may be more disk operations with sequential access to
│ │ │ │ +the file
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- volatile_read
│ │ │ │ +- don't keep the read block in cache. This is a hint that this block is
│ │ │ │ +unlikely to be read again anytime soon, and caching it would be
│ │ │ │ +wasteful.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- v1_hash
│ │ │ │ +- compute a v1 piece hash. This is only used by the async_hash() call.
│ │ │ │ +If this flag is not set in the async_hash() call, the SHA-1 piece
│ │ │ │ +hash does not need to be computed.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- flush_piece
│ │ │ │ +- this flag instructs a hash job that we just completed this piece, and
│ │ │ │ +it should be flushed to disk
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
storage_holder
│ │ │ │ +
Declared in "libtorrent/disk_interface.hpp"
│ │ │ │ +
a unique, owning, reference to the storage of a torrent in a disk io
│ │ │ │ +subsystem (class that implements disk_interface). This is held by the
│ │ │ │ +internal libtorrent torrent object to tie the storage object allocated
│ │ │ │ +for a torrent to the lifetime of the internal torrent object. When a
│ │ │ │ +torrent is removed from the session, this holder is destructed and will
│ │ │ │ +inform the disk object.
│ │ │ │ +
│ │ │ │ +struct storage_holder
│ │ │ │ +{
│ │ │ │ + storage_holder (storage_index_t idx, disk_interface& disk_io);
│ │ │ │ + ~storage_holder ();
│ │ │ │ + storage_holder () = default;
│ │ │ │ + explicit operator bool () const;
│ │ │ │ + operator storage_index_t () const;
│ │ │ │ + void reset ();
│ │ │ │ + storage_holder& operator= (storage_holder const&) = delete;
│ │ │ │ + storage_holder (storage_holder const&) = delete;
│ │ │ │ + storage_holder (storage_holder&& rhs) noexcept;
│ │ │ │ + storage_holder& operator= (storage_holder&& rhs) noexcept;
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
buffer_allocator_interface
│ │ │ │ +
Declared in "libtorrent/disk_buffer_holder.hpp"
│ │ │ │ +
the interface for freeing disk buffers, used by the disk_buffer_holder.
│ │ │ │ +when implementing disk_interface, this must also be implemented in order
│ │ │ │ +to return disk buffers back to libtorrent
│ │ │ │ +
│ │ │ │ +struct buffer_allocator_interface
│ │ │ │ +{
│ │ │ │ + virtual void free_disk_buffer (char* b) = 0;
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
disk_buffer_holder
│ │ │ │ +
Declared in "libtorrent/disk_buffer_holder.hpp"
│ │ │ │ +
The disk buffer holder acts like a unique_ptr that frees a disk buffer
│ │ │ │ +when it's destructed
│ │ │ │ +
If this buffer holder is moved-from, default constructed or reset,
│ │ │ │ +data() will return nullptr.
│ │ │ │ +
│ │ │ │ +struct disk_buffer_holder
│ │ │ │ +{
│ │ │ │ + disk_buffer_holder& operator= (disk_buffer_holder&&) & noexcept;
│ │ │ │ + disk_buffer_holder (disk_buffer_holder&&) noexcept;
│ │ │ │ + disk_buffer_holder (disk_buffer_holder const&) = delete;
│ │ │ │ + disk_buffer_holder& operator= (disk_buffer_holder const&) = delete;
│ │ │ │ + disk_buffer_holder (buffer_allocator_interface& alloc
│ │ │ │ + , char* buf, int sz) noexcept;
│ │ │ │ + disk_buffer_holder () noexcept = default;
│ │ │ │ + ~disk_buffer_holder ();
│ │ │ │ + char* data () const noexcept;
│ │ │ │ + void reset ();
│ │ │ │ + void swap (disk_buffer_holder& h) noexcept;
│ │ │ │ + bool is_mutable () const noexcept;
│ │ │ │ + explicit operator bool () const noexcept;
│ │ │ │ + std::ptrdiff_t size () const;
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
disk_buffer_holder()
│ │ │ │ +
│ │ │ │ +disk_buffer_holder (buffer_allocator_interface& alloc
│ │ │ │ + , char* buf, int sz) noexcept;
│ │ │ │ +
│ │ │ │ +
construct a buffer holder that will free the held buffer
│ │ │ │ +using a disk buffer pool directly (there's only one
│ │ │ │ +disk_buffer_pool per session)
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
disk_buffer_holder()
│ │ │ │ +
│ │ │ │ +disk_buffer_holder () noexcept = default;
│ │ │ │ +
│ │ │ │ +
default construct a holder that does not own any buffer
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
~disk_buffer_holder()
│ │ │ │ +
│ │ │ │ +~disk_buffer_holder ();
│ │ │ │ +
│ │ │ │ +
frees disk buffer held by this object
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
data()
│ │ │ │ +
│ │ │ │ +char* data () const noexcept;
│ │ │ │ +
│ │ │ │ +
return a pointer to the held buffer, if any. Otherwise returns nullptr.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
reset()
│ │ │ │ +
│ │ │ │ +void reset ();
│ │ │ │ +
│ │ │ │ +
free the held disk buffer, if any, and clear the holder. This sets the
│ │ │ │ +holder object to a default-constructed state
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
swap()
│ │ │ │ +
│ │ │ │ +void swap (disk_buffer_holder& h) noexcept;
│ │ │ │ +
│ │ │ │ +
swap pointers of two disk buffer holders.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
is_mutable()
│ │ │ │ +
│ │ │ │ +bool is_mutable () const noexcept;
│ │ │ │ +
│ │ │ │ +
if this returns true, the buffer may not be modified in place
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
bool()
│ │ │ │ +
│ │ │ │ +explicit operator bool () const noexcept;
│ │ │ │ +
│ │ │ │ +
implicitly convertible to true if the object is currently holding a
│ │ │ │ +buffer
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
settings_interface
│ │ │ │ +
Declared in "libtorrent/settings_pack.hpp"
│ │ │ │ +
the common interface to settings_pack and the internal representation of
│ │ │ │ +settings.
│ │ │ │ +
│ │ │ │ +struct settings_interface
│ │ │ │ +{
│ │ │ │ + virtual void set_int (int name, int val) = 0;
│ │ │ │ + virtual bool has_val (int name) const = 0;
│ │ │ │ + virtual void set_str (int name, std::string val) = 0;
│ │ │ │ + virtual void set_bool (int name, bool val) = 0;
│ │ │ │ + virtual bool get_bool (int name) const = 0;
│ │ │ │ + virtual int get_int (int name) const = 0;
│ │ │ │ + virtual std::string const& get_str (int name) const = 0;
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
file_open_mode_t
│ │ │ │ +
Declared in "libtorrent/disk_interface.hpp"
│ │ │ │ +
│ │ │ │ +- read_only
│ │ │ │ +- open the file for reading only
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +- write_only
│ │ │ │ +- open the file for writing only
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +- read_write
│ │ │ │ +- open the file for reading and writing
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +- rw_mask
│ │ │ │ +- the mask for the bits determining read or write mode
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +- sparse
│ │ │ │ +- open the file in sparse mode (if supported by the
│ │ │ │ +filesystem).
│ │ │ │
│ │ │ │ -
[report issue]
│ │ │ │ -
int
│ │ │ │ -
Declared in "libtorrent/alert_types.hpp"
│ │ │ │ -
│ │ │ │ -- user_alert_id
│ │ │ │ -- user defined alerts should use IDs greater than this
│ │ │ │ +
│ │ │ │ +- no_atime
│ │ │ │ +- don't update the access timestamps on the file (if
│ │ │ │ +supported by the operating system and filesystem).
│ │ │ │ +this generally improves disk performance.
│ │ │ │
│ │ │ │ -
│ │ │ │ -- num_alert_types
│ │ │ │ -- this constant represents "max_alert_index" + 1
│ │ │ │ +
│ │ │ │ +- random_access
│ │ │ │ +- When this is not set, the kernel is hinted that access to this file will
│ │ │ │ +be made sequentially.
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +- mmapped
│ │ │ │ +- the file is memory mapped
│ │ │ │
│ │ │ │ [report issue]
│ │ │ │
storage_params
│ │ │ │
Declared in "libtorrent/storage_defs.hpp"
│ │ │ │
a parameter pack used to construct the storage for a torrent, used in
│ │ │ │ disk_interface
│ │ │ │ @@ -9795,62 +8173,62 @@
│ │ │ │ std::vector<file_slice>
map_block (piece_index_t piece, std::int64_t offset
│ │ │ │ , std::int64_t size) const;
│ │ │ │ peer_request
map_file (file_index_t file, std::int64_t offset, int size) const;
│ │ │ │ int
num_files () const noexcept;
│ │ │ │ file_index_t
end_file () const noexcept;
│ │ │ │ index_range<file_index_t>
file_range () const noexcept;
│ │ │ │ std::int64_t
total_size () const;
│ │ │ │ - void
set_num_pieces (int n);
│ │ │ │ int
num_pieces () const;
│ │ │ │ + void
set_num_pieces (int n);
│ │ │ │ piece_index_t
end_piece () const;
│ │ │ │ piece_index_t
last_piece () const;
│ │ │ │ index_range<piece_index_t>
piece_range () const noexcept;
│ │ │ │ - int
piece_length () const;
│ │ │ │ void
set_piece_length (int l);
│ │ │ │ + int
piece_length () const;
│ │ │ │ int
piece_size (piece_index_t index) const;
│ │ │ │ int
piece_size2 (piece_index_t index) const;
│ │ │ │ int
blocks_in_piece2 (piece_index_t index) const;
│ │ │ │ int
blocks_per_piece () const;
│ │ │ │ - void
set_name (std::string const& n);
│ │ │ │ std::string const&
name () const;
│ │ │ │ + void
set_name (std::string const& n);
│ │ │ │ void
swap (file_storage& ti) noexcept;
│ │ │ │ void
canonicalize ();
│ │ │ │ - bool
pad_file_at (file_index_t index) const;
│ │ │ │ - string_view
file_name (file_index_t index) const;
│ │ │ │ - std::time_t
mtime (file_index_t index) const;
│ │ │ │ - char const*
root_ptr (file_index_t const index) const;
│ │ │ │ - sha1_hash
hash (file_index_t index) const;
│ │ │ │ sha256_hash
root (file_index_t index) const;
│ │ │ │ - std::int64_t
file_offset (file_index_t index) const;
│ │ │ │ std::string
symlink (file_index_t index) const;
│ │ │ │ + char const*
root_ptr (file_index_t const index) const;
│ │ │ │ + std::int64_t
file_offset (file_index_t index) const;
│ │ │ │ + bool
pad_file_at (file_index_t index) const;
│ │ │ │ std::int64_t
file_size (file_index_t index) const;
│ │ │ │ + sha1_hash
hash (file_index_t index) const;
│ │ │ │ + string_view
file_name (file_index_t index) const;
│ │ │ │ std::string
file_path (file_index_t index, std::string const& save_path = "") const;
│ │ │ │ - int
file_num_blocks (file_index_t index) const;
│ │ │ │ - index_range<piece_index_t::diff_type>
file_piece_range (file_index_t) const;
│ │ │ │ + std::time_t
mtime (file_index_t index) const;
│ │ │ │ int
file_num_pieces (file_index_t index) const;
│ │ │ │ - int
file_first_block_node (file_index_t index) const;
│ │ │ │ + index_range<piece_index_t::diff_type>
file_piece_range (file_index_t) const;
│ │ │ │ + int
file_num_blocks (file_index_t index) const;
│ │ │ │ int
file_first_piece_node (file_index_t index) const;
│ │ │ │ + int
file_first_block_node (file_index_t index) const;
│ │ │ │ std::uint32_t
file_path_hash (file_index_t index, std::string const& save_path) const;
│ │ │ │ void
all_path_hashes (std::unordered_set<std::uint32_t>& table) const;
│ │ │ │ file_flags_t
file_flags (file_index_t index) const;
│ │ │ │ bool
file_absolute_path (file_index_t index) const;
│ │ │ │ - file_index_t
file_index_at_piece (piece_index_t piece) const;
│ │ │ │ file_index_t
file_index_at_offset (std::int64_t offset) const;
│ │ │ │ + file_index_t
file_index_at_piece (piece_index_t piece) const;
│ │ │ │ file_index_t
file_index_for_root (sha256_hash const& root_hash) const;
│ │ │ │ piece_index_t
piece_index_at_file (file_index_t f) const;
│ │ │ │ void
sanitize_symlinks ();
│ │ │ │ bool
v2 () const;
│ │ │ │
│ │ │ │ static constexpr file_flags_t
flag_pad_file = 0_bit;
│ │ │ │ static constexpr file_flags_t
flag_hidden = 1_bit;
│ │ │ │ static constexpr file_flags_t
flag_executable = 2_bit;
│ │ │ │ static constexpr file_flags_t
flag_symlink = 3_bit;
│ │ │ │ };
│ │ │ │
│ │ │ │ -
[report issue]
│ │ │ │ +
[report issue]
│ │ │ │
is_valid()
│ │ │ │
│ │ │ │ bool is_valid () const;
│ │ │ │
│ │ │ │
returns true if the piece length has been initialized
│ │ │ │ on the file_storage. This is typically taken as a proxy
│ │ │ │ of whether the file_storage as a whole is initialized or
│ │ │ │ @@ -9860,18 +8238,18 @@
│ │ │ │
reserve()
│ │ │ │
│ │ │ │ void reserve (int num_files);
│ │ │ │
│ │ │ │
allocates space for num_files in the internal file list. This can
│ │ │ │ be used to avoid reallocating the internal file list when the number
│ │ │ │ of files to be added is known up-front.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
add_file() add_file_borrow()
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
add_file_borrow() add_file()
│ │ │ │
│ │ │ │ void add_file_borrow (error_code& ec, string_view filename
│ │ │ │ , std::string const& path, std::int64_t file_size
│ │ │ │ , file_flags_t file_flags = {}, char const* filehash = nullptr
│ │ │ │ , std::int64_t mtime = 0, string_view symlink_path = string_view()
│ │ │ │ , char const* root_hash = nullptr);
│ │ │ │ void add_file (error_code& ec, std::string const& path, std::int64_t file_size
│ │ │ │ @@ -9924,50 +8302,50 @@
│ │ │ │ the same root directory.
│ │ │ │ That is, the first path element of all files must be the same.
│ │ │ │ This shared path element is also set to the name of the torrent. It
│ │ │ │ can be changed by calling set_name.
│ │ │ │ The overloads that take an error_code reference will report failures
│ │ │ │ via that variable, otherwise system_error is thrown.
│ │ │ │ [report issue]
│ │ │ │ -
│ │ │ │ +
│ │ │ │
rename_file()
│ │ │ │
│ │ │ │ void rename_file (file_index_t index, std::string const& new_filename);
│ │ │ │
│ │ │ │
renames the file at index to new_filename. Keep in mind
│ │ │ │ that filenames are expected to be UTF-8 encoded.
│ │ │ │
[report issue]
│ │ │ │ -
│ │ │ │ +
│ │ │ │
map_block()
│ │ │ │
│ │ │ │ std::vector<file_slice> map_block (piece_index_t piece, std::int64_t offset
│ │ │ │ , std::int64_t size) const;
│ │ │ │
│ │ │ │
returns a list of file_slice objects representing the portions of
│ │ │ │ files the specified piece index, byte offset and size range overlaps.
│ │ │ │ -this is the inverse mapping of map_file().
│ │ │ │ +this is the inverse mapping of
map_file().
│ │ │ │
Preconditions of this function is that the input range is within the
│ │ │ │ torrents address space. piece may not be negative and
│ │ │ │
│ │ │ │ piece * piece_size + offset + size
│ │ │ │
may not exceed the total size of the torrent.
│ │ │ │
[report issue]
│ │ │ │ -
│ │ │ │ +
│ │ │ │
map_file()
│ │ │ │
│ │ │ │ peer_request map_file (file_index_t file, std::int64_t offset, int size) const;
│ │ │ │
│ │ │ │
returns a peer_request representing the piece index, byte offset
│ │ │ │ and size the specified file range overlaps. This is the inverse
│ │ │ │ -mapping over map_block(). Note that the peer_request return type
│ │ │ │ +mapping over map_block(). Note that the peer_request return type
│ │ │ │ is meant to hold bittorrent block requests, which may not be larger
│ │ │ │ than 16 kiB. Mapping a range larger than that may return an overflown
│ │ │ │ integer.
│ │ │ │
[report issue]
│ │ │ │ -
│ │ │ │ +
│ │ │ │
num_files()
│ │ │ │
│ │ │ │ int num_files () const noexcept;
│ │ │ │
│ │ │ │
returns the number of files in the file_storage
│ │ │ │
[report issue]
│ │ │ │
│ │ │ │ @@ -9982,27 +8360,27 @@
│ │ │ │
│ │ │ │ index_range<file_index_t> file_range () const noexcept;
│ │ │ │
│ │ │ │
returns an implementation-defined type that can be used as the
│ │ │ │ container in a range-for loop. Where the values are the indices of all
│ │ │ │ files in the file_storage.
│ │ │ │
[report issue]
│ │ │ │ -
│ │ │ │ +
│ │ │ │
total_size()
│ │ │ │
│ │ │ │ std::int64_t total_size () const;
│ │ │ │
│ │ │ │
returns the total number of bytes all the files in this torrent spans
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
set_num_pieces() num_pieces()
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
num_pieces() set_num_pieces()
│ │ │ │
│ │ │ │ -void set_num_pieces (int n);
│ │ │ │ int num_pieces () const;
│ │ │ │ +void set_num_pieces (int n);
│ │ │ │
│ │ │ │
set and get the number of pieces in the torrent
│ │ │ │
[report issue]
│ │ │ │
│ │ │ │
end_piece()
│ │ │ │
│ │ │ │ piece_index_t end_piece () const;
│ │ │ │ @@ -10027,26 +8405,26 @@
│ │ │ │ container in a range-for loop. Where the values are the indices of all
│ │ │ │ pieces in the file_storage.
│ │ │ │
│ │ │ │ [report issue]
│ │ │ │
│ │ │ │
set_piece_length() piece_length()
│ │ │ │
│ │ │ │ -int piece_length () const;
│ │ │ │ void set_piece_length (int l);
│ │ │ │ +int piece_length () const;
│ │ │ │
│ │ │ │
set and get the size of each piece in this torrent. It must be a power of two
│ │ │ │ and at least 16 kiB.
│ │ │ │
[report issue]
│ │ │ │ -
│ │ │ │ +
│ │ │ │
piece_size()
│ │ │ │
│ │ │ │ int piece_size (piece_index_t index) const;
│ │ │ │
│ │ │ │ -
returns the piece size of index. This will be the same as piece_length(), except
│ │ │ │ +
returns the piece size of index. This will be the same as piece_length(), except
│ │ │ │ for the last piece, which may be shorter.
│ │ │ │
[report issue]
│ │ │ │
│ │ │ │
piece_size2()
│ │ │ │
│ │ │ │ int piece_size2 (piece_index_t index) const;
│ │ │ │
│ │ │ │ @@ -10058,28 +8436,28 @@
│ │ │ │
│ │ │ │
blocks_in_piece2()
│ │ │ │
│ │ │ │ int blocks_in_piece2 (piece_index_t index) const;
│ │ │ │
│ │ │ │
returns the number of blocks in the specified piece, for v2 torrents.
│ │ │ │
[report issue]
│ │ │ │ -
│ │ │ │ +
│ │ │ │
blocks_per_piece()
│ │ │ │
│ │ │ │ int blocks_per_piece () const;
│ │ │ │
│ │ │ │
returns the number of blocks there are in the typical piece. There
│ │ │ │ may be fewer in the last piece)
│ │ │ │
│ │ │ │
[report issue]
│ │ │ │
│ │ │ │
set_name() name()
│ │ │ │
│ │ │ │ -void set_name (std::string const& n);
│ │ │ │ std::string const& name () const;
│ │ │ │ +void set_name (std::string const& n);
│ │ │ │
│ │ │ │
set and get the name of this torrent. For multi-file torrents, this is also
│ │ │ │ the name of the root directory all the files are stored in.
│ │ │ │
[report issue]
│ │ │ │
│ │ │ │
swap()
│ │ │ │
│ │ │ │ @@ -10090,37 +8468,37 @@
│ │ │ │
│ │ │ │
canonicalize()
│ │ │ │
│ │ │ │ void canonicalize ();
│ │ │ │
│ │ │ │
arrange files and padding to match the canonical form required
│ │ │ │ by BEP 52
│ │ │ │ -
│ │ │ │ -
│ │ │ │
│ │ │ │ -
│ │ │ │ +
│ │ │ │ +
│ │ │ │
│ │ │ │ -
│ │ │ │
│ │ │ │ +
│ │ │ │ +
│ │ │ │
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
pad_file_at() root_ptr() file_offset() root() file_size() symlink() hash() file_name() mtime() file_path()
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
file_offset() mtime() root_ptr() file_size() hash() file_path() pad_file_at() file_name() root() symlink()
│ │ │ │
│ │ │ │ -bool pad_file_at (file_index_t index) const;
│ │ │ │ -string_view file_name (file_index_t index) const;
│ │ │ │ -std::time_t mtime (file_index_t index) const;
│ │ │ │ -char const* root_ptr (file_index_t const index) const;
│ │ │ │ -sha1_hash hash (file_index_t index) const;
│ │ │ │ sha256_hash root (file_index_t index) const;
│ │ │ │ -std::int64_t file_offset (file_index_t index) const;
│ │ │ │ std::string symlink (file_index_t index) const;
│ │ │ │ +char const* root_ptr (file_index_t const index) const;
│ │ │ │ +std::int64_t file_offset (file_index_t index) const;
│ │ │ │ +bool pad_file_at (file_index_t index) const;
│ │ │ │ std::int64_t file_size (file_index_t index) const;
│ │ │ │ +sha1_hash hash (file_index_t index) const;
│ │ │ │ +string_view file_name (file_index_t index) const;
│ │ │ │ std::string file_path (file_index_t index, std::string const& save_path = "") const;
│ │ │ │ +std::time_t mtime (file_index_t index) const;
│ │ │ │
│ │ │ │
These functions are used to query attributes of files at
│ │ │ │ a given index.
│ │ │ │
The hash() is a SHA-1 hash of the file, or 0 if none was
│ │ │ │ provided in the torrent file. This can potentially be used to
│ │ │ │ join a bittorrent network with other file sharing networks.
│ │ │ │
root() returns the SHA-256 merkle tree root of the specified file,
│ │ │ │ @@ -10138,37 +8516,37 @@
│ │ │ │ index is a pad-file.
│ │ │ │
file_name() returns just the name of the file, whereas
│ │ │ │ file_path() returns the path (inside the torrent file) with
│ │ │ │ the filename appended.
│ │ │ │
file_offset() returns the byte offset within the torrent file
│ │ │ │ where this file starts. It can be used to map the file to a piece
│ │ │ │ index (given the piece size).
│ │ │ │ -
│ │ │ │
│ │ │ │ -
[report issue]
│ │ │ │ -
file_num_blocks() file_piece_range() file_num_pieces()
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
file_piece_range() file_num_blocks() file_num_pieces()
│ │ │ │
│ │ │ │ -int file_num_blocks (file_index_t index) const;
│ │ │ │ -index_range<piece_index_t::diff_type> file_piece_range (file_index_t) const;
│ │ │ │ int file_num_pieces (file_index_t index) const;
│ │ │ │ +index_range<piece_index_t::diff_type> file_piece_range (file_index_t) const;
│ │ │ │ +int file_num_blocks (file_index_t index) const;
│ │ │ │
│ │ │ │
Returns the number of pieces or blocks the file at index spans,
│ │ │ │ under the assumption that the file is aligned to the start of a piece.
│ │ │ │ This is only meaningful for v2 torrents, where files are guaranteed
│ │ │ │ such alignment.
│ │ │ │ These numbers are used to size and navigate the merkle hash tree for
│ │ │ │ each file.
│ │ │ │
│ │ │ │
[report issue]
│ │ │ │
file_first_block_node() file_first_piece_node()
│ │ │ │
│ │ │ │ -int file_first_block_node (file_index_t index) const;
│ │ │ │ int file_first_piece_node (file_index_t index) const;
│ │ │ │ +int file_first_block_node (file_index_t index) const;
│ │ │ │
│ │ │ │
index of first piece node in the merkle tree
│ │ │ │
[report issue]
│ │ │ │
file_path_hash()
│ │ │ │
│ │ │ │ std::uint32_t file_path_hash (file_index_t index, std::string const& save_path) const;
│ │ │ │ @@ -10204,16 +8582,16 @@
│ │ │ │ have an absolute path, i.e. is not anchored in the save path of the
│ │ │ │ torrent.
│ │ │ │
│ │ │ │ [report issue]
│ │ │ │
file_index_at_offset() file_index_at_piece()
│ │ │ │
│ │ │ │ -file_index_t file_index_at_piece (piece_index_t piece) const;
│ │ │ │ file_index_t file_index_at_offset (std::int64_t offset) const;
│ │ │ │ +file_index_t file_index_at_piece (piece_index_t piece) const;
│ │ │ │
│ │ │ │
returns the index of the file at the given offset in the torrent
│ │ │ │
[report issue]
│ │ │ │
file_index_for_root()
│ │ │ │
│ │ │ │ file_index_t file_index_for_root (sha256_hash const& root_hash) const;
│ │ │ │ @@ -10259,57 +8637,57 @@
│ │ │ │
- this file has the executable attribute set.
│ │ │ │
│ │ │ │
[report issue]
│ │ │ │ - flag_symlink
│ │ │ │ - this file is a symbolic link. It should have a link
│ │ │ │ target string associated with it.
│ │ │ │
│ │ │ │ -
[report issue]
│ │ │ │
│ │ │ │ +
│ │ │ │ +
mmap_disk_io_constructor()
│ │ │ │ +
Declared in "libtorrent/mmap_disk_io.hpp"
│ │ │ │ +
│ │ │ │ +std::unique_ptr<disk_interface> mmap_disk_io_constructor (
│ │ │ │ + io_context& ios, settings_interface const&, counters& cnt);
│ │ │ │ +
│ │ │ │ +
constructs a memory mapped file disk I/O object.
│ │ │ │ +
[report issue]
│ │ │ │
│ │ │ │
default_disk_io_constructor()
│ │ │ │
Declared in "libtorrent/session.hpp"
│ │ │ │
│ │ │ │ std::unique_ptr<disk_interface> default_disk_io_constructor (
│ │ │ │ io_context& ios, settings_interface const&, counters& cnt);
│ │ │ │
│ │ │ │
the constructor function for the default storage. On systems that support
│ │ │ │ memory mapped files (and a 64 bit address space) the memory mapped storage
│ │ │ │ will be constructed, otherwise the portable posix storage.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
posix_disk_io_constructor()
│ │ │ │ -
Declared in "libtorrent/posix_disk_io.hpp"
│ │ │ │ -
│ │ │ │ -std::unique_ptr<disk_interface> posix_disk_io_constructor (
│ │ │ │ - io_context& ios, settings_interface const&, counters& cnt);
│ │ │ │ -
│ │ │ │ -
this is a simple posix disk I/O back-end, used for systems that don't
│ │ │ │ -have a 64 bit virtual address space or don't support memory mapped files.
│ │ │ │ -It's implemented using portable C file functions and is single-threaded.
│ │ │ │
[report issue]
│ │ │ │
│ │ │ │
disabled_disk_io_constructor()
│ │ │ │
Declared in "libtorrent/disabled_disk_io.hpp"
│ │ │ │
│ │ │ │ std::unique_ptr<disk_interface> disabled_disk_io_constructor (
│ │ │ │ io_context& ios, settings_interface const&, counters& cnt);
│ │ │ │
│ │ │ │
creates a disk io object that discards all data written to it, and only
│ │ │ │ returns zero-buffers when read from. May be useful for testing and
│ │ │ │ benchmarking.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ +
│ │ │ │ +
posix_disk_io_constructor()
│ │ │ │ +
Declared in "libtorrent/posix_disk_io.hpp"
│ │ │ │
│ │ │ │ -std::unique_ptr<disk_interface> mmap_disk_io_constructor (
│ │ │ │ +std::unique_ptr<disk_interface> posix_disk_io_constructor (
│ │ │ │ io_context& ios, settings_interface const&, counters& cnt);
│ │ │ │
│ │ │ │ -
constructs a memory mapped file disk I/O object.
│ │ │ │ +
this is a simple posix disk I/O back-end, used for systems that don't
│ │ │ │ +have a 64 bit virtual address space or don't support memory mapped files.
│ │ │ │ +It's implemented using portable C file functions and is single-threaded.
│ │ │ │
[report issue]
│ │ │ │
│ │ │ │
enum storage_mode_t
│ │ │ │
Declared in "libtorrent/storage_defs.hpp"
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │ @@ -10423,14 +8801,1079 @@
│ │ │ │ | reset_save_path_unchecked |
│ │ │ │ 4 |
│ │ │ │ don't move any source files, just change save path
│ │ │ │ and continue working without any checks |
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
session_proxy
│ │ │ │ +
Declared in "libtorrent/session.hpp"
│ │ │ │ +
this is a holder for the internal session implementation object. Once the
│ │ │ │ +session destruction is explicitly initiated, this holder is used to
│ │ │ │ +synchronize the completion of the shutdown. The lifetime of this object
│ │ │ │ +may outlive session, causing the session destructor to not block. The
│ │ │ │ +session_proxy destructor will block however, until the underlying session
│ │ │ │ +is done shutting down.
│ │ │ │ +
│ │ │ │ +struct session_proxy
│ │ │ │ +{
│ │ │ │ + session_proxy& operator= (session_proxy const&) &;
│ │ │ │ + session_proxy& operator= (session_proxy&&) & noexcept;
│ │ │ │ + session_proxy (session_proxy&&) noexcept;
│ │ │ │ + session_proxy ();
│ │ │ │ + ~session_proxy ();
│ │ │ │ + session_proxy (session_proxy const&);
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
~session_proxy() session_proxy() operator=()
│ │ │ │ +
│ │ │ │ +session_proxy& operator= (session_proxy const&) &;
│ │ │ │ +session_proxy& operator= (session_proxy&&) & noexcept;
│ │ │ │ +session_proxy (session_proxy&&) noexcept;
│ │ │ │ +session_proxy ();
│ │ │ │ +~session_proxy ();
│ │ │ │ +session_proxy (session_proxy const&);
│ │ │ │ +
│ │ │ │ +
default constructor, does not refer to any session
│ │ │ │ +implementation object.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
session
│ │ │ │ +
Declared in "libtorrent/session.hpp"
│ │ │ │ +
The session holds all state that spans multiple torrents. Among other
│ │ │ │ +things it runs the network loop and manages all torrents. Once it's
│ │ │ │ +created, the session object will spawn the main thread that will do all
│ │ │ │ +the work. The main thread will be idle as long it doesn't have any
│ │ │ │ +torrents to participate in.
│ │ │ │ +
You have some control over session configuration through the
│ │ │ │ +session_handle::apply_settings() member function. To change one or more
│ │ │ │ +configuration options, create a settings_pack. object and fill it with
│ │ │ │ +the settings to be set and pass it in to session::apply_settings().
│ │ │ │ +
see apply_settings().
│ │ │ │ +
│ │ │ │ +struct session : session_handle
│ │ │ │ +{
│ │ │ │ + explicit session (session_params const& params);
│ │ │ │ + session (session_params&& params, session_flags_t flags);
│ │ │ │ + session ();
│ │ │ │ + session (session_params const& params, session_flags_t flags);
│ │ │ │ + explicit session (session_params&& params);
│ │ │ │ + session (session_params&& params, io_context& ios);
│ │ │ │ + session (session_params const& params, io_context& ios);
│ │ │ │ + session (session_params&& params, io_context& ios, session_flags_t);
│ │ │ │ + session (session_params const& params, io_context& ios, session_flags_t);
│ │ │ │ + ~session ();
│ │ │ │ + session_proxy abort ();
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
session()
│ │ │ │ +
│ │ │ │ +explicit session (session_params const& params);
│ │ │ │ +session (session_params&& params, session_flags_t flags);
│ │ │ │ +session ();
│ │ │ │ +session (session_params const& params, session_flags_t flags);
│ │ │ │ +explicit session (session_params&& params);
│ │ │ │ +
│ │ │ │ +
Constructs the session objects which acts as the container of torrents.
│ │ │ │ +In order to avoid a race condition between starting the session and
│ │ │ │ +configuring it, you can pass in a session_params object. Its settings
│ │ │ │ +will take effect before the session starts up.
│ │ │ │ +
The overloads taking flags can be used to start a session in
│ │ │ │ +paused mode (by passing in session::paused). Note that
│ │ │ │ +add_default_plugins do not have an affect on constructors that
│ │ │ │ +take a session_params object. It already contains the plugins to use.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
session()
│ │ │ │ +
│ │ │ │ +session (session_params&& params, io_context& ios);
│ │ │ │ +session (session_params const& params, io_context& ios);
│ │ │ │ +session (session_params&& params, io_context& ios, session_flags_t);
│ │ │ │ +session (session_params const& params, io_context& ios, session_flags_t);
│ │ │ │ +
│ │ │ │ +
Overload of the constructor that takes an external io_context to run
│ │ │ │ +the session object on. This is primarily useful for tests that may want
│ │ │ │ +to run multiple sessions on a single io_context, or low resource
│ │ │ │ +systems where additional threads are expensive and sharing an
│ │ │ │ +io_context with other events is fine.
│ │ │ │ +
│ │ │ │ +
Warning
│ │ │ │ +
The session object does not cleanly terminate with an external
│ │ │ │ +io_context. The io_context::run() call must have returned
│ │ │ │ +before it's safe to destruct the session. Which means you MUST
│ │ │ │ +call session::abort() and save the session_proxy first, then
│ │ │ │ +destruct the session object, then sync with the io_context, then
│ │ │ │ +destruct the session_proxy object.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
~session()
│ │ │ │ +
│ │ │ │ +~session ();
│ │ │ │ +
│ │ │ │ +
The destructor of session will notify all trackers that our torrents
│ │ │ │ +have been shut down. If some trackers are down, they will time out.
│ │ │ │ +All this before the destructor of session returns. So, it's advised
│ │ │ │ +that any kind of interface (such as windows) are closed before
│ │ │ │ +destructing the session object. Because it can take a few second for
│ │ │ │ +it to finish. The timeout can be set with apply_settings().
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
abort()
│ │ │ │ +
│ │ │ │ +session_proxy abort ();
│ │ │ │ +
│ │ │ │ +
In case you want to destruct the session asynchronously, you can
│ │ │ │ +request a session destruction proxy. If you don't do this, the
│ │ │ │ +destructor of the session object will block while the trackers are
│ │ │ │ +contacted. If you keep one session_proxy to the session when
│ │ │ │ +destructing it, the destructor will not block, but start to close down
│ │ │ │ +the session, the destructor of the proxy will then synchronize the
│ │ │ │ +threads. So, the destruction of the session is performed from the
│ │ │ │ +session destructor call until the session_proxy destructor
│ │ │ │ +call. The session_proxy does not have any operations on it (since
│ │ │ │ +the session is being closed down, no operations are allowed on it).
│ │ │ │ +The only valid operation is calling the destructor:
│ │ │ │ +
│ │ │ │ +struct session_proxy {};
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
session_handle
│ │ │ │ +
Declared in "libtorrent/session_handle.hpp"
│ │ │ │ +
this class provides a non-owning handle to a session and a subset of the
│ │ │ │ +interface of the session class. If the underlying session is destructed
│ │ │ │ +any handle to it will no longer be valid. is_valid() will return false and
│ │ │ │ +any operation on it will throw a system_error exception, with error code
│ │ │ │ +invalid_session_handle.
│ │ │ │ +
│ │ │ │ +struct session_handle
│ │ │ │ +{
│ │ │ │ + bool is_valid () const;
│ │ │ │ + session_params session_state (save_state_flags_t flags = save_state_flags_t::all()) const;
│ │ │ │ + std::vector<torrent_status> get_torrent_status (
│ │ │ │ + std::function<bool(torrent_status const&)> const& pred
│ │ │ │ + , status_flags_t flags = {}) const;
│ │ │ │ + void refresh_torrent_status (std::vector<torrent_status>* ret
│ │ │ │ + , status_flags_t flags = {}) const;
│ │ │ │ + void post_torrent_updates (status_flags_t flags = status_flags_t::all());
│ │ │ │ + void post_session_stats ();
│ │ │ │ + void post_dht_stats ();
│ │ │ │ + void set_dht_state (dht::dht_state const& st);
│ │ │ │ + void set_dht_state (dht::dht_state&& st);
│ │ │ │ + torrent_handle find_torrent (sha1_hash const& info_hash) const;
│ │ │ │ + std::vector<torrent_handle> get_torrents () const;
│ │ │ │ + torrent_handle add_torrent (add_torrent_params const& params, error_code& ec);
│ │ │ │ + torrent_handle add_torrent (add_torrent_params const& params);
│ │ │ │ + torrent_handle add_torrent (add_torrent_params&& params);
│ │ │ │ + void async_add_torrent (add_torrent_params&& params);
│ │ │ │ + void async_add_torrent (add_torrent_params const& params);
│ │ │ │ + torrent_handle add_torrent (add_torrent_params&& params, error_code& ec);
│ │ │ │ + bool is_paused () const;
│ │ │ │ + void pause ();
│ │ │ │ + void resume ();
│ │ │ │ + bool is_dht_running () const;
│ │ │ │ + void set_dht_storage (dht::dht_storage_constructor_type sc);
│ │ │ │ + void add_dht_node (std::pair<std::string, int> const& node);
│ │ │ │ + void dht_get_item (sha1_hash const& target);
│ │ │ │ + void dht_get_item (std::array<char, 32> key
│ │ │ │ + , std::string salt = std::string());
│ │ │ │ + sha1_hash dht_put_item (entry data);
│ │ │ │ + void dht_put_item (std::array<char, 32> key
│ │ │ │ + , std::function<void(entry&, std::array<char, 64>&
│ │ │ │ + , std::int64_t&, std::string const&)> cb
│ │ │ │ + , std::string salt = std::string());
│ │ │ │ + void dht_get_peers (sha1_hash const& info_hash);
│ │ │ │ + void dht_announce (sha1_hash const& info_hash, int port = 0, dht::announce_flags_t flags = {});
│ │ │ │ + void dht_live_nodes (sha1_hash const& nid);
│ │ │ │ + void dht_sample_infohashes (udp::endpoint const& ep, sha1_hash const& target);
│ │ │ │ + void dht_direct_request (udp::endpoint const& ep, entry const& e, client_data_t userdata = {});
│ │ │ │ + void add_extension (std::function<std::shared_ptr<torrent_plugin>(
│ │ │ │ + torrent_handle const&, client_data_t)> ext);
│ │ │ │ + void add_extension (std::shared_ptr<plugin> ext);
│ │ │ │ + ip_filter get_ip_filter () const;
│ │ │ │ + void set_ip_filter (ip_filter f);
│ │ │ │ + void set_port_filter (port_filter const& f);
│ │ │ │ + unsigned short listen_port () const;
│ │ │ │ + unsigned short ssl_listen_port () const;
│ │ │ │ + bool is_listening () const;
│ │ │ │ + ip_filter get_peer_class_filter () const;
│ │ │ │ + void set_peer_class_filter (ip_filter const& f);
│ │ │ │ + peer_class_type_filter get_peer_class_type_filter () const;
│ │ │ │ + void set_peer_class_type_filter (peer_class_type_filter const& f);
│ │ │ │ + peer_class_t create_peer_class (char const* name);
│ │ │ │ + void delete_peer_class (peer_class_t cid);
│ │ │ │ + peer_class_info get_peer_class (peer_class_t cid) const;
│ │ │ │ + void set_peer_class (peer_class_t cid, peer_class_info const& pci);
│ │ │ │ + void remove_torrent (const torrent_handle&, remove_flags_t = {});
│ │ │ │ + void apply_settings (settings_pack&&);
│ │ │ │ + void apply_settings (settings_pack const&);
│ │ │ │ + settings_pack get_settings () const;
│ │ │ │ + void pop_alerts (std::vector<alert*>* alerts);
│ │ │ │ + alert* wait_for_alert (time_duration max_wait);
│ │ │ │ + void set_alert_notify (std::function<void()> const& fun);
│ │ │ │ + void delete_port_mapping (port_mapping_t handle);
│ │ │ │ + std::vector<port_mapping_t> add_port_mapping (portmap_protocol t, int external_port, int local_port);
│ │ │ │ + void reopen_network_sockets (reopen_network_flags_t options = reopen_map_ports);
│ │ │ │ + std::shared_ptr<aux::session_impl> native_handle () const;
│ │ │ │ +
│ │ │ │ + static constexpr save_state_flags_t save_settings = 0_bit;
│ │ │ │ + static constexpr save_state_flags_t save_dht_state = 2_bit;
│ │ │ │ + static constexpr save_state_flags_t save_extension_state = 11_bit;
│ │ │ │ + static constexpr save_state_flags_t save_ip_filter = 12_bit;
│ │ │ │ + static constexpr peer_class_t global_peer_class_id {0};
│ │ │ │ + static constexpr peer_class_t tcp_peer_class_id {1};
│ │ │ │ + static constexpr peer_class_t local_peer_class_id {2};
│ │ │ │ + static constexpr remove_flags_t delete_files = 0_bit;
│ │ │ │ + static constexpr remove_flags_t delete_partfile = 1_bit;
│ │ │ │ + static constexpr session_flags_t paused = 2_bit;
│ │ │ │ + static constexpr portmap_protocol udp = portmap_protocol::udp;
│ │ │ │ + static constexpr portmap_protocol tcp = portmap_protocol::tcp;
│ │ │ │ + static constexpr reopen_network_flags_t reopen_map_ports = 0_bit;
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
is_valid()
│ │ │ │ +
│ │ │ │ +bool is_valid () const;
│ │ │ │ +
│ │ │ │ +
returns true if this handle refers to a valid session object. If the
│ │ │ │ +session has been destroyed, all session_handle objects will expire and
│ │ │ │ +not be valid.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
session_state()
│ │ │ │ +
│ │ │ │ +session_params session_state (save_state_flags_t flags = save_state_flags_t::all()) const;
│ │ │ │ +
│ │ │ │ +
returns the current session state. This can be passed to
│ │ │ │ +write_session_params() to save the state to disk and restored using
│ │ │ │ +read_session_params() when constructing a new session. The kind of
│ │ │ │ +state that's included is all settings, the DHT routing table, possibly
│ │ │ │ +plugin-specific state.
│ │ │ │ +the flags parameter can be used to only save certain parts of the
│ │ │ │ +session state
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
get_torrent_status() refresh_torrent_status()
│ │ │ │ +
│ │ │ │ +std::vector<torrent_status> get_torrent_status (
│ │ │ │ + std::function<bool(torrent_status const&)> const& pred
│ │ │ │ + , status_flags_t flags = {}) const;
│ │ │ │ +void refresh_torrent_status (std::vector<torrent_status>* ret
│ │ │ │ + , status_flags_t flags = {}) const;
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
Note
│ │ │ │ +
these calls are potentially expensive and won't scale well with
│ │ │ │ +lots of torrents. If you're concerned about performance, consider
│ │ │ │ +using post_torrent_updates() instead.
│ │ │ │ +
│ │ │ │ +
get_torrent_status returns a vector of the torrent_status for
│ │ │ │ +every torrent which satisfies pred, which is a predicate function
│ │ │ │ +which determines if a torrent should be included in the returned set
│ │ │ │ +or not. Returning true means it should be included and false means
│ │ │ │ +excluded. The flags argument is the same as to
│ │ │ │ +torrent_handle::status(). Since pred is guaranteed to be
│ │ │ │ +called for every torrent, it may be used to count the number of
│ │ │ │ +torrents of different categories as well.
│ │ │ │ +
refresh_torrent_status takes a vector of torrent_status structs
│ │ │ │ +(for instance the same vector that was returned by
│ │ │ │ +get_torrent_status() ) and refreshes the status based on the
│ │ │ │ +handle member. It is possible to use this function by first
│ │ │ │ +setting up a vector of default constructed torrent_status objects,
│ │ │ │ +only initializing the handle member, in order to request the
│ │ │ │ +torrent status for multiple torrents in a single call. This can save a
│ │ │ │ +significant amount of time if you have a lot of torrents.
│ │ │ │ +
Any torrent_status object whose handle member is not referring to
│ │ │ │ +a valid torrent are ignored.
│ │ │ │ +
The intended use of these functions is to start off by calling
│ │ │ │ +get_torrent_status() to get a list of all torrents that match your
│ │ │ │ +criteria. Then call refresh_torrent_status() on that list. This
│ │ │ │ +will only refresh the status for the torrents in your list, and thus
│ │ │ │ +ignore all other torrents you might be running. This may save a
│ │ │ │ +significant amount of time, especially if the number of torrents you're
│ │ │ │ +interested in is small. In order to keep your list of interested
│ │ │ │ +torrents up to date, you can either call get_torrent_status() from
│ │ │ │ +time to time, to include torrents you might have become interested in
│ │ │ │ +since the last time. In order to stop refreshing a certain torrent,
│ │ │ │ +simply remove it from the list.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
post_torrent_updates()
│ │ │ │ +
│ │ │ │ +void post_torrent_updates (status_flags_t flags = status_flags_t::all());
│ │ │ │ +
│ │ │ │ +
This functions instructs the session to post the state_update_alert,
│ │ │ │ +containing the status of all torrents whose state changed since the
│ │ │ │ +last time this function was called.
│ │ │ │ +
Only torrents who has the state subscription flag set will be
│ │ │ │ +included. This flag is on by default. See add_torrent_params.
│ │ │ │ +the flags argument is the same as for torrent_handle::status().
│ │ │ │ +see status_flags_t in torrent_handle.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
post_session_stats()
│ │ │ │ +
│ │ │ │ +void post_session_stats ();
│ │ │ │ +
│ │ │ │ +
This function will post a session_stats_alert object, containing a
│ │ │ │ +snapshot of the performance counters from the internals of libtorrent.
│ │ │ │ +To interpret these counters, query the session via
│ │ │ │ +session_stats_metrics().
│ │ │ │ +
For more information, see the session statistics section.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
post_dht_stats()
│ │ │ │ +
│ │ │ │ +void post_dht_stats ();
│ │ │ │ +
│ │ │ │ +
This will cause a dht_stats_alert to be posted.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
set_dht_state()
│ │ │ │ +
│ │ │ │ +void set_dht_state (dht::dht_state const& st);
│ │ │ │ +void set_dht_state (dht::dht_state&& st);
│ │ │ │ +
│ │ │ │ +
set the DHT state for the session. This will be taken into account the
│ │ │ │ +next time the DHT is started, as if it had been passed in via the
│ │ │ │ +session_params on startup.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
find_torrent() get_torrents()
│ │ │ │ +
│ │ │ │ +torrent_handle find_torrent (sha1_hash const& info_hash) const;
│ │ │ │ +std::vector<torrent_handle> get_torrents () const;
│ │ │ │ +
│ │ │ │ +
find_torrent() looks for a torrent with the given info-hash. In
│ │ │ │ +case there is such a torrent in the session, a torrent_handle to that
│ │ │ │ +torrent is returned. In case the torrent cannot be found, an invalid
│ │ │ │ +torrent_handle is returned.
│ │ │ │ +
See torrent_handle::is_valid() to know if the torrent was found or
│ │ │ │ +not.
│ │ │ │ +
get_torrents() returns a vector of torrent_handles to all the
│ │ │ │ +torrents currently in the session.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
add_torrent() async_add_torrent()
│ │ │ │ +
│ │ │ │ +torrent_handle add_torrent (add_torrent_params const& params, error_code& ec);
│ │ │ │ +torrent_handle add_torrent (add_torrent_params const& params);
│ │ │ │ +torrent_handle add_torrent (add_torrent_params&& params);
│ │ │ │ +void async_add_torrent (add_torrent_params&& params);
│ │ │ │ +void async_add_torrent (add_torrent_params const& params);
│ │ │ │ +torrent_handle add_torrent (add_torrent_params&& params, error_code& ec);
│ │ │ │ +
│ │ │ │ +
You add torrents through the add_torrent() function where you give an
│ │ │ │ +object with all the parameters. The add_torrent() overloads will block
│ │ │ │ +until the torrent has been added (or failed to be added) and returns
│ │ │ │ +an error code and a torrent_handle. In order to add torrents more
│ │ │ │ +efficiently, consider using async_add_torrent() which returns
│ │ │ │ +immediately, without waiting for the torrent to add. Notification of
│ │ │ │ +the torrent being added is sent as add_torrent_alert.
│ │ │ │ +
The save_path field in add_torrent_params must be set to a valid
│ │ │ │ +path where the files for the torrent will be saved. Even when using a
│ │ │ │ +custom storage, this needs to be set to something. If the save_path
│ │ │ │ +is empty, the call to add_torrent() will throw a system_error
│ │ │ │ +exception.
│ │ │ │ +
The overload that does not take an error_code throws an exception on
│ │ │ │ +error and is not available when building without exception support.
│ │ │ │ +The torrent_handle returned by add_torrent() can be used to retrieve
│ │ │ │ +information about the torrent's progress, its peers etc. It is also
│ │ │ │ +used to abort a torrent.
│ │ │ │ +
If the torrent you are trying to add already exists in the session (is
│ │ │ │ +either queued for checking, being checked or downloading)
│ │ │ │ +add_torrent() will throw system_error which derives from
│ │ │ │ +std::exception unless duplicate_is_error is set to false. In that
│ │ │ │ +case, add_torrent() will return the handle to the existing torrent.
│ │ │ │ +
The add_torrent_params class has a flags field. It can be used to
│ │ │ │ +control what state the new torrent will be added in. Common flags to
│ │ │ │ +want to control are torrent_flags::paused and
│ │ │ │ +torrent_flags::auto_managed. In order to add a magnet link that will
│ │ │ │ +just download the metadata, but no payload, set the
│ │ │ │ +torrent_flags::upload_mode flag.
│ │ │ │ +
Special consideration has to be taken when adding hybrid torrents
│ │ │ │ +(i.e. torrents that are BitTorrent v2 torrents that are backwards
│ │ │ │ +compatible with v1). For more details, see BitTorrent v2 torrents.
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
resume() pause() is_paused()
│ │ │ │ +
│ │ │ │ +bool is_paused () const;
│ │ │ │ +void pause ();
│ │ │ │ +void resume ();
│ │ │ │ +
│ │ │ │ +
Pausing the session has the same effect as pausing every torrent in
│ │ │ │ +it, except that torrents will not be resumed by the auto-manage
│ │ │ │ +mechanism. Resuming will restore the torrents to their previous paused
│ │ │ │ +state. i.e. the session pause state is separate from the torrent pause
│ │ │ │ +state. A torrent is inactive if it is paused or if the session is
│ │ │ │ +paused.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
is_dht_running()
│ │ │ │ +
│ │ │ │ +bool is_dht_running () const;
│ │ │ │ +
│ │ │ │ +
is_dht_running() returns true if the DHT support has been started
│ │ │ │ +and false otherwise.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
set_dht_storage()
│ │ │ │ +
│ │ │ │ +void set_dht_storage (dht::dht_storage_constructor_type sc);
│ │ │ │ +
│ │ │ │ +
set_dht_storage set a dht custom storage constructor function
│ │ │ │ +to be used internally when the dht is created.
│ │ │ │ +
Since the dht storage is a critical component for the dht behavior,
│ │ │ │ +this function will only be effective the next time the dht is started.
│ │ │ │ +If you never touch this feature, a default map-memory based storage
│ │ │ │ +is used.
│ │ │ │ +
If you want to make sure the dht is initially created with your
│ │ │ │ +custom storage, create a session with the setting
│ │ │ │ +settings_pack::enable_dht to false, set your constructor function
│ │ │ │ +and call apply_settings with settings_pack::enable_dht to true.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
add_dht_node()
│ │ │ │ +
│ │ │ │ +void add_dht_node (std::pair<std::string, int> const& node);
│ │ │ │ +
│ │ │ │ +
add_dht_node takes a host name and port pair. That endpoint will be
│ │ │ │ +pinged, and if a valid DHT reply is received, the node will be added to
│ │ │ │ +the routing table.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
dht_get_item()
│ │ │ │ +
│ │ │ │ +void dht_get_item (sha1_hash const& target);
│ │ │ │ +
│ │ │ │ +
query the DHT for an immutable item at the target hash.
│ │ │ │ +the result is posted as a dht_immutable_item_alert.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
dht_get_item()
│ │ │ │ +
│ │ │ │ +void dht_get_item (std::array<char, 32> key
│ │ │ │ + , std::string salt = std::string());
│ │ │ │ +
│ │ │ │ +
query the DHT for a mutable item under the public key key.
│ │ │ │ +this is an ed25519 key. salt is optional and may be left
│ │ │ │ +as an empty string if no salt is to be used.
│ │ │ │ +if the item is found in the DHT, a dht_mutable_item_alert is
│ │ │ │ +posted.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
dht_put_item()
│ │ │ │ +
│ │ │ │ +sha1_hash dht_put_item (entry data);
│ │ │ │ +
│ │ │ │ +
store the given bencoded data as an immutable item in the DHT.
│ │ │ │ +the returned hash is the key that is to be used to look the item
│ │ │ │ +up again. It's just the SHA-1 hash of the bencoded form of the
│ │ │ │ +structure.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
dht_put_item()
│ │ │ │ +
│ │ │ │ +void dht_put_item (std::array<char, 32> key
│ │ │ │ + , std::function<void(entry&, std::array<char, 64>&
│ │ │ │ + , std::int64_t&, std::string const&)> cb
│ │ │ │ + , std::string salt = std::string());
│ │ │ │ +
│ │ │ │ +
store a mutable item. The key is the public key the blob is
│ │ │ │ +to be stored under. The optional salt argument is a string that
│ │ │ │ +is to be mixed in with the key when determining where in the DHT
│ │ │ │ +the value is to be stored. The callback function is called from within
│ │ │ │ +the libtorrent network thread once we've found where to store the blob,
│ │ │ │ +possibly with the current value stored under the key.
│ │ │ │ +The values passed to the callback functions are:
│ │ │ │ +
│ │ │ │ +- entry& value
│ │ │ │ +- the current value stored under the key (may be empty). Also expected
│ │ │ │ +to be set to the value to be stored by the function.
│ │ │ │ +- std::array<char,64>& signature
│ │ │ │ +- the signature authenticating the current value. This may be zeros
│ │ │ │ +if there is currently no value stored. The function is expected to
│ │ │ │ +fill in this buffer with the signature of the new value to store.
│ │ │ │ +To generate the signature, you may want to use the
│ │ │ │ +sign_mutable_item function.
│ │ │ │ +- std::int64_t& seq
│ │ │ │ +- current sequence number. May be zero if there is no current value.
│ │ │ │ +The function is expected to set this to the new sequence number of
│ │ │ │ +the value that is to be stored. Sequence numbers must be monotonically
│ │ │ │ +increasing. Attempting to overwrite a value with a lower or equal
│ │ │ │ +sequence number will fail, even if the signature is correct.
│ │ │ │ +- std::string const& salt
│ │ │ │ +- this is the salt that was used for this put call.
│ │ │ │ +
│ │ │ │ +
Since the callback function cb is called from within libtorrent,
│ │ │ │ +it is critical to not perform any blocking operations. Ideally not
│ │ │ │ +even locking a mutex. Pass any data required for this function along
│ │ │ │ +with the function object's context and make the function entirely
│ │ │ │ +self-contained. The only reason data blob's value is computed
│ │ │ │ +via a function instead of just passing in the new value is to avoid
│ │ │ │ +race conditions. If you want to update the value in the DHT, you
│ │ │ │ +must first retrieve it, then modify it, then write it back. The way
│ │ │ │ +the DHT works, it is natural to always do a lookup before storing and
│ │ │ │ +calling the callback in between is convenient.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
dht_announce() dht_get_peers()
│ │ │ │ +
│ │ │ │ +void dht_get_peers (sha1_hash const& info_hash);
│ │ │ │ +void dht_announce (sha1_hash const& info_hash, int port = 0, dht::announce_flags_t flags = {});
│ │ │ │ +
│ │ │ │ +
dht_get_peers() will issue a DHT get_peer request to the DHT for the
│ │ │ │ +specified info-hash. The response (the peers) will be posted back in a
│ │ │ │ +dht_get_peers_reply_alert.
│ │ │ │ +
dht_announce() will issue a DHT announce request to the DHT to the
│ │ │ │ +specified info-hash, advertising the specified port. If the port is
│ │ │ │ +left at its default, 0, the port will be implied by the DHT message's
│ │ │ │ +source port (which may improve connectivity through a NAT).
│ │ │ │ +dht_announce() is not affected by the announce_port override setting.
│ │ │ │ +
Both these functions are exposed for advanced custom use of the DHT.
│ │ │ │ +All torrents eligible to be announce to the DHT will be automatically,
│ │ │ │ +by libtorrent.
│ │ │ │ +
For possible flags, see announce_flags_t.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
dht_live_nodes()
│ │ │ │ +
│ │ │ │ +void dht_live_nodes (sha1_hash const& nid);
│ │ │ │ +
│ │ │ │ +
Retrieve all the live DHT (identified by nid) nodes. All the
│ │ │ │ +nodes id and endpoint will be returned in the list of nodes in the
│ │ │ │ +alert dht_live_nodes_alert.
│ │ │ │ +Since this alert is a response to an explicit call, it will always be
│ │ │ │ +posted, regardless of the alert mask.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
dht_sample_infohashes()
│ │ │ │ +
│ │ │ │ +void dht_sample_infohashes (udp::endpoint const& ep, sha1_hash const& target);
│ │ │ │ +
│ │ │ │ +
Query the DHT node specified by ep to retrieve a sample of the
│ │ │ │ +info-hashes that the node currently have in their storage.
│ │ │ │ +The target is included for iterative lookups so that indexing nodes
│ │ │ │ +can perform a key space traversal with a single RPC per node by adjusting
│ │ │ │ +the target value for each RPC. It has no effect on the returned sample value.
│ │ │ │ +The result is posted as a dht_sample_infohashes_alert.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
dht_direct_request()
│ │ │ │ +
│ │ │ │ +void dht_direct_request (udp::endpoint const& ep, entry const& e, client_data_t userdata = {});
│ │ │ │ +
│ │ │ │ +
Send an arbitrary DHT request directly to the specified endpoint. This
│ │ │ │ +function is intended for use by plugins. When a response is received
│ │ │ │ +or the request times out, a dht_direct_response_alert will be posted
│ │ │ │ +with the response (if any) and the userdata pointer passed in here.
│ │ │ │ +Since this alert is a response to an explicit call, it will always be
│ │ │ │ +posted, regardless of the alert mask.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
add_extension()
│ │ │ │ +
│ │ │ │ +void add_extension (std::function<std::shared_ptr<torrent_plugin>(
│ │ │ │ + torrent_handle const&, client_data_t)> ext);
│ │ │ │ +void add_extension (std::shared_ptr<plugin> ext);
│ │ │ │ +
│ │ │ │ +
This function adds an extension to this session. The argument is a
│ │ │ │ +function object that is called with a torrent_handle and which should
│ │ │ │ +return a std::shared_ptr<torrent_plugin>. To write custom
│ │ │ │ +plugins, see libtorrent plugins. For the typical bittorrent client
│ │ │ │ +all of these extensions should be added. The main plugins implemented
│ │ │ │ +in libtorrent are:
│ │ │ │ +
│ │ │ │ +- uTorrent metadata
│ │ │ │ +- Allows peers to download the metadata (.torrent files) from the swarm
│ │ │ │ +directly. Makes it possible to join a swarm with just a tracker and
│ │ │ │ +info-hash.
│ │ │ │ +
│ │ │ │ +
│ │ │ │ + ses.add_extension(<::create_ut_metadata_plugin);
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +- uTorrent peer exchange
│ │ │ │ +- Exchanges peers between clients.
│ │ │ │ +
│ │ │ │ +
│ │ │ │ + ses.add_extension(<::create_ut_pex_plugin);
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +- smart ban plugin
│ │ │ │ +- A plugin that, with a small overhead, can ban peers
│ │ │ │ +that sends bad data with very high accuracy. Should
│ │ │ │ +eliminate most problems on poisoned torrents.
│ │ │ │ +
│ │ │ │ +
│ │ │ │ + ses.add_extension(<::create_smart_ban_plugin);
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
set_ip_filter() get_ip_filter()
│ │ │ │ +
│ │ │ │ +ip_filter get_ip_filter () const;
│ │ │ │ +void set_ip_filter (ip_filter f);
│ │ │ │ +
│ │ │ │ +
Sets a filter that will be used to reject and accept incoming as well
│ │ │ │ +as outgoing connections based on their originating ip address. The
│ │ │ │ +default filter will allow connections to any ip address. To build a
│ │ │ │ +set of rules for which addresses are accepted and not, see ip_filter.
│ │ │ │ +
Each time a peer is blocked because of the IP filter, a
│ │ │ │ +peer_blocked_alert is generated. get_ip_filter() Returns the
│ │ │ │ +ip_filter currently in the session. See ip_filter.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
set_port_filter()
│ │ │ │ +
│ │ │ │ +void set_port_filter (port_filter const& f);
│ │ │ │ +
│ │ │ │ +
apply port_filter f to incoming and outgoing peers. a port filter
│ │ │ │ +will reject making outgoing peer connections to certain remote ports.
│ │ │ │ +The main intention is to be able to avoid triggering certain
│ │ │ │ +anti-virus software by connecting to SMTP, FTP ports.
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
ssl_listen_port() listen_port() is_listening()
│ │ │ │ +
│ │ │ │ +unsigned short listen_port () const;
│ │ │ │ +unsigned short ssl_listen_port () const;
│ │ │ │ +bool is_listening () const;
│ │ │ │ +
│ │ │ │ +
is_listening() will tell you whether or not the session has
│ │ │ │ +successfully opened a listening port. If it hasn't, this function will
│ │ │ │ +return false, and then you can set a new
│ │ │ │ +settings_pack::listen_interfaces to try another interface and port to
│ │ │ │ +bind to.
│ │ │ │ +
listen_port() returns the port we ended up listening on.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
get_peer_class_filter() set_peer_class_filter()
│ │ │ │ +
│ │ │ │ +ip_filter get_peer_class_filter () const;
│ │ │ │ +void set_peer_class_filter (ip_filter const& f);
│ │ │ │ +
│ │ │ │ +
Sets the peer class filter for this session. All new peer connections
│ │ │ │ +will take this into account and be added to the peer classes specified
│ │ │ │ +by this filter, based on the peer's IP address.
│ │ │ │ +
The ip-filter essentially maps an IP -> uint32. Each bit in that 32
│ │ │ │ +bit integer represents a peer class. The least significant bit
│ │ │ │ +represents class 0, the next bit class 1 and so on.
│ │ │ │ +
For more info, see ip_filter.
│ │ │ │ +
For example, to make all peers in the range 200.1.1.0 - 200.1.255.255
│ │ │ │ +belong to their own peer class, apply the following filter:
│ │ │ │ +
│ │ │ │ +ip_filter f = ses.get_peer_class_filter();
│ │ │ │ +peer_class_t my_class = ses.create_peer_class("200.1.x.x IP range");
│ │ │ │ +f.add_rule(make_address("200.1.1.0"), make_address("200.1.255.255")
│ │ │ │ + , 1 << static_cast<std::uint32_t>(my_class));
│ │ │ │ +ses.set_peer_class_filter(f);
│ │ │ │ +
│ │ │ │ +
This setting only applies to new connections, it won't affect existing
│ │ │ │ +peer connections.
│ │ │ │ +
This function is limited to only peer class 0-31, since there are only
│ │ │ │ +32 bits in the IP range mapping. Only the set bits matter; no peer
│ │ │ │ +class will be removed from a peer as a result of this call, peer
│ │ │ │ +classes are only added.
│ │ │ │ +
The peer_class argument cannot be greater than 31. The bitmasks
│ │ │ │ +representing peer classes in the peer_class_filter are 32 bits.
│ │ │ │ +
The get_peer_class_filter() function returns the current filter.
│ │ │ │ +
For more information, see peer classes.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
get_peer_class_type_filter() set_peer_class_type_filter()
│ │ │ │ +
│ │ │ │ +peer_class_type_filter get_peer_class_type_filter () const;
│ │ │ │ +void set_peer_class_type_filter (peer_class_type_filter const& f);
│ │ │ │ +
│ │ │ │ +
Sets and gets the peer class type filter. This is controls automatic
│ │ │ │ +peer class assignments to peers based on what kind of socket it is.
│ │ │ │ +
It does not only support assigning peer classes, it also supports
│ │ │ │ +removing peer classes based on socket type.
│ │ │ │ +
The order of these rules being applied are:
│ │ │ │ +
│ │ │ │ +- peer-class IP filter
│ │ │ │ +- peer-class type filter, removing classes
│ │ │ │ +- peer-class type filter, adding classes
│ │ │ │ +
│ │ │ │ +
For more information, see peer classes.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
create_peer_class()
│ │ │ │ +
│ │ │ │ +peer_class_t create_peer_class (char const* name);
│ │ │ │ +
│ │ │ │ +
Creates a new peer class (see peer classes) with the given name. The
│ │ │ │ +returned integer is the new peer class identifier. Peer classes may
│ │ │ │ +have the same name, so each invocation of this function creates a new
│ │ │ │ +class and returns a unique identifier.
│ │ │ │ +
Identifiers are assigned from low numbers to higher. So if you plan on
│ │ │ │ +using certain peer classes in a call to set_peer_class_filter(),
│ │ │ │ +make sure to create those early on, to get low identifiers.
│ │ │ │ +
For more information on peer classes, see peer classes.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
delete_peer_class()
│ │ │ │ +
│ │ │ │ +void delete_peer_class (peer_class_t cid);
│ │ │ │ +
│ │ │ │ +
This call dereferences the reference count of the specified peer
│ │ │ │ +class. When creating a peer class it's automatically referenced by 1.
│ │ │ │ +If you want to recycle a peer class, you may call this function. You
│ │ │ │ +may only call this function once per peer class you create.
│ │ │ │ +Calling it more than once for the same class will lead to memory
│ │ │ │ +corruption.
│ │ │ │ +
Since peer classes are reference counted, this function will not
│ │ │ │ +remove the peer class if it's still assigned to torrents or peers. It
│ │ │ │ +will however remove it once the last peer and torrent drops their
│ │ │ │ +references to it.
│ │ │ │ +
There is no need to call this function for custom peer classes. All
│ │ │ │ +peer classes will be properly destructed when the session object
│ │ │ │ +destructs.
│ │ │ │ +
For more information on peer classes, see peer classes.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
get_peer_class() set_peer_class()
│ │ │ │ +
│ │ │ │ +peer_class_info get_peer_class (peer_class_t cid) const;
│ │ │ │ +void set_peer_class (peer_class_t cid, peer_class_info const& pci);
│ │ │ │ +
│ │ │ │ +
These functions queries information from a peer class and updates the
│ │ │ │ +configuration of a peer class, respectively.
│ │ │ │ +
cid must refer to an existing peer class. If it does not, the
│ │ │ │ +return value of get_peer_class() is undefined.
│ │ │ │ +
set_peer_class() sets all the information in the
│ │ │ │ +peer_class_info object in the specified peer class. There is no
│ │ │ │ +option to only update a single property.
│ │ │ │ +
A peer or torrent belonging to more than one class, the highest
│ │ │ │ +priority among any of its classes is the one that is taken into
│ │ │ │ +account.
│ │ │ │ +
For more information, see peer classes.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
remove_torrent()
│ │ │ │ +
│ │ │ │ +void remove_torrent (const torrent_handle&, remove_flags_t = {});
│ │ │ │ +
│ │ │ │ +
remove_torrent() will close all peer connections associated with
│ │ │ │ +the torrent and tell the tracker that we've stopped participating in
│ │ │ │ +the swarm. This operation cannot fail. When it completes, you will
│ │ │ │ +receive a torrent_removed_alert.
│ │ │ │ +
remove_torrent() is non-blocking, but will remove the torrent from the
│ │ │ │ +session synchronously. Calling session_handle::add_torrent() immediately
│ │ │ │ +afterward with the same torrent will succeed. Note that this creates a
│ │ │ │ +new handle which is not equal to the removed one.
│ │ │ │ +
The optional second argument options can be used to delete all the
│ │ │ │ +files downloaded by this torrent. To do so, pass in the value
│ │ │ │ +session_handle::delete_files. Once the torrent is deleted, a
│ │ │ │ +torrent_deleted_alert is posted.
│ │ │ │ +
The torrent_handle remains valid for some time after remove_torrent() is
│ │ │ │ +called. It will become invalid only after all libtorrent tasks (such as
│ │ │ │ +I/O tasks) release their references to the torrent. Until this happens,
│ │ │ │ +torrent_handle::is_valid() will return true, and other calls such
│ │ │ │ +as torrent_handle::status() will succeed. Because of this, and because
│ │ │ │ +remove_torrent() is non-blocking, the following sequence usually
│ │ │ │ +succeeds (does not throw system_error):
│ │ │ │ +.. code:: c++
│ │ │ │ +
│ │ │ │ +session.remove_handle(handle);
│ │ │ │ +handle.save_resume_data();
│ │ │ │ +
Note that when a queued or downloading torrent is removed, its position
│ │ │ │ +in the download queue is vacated and every subsequent torrent in the
│ │ │ │ +queue has their queue positions updated. This can potentially cause a
│ │ │ │ +large state_update to be posted. When removing all torrents, it is
│ │ │ │ +advised to remove them from the back of the queue, to minimize the
│ │ │ │ +shifting.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
get_settings() apply_settings()
│ │ │ │ +
│ │ │ │ +void apply_settings (settings_pack&&);
│ │ │ │ +void apply_settings (settings_pack const&);
│ │ │ │ +settings_pack get_settings () const;
│ │ │ │ +
│ │ │ │ +
Applies the settings specified by the settings_pack s. This is an
│ │ │ │ +asynchronous operation that will return immediately and actually apply
│ │ │ │ +the settings to the main thread of libtorrent some time later.
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
wait_for_alert() pop_alerts() set_alert_notify()
│ │ │ │ +
│ │ │ │ +void pop_alerts (std::vector<alert*>* alerts);
│ │ │ │ +alert* wait_for_alert (time_duration max_wait);
│ │ │ │ +void set_alert_notify (std::function<void()> const& fun);
│ │ │ │ +
│ │ │ │ +
Alerts is the main mechanism for libtorrent to report errors and
│ │ │ │ +events. pop_alerts fills in the vector passed to it with pointers
│ │ │ │ +to new alerts. The session still owns these alerts and they will stay
│ │ │ │ +valid until the next time pop_alerts is called. You may not delete
│ │ │ │ +the alert objects.
│ │ │ │ +
It is safe to call pop_alerts from multiple different threads, as
│ │ │ │ +long as the alerts themselves are not accessed once another thread
│ │ │ │ +calls pop_alerts. Doing this requires manual synchronization
│ │ │ │ +between the popping threads.
│ │ │ │ +
wait_for_alert will block the current thread for max_wait time
│ │ │ │ +duration, or until another alert is posted. If an alert is available
│ │ │ │ +at the time of the call, it returns immediately. The returned alert
│ │ │ │ +pointer is the head of the alert queue. wait_for_alert does not
│ │ │ │ +pop alerts from the queue, it merely peeks at it. The returned alert
│ │ │ │ +will stay valid until pop_alerts is called twice. The first time
│ │ │ │ +will pop it and the second will free it.
│ │ │ │ +
If there is no alert in the queue and no alert arrives within the
│ │ │ │ +specified timeout, wait_for_alert returns nullptr.
│ │ │ │ +
In the python binding, wait_for_alert takes the number of
│ │ │ │ +milliseconds to wait as an integer.
│ │ │ │ +
The alert queue in the session will not grow indefinitely. Make sure
│ │ │ │ +to pop periodically to not miss notifications. To control the max
│ │ │ │ +number of alerts that's queued by the session, see
│ │ │ │ +settings_pack::alert_queue_size.
│ │ │ │ +
Some alerts are considered so important that they are posted even when
│ │ │ │ +the alert queue is full. Some alerts are considered mandatory and cannot
│ │ │ │ +be disabled by the alert_mask. For instance,
│ │ │ │ +save_resume_data_alert and save_resume_data_failed_alert are always
│ │ │ │ +posted, regardless of the alert mask.
│ │ │ │ +
To control which alerts are posted, set the alert_mask
│ │ │ │ +(settings_pack::alert_mask).
│ │ │ │ +
If the alert queue fills up to the point where alerts are dropped, this
│ │ │ │ +will be indicated by a alerts_dropped_alert, which contains a bitmask
│ │ │ │ +of which types of alerts were dropped. Generally it is a good idea to
│ │ │ │ +make sure the alert queue is large enough, the alert_mask doesn't have
│ │ │ │ +unnecessary categories enabled and to call pop_alert() frequently, to
│ │ │ │ +avoid alerts being dropped.
│ │ │ │ +
the set_alert_notify function lets the client set a function object
│ │ │ │ +to be invoked every time the alert queue goes from having 0 alerts to
│ │ │ │ +1 alert. This function is called from within libtorrent, it may be the
│ │ │ │ +main thread, or it may be from within a user call. The intention of
│ │ │ │ +of the function is that the client wakes up its main thread, to poll
│ │ │ │ +for more alerts using pop_alerts(). If the notify function fails
│ │ │ │ +to do so, it won't be called again, until pop_alerts is called for
│ │ │ │ +some other reason. For instance, it could signal an eventfd, post a
│ │ │ │ +message to an HWND or some other main message pump. The actual
│ │ │ │ +retrieval of alerts should not be done in the callback. In fact, the
│ │ │ │ +callback should not block. It should not perform any expensive work.
│ │ │ │ +It really should just notify the main application thread.
│ │ │ │ +
The type of an alert is returned by the polymorphic function
│ │ │ │ +alert::type() but can also be queries from a concrete type via
│ │ │ │ +T::alert_type, as a static constant.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
delete_port_mapping() add_port_mapping()
│ │ │ │ +
│ │ │ │ +void delete_port_mapping (port_mapping_t handle);
│ │ │ │ +std::vector<port_mapping_t> add_port_mapping (portmap_protocol t, int external_port, int local_port);
│ │ │ │ +
│ │ │ │ +
add_port_mapping adds one or more port forwards on UPnP and/or NAT-PMP,
│ │ │ │ +whichever is enabled. A mapping is created for each listen socket
│ │ │ │ +in the session. The return values are all handles referring to the
│ │ │ │ +port mappings that were just created. Pass them to delete_port_mapping()
│ │ │ │ +to remove them.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
reopen_network_sockets()
│ │ │ │ +
│ │ │ │ +void reopen_network_sockets (reopen_network_flags_t options = reopen_map_ports);
│ │ │ │ +
│ │ │ │ +
Instructs the session to reopen all listen and outgoing sockets.
│ │ │ │ +
It's useful in the case your platform doesn't support the built in
│ │ │ │ +IP notifier mechanism, or if you have a better more reliable way to
│ │ │ │ +detect changes in the IP routing table.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
native_handle()
│ │ │ │ +
│ │ │ │ +std::shared_ptr<aux::session_impl> native_handle () const;
│ │ │ │ +
│ │ │ │ +
This function is intended only for use by plugins. This type does
│ │ │ │ +not have a stable API and should be relied on as little as possible.
│ │ │ │ +
[report issue]
│ │ │ │ +- save_settings
│ │ │ │ +- saves settings (i.e. the settings_pack)
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- save_dht_state
│ │ │ │ +- saves dht state such as nodes and node-id, possibly accelerating
│ │ │ │ +joining the DHT if provided at next session startup.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- save_extension_state
│ │ │ │ +- load or save state from plugins
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- save_ip_filter
│ │ │ │ +- load or save the IP filter set on the session
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- global_peer_class_id tcp_peer_class_id local_peer_class_id
│ │ │ │ +- built-in peer classes
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- delete_files
│ │ │ │ +- delete the files belonging to the torrent from disk.
│ │ │ │ +including the part-file, if there is one
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- delete_partfile
│ │ │ │ +- delete just the part-file associated with this torrent
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- paused
│ │ │ │ +- when set, the session will start paused. Call
│ │ │ │ +session_handle::resume() to start
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- udp tcp
│ │ │ │ +- protocols used by add_port_mapping()
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- reopen_map_ports
│ │ │ │ +- This option indicates if the ports are mapped using natpmp
│ │ │ │ +and upnp. If mapping was already made, they are deleted and added
│ │ │ │ +again. This only works if natpmp and/or upnp are configured to be
│ │ │ │ +enable.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
session_params
│ │ │ │ +
Declared in "libtorrent/session_params.hpp"
│ │ │ │ +
The session_params is a parameters pack for configuring the session
│ │ │ │ +before it's started.
│ │ │ │ +
│ │ │ │ +struct session_params
│ │ │ │ +{
│ │ │ │ + session_params (settings_pack const& sp);
│ │ │ │ + session_params ();
│ │ │ │ + session_params (settings_pack&& sp);
│ │ │ │ + session_params (settings_pack&& sp
│ │ │ │ + , std::vector<std::shared_ptr<plugin>> exts);
│ │ │ │ + session_params (settings_pack const& sp
│ │ │ │ + , std::vector<std::shared_ptr<plugin>> exts);
│ │ │ │ +
│ │ │ │ + settings_pack settings;
│ │ │ │ + std::vector<std::shared_ptr<plugin>> extensions;
│ │ │ │ + dht::dht_state dht_state;
│ │ │ │ + dht::dht_storage_constructor_type dht_storage_constructor;
│ │ │ │ + disk_io_constructor_type disk_io_constructor;
│ │ │ │ + std::map<std::string, std::string> ext_state;
│ │ │ │ + libtorrent::ip_filter ip_filter;
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
session_params()
│ │ │ │ +
│ │ │ │ +session_params (settings_pack const& sp);
│ │ │ │ +session_params ();
│ │ │ │ +session_params (settings_pack&& sp);
│ │ │ │ +
│ │ │ │ +
This constructor can be used to start with the default plugins
│ │ │ │ +(ut_metadata, ut_pex and smart_ban). Pass a settings_pack to set the
│ │ │ │ +initial settings when the session starts.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
session_params()
│ │ │ │ +
│ │ │ │ +session_params (settings_pack&& sp
│ │ │ │ + , std::vector<std::shared_ptr<plugin>> exts);
│ │ │ │ +session_params (settings_pack const& sp
│ │ │ │ + , std::vector<std::shared_ptr<plugin>> exts);
│ │ │ │ +
│ │ │ │ +
This constructor helps to configure the set of initial plugins
│ │ │ │ +to be added to the session before it's started.
│ │ │ │ +
[report issue]
│ │ │ │ +- settings
│ │ │ │ +- The settings to configure the session with
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- extensions
│ │ │ │ +- the plugins to add to the session as it is constructed
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- dht_state
│ │ │ │ +- DHT node ID and node addresses to bootstrap the DHT with.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- dht_storage_constructor
│ │ │ │ +- function object to construct the storage object for DHT items.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- disk_io_constructor
│ │ │ │ +- function object to create the disk I/O subsystem. Defaults to
│ │ │ │ +default_disk_io_constructor.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- ext_state
│ │ │ │ +- this container can be used by extensions/plugins to store settings. It's
│ │ │ │ +primarily here to make it convenient to save and restore state across
│ │ │ │ +sessions, using read_session_params() and write_session_params().
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- ip_filter
│ │ │ │ +- the IP filter to use for the session. This restricts which peers are allowed
│ │ │ │ +to connect. As if passed to set_ip_filter().
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
write_session_params_buf() write_session_params() read_session_params()
│ │ │ │ +
Declared in "libtorrent/session_params.hpp"
│ │ │ │ +
│ │ │ │ +session_params read_session_params (bdecode_node const& e
│ │ │ │ + , save_state_flags_t flags = save_state_flags_t::all());
│ │ │ │ +session_params read_session_params (span<char const> buf
│ │ │ │ + , save_state_flags_t flags = save_state_flags_t::all());
│ │ │ │ +entry write_session_params (session_params const& sp
│ │ │ │ + , save_state_flags_t flags = save_state_flags_t::all());
│ │ │ │ +std::vector<char> write_session_params_buf (session_params const& sp
│ │ │ │ + , save_state_flags_t flags = save_state_flags_t::all());
│ │ │ │ +
│ │ │ │ +
These functions serialize and de-serialize a session_params object to and
│ │ │ │ +from bencoded form. The session_params object is used to initialize a new
│ │ │ │ +session using the state from a previous one (or by programmatically configure
│ │ │ │ +the session up-front).
│ │ │ │ +The flags parameter can be used to only save and load certain aspects of the
│ │ │ │ +session's state.
│ │ │ │ +The _buf suffix indicates the function operates on buffer rather than the
│ │ │ │ +bencoded structure.
│ │ │ │ +The torrents in a session are not part of the session_params state, they have
│ │ │ │ +to be restored separately.
│ │ │ │
libtorrent has a plugin interface for implementing extensions to the protocol.
│ │ │ │ These can be general extensions for transferring metadata or peer exchange
│ │ │ │ extensions, or it could be used to provide a way to customize the protocol
│ │ │ │ to fit a particular (closed) network.
│ │ │ │
In short, the plugin interface makes it possible to:
│ │ │ │
│ │ │ │ - register extension messages (sent in the extension handshake), see
│ │ │ │ @@ -10518,84 +9961,14 @@
│ │ │ │ expected.
│ │ │ │
The static category is required for checking whether or not the category
│ │ │ │ for a specific alert is enabled or not, without instantiating the alert.
│ │ │ │ The category virtual function is the run-time equivalence.
│ │ │ │ The what() virtual function may simply be a string literal of the class
│ │ │ │ name of your alert.
│ │ │ │ For more information, see the alert section.
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -
peer_connection_handle
│ │ │ │ -
Declared in "libtorrent/peer_connection_handle.hpp"
│ │ │ │ -
the peer_connection_handle class provides a handle to the internal peer
│ │ │ │ -connection object, to be used by plugins. This is a low level interface that
│ │ │ │ -may not be stable across libtorrent versions
│ │ │ │ -
│ │ │ │ -struct peer_connection_handle
│ │ │ │ -{
│ │ │ │ - explicit peer_connection_handle (std::weak_ptr<peer_connection> impl);
│ │ │ │ - connection_type type () const;
│ │ │ │ - peer_plugin const* find_plugin (string_view type) const;
│ │ │ │ - void add_extension (std::shared_ptr<peer_plugin>);
│ │ │ │ - bool is_seed () const;
│ │ │ │ - bool upload_only () const;
│ │ │ │ - bool has_piece (piece_index_t i) const;
│ │ │ │ - peer_id const& pid () const;
│ │ │ │ - bool is_interesting () const;
│ │ │ │ - bool is_choked () const;
│ │ │ │ - bool is_peer_interested () const;
│ │ │ │ - bool has_peer_choked () const;
│ │ │ │ - void choke_this_peer ();
│ │ │ │ - void maybe_unchoke_this_peer ();
│ │ │ │ - void get_peer_info (peer_info& p) const;
│ │ │ │ - torrent_handle associated_torrent () const;
│ │ │ │ - tcp::endpoint const& remote () const;
│ │ │ │ - tcp::endpoint local_endpoint () const;
│ │ │ │ - bool is_disconnecting () const;
│ │ │ │ - bool is_connecting () const;
│ │ │ │ - bool is_outgoing () const;
│ │ │ │ - void disconnect (error_code const& ec, operation_t op
│ │ │ │ - , disconnect_severity_t = peer_connection_interface::normal);
│ │ │ │ - bool ignore_unchoke_slots () const;
│ │ │ │ - bool on_local_network () const;
│ │ │ │ - bool failed () const;
│ │ │ │ - void peer_log (peer_log_alert::direction_t direction
│ │ │ │ - , char const* event, char const* fmt = "", ...) const TORRENT_FORMAT(4,5);
│ │ │ │ - bool should_log (peer_log_alert::direction_t direction) const;
│ │ │ │ - bool can_disconnect (error_code const& ec) const;
│ │ │ │ - bool has_metadata () const;
│ │ │ │ - bool in_handshake () const;
│ │ │ │ - void send_buffer (char const* begin, int size);
│ │ │ │ - std::time_t last_seen_complete () const;
│ │ │ │ - time_point time_of_last_unchoke () const;
│ │ │ │ - bool operator!= (peer_connection_handle const& o) const;
│ │ │ │ - bool operator< (peer_connection_handle const& o) const;
│ │ │ │ - bool operator== (peer_connection_handle const& o) const;
│ │ │ │ - std::shared_ptr<peer_connection> native_handle () const;
│ │ │ │ -};
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
bt_peer_connection_handle
│ │ │ │ -
Declared in "libtorrent/peer_connection_handle.hpp"
│ │ │ │ -
The bt_peer_connection_handle provides a handle to the internal bittorrent
│ │ │ │ -peer connection object to plugins. It's low level and may not be a stable API
│ │ │ │ -across libtorrent versions.
│ │ │ │ -
│ │ │ │ -struct bt_peer_connection_handle : peer_connection_handle
│ │ │ │ -{
│ │ │ │ - explicit bt_peer_connection_handle (peer_connection_handle pc);
│ │ │ │ - bool support_extensions () const;
│ │ │ │ - bool packet_finished () const;
│ │ │ │ - bool supports_encryption () const;
│ │ │ │ - void switch_recv_crypto (std::shared_ptr<crypto_plugin> crypto);
│ │ │ │ - void switch_send_crypto (std::shared_ptr<crypto_plugin> crypto);
│ │ │ │ - std::shared_ptr<bt_peer_connection> native_handle () const;
│ │ │ │ -};
│ │ │ │ -
│ │ │ │
[report issue]
│ │ │ │
│ │ │ │
plugin
│ │ │ │
Declared in "libtorrent/extensions.hpp"
│ │ │ │
this is the base class for a session plugin. One primary feature
│ │ │ │ is that it is notified of all torrents that are added to the session,
│ │ │ │ and can add its own torrent_plugins.
│ │ │ │ @@ -10632,15 +10005,15 @@
│ │ │ │
This function is expected to return a bitmask indicating which features
│ │ │ │ this plugin implements. Some callbacks on this object may not be called
│ │ │ │ unless the corresponding feature flag is returned here. Note that
│ │ │ │ callbacks may still be called even if the corresponding feature is not
│ │ │ │ specified in the return value here. See feature_flags_t for possible
│ │ │ │ flags to return.
│ │ │ │
[report issue]
│ │ │ │ -
│ │ │ │ +
│ │ │ │
new_torrent()
│ │ │ │
│ │ │ │ virtual std::shared_ptr<torrent_plugin> new_torrent (torrent_handle const&, client_data_t);
│ │ │ │
│ │ │ │
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 client_data_t is the userdata pointer as
│ │ │ │ @@ -10652,15 +10025,15 @@
│ │ │ │
│ │ │ │
added()
│ │ │ │
│ │ │ │ virtual void added (session_handle const&);
│ │ │ │
│ │ │ │
called when plugin is added to a session
│ │ │ │
[report issue]
│ │ │ │ -
│ │ │ │ +
│ │ │ │
abort()
│ │ │ │
│ │ │ │ virtual void abort ();
│ │ │ │
│ │ │ │
called when the session is aborted
│ │ │ │ the plugin should perform any cleanup necessary to allow the session's
│ │ │ │ destruction (e.g. cancel outstanding async operations)
│ │ │ │ @@ -10755,19 +10128,19 @@
│ │ │ │
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_plugin
│ │ │ │ {
│ │ │ │ virtual std::shared_ptr<peer_plugin> new_connection (peer_connection_handle const&);
│ │ │ │ - virtual void on_piece_pass (piece_index_t);
│ │ │ │ virtual void on_piece_failed (piece_index_t);
│ │ │ │ + virtual void on_piece_pass (piece_index_t);
│ │ │ │ virtual void tick ();
│ │ │ │ - virtual bool on_resume ();
│ │ │ │ virtual bool on_pause ();
│ │ │ │ + virtual bool on_resume ();
│ │ │ │ virtual void on_files_checked ();
│ │ │ │ virtual void on_state (torrent_status::state_t);
│ │ │ │ virtual void on_add_peer (tcp::endpoint const&,
│ │ │ │ peer_source_flags_t, add_peer_flags_t);
│ │ │ │
│ │ │ │ static constexpr add_peer_flags_t first_time = 1_bit;
│ │ │ │ static constexpr add_peer_flags_t filtered = 2_bit;
│ │ │ │ @@ -10791,16 +10164,16 @@
│ │ │ │ to it, use weak_ptr.
│ │ │ │ If this function throws an exception, the connection will be closed.
│ │ │ │
│ │ │ │ [report issue]
│ │ │ │
│ │ │ │
on_piece_pass() on_piece_failed()
│ │ │ │
│ │ │ │ -virtual void on_piece_pass (piece_index_t);
│ │ │ │ virtual void on_piece_failed (piece_index_t);
│ │ │ │ +virtual void on_piece_pass (piece_index_t);
│ │ │ │
│ │ │ │
These hooks are called when a piece passes the hash check or fails the hash
│ │ │ │ check, respectively. The index is the piece index that was downloaded.
│ │ │ │ It is possible to access the list of peers that participated in sending the
│ │ │ │ piece through the torrent and the piece_picker.
│ │ │ │
[report issue]
│ │ │ │
│ │ │ │ @@ -10811,16 +10184,16 @@
│ │ │ │
This hook is called approximately once per second. It is a way of making it
│ │ │ │ easy for plugins to do timed events, for sending messages or whatever.
│ │ │ │
│ │ │ │
[report issue]
│ │ │ │
│ │ │ │
on_resume() on_pause()
│ │ │ │
│ │ │ │ -virtual bool on_resume ();
│ │ │ │ virtual bool on_pause ();
│ │ │ │ +virtual bool on_resume ();
│ │ │ │
│ │ │ │
These hooks are called when the torrent is paused and resumed respectively.
│ │ │ │ The return value indicates if the event was handled. A return value of
│ │ │ │ true indicates that it was handled, and no other plugin after this one
│ │ │ │ will have this hook function called, and the standard handler will also not be
│ │ │ │ invoked. So, returning true effectively overrides the standard behavior of
│ │ │ │ pause or resume.
│ │ │ │ @@ -10885,51 +10258,51 @@
│ │ │ │ {
│ │ │ │ virtual string_view
type () const;
│ │ │ │ virtual void
add_handshake (entry&);
│ │ │ │ virtual void
on_disconnect (error_code const&);
│ │ │ │ virtual void
on_connected ();
│ │ │ │ virtual bool
on_handshake (span<char const>);
│ │ │ │ virtual bool
on_extension_handshake (bdecode_node const&);
│ │ │ │ - virtual bool
on_have_all ();
│ │ │ │ virtual bool
on_dont_have (piece_index_t);
│ │ │ │ - virtual bool
on_have_none ();
│ │ │ │ virtual bool
on_bitfield (bitfield const&
/*bitfield*/);
│ │ │ │ - virtual bool
on_choke ();
│ │ │ │ + virtual bool
on_have_all ();
│ │ │ │ virtual bool
on_unchoke ();
│ │ │ │ - virtual bool
on_request (peer_request const&);
│ │ │ │ - virtual bool
on_interested ();
│ │ │ │ - virtual bool
on_not_interested ();
│ │ │ │ + virtual bool
on_choke ();
│ │ │ │ + virtual bool
on_have_none ();
│ │ │ │ virtual bool
on_have (piece_index_t);
│ │ │ │ + virtual bool
on_interested ();
│ │ │ │ virtual bool
on_allowed_fast (piece_index_t);
│ │ │ │ + virtual bool
on_not_interested ();
│ │ │ │ + virtual bool
on_request (peer_request const&);
│ │ │ │ virtual bool
on_piece (peer_request const&
/*piece*/
│ │ │ │ , span<char const>
/*buf*/);
│ │ │ │ virtual bool
on_reject (peer_request const&);
│ │ │ │ - virtual bool
on_suggest (piece_index_t);
│ │ │ │ virtual bool
on_cancel (peer_request const&);
│ │ │ │ - virtual void
sent_have_all ();
│ │ │ │ + virtual bool
on_suggest (piece_index_t);
│ │ │ │ + virtual void
sent_reject_request (peer_request const&);
│ │ │ │ virtual void
sent_suggest (piece_index_t);
│ │ │ │ - virtual void
sent_allow_fast (piece_index_t);
│ │ │ │ - virtual void
sent_cancel (peer_request const&);
│ │ │ │ + virtual void
sent_have_all ();
│ │ │ │ + virtual void
sent_have_none ();
│ │ │ │ virtual void
sent_request (peer_request const&);
│ │ │ │ + virtual void
sent_cancel (peer_request const&);
│ │ │ │ virtual void
sent_choke ();
│ │ │ │ - virtual void
sent_reject_request (peer_request const&);
│ │ │ │ - virtual void
sent_have_none ();
│ │ │ │ - virtual void
sent_not_interested ();
│ │ │ │ - virtual void
sent_interested ();
│ │ │ │ + virtual void
sent_allow_fast (piece_index_t);
│ │ │ │ virtual void
sent_piece (peer_request const&);
│ │ │ │ virtual void
sent_unchoke ();
│ │ │ │ + virtual void
sent_not_interested ();
│ │ │ │ virtual void
sent_have (piece_index_t);
│ │ │ │ + virtual void
sent_interested ();
│ │ │ │ virtual void
sent_payload (int
/* bytes */);
│ │ │ │ virtual bool
can_disconnect (error_code const&
/*ec*/);
│ │ │ │ virtual bool
on_extended (int
/*length*/, int
/*msg*/,
│ │ │ │ span<char const>
/*body*/);
│ │ │ │ virtual bool
on_unknown_message (int
/*length*/, int
/*msg*/,
│ │ │ │ span<char const>
/*body*/);
│ │ │ │ - virtual void
on_piece_pass (piece_index_t);
│ │ │ │ virtual void
on_piece_failed (piece_index_t);
│ │ │ │ + virtual void
on_piece_pass (piece_index_t);
│ │ │ │ virtual void
tick ();
│ │ │ │ virtual bool
write_request (peer_request const&);
│ │ │ │ };
│ │ │ │
│ │ │ │
[report issue]
│ │ │ │
type()
│ │ │ │
│ │ │ │ @@ -10979,39 +10352,39 @@
│ │ │ │ virtual bool on_extension_handshake (bdecode_node const&);
│ │ │ │
│ │ │ │
called when the extension handshake from the other end is received
│ │ │ │ if this returns false, it means that this extension isn't
│ │ │ │ supported by this peer. It will result in this peer_plugin
│ │ │ │ being removed from the peer_connection and destructed.
│ │ │ │ this is not called for web seeds
│ │ │ │ -
│ │ │ │ -
│ │ │ │
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
│ │ │ │
│ │ │ │ +
│ │ │ │ +
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
on_dont_have() on_bitfield() on_interested() on_have_all() on_allowed_fast() on_unchoke() on_not_interested() on_request() on_choke() on_have() on_have_none()
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
on_interested() on_choke() on_bitfield() on_have_none() on_have_all() on_dont_have() on_have() on_allowed_fast() on_unchoke() on_not_interested() on_request()
│ │ │ │
│ │ │ │ -virtual bool on_have_all ();
│ │ │ │ virtual bool on_dont_have (piece_index_t);
│ │ │ │ -virtual bool on_have_none ();
│ │ │ │ virtual bool on_bitfield (bitfield const& /*bitfield*/);
│ │ │ │ -virtual bool on_choke ();
│ │ │ │ +virtual bool on_have_all ();
│ │ │ │ virtual bool on_unchoke ();
│ │ │ │ -virtual bool on_request (peer_request const&);
│ │ │ │ -virtual bool on_interested ();
│ │ │ │ -virtual bool on_not_interested ();
│ │ │ │ +virtual bool on_choke ();
│ │ │ │ +virtual bool on_have_none ();
│ │ │ │ virtual bool on_have (piece_index_t);
│ │ │ │ +virtual bool on_interested ();
│ │ │ │ virtual bool on_allowed_fast (piece_index_t);
│ │ │ │ +virtual bool on_not_interested ();
│ │ │ │ +virtual bool on_request (peer_request const&);
│ │ │ │
│ │ │ │
returning true from any of the message handlers
│ │ │ │ indicates that the plugin has handled the message.
│ │ │ │ it will break the plugin chain traversing and not let
│ │ │ │ anyone else handle the message, including the default
│ │ │ │ handler.
│ │ │ │
[report issue]
│ │ │ │ @@ -11024,26 +10397,26 @@
│ │ │ │
This function is called when the peer connection is receiving
│ │ │ │ a piece. buf points (non-owning pointer) to the data in an
│ │ │ │ internal immutable disk buffer. The length of the data is specified
│ │ │ │ in the length member of the piece parameter.
│ │ │ │ returns true to indicate that the piece is handled and the
│ │ │ │ rest of the logic should be ignored.
│ │ │ │
│ │ │ │ -
│ │ │ │
│ │ │ │ +
│ │ │ │
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
sent_unchoke() sent_piece() sent_have() sent_not_interested() sent_interested()
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
sent_unchoke() sent_have() sent_piece() sent_not_interested() sent_interested()
│ │ │ │
│ │ │ │ -virtual void sent_not_interested ();
│ │ │ │ -virtual void sent_interested ();
│ │ │ │ virtual void sent_piece (peer_request const&);
│ │ │ │ virtual void sent_unchoke ();
│ │ │ │ +virtual void sent_not_interested ();
│ │ │ │ virtual void sent_have (piece_index_t);
│ │ │ │ +virtual void sent_interested ();
│ │ │ │
│ │ │ │
called after a choke message has been sent to the peer
│ │ │ │
[report issue]
│ │ │ │
│ │ │ │
sent_payload()
│ │ │ │
│ │ │ │ virtual void sent_payload (int /* bytes */);
│ │ │ │ @@ -11084,16 +10457,16 @@
│ │ │ │
│ │ │ │
this is not called for web seeds
│ │ │ │
│ │ │ │
[report issue]
│ │ │ │
│ │ │ │
on_piece_pass() on_piece_failed()
│ │ │ │
│ │ │ │ -virtual void on_piece_pass (piece_index_t);
│ │ │ │ virtual void on_piece_failed (piece_index_t);
│ │ │ │ +virtual void on_piece_pass (piece_index_t);
│ │ │ │
│ │ │ │
called when a piece that this peer participated in either
│ │ │ │ fails or passes the hash_check
│ │ │ │
[report issue]
│ │ │ │
│ │ │ │
tick()
│ │ │ │
│ │ │ │ @@ -11113,16 +10486,16 @@
│ │ │ │
│ │ │ │
│ │ │ │
crypto_plugin
│ │ │ │
Declared in "libtorrent/extensions.hpp"
│ │ │ │
│ │ │ │ struct crypto_plugin
│ │ │ │ {
│ │ │ │ - virtual void set_outgoing_key (span<char const> key) = 0;
│ │ │ │ virtual void set_incoming_key (span<char const> key) = 0;
│ │ │ │ + virtual void set_outgoing_key (span<char const> key) = 0;
│ │ │ │ encrypt (span<span<char>> /*send_vec*/) = 0;
│ │ │ │ virtual std::tuple<int, int, int> decrypt (span<span<char>> /*receive_vec*/) = 0;
│ │ │ │ };
│ │ │ │
│ │ │ │
[report issue]
│ │ │ │
decrypt()
│ │ │ │
│ │ │ │ @@ -11133,42 +10506,112 @@
│ │ │ │ (consume, produce, packet_size)
│ │ │ │ consume is set to the number of bytes which should be trimmed from the
│ │ │ │ head of the buffers, default is 0
│ │ │ │ produce is set to the number of bytes of payload which are now ready to
│ │ │ │ be sent to the upper layer. default is the number of bytes passed in receive_vec
│ │ │ │ packet_size is set to the minimum number of bytes which must be read to
│ │ │ │ advance the next step of decryption. default is 0
│ │ │ │ -[report issue]
│ │ │ │ +
[report issue]
│ │ │ │
│ │ │ │ -
│ │ │ │ -
create_smart_ban_plugin()
│ │ │ │ -
Declared in "libtorrent/extensions/smart_ban.hpp"
│ │ │ │ +
│ │ │ │ +
peer_connection_handle
│ │ │ │ +
Declared in "libtorrent/peer_connection_handle.hpp"
│ │ │ │ +
the peer_connection_handle class provides a handle to the internal peer
│ │ │ │ +connection object, to be used by plugins. This is a low level interface that
│ │ │ │ +may not be stable across libtorrent versions
│ │ │ │
│ │ │ │ -std::shared_ptr<torrent_plugin> create_smart_ban_plugin (torrent_handle const&, client_data_t);
│ │ │ │ +struct peer_connection_handle
│ │ │ │ +{
│ │ │ │ + explicit peer_connection_handle (std::weak_ptr<peer_connection> impl);
│ │ │ │ + connection_type type () const;
│ │ │ │ + void add_extension (std::shared_ptr<peer_plugin>);
│ │ │ │ + peer_plugin const* find_plugin (string_view type) const;
│ │ │ │ + bool is_seed () const;
│ │ │ │ + bool upload_only () const;
│ │ │ │ + bool has_piece (piece_index_t i) const;
│ │ │ │ + peer_id const& pid () const;
│ │ │ │ + bool is_interesting () const;
│ │ │ │ + bool is_choked () const;
│ │ │ │ + bool is_peer_interested () const;
│ │ │ │ + bool has_peer_choked () const;
│ │ │ │ + void maybe_unchoke_this_peer ();
│ │ │ │ + void choke_this_peer ();
│ │ │ │ + void get_peer_info (peer_info& p) const;
│ │ │ │ + torrent_handle associated_torrent () const;
│ │ │ │ + tcp::endpoint const& remote () const;
│ │ │ │ + tcp::endpoint local_endpoint () const;
│ │ │ │ + void disconnect (error_code const& ec, operation_t op
│ │ │ │ + , disconnect_severity_t = peer_connection_interface::normal);
│ │ │ │ + bool is_outgoing () const;
│ │ │ │ + bool is_disconnecting () const;
│ │ │ │ + bool is_connecting () const;
│ │ │ │ + bool on_local_network () const;
│ │ │ │ + bool ignore_unchoke_slots () const;
│ │ │ │ + bool failed () const;
│ │ │ │ + bool should_log (peer_log_alert::direction_t direction) const;
│ │ │ │ + void peer_log (peer_log_alert::direction_t direction
│ │ │ │ + , char const* event, char const* fmt = "", ...) const TORRENT_FORMAT(4,5);
│ │ │ │ + bool can_disconnect (error_code const& ec) const;
│ │ │ │ + bool has_metadata () const;
│ │ │ │ + bool in_handshake () const;
│ │ │ │ + void send_buffer (char const* begin, int size);
│ │ │ │ + std::time_t last_seen_complete () const;
│ │ │ │ + time_point time_of_last_unchoke () const;
│ │ │ │ + bool operator< (peer_connection_handle const& o) const;
│ │ │ │ + bool operator!= (peer_connection_handle const& o) const;
│ │ │ │ + bool operator== (peer_connection_handle const& o) const;
│ │ │ │ + std::shared_ptr<peer_connection> native_handle () const;
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
bt_peer_connection_handle
│ │ │ │ +
Declared in "libtorrent/peer_connection_handle.hpp"
│ │ │ │ +
The bt_peer_connection_handle provides a handle to the internal bittorrent
│ │ │ │ +peer connection object to plugins. It's low level and may not be a stable API
│ │ │ │ +across libtorrent versions.
│ │ │ │ +
│ │ │ │ +struct bt_peer_connection_handle : peer_connection_handle
│ │ │ │ +{
│ │ │ │ + explicit bt_peer_connection_handle (peer_connection_handle pc);
│ │ │ │ + bool support_extensions () const;
│ │ │ │ + bool packet_finished () const;
│ │ │ │ + bool supports_encryption () const;
│ │ │ │ + void switch_recv_crypto (std::shared_ptr<crypto_plugin> crypto);
│ │ │ │ + void switch_send_crypto (std::shared_ptr<crypto_plugin> crypto);
│ │ │ │ + std::shared_ptr<bt_peer_connection> native_handle () const;
│ │ │ │ +};
│ │ │ │
│ │ │ │ -
constructor function for the smart ban extension. The extension keeps
│ │ │ │ -track of the data peers have sent us for failing pieces and once the
│ │ │ │ -piece completes and passes the hash check bans the peers that turned
│ │ │ │ -out to have sent corrupt data.
│ │ │ │ -This function can either be passed in the add_torrent_params::extensions
│ │ │ │ -field, or via torrent_handle::add_extension().
│ │ │ │
[report issue]
│ │ │ │
│ │ │ │
create_ut_pex_plugin()
│ │ │ │
Declared in "libtorrent/extensions/ut_pex.hpp"
│ │ │ │
│ │ │ │ std::shared_ptr<torrent_plugin> create_ut_pex_plugin (torrent_handle const&, client_data_t);
│ │ │ │
│ │ │ │
constructor function for the ut_pex extension. The ut_pex
│ │ │ │ extension allows peers to gossip about their connections, allowing
│ │ │ │ the swarm stay well connected and peers aware of more peers in the
│ │ │ │ swarm. This extension is enabled by default unless explicitly disabled in
│ │ │ │ the session constructor.
│ │ │ │
This can either be passed in the add_torrent_params::extensions field, or
│ │ │ │ via torrent_handle::add_extension().
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
create_smart_ban_plugin()
│ │ │ │ +
Declared in "libtorrent/extensions/smart_ban.hpp"
│ │ │ │ +
│ │ │ │ +std::shared_ptr<torrent_plugin> create_smart_ban_plugin (torrent_handle const&, client_data_t);
│ │ │ │ +
│ │ │ │ +
constructor function for the smart ban extension. The extension keeps
│ │ │ │ +track of the data peers have sent us for failing pieces and once the
│ │ │ │ +piece completes and passes the hash check bans the peers that turned
│ │ │ │ +out to have sent corrupt data.
│ │ │ │ +This function can either be passed in the add_torrent_params::extensions
│ │ │ │ +field, or via torrent_handle::add_extension().
│ │ │ │
[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().
│ │ │ │ +
This section describes the functions and classes that are used
│ │ │ │ +to create torrent files. It is a layered API with low level classes
│ │ │ │ +and higher level convenience functions. A torrent is created in 4
│ │ │ │ +steps:
│ │ │ │ +
│ │ │ │ +- first the files that will be part of the torrent are determined.
│ │ │ │ +- the torrent properties are set, such as tracker url, web seeds,
│ │ │ │ +DHT nodes etc.
│ │ │ │ +- Read through all the files in the torrent, SHA-1 all the data
│ │ │ │ +and set the piece hashes.
│ │ │ │ +- The torrent is bencoded into a file or buffer.
│ │ │ │ +
│ │ │ │ +
If there are a lot of files and or deep directory hierarchies to
│ │ │ │ +traverse, step one can be time consuming.
│ │ │ │ +
Typically step 3 is by far the most time consuming step, since it
│ │ │ │ +requires to read all the bytes from all the files in the torrent.
│ │ │ │ +
All of these classes and functions are declared by including
│ │ │ │ +libtorrent/create_torrent.hpp.
│ │ │ │ +
example:
│ │ │ │ +
│ │ │ │ +file_storage fs;
│ │ │ │ +
│ │ │ │ +add_files(fs, "./my_torrent");
│ │ │ │ +
│ │ │ │ +create_torrent t(fs);
│ │ │ │ +t.add_tracker("http://my.tracker.com/announce");
│ │ │ │ +t.set_creator("libtorrent example");
│ │ │ │ +
│ │ │ │ +set_piece_hashes(t, ".");
│ │ │ │ +
│ │ │ │ +ofstream out("my_torrent.torrent", std::ios_base::binary);
│ │ │ │ +std::vector<char> buf = t.generate_buf();
│ │ │ │ +out.write(buf.data(), buf.size());
│ │ │ │ +
│ │ │ │ +bencode(std::ostream_iterator<char>(out), t.generate());
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
create_torrent
│ │ │ │ +
Declared in "libtorrent/create_torrent.hpp"
│ │ │ │ +
This class holds state for creating a torrent. After having added
│ │ │ │ +all information to it, call create_torrent::generate() to generate
│ │ │ │ +the torrent. The entry that's returned can then be bencoded into a
│ │ │ │ +.torrent file using bencode().
│ │ │ │
│ │ │ │ -struct torrent_status
│ │ │ │ +struct create_torrent
│ │ │ │ {
│ │ │ │ - bool operator== (torrent_status const& st) const;
│ │ │ │ + explicit create_torrent (torrent_info const& ti);
│ │ │ │ + explicit create_torrent (file_storage& fs, int piece_size = 0
│ │ │ │ + , create_flags_t flags = {});
│ │ │ │ + entry generate () const;
│ │ │ │ + std::vector<char> generate_buf () const;
│ │ │ │ + file_storage const& files () const;
│ │ │ │ + void set_comment (char const* str);
│ │ │ │ + void set_creator (char const* str);
│ │ │ │ + void set_creation_date (std::time_t timestamp);
│ │ │ │ + void set_hash (piece_index_t index, sha1_hash const& h);
│ │ │ │ + void set_hash2 (file_index_t file, piece_index_t::diff_type piece, sha256_hash const& h);
│ │ │ │ + void add_url_seed (string_view url);
│ │ │ │ + void add_http_seed (string_view url);
│ │ │ │ + void add_node (std::pair<std::string, int> node);
│ │ │ │ + void add_tracker (string_view url, int tier = 0);
│ │ │ │ + void set_root_cert (string_view cert);
│ │ │ │ + bool priv () const;
│ │ │ │ + void set_priv (bool p);
│ │ │ │ + bool is_v1_only () const;
│ │ │ │ + bool is_v2_only () const;
│ │ │ │ + int num_pieces () const;
│ │ │ │ + piece_index_t end_piece () const;
│ │ │ │ + index_range<piece_index_t> piece_range () const noexcept;
│ │ │ │ + file_index_t end_file () const;
│ │ │ │ + index_range<file_index_t> file_range () const noexcept;
│ │ │ │ + index_range<piece_index_t::diff_type> file_piece_range (file_index_t f);
│ │ │ │ + std::int64_t total_size () const;
│ │ │ │ + int piece_size (piece_index_t i) const;
│ │ │ │ + int piece_length () const;
│ │ │ │ + void add_similar_torrent (sha1_hash ih);
│ │ │ │ + void add_collection (string_view c);
│ │ │ │
│ │ │ │ - enum state_t
│ │ │ │ + static constexpr create_flags_t modification_time = 2_bit;
│ │ │ │ + static constexpr create_flags_t symlinks = 3_bit;
│ │ │ │ + static constexpr create_flags_t v2_only = 5_bit;
│ │ │ │ + static constexpr create_flags_t v1_only = 6_bit;
│ │ │ │ + static constexpr create_flags_t canonical_files = 7_bit;
│ │ │ │ + static constexpr create_flags_t no_attributes = 8_bit;
│ │ │ │ + static constexpr create_flags_t canonical_files_no_tail_padding = 9_bit;
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
create_torrent()
│ │ │ │ +
│ │ │ │ +explicit create_torrent (torrent_info const& ti);
│ │ │ │ +explicit create_torrent (file_storage& fs, int piece_size = 0
│ │ │ │ + , create_flags_t flags = {});
│ │ │ │ +
│ │ │ │ +
The piece_size is the size of each piece in bytes. It must be a
│ │ │ │ +power of 2 and a minimum of 16 kiB. If a piece size of 0 is
│ │ │ │ +specified, a piece_size will be set automatically.
│ │ │ │ +Piece sizes greater than 128 MiB are considered unreasonable and will
│ │ │ │ +be rejected (with an lt::system_error exception).
│ │ │ │ +
The flags arguments specifies options for the torrent creation. It can
│ │ │ │ +be any combination of the flags defined by create_flags_t.
│ │ │ │ +
The file_storage (fs) parameter defines the files, sizes and
│ │ │ │ +their properties for the torrent to be created. Set this up first,
│ │ │ │ +before passing it to the create_torrent constructor.
│ │ │ │ +
The overload that takes a torrent_info object will make a verbatim
│ │ │ │ +copy of its info dictionary (to preserve the info-hash). The copy of
│ │ │ │ +the info dictionary will be used by create_torrent::generate(). This means
│ │ │ │ +that none of the member functions of create_torrent that affects
│ │ │ │ +the content of the info dictionary (such as set_hash()), will
│ │ │ │ +have any affect. Instead of using this overload, consider using
│ │ │ │ +write_torrent_file() instead.
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
generate() generate_buf()
│ │ │ │ +
│ │ │ │ +entry generate () const;
│ │ │ │ +std::vector<char> generate_buf () const;
│ │ │ │ +
│ │ │ │ +
This function will generate the .torrent file as a bencode tree, or a
│ │ │ │ +bencoded into a buffer.
│ │ │ │ +In order to encode the entry into a flat file, use the bencode() function.
│ │ │ │ +
The function returning an entry may be useful to add custom entries
│ │ │ │ +to the torrent file before bencoding it and saving it to disk.
│ │ │ │ +
Whether the resulting torrent object is v1, v2 or hybrid depends on
│ │ │ │ +whether any of the v1_only or v2_only flags were set on the
│ │ │ │ +constructor. If neither were set, the resulting torrent depends on
│ │ │ │ +which hashes were set. If both v1 and v2 hashes were set, a hybrid
│ │ │ │ +torrent is created.
│ │ │ │ +
Any failure will cause this function to throw system_error, with an
│ │ │ │ +appropriate error message. These are the reasons this call may throw:
│ │ │ │ +
│ │ │ │ +- the file storage has 0 files
│ │ │ │ +- the total size of the file storage is 0 bytes (i.e. it only has
│ │ │ │ +empty files)
│ │ │ │ +- not all v1 hashes (set_hash()) and not all v2 hashes (set_hash2())
│ │ │ │ +were set
│ │ │ │ +- for v2 torrents, you may not have a directory with the same name as
│ │ │ │ +a file. If that's encountered in the file storage, generate()
│ │ │ │ +fails.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
files()
│ │ │ │ +
│ │ │ │ +file_storage const& files () const;
│ │ │ │ +
│ │ │ │ +
returns an immutable reference to the file_storage used to create
│ │ │ │ +the torrent from.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
set_creator()
│ │ │ │ +
│ │ │ │ +void set_creator (char const* str);
│ │ │ │ +
│ │ │ │ +
Sets the creator of the torrent. The string str should be utf-8 encoded.
│ │ │ │ +This is optional.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
set_creation_date()
│ │ │ │ +
│ │ │ │ +void set_creation_date (std::time_t timestamp);
│ │ │ │ +
│ │ │ │ +
sets the "creation time" field. Defaults to the system clock at the
│ │ │ │ +time of construction of the create_torrent object. The timestamp is
│ │ │ │ +specified in seconds, posix time. If the creation date is set to 0,
│ │ │ │ +the "creation date" field will be omitted from the generated torrent.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
set_hash()
│ │ │ │ +
│ │ │ │ +void set_hash (piece_index_t index, sha1_hash const& h);
│ │ │ │ +
│ │ │ │ +
This sets the SHA-1 hash for the specified piece (index). You are required
│ │ │ │ +to set the hash for every piece in the torrent before generating it. If you have
│ │ │ │ +the files on disk, you can use the high level convenience function to do this.
│ │ │ │ +See set_piece_hashes().
│ │ │ │ +A SHA-1 hash of all zeros is internally used to indicate a hash that
│ │ │ │ +has not been set. Setting such hash will not be considered set when
│ │ │ │ +calling generate().
│ │ │ │ +This function will throw std::system_error if it is called on an
│ │ │ │ +object constructed with the v2_only flag.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
set_hash2()
│ │ │ │ +
│ │ │ │ +void set_hash2 (file_index_t file, piece_index_t::diff_type piece, sha256_hash const& h);
│ │ │ │ +
│ │ │ │ +
sets the bittorrent v2 hash for file file of the piece piece.
│ │ │ │ +piece is relative to the first piece of the file, starting at 0. The
│ │ │ │ +first piece in the file can be computed with
│ │ │ │ +file_storage::file_index_at_piece().
│ │ │ │ +The hash, h, is the root of the merkle tree formed by the piece's
│ │ │ │ +16 kiB blocks. Note that piece sizes must be powers-of-2, so all
│ │ │ │ +per-piece merkle trees are complete.
│ │ │ │ +A SHA-256 hash of all zeros is internally used to indicate a hash
│ │ │ │ +that has not been set. Setting such hash will not be considered set
│ │ │ │ +when calling generate().
│ │ │ │ +This function will throw std::system_error if it is called on an
│ │ │ │ +object constructed with the v1_only flag.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
add_http_seed() add_url_seed()
│ │ │ │ +
│ │ │ │ +void add_url_seed (string_view url);
│ │ │ │ +void add_http_seed (string_view url);
│ │ │ │ +
│ │ │ │ +
This adds a url seed to the torrent. You can have any number of url seeds. For a
│ │ │ │ +single file torrent, this should be an HTTP url, pointing to a file with identical
│ │ │ │ +content as the file of the torrent. For a multi-file torrent, it should point to
│ │ │ │ +a directory containing a directory with the same name as this torrent, and all the
│ │ │ │ +files of the torrent in it.
│ │ │ │ +
The second function, add_http_seed() adds an HTTP seed instead.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
add_node()
│ │ │ │ +
│ │ │ │ +void add_node (std::pair<std::string, int> node);
│ │ │ │ +
│ │ │ │ +
This adds a DHT node to the torrent. This especially useful if you're creating a
│ │ │ │ +tracker less torrent. It can be used by clients to bootstrap their DHT node from.
│ │ │ │ +The node is a hostname and a port number where there is a DHT node running.
│ │ │ │ +You can have any number of DHT nodes in a torrent.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
add_tracker()
│ │ │ │ +
│ │ │ │ +void add_tracker (string_view url, int tier = 0);
│ │ │ │ +
│ │ │ │ +
Adds a tracker to the torrent. This is not strictly required, but most torrents
│ │ │ │ +use a tracker as their main source of peers. The url should be an http:// or udp://
│ │ │ │ +url to a machine running a bittorrent tracker that accepts announces for this torrent's
│ │ │ │ +info-hash. The tier is the fallback priority of the tracker. All trackers with tier 0 are
│ │ │ │ +tried first (in any order). If all fail, trackers with tier 1 are tried. If all of those
│ │ │ │ +fail, trackers with tier 2 are tried, and so on.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
set_root_cert()
│ │ │ │ +
│ │ │ │ +void set_root_cert (string_view cert);
│ │ │ │ +
│ │ │ │ +
This function sets an X.509 certificate in PEM format to the torrent. This makes the
│ │ │ │ +torrent an SSL torrent. An SSL torrent requires that each peer has a valid certificate
│ │ │ │ +signed by this root certificate. For SSL torrents, all peers are connecting over SSL
│ │ │ │ +connections. For more information, see the section on ssl torrents.
│ │ │ │ +
The string is not the path to the cert, it's the actual content of the
│ │ │ │ +certificate.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
priv() set_priv()
│ │ │ │ +
│ │ │ │ +bool priv () const;
│ │ │ │ +void set_priv (bool p);
│ │ │ │ +
│ │ │ │ +
Sets and queries the private flag of the torrent.
│ │ │ │ +Torrents with the private flag set ask the client to not use any other
│ │ │ │ +sources than the tracker for peers, and to not use DHT to advertise itself publicly,
│ │ │ │ +only the tracker.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
num_pieces()
│ │ │ │ +
│ │ │ │ +int num_pieces () const;
│ │ │ │ +
│ │ │ │ +
returns the number of pieces in the associated file_storage object.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
piece_range()
│ │ │ │ +
│ │ │ │ +index_range<piece_index_t> piece_range () const noexcept;
│ │ │ │ +
│ │ │ │ +
all piece indices in the torrent to be created
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
file_range()
│ │ │ │ +
│ │ │ │ +index_range<file_index_t> file_range () const noexcept;
│ │ │ │ +
│ │ │ │ +
all file indices in the torrent to be created
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
file_piece_range()
│ │ │ │ +
│ │ │ │ +index_range<piece_index_t::diff_type> file_piece_range (file_index_t f);
│ │ │ │ +
│ │ │ │ +
for v2 and hybrid torrents only, the pieces in the
│ │ │ │ +specified file, specified as delta from the first piece in the file.
│ │ │ │ +i.e. the first index is 0.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
total_size()
│ │ │ │ +
│ │ │ │ +std::int64_t total_size () const;
│ │ │ │ +
│ │ │ │ +
the total number of bytes of all files and pad files
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
piece_size() piece_length()
│ │ │ │ +
│ │ │ │ +int piece_size (piece_index_t i) const;
│ │ │ │ +int piece_length () const;
│ │ │ │ +
│ │ │ │ +
piece_length() returns the piece size of all pieces but the
│ │ │ │ +last one. piece_size() returns the size of the specified piece.
│ │ │ │ +these functions are just forwarding to the associated file_storage.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
add_similar_torrent() add_collection()
│ │ │ │ +
│ │ │ │ +void add_similar_torrent (sha1_hash ih);
│ │ │ │ +void add_collection (string_view c);
│ │ │ │ +
│ │ │ │ +
Add similar torrents (by info-hash) or collections of similar torrents.
│ │ │ │ +Similar torrents are expected to share some files with this torrent.
│ │ │ │ +Torrents sharing a collection name with this torrent are also expected
│ │ │ │ +to share files with this torrent. A torrent may have more than one
│ │ │ │ +collection and more than one similar torrents. For more information,
│ │ │ │ +see BEP 38.
│ │ │ │ +
[report issue]
│ │ │ │ +- modification_time
│ │ │ │ +- This will include the file modification time as part of the torrent.
│ │ │ │ +This is not enabled by default, as it might cause problems when you
│ │ │ │ +create a torrent from separate files with the same content, hoping to
│ │ │ │ +yield the same info-hash. If the files have different modification times,
│ │ │ │ +with this option enabled, you would get different info-hashes for the
│ │ │ │ +files.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- symlinks
│ │ │ │ +- If this flag is set, files that are symlinks get a symlink attribute
│ │ │ │ +set on them and their data will not be included in the torrent. This
│ │ │ │ +is useful if you need to reconstruct a file hierarchy which contains
│ │ │ │ +symlinks.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- v2_only
│ │ │ │ +- Do not generate v1 metadata. The resulting torrent will only be usable by
│ │ │ │ +clients which support v2. This requires setting all v2 hashes, with
│ │ │ │ +set_hash2() before calling generate(). Setting v1 hashes (with
│ │ │ │ +set_hash()) is an error with this flag set.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- v1_only
│ │ │ │ +- do not generate v2 metadata or enforce v2 alignment and padding rules
│ │ │ │ +this is mainly for tests, not recommended for production use. This
│ │ │ │ +requires setting all v1 hashes, with set_hash(), before calling
│ │ │ │ +generate(). Setting v2 hashes (with set_hash2()) is an error with
│ │ │ │ +this flag set.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- canonical_files
│ │ │ │ +- This flag only affects v1-only torrents, and is only relevant
│ │ │ │ +together with the v1_only_flag. This flag will force the
│ │ │ │ +same file order and padding as a v2 (or hybrid) torrent would have.
│ │ │ │ +It has the effect of ordering files and inserting pad files to align
│ │ │ │ +them with piece boundaries.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- no_attributes
│ │ │ │ +- passing this flag to add_files() will ignore file attributes (such as
│ │ │ │ +executable or hidden) when adding the files to the file storage.
│ │ │ │ +Since not all filesystems and operating systems support all file
│ │ │ │ +attributes the resulting torrent may differ depending on where it's
│ │ │ │ +created. If it's important for torrents to be created consistently
│ │ │ │ +across systems, this flag should be set.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- canonical_files_no_tail_padding
│ │ │ │ +- this flag enforces the file layout to be canonical according to the
│ │ │ │ +bittorrent v2 specification (just like the canonical_files flag)
│ │ │ │ +with the one exception that tail padding is not added to the last
│ │ │ │ +file.
│ │ │ │ +This behavior deviates from the specification but was the way
│ │ │ │ +libtorrent created torrents in version up to and including 2.0.7.
│ │ │ │ +This flag is here for backwards compatibility.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
add_files()
│ │ │ │ +
Declared in "libtorrent/create_torrent.hpp"
│ │ │ │ +
│ │ │ │ +void add_files (file_storage& fs, std::string const& file
│ │ │ │ + , std::function<bool(std::string)> p, create_flags_t flags = {});
│ │ │ │ +void add_files (file_storage& fs, std::string const& file
│ │ │ │ + , create_flags_t flags = {});
│ │ │ │ +
│ │ │ │ +
Adds the file specified by path to the file_storage object. In case path
│ │ │ │ +refers to a directory, files will be added recursively from the directory.
│ │ │ │ +
If specified, the predicate p is called once for every file and directory that
│ │ │ │ +is encountered. Files for which p returns true are added, and directories for
│ │ │ │ +which p returns true are traversed. p must have the following signature:
│ │ │ │ +
│ │ │ │ +bool Pred(std::string const& p);
│ │ │ │ +
│ │ │ │ +
The path that is passed in to the predicate is the full path of the file or
│ │ │ │ +directory. If no predicate is specified, all files are added, and all directories
│ │ │ │ +are traversed.
│ │ │ │ +
The ".." directory is never traversed.
│ │ │ │ +
The flags argument should be the same as the flags passed to the create_torrent
│ │ │ │ +constructor.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
set_piece_hashes()
│ │ │ │ +
Declared in "libtorrent/create_torrent.hpp"
│ │ │ │ +
│ │ │ │ +void set_piece_hashes (create_torrent& t, std::string const& p
│ │ │ │ + , std::function<void(piece_index_t)> const& f, error_code& ec);
│ │ │ │ +inline void set_piece_hashes (create_torrent& t, std::string const& p, error_code& ec);
│ │ │ │ +void set_piece_hashes (create_torrent& t, std::string const& p
│ │ │ │ + , settings_interface const& settings, disk_io_constructor_type disk_io
│ │ │ │ + , std::function<void(piece_index_t)> const& f, error_code& ec);
│ │ │ │ +void set_piece_hashes (create_torrent& t, std::string const& p
│ │ │ │ + , settings_interface const& settings
│ │ │ │ + , std::function<void(piece_index_t)> const& f, error_code& ec);
│ │ │ │ +inline void set_piece_hashes (create_torrent& t, std::string const& p
│ │ │ │ + , std::function<void(piece_index_t)> const& f);
│ │ │ │ +inline void set_piece_hashes (create_torrent& t, std::string const& p);
│ │ │ │ +inline void set_piece_hashes (create_torrent& t, std::string const& p
│ │ │ │ + , settings_interface const& settings
│ │ │ │ + , std::function<void(piece_index_t)> const& f);
│ │ │ │ +
│ │ │ │ +
This function will assume that the files added to the torrent file exists at path
│ │ │ │ +p, read those files and hash the content and set the hashes in the create_torrent
│ │ │ │ +object. The optional function f is called in between every hash that is set. f
│ │ │ │ +must have the following signature:
│ │ │ │ +
│ │ │ │ +void Fun(piece_index_t);
│ │ │ │ +
│ │ │ │ +
The overloads taking a settings_pack may be used to configure the
│ │ │ │ +underlying disk access. Such as settings_pack::aio_threads.
│ │ │ │ +
The overloads that don't take an error_code& may throw an exception in case of a
│ │ │ │ +file error, the other overloads sets the error code to reflect the error, if any.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
ip_filter
│ │ │ │ +
Declared in "libtorrent/ip_filter.hpp"
│ │ │ │ +
The ip_filter class is a set of rules that uniquely categorizes all
│ │ │ │ +ip addresses as allowed or disallowed. The default constructor creates
│ │ │ │ +a single rule that allows all addresses (0.0.0.0 - 255.255.255.255 for
│ │ │ │ +the IPv4 range, and the equivalent range covering all addresses for the
│ │ │ │ +IPv6 range).
│ │ │ │ +
A default constructed ip_filter does not filter any address.
│ │ │ │ +
│ │ │ │ +struct ip_filter
│ │ │ │ +{
│ │ │ │ + ip_filter (ip_filter&&);
│ │ │ │ + ~ip_filter ();
│ │ │ │ + ip_filter& operator= (ip_filter&&);
│ │ │ │ + ip_filter& operator= (ip_filter const&);
│ │ │ │ + ip_filter ();
│ │ │ │ + ip_filter (ip_filter const&);
│ │ │ │ + bool empty () const;
│ │ │ │ + void add_rule (address const& first, address const& last, std::uint32_t flags);
│ │ │ │ + std::uint32_t access (address const& addr) const;
│ │ │ │ + filter_tuple_t export_filter () const;
│ │ │ │ +
│ │ │ │ + enum access_flags
│ │ │ │ {
│ │ │ │ - checking_files,
│ │ │ │ - downloading_metadata,
│ │ │ │ - downloading,
│ │ │ │ - finished,
│ │ │ │ - seeding,
│ │ │ │ - unused_enum_for_backwards_compatibility_allocating,
│ │ │ │ - checking_resume_data,
│ │ │ │ + blocked,
│ │ │ │ };
│ │ │ │ -
│ │ │ │ - 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==()
│ │ │ │ +
[report issue]
│ │ │ │ +
empty()
│ │ │ │
│ │ │ │ -bool operator== (torrent_status const& st) const;
│ │ │ │ +bool empty () const;
│ │ │ │
│ │ │ │ -
compares if the torrent status objects come from the same torrent. i.e.
│ │ │ │ -only the torrent_handle field is compared.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ +
│ │ │ │ +
add_rule()
│ │ │ │ +
│ │ │ │ +void add_rule (address const& first, address const& last, std::uint32_t flags);
│ │ │ │ +
│ │ │ │ +
Adds a rule to the filter. first and last defines a range of
│ │ │ │ +ip addresses that will be marked with the given flags. The flags
│ │ │ │ +can currently be 0, which means allowed, or ip_filter::blocked, which
│ │ │ │ +means disallowed.
│ │ │ │ +
precondition:
│ │ │ │ +first.is_v4() == last.is_v4() && first.is_v6() == last.is_v6()
│ │ │ │ +
postcondition:
│ │ │ │ +access(x) == flags for every x in the range [first, last]
│ │ │ │ +
This means that in a case of overlapping ranges, the last one applied takes
│ │ │ │ +precedence.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
access()
│ │ │ │ +
│ │ │ │ +std::uint32_t access (address const& addr) const;
│ │ │ │ +
│ │ │ │ +
Returns the access permissions for the given address (addr). The permission
│ │ │ │ +can currently be 0 or ip_filter::blocked. The complexity of this operation
│ │ │ │ +is O(log n), where n is the minimum number of non-overlapping ranges to describe
│ │ │ │ +the current filter.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
export_filter()
│ │ │ │ +
│ │ │ │ +filter_tuple_t export_filter () const;
│ │ │ │ +
│ │ │ │ +
This function will return the current state of the filter in the minimum number of
│ │ │ │ +ranges possible. They are sorted from ranges in low addresses to high addresses. Each
│ │ │ │ +entry in the returned vector is a range with the access control specified in its
│ │ │ │ +flags field.
│ │ │ │ +
The return value is a tuple containing two range-lists. One for IPv4 addresses
│ │ │ │ +and one for IPv6 addresses.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
enum access_flags
│ │ │ │ +
Declared in "libtorrent/ip_filter.hpp"
│ │ │ │
│ │ │ │
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
│ │ │ │
│ │ │ │
│ │ │ │ | name |
│ │ │ │ value |
│ │ │ │ description |
│ │ │ │
|---|
│ │ │ │
│ │ │ │
│ │ │ │ -| checking_files |
│ │ │ │ +
| blocked |
│ │ │ │ 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. |
│ │ │ │ +indicates that IPs in this range should not be connected
│ │ │ │ +to nor accepted as incoming connections |
│ │ │ │
│ │ │ │ -| 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. |
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
port_filter
│ │ │ │ +
Declared in "libtorrent/ip_filter.hpp"
│ │ │ │ +
the port filter maps non-overlapping port ranges to flags. This
│ │ │ │ +is primarily used to indicate whether a range of ports should
│ │ │ │ +be connected to or not. The default is to have the full port
│ │ │ │ +range (0-65535) set to flag 0.
│ │ │ │ +
│ │ │ │ +class port_filter
│ │ │ │ +{
│ │ │ │ + port_filter (port_filter&&);
│ │ │ │ + port_filter& operator= (port_filter&&);
│ │ │ │ + port_filter& operator= (port_filter const&);
│ │ │ │ + ~port_filter ();
│ │ │ │ + port_filter ();
│ │ │ │ + port_filter (port_filter const&);
│ │ │ │ + void add_rule (std::uint16_t first, std::uint16_t last, std::uint32_t flags);
│ │ │ │ + std::uint32_t access (std::uint16_t port) const;
│ │ │ │ +
│ │ │ │ + enum access_flags
│ │ │ │ + {
│ │ │ │ + blocked,
│ │ │ │ + };
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
add_rule()
│ │ │ │ +
│ │ │ │ +void add_rule (std::uint16_t first, std::uint16_t last, std::uint32_t flags);
│ │ │ │ +
│ │ │ │ +
set the flags for the specified port range (first, last) to
│ │ │ │ +flags overwriting any existing rule for those ports. The range
│ │ │ │ +is inclusive, i.e. the port last also has the flag set on it.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
access()
│ │ │ │ +
│ │ │ │ +std::uint32_t access (std::uint16_t port) const;
│ │ │ │ +
│ │ │ │ +
test the specified port (port) for whether it is blocked
│ │ │ │ +or not. The returned value is the flags set for this port.
│ │ │ │ +see access_flags.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
enum access_flags
│ │ │ │ +
Declared in "libtorrent/ip_filter.hpp"
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +| name |
│ │ │ │ +value |
│ │ │ │ +description |
│ │ │ │
|---|
│ │ │ │ -| 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. |
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +| blocked |
│ │ │ │ +1 |
│ │ │ │ +this flag indicates that destination ports in the
│ │ │ │ +range should not be connected to |
│ │ │ │
│ │ │ │ -| seeding |
│ │ │ │ -5 |
│ │ │ │ -In this state the torrent has finished downloading and
│ │ │ │ -is a pure seeder. |
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
web_seed_entry
│ │ │ │ +
Declared in "libtorrent/torrent_info.hpp"
│ │ │ │ +
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
│ │ │ │ +{
│ │ │ │ + bool operator== (web_seed_entry const& e) const;
│ │ │ │ + bool operator< (web_seed_entry const& e) const;
│ │ │ │ +
│ │ │ │ + enum type_t
│ │ │ │ + {
│ │ │ │ + url_seed,
│ │ │ │ + http_seed,
│ │ │ │ + };
│ │ │ │ +
│ │ │ │ + std::string url;
│ │ │ │ + std::string auth;
│ │ │ │ + headers_t extra_headers;
│ │ │ │ + std::uint8_t type;
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
operator==()
│ │ │ │ +
│ │ │ │ +bool operator== (web_seed_entry const& e) const;
│ │ │ │ +
│ │ │ │ +
URL and type comparison
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
operator<()
│ │ │ │ +
│ │ │ │ +bool operator< (web_seed_entry const& e) const;
│ │ │ │ +
│ │ │ │ +
URL and type less-than comparison
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
enum type_t
│ │ │ │ +
Declared in "libtorrent/torrent_info.hpp"
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +| name |
│ │ │ │ +value |
│ │ │ │ +description |
│ │ │ │
|---|
│ │ │ │ -| 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. |
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +| url_seed |
│ │ │ │ +0 |
│ │ │ │ + |
│ │ │ │
│ │ │ │ -| 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. |
│ │ │ │ +
| http_seed |
│ │ │ │ +1 |
│ │ │ │ + |
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │ -
[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.
│ │ │ │ -Note that these pieces have not necessarily been written to disk yet,
│ │ │ │ -and there is a risk the write to disk will fail.
│ │ │ │ -
│ │ │ │ -
[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]
│ │ │ │ +- url
│ │ │ │ +- The URL of the web seed
│ │ │ │
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -- last_upload last_download
│ │ │ │ -- the timestamps of the last time this torrent uploaded or downloaded
│ │ │ │ -payload to any peer.
│ │ │ │ +[report issue]
│ │ │ │ +- auth
│ │ │ │ +- Optional authentication. If this is set, it's passed
│ │ │ │ +in as HTTP basic auth to the web seed. The format is:
│ │ │ │ +username:password.
│ │ │ │
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -[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]
│ │ │ │ +- extra_headers
│ │ │ │ +- Any extra HTTP headers that need to be passed to the web seed
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -- flags
│ │ │ │ -- reflects several of the torrent's flags. For more
│ │ │ │ -information, see torrent_handle::flags().
│ │ │ │ +[report issue]
│ │ │ │ +- type
│ │ │ │ +- The type of web seed (see type_t)
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ +
[report issue]
│ │ │ │
│ │ │ │ -
│ │ │ │ -
peer_class_info
│ │ │ │ -
Declared in "libtorrent/peer_class.hpp"
│ │ │ │ -
holds settings for a peer class. Used in set_peer_class() and
│ │ │ │ -get_peer_class() calls.
│ │ │ │ +
│ │ │ │ +
load_torrent_limits
│ │ │ │ +
Declared in "libtorrent/torrent_info.hpp"
│ │ │ │ +
this object holds configuration options for limits to use when loading
│ │ │ │ +torrents. They are meant to prevent loading potentially malicious torrents
│ │ │ │ +that cause excessive memory allocations.
│ │ │ │
│ │ │ │ -struct peer_class_info
│ │ │ │ +struct load_torrent_limits
│ │ │ │ {
│ │ │ │ - bool ignore_unchoke_slots;
│ │ │ │ - int connection_limit_factor;
│ │ │ │ - std::string label;
│ │ │ │ - int upload_limit;
│ │ │ │ - int download_limit;
│ │ │ │ - int upload_priority;
│ │ │ │ - int download_priority;
│ │ │ │ + int max_buffer_size = 10000000;
│ │ │ │ + int max_pieces = 0x200000;
│ │ │ │ + int max_decode_depth = 100;
│ │ │ │ + int max_decode_tokens = 3000000;
│ │ │ │ };
│ │ │ │
│ │ │ │ -
[report issue]
│ │ │ │ -- ignore_unchoke_slots
│ │ │ │ -- ignore_unchoke_slots determines whether peers should always
│ │ │ │ -unchoke a peer, regardless of the choking algorithm, or if it should
│ │ │ │ -honor the unchoke slot limits. It's used for local peers by default.
│ │ │ │ -If any of the peer classes a peer belongs to has this set to true,
│ │ │ │ -that peer will be unchoked at all times.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -- connection_limit_factor
│ │ │ │ -- adjusts the connection limit (global and per torrent) that applies to
│ │ │ │ -this peer class. By default, local peers are allowed to exceed the
│ │ │ │ -normal connection limit for instance. This is specified as a percent
│ │ │ │ -factor. 100 makes the peer class apply normally to the limit. 200
│ │ │ │ -means as long as there are fewer connections than twice the limit, we
│ │ │ │ -accept this peer. This factor applies both to the global connection
│ │ │ │ -limit and the per-torrent limit. Note that if not used carefully one
│ │ │ │ -peer class can potentially completely starve out all other over time.
│ │ │ │ +[report issue]
│ │ │ │ +- max_buffer_size
│ │ │ │ +- the max size of a .torrent file to load into RAM
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -- label
│ │ │ │ -- not used by libtorrent. It's intended as a potentially user-facing
│ │ │ │ -identifier of this peer class.
│ │ │ │ +[report issue]
│ │ │ │ +- max_pieces
│ │ │ │ +- the max number of pieces allowed in the torrent
│ │ │ │
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -- upload_limit download_limit
│ │ │ │ -- transfer rates limits for the whole peer class. They are specified in
│ │ │ │ -bytes per second and apply to the sum of all peers that are members of
│ │ │ │ -this class.
│ │ │ │ +[report issue]
│ │ │ │ +- max_decode_depth
│ │ │ │ +- the max recursion depth in the bdecoded structure
│ │ │ │
│ │ │ │ -
│ │ │ │ -[report issue]
│ │ │ │ -- upload_priority download_priority
│ │ │ │ -- relative priorities used by the bandwidth allocator in the rate
│ │ │ │ -limiter. If no rate limits are in use, the priority is not used
│ │ │ │ -either. Priorities start at 1 (0 is not a valid priority) and may not
│ │ │ │ -exceed 255.
│ │ │ │ +[report issue]
│ │ │ │ +- max_decode_tokens
│ │ │ │ +- the max number of bdecode tokens
│ │ │ │
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +
torrent_info
│ │ │ │ +
Declared in "libtorrent/torrent_info.hpp"
│ │ │ │ +
the torrent_info class holds the information found in a .torrent file.
│ │ │ │ +
│ │ │ │ +class torrent_info
│ │ │ │ +{
│ │ │ │ + explicit torrent_info (span<char const> buffer, from_span_t);
│ │ │ │ + torrent_info (std::string const& filename, error_code& ec);
│ │ │ │ + explicit torrent_info (bdecode_node const& torrent_file);
│ │ │ │ + torrent_info (span<char const> buffer, error_code& ec, from_span_t);
│ │ │ │ + torrent_info (char const* buffer, int size);
│ │ │ │ + torrent_info (bdecode_node const& torrent_file, load_torrent_limits const& cfg);
│ │ │ │ + torrent_info (torrent_info const& t);
│ │ │ │ + explicit torrent_info (info_hash_t const& info_hash);
│ │ │ │ + explicit torrent_info (std::string const& filename);
│ │ │ │ + torrent_info (bdecode_node const& torrent_file, error_code& ec);
│ │ │ │ + torrent_info (span<char const> buffer, load_torrent_limits const& cfg, from_span_t);
│ │ │ │ + torrent_info (char const* buffer, int size, error_code& ec);
│ │ │ │ + torrent_info (std::string const& filename, load_torrent_limits const& cfg);
│ │ │ │ + ~torrent_info ();
│ │ │ │ + file_storage const& orig_files () const;
│ │ │ │ + file_storage const& files () const;
│ │ │ │ + void rename_file (file_index_t index, std::string const& new_filename);
│ │ │ │ + void remap_files (file_storage const& f);
│ │ │ │ + void add_tracker (std::string const& url, int tier = 0);
│ │ │ │ + void clear_trackers ();
│ │ │ │ + void add_tracker (std::string const& url, int tier
│ │ │ │ + , announce_entry::tracker_source source);
│ │ │ │ + std::vector<announce_entry> const& trackers () const;
│ │ │ │ + std::vector<sha1_hash> similar_torrents () const;
│ │ │ │ + std::vector<std::string> collections () const;
│ │ │ │ + void set_web_seeds (std::vector<web_seed_entry> seeds);
│ │ │ │ + void add_url_seed (std::string const& url
│ │ │ │ + , std::string const& ext_auth = std::string()
│ │ │ │ + , web_seed_entry::headers_t const& ext_headers = web_seed_entry::headers_t());
│ │ │ │ + void add_http_seed (std::string const& url
│ │ │ │ + , std::string const& extern_auth = std::string()
│ │ │ │ + , web_seed_entry::headers_t const& extra_headers = web_seed_entry::headers_t());
│ │ │ │ + std::vector<web_seed_entry> const& web_seeds () const;
│ │ │ │ + std::int64_t total_size () const;
│ │ │ │ + int num_pieces () const;
│ │ │ │ + int piece_length () const;
│ │ │ │ + int blocks_per_piece () const;
│ │ │ │ + piece_index_t last_piece () const;
│ │ │ │ + index_range<piece_index_t> piece_range () const;
│ │ │ │ + piece_index_t end_piece () const;
│ │ │ │ + info_hash_t const& info_hashes () const;
│ │ │ │ + sha1_hash info_hash () const noexcept;
│ │ │ │ + bool v1 () const;
│ │ │ │ + bool v2 () const;
│ │ │ │ + int num_files () const;
│ │ │ │ + std::vector<file_slice> map_block (piece_index_t const piece
│ │ │ │ + , std::int64_t offset, int size) const;
│ │ │ │ + peer_request map_file (file_index_t const file, std::int64_t offset, int size) const;
│ │ │ │ + string_view ssl_cert () const;
│ │ │ │ + bool is_valid () const;
│ │ │ │ + bool priv () const;
│ │ │ │ + bool is_i2p () const;
│ │ │ │ + int piece_size (piece_index_t index) const;
│ │ │ │ + char const* hash_for_piece_ptr (piece_index_t const index) const;
│ │ │ │ + sha1_hash hash_for_piece (piece_index_t index) const;
│ │ │ │ + bool is_loaded () const;
│ │ │ │ + const std::string& name () const;
│ │ │ │ + std::time_t creation_date () const;
│ │ │ │ + const std::string& creator () const;
│ │ │ │ + const std::string& comment () const;
│ │ │ │ + std::vector<std::pair<std::string, int>> const& nodes () const;
│ │ │ │ + void add_node (std::pair<std::string, int> const& node);
│ │ │ │ + bool parse_info_section (bdecode_node const& info, error_code& ec, int max_pieces);
│ │ │ │ + bdecode_node info (char const* key) const;
│ │ │ │ + span<char const> info_section () const;
│ │ │ │ + span<char const> piece_layer (file_index_t) const;
│ │ │ │ + void free_piece_layers ();
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
torrent_info()
│ │ │ │ +
│ │ │ │ +explicit torrent_info (span<char const> buffer, from_span_t);
│ │ │ │ +torrent_info (std::string const& filename, error_code& ec);
│ │ │ │ +explicit torrent_info (bdecode_node const& torrent_file);
│ │ │ │ +torrent_info (span<char const> buffer, error_code& ec, from_span_t);
│ │ │ │ +torrent_info (char const* buffer, int size);
│ │ │ │ +torrent_info (bdecode_node const& torrent_file, load_torrent_limits const& cfg);
│ │ │ │ +torrent_info (torrent_info const& t);
│ │ │ │ +explicit torrent_info (info_hash_t const& info_hash);
│ │ │ │ +explicit torrent_info (std::string const& filename);
│ │ │ │ +torrent_info (bdecode_node const& torrent_file, error_code& ec);
│ │ │ │ +torrent_info (span<char const> buffer, load_torrent_limits const& cfg, from_span_t);
│ │ │ │ +torrent_info (char const* buffer, int size, error_code& ec);
│ │ │ │ +torrent_info (std::string const& filename, load_torrent_limits const& cfg);
│ │ │ │ +
│ │ │ │ +
The constructor that takes an info-hash will initialize the info-hash
│ │ │ │ +to the given value, but leave all other fields empty. This is used
│ │ │ │ +internally when downloading torrents without the metadata. The
│ │ │ │ +metadata will be created by libtorrent as soon as it has been
│ │ │ │ +downloaded from the swarm.
│ │ │ │ +
The constructor that takes a bdecode_node will create a torrent_info
│ │ │ │ +object from the information found in the given torrent_file. The
│ │ │ │ +bdecode_node represents a tree node in an bencoded file. To load an
│ │ │ │ +ordinary .torrent file into a bdecode_node, use bdecode().
│ │ │ │ +
The version that takes a buffer pointer and a size will decode it as a
│ │ │ │ +.torrent file and initialize the torrent_info object for you.
│ │ │ │ +
The version that takes a filename will simply load the torrent file
│ │ │ │ +and decode it inside the constructor, for convenience. This might not
│ │ │ │ +be the most suitable for applications that want to be able to report
│ │ │ │ +detailed errors on what might go wrong.
│ │ │ │ +
There is an upper limit on the size of the torrent file that will be
│ │ │ │ +loaded by the overload taking a filename. If it's important that even
│ │ │ │ +very large torrent files are loaded, use one of the other overloads.
│ │ │ │ +
The overloads that takes an error_code const& never throws if an
│ │ │ │ +error occur, they will simply set the error code to describe what went
│ │ │ │ +wrong and not fully initialize the torrent_info object. The overloads
│ │ │ │ +that do not take the extra error_code parameter will always throw if
│ │ │ │ +an error occurs. These overloads are not available when building
│ │ │ │ +without exception support.
│ │ │ │ +
The overload that takes a span also needs an extra parameter of
│ │ │ │ +type from_span_t to disambiguate the std::string overload for
│ │ │ │ +string literals. There is an object in the libtorrent namespace of this
│ │ │ │ +type called from_span.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
~torrent_info()
│ │ │ │ +
│ │ │ │ +~torrent_info ();
│ │ │ │ +
│ │ │ │ +
frees all storage associated with this torrent_info object
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
files() orig_files()
│ │ │ │ +
│ │ │ │ +file_storage const& orig_files () const;
│ │ │ │ +file_storage const& files () const;
│ │ │ │ +
│ │ │ │ +
The file_storage object contains the information on how to map the
│ │ │ │ +pieces to files. It is separated from the torrent_info object because
│ │ │ │ +when creating torrents a storage object needs to be created without
│ │ │ │ +having a torrent file. When renaming files in a storage, the storage
│ │ │ │ +needs to make its own copy of the file_storage in order to make its
│ │ │ │ +mapping differ from the one in the torrent file.
│ │ │ │ +
orig_files() returns the original (unmodified) file storage for
│ │ │ │ +this torrent. This is used by the web server connection, which needs
│ │ │ │ +to request files with the original names. Filename may be changed using
│ │ │ │ +torrent_info::rename_file().
│ │ │ │ +
For more information on the file_storage object, see the separate
│ │ │ │ +document on how to create torrents.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
rename_file()
│ │ │ │ +
│ │ │ │ +void rename_file (file_index_t index, std::string const& new_filename);
│ │ │ │ +
│ │ │ │ +
Renames the file with the specified index to the new name. The new
│ │ │ │ +filename is reflected by the file_storage returned by files()
│ │ │ │ +but not by the one returned by orig_files().
│ │ │ │ +
If you want to rename the base name of the torrent (for a multi file
│ │ │ │ +torrent), you can copy the file_storage (see files() and
│ │ │ │ +orig_files() ), change the name, and then use remap_files().
│ │ │ │ +
The new_filename can both be a relative path, in which case the
│ │ │ │ +file name is relative to the save_path of the torrent. If the
│ │ │ │ +new_filename is an absolute path (i.e. is_complete(new_filename)
│ │ │ │ +== true), then the file is detached from the save_path of the
│ │ │ │ +torrent. In this case the file is not moved when move_storage() is
│ │ │ │ +invoked.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
remap_files()
│ │ │ │ +
│ │ │ │ +void remap_files (file_storage const& f);
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
Warning
│ │ │ │ +
Using remap_files() is discouraged as it's incompatible with v2
│ │ │ │ +torrents. This is because the piece boundaries and piece hashes in
│ │ │ │ +v2 torrents are intimately tied to the file boundaries. Instead,
│ │ │ │ +just rename individual files, or implement a custom disk_interface
│ │ │ │ +to customize how to store files.
│ │ │ │ +
│ │ │ │ +
Remaps the file storage to a new file layout. This can be used to, for
│ │ │ │ +instance, download all data in a torrent to a single file, or to a
│ │ │ │ +number of fixed size sector aligned files, regardless of the number
│ │ │ │ +and sizes of the files in the torrent.
│ │ │ │ +
The new specified file_storage must have the exact same size as
│ │ │ │ +the current one.
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
trackers() clear_trackers() add_tracker()
│ │ │ │ +
│ │ │ │ +void add_tracker (std::string const& url, int tier = 0);
│ │ │ │ +void clear_trackers ();
│ │ │ │ +void add_tracker (std::string const& url, int tier
│ │ │ │ + , announce_entry::tracker_source source);
│ │ │ │ +std::vector<announce_entry> const& trackers () const;
│ │ │ │ +
│ │ │ │ +
add_tracker() adds a tracker to the announce-list. The tier
│ │ │ │ +determines the order in which the trackers are to be tried.
│ │ │ │ +The trackers() function will return a sorted vector of
│ │ │ │ +announce_entry. Each announce entry contains a string, which is
│ │ │ │ +the tracker url, and a tier index. The tier index is the high-level
│ │ │ │ +priority. No matter which trackers that works or not, the ones with
│ │ │ │ +lower tier will always be tried before the one with higher tier
│ │ │ │ +number. For more information, see announce_entry.
│ │ │ │ +
trackers() returns all entries from announce-list.
│ │ │ │ +
clear_trackers() removes all trackers from announce-list.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
collections() similar_torrents()
│ │ │ │ +
│ │ │ │ +std::vector<sha1_hash> similar_torrents () const;
│ │ │ │ +std::vector<std::string> collections () const;
│ │ │ │ +
│ │ │ │ +
These two functions are related to BEP 38 (mutable torrents). The
│ │ │ │ +vectors returned from these correspond to the "similar" and
│ │ │ │ +"collections" keys in the .torrent file. Both info-hashes and
│ │ │ │ +collections from within the info-dict and from outside of it are
│ │ │ │ +included.
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
set_web_seeds() web_seeds() add_http_seed() add_url_seed()
│ │ │ │ +
│ │ │ │ +void set_web_seeds (std::vector<web_seed_entry> seeds);
│ │ │ │ +void add_url_seed (std::string const& url
│ │ │ │ + , std::string const& ext_auth = std::string()
│ │ │ │ + , web_seed_entry::headers_t const& ext_headers = web_seed_entry::headers_t());
│ │ │ │ +void add_http_seed (std::string const& url
│ │ │ │ + , std::string const& extern_auth = std::string()
│ │ │ │ + , web_seed_entry::headers_t const& extra_headers = web_seed_entry::headers_t());
│ │ │ │ +std::vector<web_seed_entry> const& web_seeds () const;
│ │ │ │ +
│ │ │ │ +
web_seeds() returns all url seeds and http seeds in the torrent.
│ │ │ │ +Each entry is a web_seed_entry and may refer to either a url seed
│ │ │ │ +or http seed.
│ │ │ │ +
add_url_seed() and add_http_seed() adds one url to the list of
│ │ │ │ +url/http seeds.
│ │ │ │ +
set_web_seeds() replaces all web seeds with the ones specified in
│ │ │ │ +the seeds vector.
│ │ │ │ +
The extern_auth argument can be used for other authorization
│ │ │ │ +schemes than basic HTTP authorization. If set, it will override any
│ │ │ │ +username and password found in the URL itself. The string will be sent
│ │ │ │ +as the HTTP authorization header's value (without specifying "Basic").
│ │ │ │ +
The extra_headers argument defaults to an empty list, but can be
│ │ │ │ +used to insert custom HTTP headers in the requests to a specific web
│ │ │ │ +seed.
│ │ │ │ +
See http seeding for more information.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
total_size()
│ │ │ │ +
│ │ │ │ +std::int64_t total_size () const;
│ │ │ │ +
│ │ │ │ +
total_size() returns the total number of bytes the torrent-file
│ │ │ │ +represents. Note that this is the number of pieces times the piece
│ │ │ │ +size (modulo the last piece possibly being smaller). With pad files,
│ │ │ │ +the total size will be larger than the sum of all (regular) file
│ │ │ │ +sizes.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
num_pieces() piece_length()
│ │ │ │ +
│ │ │ │ +int num_pieces () const;
│ │ │ │ +int piece_length () const;
│ │ │ │ +
│ │ │ │ +
piece_length() and num_pieces() returns the number of byte
│ │ │ │ +for each piece and the total number of pieces, respectively. The
│ │ │ │ +difference between piece_size() and piece_length() is that
│ │ │ │ +piece_size() takes the piece index as argument and gives you the
│ │ │ │ +exact size of that piece. It will always be the same as
│ │ │ │ +piece_length() except in the case of the last piece, which may be
│ │ │ │ +smaller.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
blocks_per_piece()
│ │ │ │ +
│ │ │ │ +int blocks_per_piece () const;
│ │ │ │ +
│ │ │ │ +
returns the number of blocks there are in the typical piece. There
│ │ │ │ +may be fewer in the last piece)
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
last_piece() piece_range() end_piece()
│ │ │ │ +
│ │ │ │ +piece_index_t last_piece () const;
│ │ │ │ +index_range<piece_index_t> piece_range () const;
│ │ │ │ +piece_index_t end_piece () const;
│ │ │ │ +
│ │ │ │ +
last_piece() returns the index to the last piece in the torrent and
│ │ │ │ +end_piece() returns the index to the one-past-end piece in the
│ │ │ │ +torrent
│ │ │ │ +piece_range() returns an implementation-defined type that can be
│ │ │ │ +used as the container in a range-for loop. Where the values are the
│ │ │ │ +indices of all pieces in the file_storage.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
info_hashes() info_hash()
│ │ │ │ +
│ │ │ │ +info_hash_t const& info_hashes () const;
│ │ │ │ +sha1_hash info_hash () const noexcept;
│ │ │ │ +
│ │ │ │ +
returns the info-hash of the torrent. For BitTorrent v2 support, use
│ │ │ │ +info_hashes() to get an object that may hold both a v1 and v2
│ │ │ │ +info-hash
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
v1() v2()
│ │ │ │ +
│ │ │ │ +bool v1 () const;
│ │ │ │ +bool v2 () const;
│ │ │ │ +
│ │ │ │ +
returns whether this torrent has v1 and/or v2 metadata, respectively.
│ │ │ │ +Hybrid torrents have both. These are shortcuts for
│ │ │ │ +info_hashes().has_v1() and info_hashes().has_v2() calls.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
num_files()
│ │ │ │ +
│ │ │ │ +int num_files () const;
│ │ │ │ +
│ │ │ │ +
If you need index-access to files you can use the num_files() along
│ │ │ │ +with the file_path(), file_size()-family of functions to access
│ │ │ │ +files using indices.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
map_block()
│ │ │ │ +
│ │ │ │ +std::vector<file_slice> map_block (piece_index_t const piece
│ │ │ │ + , std::int64_t offset, int size) const;
│ │ │ │ +
│ │ │ │ +
This function will map a piece index, a byte offset within that piece
│ │ │ │ +and a size (in bytes) into the corresponding files with offsets where
│ │ │ │ +that data for that piece is supposed to be stored. See file_slice.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
map_file()
│ │ │ │ +
│ │ │ │ +peer_request map_file (file_index_t const file, std::int64_t offset, int size) const;
│ │ │ │ +
│ │ │ │ +
This function will map a range in a specific file into a range in the
│ │ │ │ +torrent. The file_offset parameter is the offset in the file,
│ │ │ │ +given in bytes, where 0 is the start of the file. See peer_request.
│ │ │ │ +
The input range is assumed to be valid within the torrent.
│ │ │ │ +file_offset + size is not allowed to be greater than the file
│ │ │ │ +size. file_index must refer to a valid file, i.e. it cannot be >=
│ │ │ │ +num_files().
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
ssl_cert()
│ │ │ │ +
│ │ │ │ +string_view ssl_cert () const;
│ │ │ │ +
│ │ │ │ +
Returns the SSL root certificate for the torrent, if it is an SSL
│ │ │ │ +torrent. Otherwise returns an empty string. The certificate is
│ │ │ │ +the public certificate in x509 format.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
is_valid()
│ │ │ │ +
│ │ │ │ +bool is_valid () const;
│ │ │ │ +
│ │ │ │ +
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.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
priv()
│ │ │ │ +
│ │ │ │ +bool priv () const;
│ │ │ │ +
│ │ │ │ +
returns true if this torrent is private. i.e., the client should not
│ │ │ │ +advertise itself on the trackerless network (the Kademlia DHT) for this torrent.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
is_i2p()
│ │ │ │ +
│ │ │ │ +bool is_i2p () const;
│ │ │ │ +
│ │ │ │ +
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.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
piece_size()
│ │ │ │ +
│ │ │ │ +int piece_size (piece_index_t index) const;
│ │ │ │ +
│ │ │ │ +
returns the piece size of file with index. This will be the same as piece_length(),
│ │ │ │ +except for the last piece, which may be shorter.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
hash_for_piece_ptr() hash_for_piece()
│ │ │ │ +
│ │ │ │ +char const* hash_for_piece_ptr (piece_index_t const index) const;
│ │ │ │ +sha1_hash hash_for_piece (piece_index_t index) const;
│ │ │ │ +
│ │ │ │ +
hash_for_piece() takes a piece-index and returns the 20-bytes
│ │ │ │ +sha1-hash for that piece and info_hash() returns the 20-bytes
│ │ │ │ +sha1-hash for the info-section of the torrent file.
│ │ │ │ +hash_for_piece_ptr() returns a pointer to the 20 byte sha1 digest
│ │ │ │ +for the piece. Note that the string is not 0-terminated.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
name()
│ │ │ │ +
│ │ │ │ +const std::string& name () const;
│ │ │ │ +
│ │ │ │ +
name() returns the name of the torrent.
│ │ │ │ +name contains UTF-8 encoded string.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
creator()
│ │ │ │ +
│ │ │ │ +const std::string& creator () const;
│ │ │ │ +
│ │ │ │ +
creator() returns the creator string in the torrent. If there is
│ │ │ │ +no creator string it will return an empty string.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
nodes()
│ │ │ │ +
│ │ │ │ +std::vector<std::pair<std::string, int>> const& nodes () const;
│ │ │ │ +
│ │ │ │ +
If this torrent contains any DHT nodes, they are put in this vector in
│ │ │ │ +their original form (host name and port number).
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
add_node()
│ │ │ │ +
│ │ │ │ +void add_node (std::pair<std::string, int> const& node);
│ │ │ │ +
│ │ │ │ +
This is used when creating torrent. Use this to add a known DHT node.
│ │ │ │ +It may be used, by the client, to bootstrap into the DHT network.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
parse_info_section()
│ │ │ │ +
│ │ │ │ +bool parse_info_section (bdecode_node const& info, error_code& ec, int max_pieces);
│ │ │ │ +
│ │ │ │ +
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 bdecode_node e points to a
│ │ │ │ +parsed info-dictionary. ec returns an error code if something
│ │ │ │ +fails (typically if the info dictionary is malformed).
│ │ │ │ +The max_pieces parameter allows limiting the amount of memory
│ │ │ │ +dedicated to loading the torrent, and fails for torrents that exceed
│ │ │ │ +the limit. To load large torrents, this limit may also need to be
│ │ │ │ +raised in settings_pack::max_piece_count and in calls to
│ │ │ │ +read_resume_data().
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
info()
│ │ │ │ +
│ │ │ │ +bdecode_node info (char const* key) const;
│ │ │ │ +
│ │ │ │ +
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 nullptr.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
info_section()
│ │ │ │ +
│ │ │ │ +span<char const> info_section () const;
│ │ │ │ +
│ │ │ │ +
returns a the raw info section of the torrent file.
│ │ │ │ +The underlying buffer is still owned by the torrent_info object
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
piece_layer()
│ │ │ │ +
│ │ │ │ +span<char const> piece_layer (file_index_t) const;
│ │ │ │ +
│ │ │ │ +
return the bytes of the piece layer hashes for the specified file. If
│ │ │ │ +the file doesn't have a piece layer, an empty span is returned.
│ │ │ │ +The span size is divisible by 32, the size of a SHA-256 hash.
│ │ │ │ +If the size of the file is smaller than or equal to the piece size,
│ │ │ │ +the files "root hash" is the hash of the file and is not saved
│ │ │ │ +separately in the "piece layers" field, but this function still
│ │ │ │ +returns the root hash of the file in that case.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
free_piece_layers()
│ │ │ │ +
│ │ │ │ +void free_piece_layers ();
│ │ │ │ +
│ │ │ │ +
clears the piece layers from the torrent_info. This is done by the
│ │ │ │ +session when a torrent is added, to avoid storing it twice. The piece
│ │ │ │ +layer (or other hashes part of the merkle tree) are stored in the
│ │ │ │ +internal torrent object.
│ │ │ │
[report issue]
│ │ │ │ +
│ │ │ │
│ │ │ │
peer_class_type_filter
│ │ │ │
Declared in "libtorrent/peer_class_type_filter.hpp"
│ │ │ │
peer_class_type_filter is a simple container for rules for adding and subtracting
│ │ │ │ peer-classes from peers. It is applied after the peer class filter is applied (which
│ │ │ │ is based on the peer's IP address).
│ │ │ │
│ │ │ │ @@ -11915,604 +11982,1763 @@
│ │ │ │
│ │ │ │ | num_socket_types |
│ │ │ │ 5 |
│ │ │ │ |
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │ -
You have some control over session configuration through the session::apply_settings()
│ │ │ │ -member function. To change one or more configuration options, create a settings_pack
│ │ │ │ -object and fill it with the settings to be set and pass it in to session::apply_settings().
│ │ │ │ -
The settings_pack object is a collection of settings updates that are applied
│ │ │ │ -to the session when passed to session::apply_settings(). It's empty when
│ │ │ │ -constructed.
│ │ │ │ -
You have control over proxy and authorization settings and also the user-agent
│ │ │ │ -that will be sent to the tracker. The user-agent will also be used to identify the
│ │ │ │ -client with other peers.
│ │ │ │ -
Each configuration option is named with an enum value inside the
│ │ │ │ -settings_pack class. These are the available settings:
│ │ │ │ -
[report issue]
│ │ │ │ +
[report issue]
│ │ │ │
│ │ │ │ -
│ │ │ │ -
disk_observer
│ │ │ │ -
Declared in "libtorrent/disk_observer.hpp"
│ │ │ │ +
│ │ │ │ +
peer_class_info
│ │ │ │ +
Declared in "libtorrent/peer_class.hpp"
│ │ │ │ +
holds settings for a peer class. Used in set_peer_class() and
│ │ │ │ +get_peer_class() calls.
│ │ │ │
│ │ │ │ -struct disk_observer
│ │ │ │ +struct peer_class_info
│ │ │ │ {
│ │ │ │ - virtual void on_disk () = 0;
│ │ │ │ + bool ignore_unchoke_slots;
│ │ │ │ + int connection_limit_factor;
│ │ │ │ + std::string label;
│ │ │ │ + int upload_limit;
│ │ │ │ + int download_limit;
│ │ │ │ + int upload_priority;
│ │ │ │ + int download_priority;
│ │ │ │ };
│ │ │ │
│ │ │ │ -
[report issue]
│ │ │ │ -
on_disk()
│ │ │ │ +
[report issue]
│ │ │ │ +- ignore_unchoke_slots
│ │ │ │ +- ignore_unchoke_slots determines whether peers should always
│ │ │ │ +unchoke a peer, regardless of the choking algorithm, or if it should
│ │ │ │ +honor the unchoke slot limits. It's used for local peers by default.
│ │ │ │ +If any of the peer classes a peer belongs to has this set to true,
│ │ │ │ +that peer will be unchoked at all times.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- connection_limit_factor
│ │ │ │ +- adjusts the connection limit (global and per torrent) that applies to
│ │ │ │ +this peer class. By default, local peers are allowed to exceed the
│ │ │ │ +normal connection limit for instance. This is specified as a percent
│ │ │ │ +factor. 100 makes the peer class apply normally to the limit. 200
│ │ │ │ +means as long as there are fewer connections than twice the limit, we
│ │ │ │ +accept this peer. This factor applies both to the global connection
│ │ │ │ +limit and the per-torrent limit. Note that if not used carefully one
│ │ │ │ +peer class can potentially completely starve out all other over time.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- label
│ │ │ │ +- not used by libtorrent. It's intended as a potentially user-facing
│ │ │ │ +identifier of this peer class.
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- upload_limit download_limit
│ │ │ │ +- transfer rates limits for the whole peer class. They are specified in
│ │ │ │ +bytes per second and apply to the sum of all peers that are members of
│ │ │ │ +this class.
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- upload_priority download_priority
│ │ │ │ +- relative priorities used by the bandwidth allocator in the rate
│ │ │ │ +limiter. If no rate limits are in use, the priority is not used
│ │ │ │ +either. Priorities start at 1 (0 is not a valid priority) and may not
│ │ │ │ +exceed 255.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
bitfield
│ │ │ │ +
Declared in "libtorrent/bitfield.hpp"
│ │ │ │ +
The bitfield type stores any number of bits as a bitfield
│ │ │ │ +in a heap allocated array.
│ │ │ │
│ │ │ │ -virtual void on_disk () = 0;
│ │ │ │ +struct bitfield
│ │ │ │ +{
│ │ │ │ + bitfield (bitfield&& rhs) noexcept = default;
│ │ │ │ + bitfield (char const* b, int bits);
│ │ │ │ + explicit bitfield (int bits);
│ │ │ │ + bitfield () noexcept = default;
│ │ │ │ + bitfield (int bits, bool val);
│ │ │ │ + bitfield (bitfield const& rhs);
│ │ │ │ + void assign (char const* b, int const bits);
│ │ │ │ + bool operator[] (int index) const noexcept;
│ │ │ │ + bool get_bit (int index) const noexcept;
│ │ │ │ + void set_bit (int index) noexcept;
│ │ │ │ + void clear_bit (int index) noexcept;
│ │ │ │ + bool all_set () const noexcept;
│ │ │ │ + bool none_set () const noexcept;
│ │ │ │ + int size () const noexcept;
│ │ │ │ + int num_words () const noexcept;
│ │ │ │ + int num_bytes () const noexcept;
│ │ │ │ + bool empty () const noexcept;
│ │ │ │ + char const* data () const noexcept;
│ │ │ │ + char* data () noexcept;
│ │ │ │ + void swap (bitfield& rhs) noexcept;
│ │ │ │ + int count () const noexcept;
│ │ │ │ + int find_first_set () const noexcept;
│ │ │ │ + int find_last_clear () const noexcept;
│ │ │ │ + bool operator== (lt::bitfield const& rhs) const;
│ │ │ │ +};
│ │ │ │
│ │ │ │ -
called when the disk cache size has dropped
│ │ │ │ -below the low watermark again and we can
│ │ │ │ -resume downloading from peers
│ │ │ │ -
[report issue]
│ │ │ │ +
[report issue]
│ │ │ │ +
bitfield()
│ │ │ │ +
│ │ │ │ +bitfield (bitfield&& rhs) noexcept = default;
│ │ │ │ +bitfield (char const* b, int bits);
│ │ │ │ +explicit bitfield (int bits);
│ │ │ │ +bitfield () noexcept = default;
│ │ │ │ +bitfield (int bits, bool val);
│ │ │ │ +bitfield (bitfield const& rhs);
│ │ │ │ +
│ │ │ │ +
constructs a new bitfield. The default constructor creates an empty
│ │ │ │ +bitfield. bits is the size of the bitfield (specified in bits).
│ │ │ │ +val is the value to initialize the bits to. If not specified
│ │ │ │ +all bits are initialized to 0.
│ │ │ │ +
The constructor taking a pointer b and bits copies a bitfield
│ │ │ │ +from the specified buffer, and bits number of bits (rounded up to
│ │ │ │ +the nearest byte boundary).
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
assign()
│ │ │ │ +
│ │ │ │ +void assign (char const* b, int const bits);
│ │ │ │ +
│ │ │ │ +
copy bitfield from buffer b of bits number of bits, rounded up to
│ │ │ │ +the nearest byte boundary.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
operator[]() get_bit()
│ │ │ │ +
│ │ │ │ +bool operator[] (int index) const noexcept;
│ │ │ │ +bool get_bit (int index) const noexcept;
│ │ │ │ +
│ │ │ │ +
query bit at index. Returns true if bit is 1, otherwise false.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
set_bit() clear_bit()
│ │ │ │ +
│ │ │ │ +void set_bit (int index) noexcept;
│ │ │ │ +void clear_bit (int index) noexcept;
│ │ │ │ +
│ │ │ │ +
set bit at index to 0 (clear_bit) or 1 (set_bit).
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
all_set()
│ │ │ │ +
│ │ │ │ +bool all_set () const noexcept;
│ │ │ │ +
│ │ │ │ +
returns true if all bits in the bitfield are set
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
none_set()
│ │ │ │ +
│ │ │ │ +bool none_set () const noexcept;
│ │ │ │ +
│ │ │ │ +
returns true if no bit in the bitfield is set
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
size()
│ │ │ │ +
│ │ │ │ +int size () const noexcept;
│ │ │ │ +
│ │ │ │ +
returns the size of the bitfield in bits.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
num_words()
│ │ │ │ +
│ │ │ │ +int num_words () const noexcept;
│ │ │ │ +
│ │ │ │ +
returns the number of 32 bit words are needed to represent all bits in
│ │ │ │ +this bitfield.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
num_bytes()
│ │ │ │ +
│ │ │ │ +int num_bytes () const noexcept;
│ │ │ │ +
│ │ │ │ +
returns the number of bytes needed to represent all bits in this
│ │ │ │ +bitfield
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
empty()
│ │ │ │ +
│ │ │ │ +bool empty () const noexcept;
│ │ │ │ +
│ │ │ │ +
returns true if the bitfield has zero size.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
data()
│ │ │ │ +
│ │ │ │ +char const* data () const noexcept;
│ │ │ │ +char* data () noexcept;
│ │ │ │ +
│ │ │ │ +
returns a pointer to the internal buffer of the bitfield, or
│ │ │ │ +nullptr if it's empty.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
swap()
│ │ │ │ +
│ │ │ │ +void swap (bitfield& rhs) noexcept;
│ │ │ │ +
│ │ │ │ +
swaps the bit-fields two variables refer to
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
count()
│ │ │ │ +
│ │ │ │ +int count () const noexcept;
│ │ │ │ +
│ │ │ │ +
count the number of bits in the bitfield that are set to 1.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
find_first_set()
│ │ │ │ +
│ │ │ │ +int find_first_set () const noexcept;
│ │ │ │ +
│ │ │ │ +
returns the index of the first set bit in the bitfield, i.e. 1 bit.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
find_last_clear()
│ │ │ │ +
│ │ │ │ +int find_last_clear () const noexcept;
│ │ │ │ +
│ │ │ │ +
returns the index to the last cleared bit in the bitfield, i.e. 0 bit.
│ │ │ │ +
[report issue]
│ │ │ │
│ │ │ │ -
│ │ │ │ -
open_file_state
│ │ │ │ -
Declared in "libtorrent/disk_interface.hpp"
│ │ │ │ -
this contains information about a file that's currently open by the
│ │ │ │ -libtorrent disk I/O subsystem. It's associated with a single torrent.
│ │ │ │ +
│ │ │ │ +
hasher
│ │ │ │ +
Declared in "libtorrent/hasher.hpp"
│ │ │ │ +
this is a SHA-1 hash class.
│ │ │ │ +
You use it by first instantiating it, then call update() to feed it
│ │ │ │ +with data. i.e. you don't have to keep the entire buffer of which you want to
│ │ │ │ +create the hash in memory. You can feed the hasher parts of it at a time. When
│ │ │ │ +You have fed the hasher with all the data, you call final() and it
│ │ │ │ +will return the sha1-hash of the data.
│ │ │ │ +
The constructor that takes a char const* and an integer will construct the
│ │ │ │ +sha1 context and feed it the data passed in.
│ │ │ │ +
If you want to reuse the hasher object once you have created a hash, you have to
│ │ │ │ +call reset() to reinitialize it.
│ │ │ │ +
The built-in software version of sha1-algorithm was implemented
│ │ │ │ +by Steve Reid and released as public domain.
│ │ │ │ +For more info, see src/sha1.cpp.
│ │ │ │
│ │ │ │ -struct open_file_state
│ │ │ │ +class hasher
│ │ │ │ {
│ │ │ │ - file_index_t file_index;
│ │ │ │ - file_open_mode_t open_mode;
│ │ │ │ - time_point last_use;
│ │ │ │ + hasher ();
│ │ │ │ + hasher (hasher const&);
│ │ │ │ + hasher (char const* data, int len);
│ │ │ │ + hasher& operator= (hasher const&) &;
│ │ │ │ + explicit hasher (span<char const> data);
│ │ │ │ + hasher& update (char const* data, int len);
│ │ │ │ + hasher& update (span<char const> data);
│ │ │ │ + sha1_hash final ();
│ │ │ │ + void reset ();
│ │ │ │ };
│ │ │ │
│ │ │ │ -
[report issue]
│ │ │ │ -- file_index
│ │ │ │ -- the index of the file this entry refers to into the file_storage
│ │ │ │ -file list of this torrent. This starts indexing at 0.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +
hasher() operator=()
│ │ │ │ +
│ │ │ │ +hasher (hasher const&);
│ │ │ │ +hasher (char const* data, int len);
│ │ │ │ +hasher& operator= (hasher const&) &;
│ │ │ │ +explicit hasher (span<char const> data);
│ │ │ │ +
│ │ │ │ +
this is the same as default constructing followed by a call to
│ │ │ │ +update(data, len).
│ │ │ │ +
[report issue]
│ │ │ │ +
update()
│ │ │ │ +
│ │ │ │ +hasher& update (char const* data, int len);
│ │ │ │ +hasher& update (span<char const> data);
│ │ │ │ +
│ │ │ │ +
append the following bytes to what is being hashed
│ │ │ │ +
[report issue]
│ │ │ │ +
final()
│ │ │ │ +
│ │ │ │ +sha1_hash final ();
│ │ │ │ +
│ │ │ │ +
returns the SHA-1 digest of the buffers previously passed to
│ │ │ │ +update() and the hasher constructor.
│ │ │ │ +
[report issue]
│ │ │ │ +
reset()
│ │ │ │ +
│ │ │ │ +void reset ();
│ │ │ │ +
│ │ │ │ +
restore the hasher state to be as if the hasher has just been
│ │ │ │ +default constructed.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
hasher256
│ │ │ │ +
Declared in "libtorrent/hasher.hpp"
│ │ │ │ +
│ │ │ │ +class hasher256
│ │ │ │ +{
│ │ │ │ + hasher256 ();
│ │ │ │ + explicit hasher256 (span<char const> data);
│ │ │ │ + hasher256 (hasher256 const&);
│ │ │ │ + hasher256& operator= (hasher256 const&) &;
│ │ │ │ + hasher256 (char const* data, int len);
│ │ │ │ + hasher256& update (char const* data, int len);
│ │ │ │ + hasher256& update (span<char const> data);
│ │ │ │ + sha256_hash final ();
│ │ │ │ + void reset ();
│ │ │ │ + ~hasher256 ();
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
operator=() hasher256()
│ │ │ │ +
│ │ │ │ +explicit hasher256 (span<char const> data);
│ │ │ │ +hasher256 (hasher256 const&);
│ │ │ │ +hasher256& operator= (hasher256 const&) &;
│ │ │ │ +hasher256 (char const* data, int len);
│ │ │ │ +
│ │ │ │ +
this is the same as default constructing followed by a call to
│ │ │ │ +update(data, len).
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
update()
│ │ │ │ +
│ │ │ │ +hasher256& update (char const* data, int len);
│ │ │ │ +hasher256& update (span<char const> data);
│ │ │ │ +
│ │ │ │ +
append the following bytes to what is being hashed
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
final()
│ │ │ │ +
│ │ │ │ +sha256_hash final ();
│ │ │ │ +
│ │ │ │ +
returns the SHA-1 digest of the buffers previously passed to
│ │ │ │ +update() and the hasher constructor.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
reset()
│ │ │ │ +
│ │ │ │ +void reset ();
│ │ │ │ +
│ │ │ │ +
restore the hasher state to be as if the hasher has just been
│ │ │ │ +default constructed.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
block_info
│ │ │ │ +
Declared in "libtorrent/torrent_handle.hpp"
│ │ │ │ +
holds the state of a block in a piece. Who we requested
│ │ │ │ +it from and how far along we are at downloading it.
│ │ │ │ +
│ │ │ │ +struct block_info
│ │ │ │ +{
│ │ │ │ + tcp::endpoint peer () const;
│ │ │ │ + void set_peer (tcp::endpoint const& ep);
│ │ │ │ +
│ │ │ │ + enum block_state_t
│ │ │ │ + {
│ │ │ │ + none,
│ │ │ │ + requested,
│ │ │ │ + writing,
│ │ │ │ + finished,
│ │ │ │ + };
│ │ │ │ +
│ │ │ │ + unsigned bytes_progress:15;
│ │ │ │ + unsigned block_size:15;
│ │ │ │ + unsigned state:2;
│ │ │ │ + unsigned num_peers:14;
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
peer() set_peer()
│ │ │ │ +
│ │ │ │ +tcp::endpoint peer () const;
│ │ │ │ +void set_peer (tcp::endpoint const& ep);
│ │ │ │ +
│ │ │ │ +
The peer is the ip address of the peer this block was downloaded from.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
enum block_state_t
│ │ │ │ +
Declared in "libtorrent/torrent_handle.hpp"
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +| name |
│ │ │ │ +value |
│ │ │ │ +description |
│ │ │ │ +
|---|
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +| none |
│ │ │ │ +0 |
│ │ │ │ +This block has not been downloaded or requested form any peer. |
│ │ │ │ +
│ │ │ │ +| requested |
│ │ │ │ +1 |
│ │ │ │ +The block has been requested, but not completely downloaded yet. |
│ │ │ │ +
│ │ │ │ +| writing |
│ │ │ │ +2 |
│ │ │ │ +The block has been downloaded and is currently queued for being
│ │ │ │ +written to disk. |
│ │ │ │ +
│ │ │ │ +| finished |
│ │ │ │ +3 |
│ │ │ │ +The block has been written to disk. |
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- bytes_progress
│ │ │ │ +- the number of bytes that have been received for this block
│ │ │ │
│ │ │ │ -
[report issue]
│ │ │ │ -- open_mode
│ │ │ │ -open_mode is a bitmask of the file flags this file is currently
│ │ │ │ -opened with. For possible flags, see file_open_mode_t.
│ │ │ │ -Note that the read/write mode is not a bitmask. The two least significant bits are used
│ │ │ │ -to represent the read/write mode. Those bits can be masked out using the rw_mask constant.
│ │ │ │ -
│ │ │ │ +- block_size
│ │ │ │ +- the total number of bytes in this block.
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -- last_use
│ │ │ │ -- a (high precision) timestamp of when the file was last used.
│ │ │ │ +[report issue]
│ │ │ │ +- state
│ │ │ │ +- the state this block is in (see block_state_t)
│ │ │ │
│ │ │ │ -[report issue]
│ │ │ │ -
│ │ │ │ -
disk_interface
│ │ │ │ -
Declared in "libtorrent/disk_interface.hpp"
│ │ │ │ -
The disk_interface is the customization point for disk I/O in libtorrent.
│ │ │ │ -implement this interface and provide a factory function to the session constructor
│ │ │ │ -use custom disk I/O. All functions on the disk subsystem (implementing
│ │ │ │ -disk_interface) are called from within libtorrent's network thread. For
│ │ │ │ -disk I/O to be performed in a separate thread, the disk subsystem has to
│ │ │ │ -manage that itself.
│ │ │ │ -
Although the functions are called async_*, they do not technically
│ │ │ │ -have to be asynchronous, but they support being asynchronous, by
│ │ │ │ -expecting the result passed back into a callback. The callbacks must be
│ │ │ │ -posted back onto the network thread via the io_context object passed into
│ │ │ │ -the constructor. The callbacks will be run in the network thread.
│ │ │ │ +
[report issue]
│ │ │ │ +- num_peers
│ │ │ │ +- the number of peers that is currently requesting this block. Typically
│ │ │ │ +this is 0 or 1, but at the end of the torrent blocks may be requested
│ │ │ │ +by more peers in parallel to speed things up.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
partial_piece_info
│ │ │ │ +
Declared in "libtorrent/torrent_handle.hpp"
│ │ │ │ +
This class holds information about pieces that have outstanding requests
│ │ │ │ +or outstanding writes
│ │ │ │ +
│ │ │ │ +struct partial_piece_info
│ │ │ │ +{
│ │ │ │ + piece_index_t piece_index;
│ │ │ │ + int blocks_in_piece;
│ │ │ │ + int finished;
│ │ │ │ + int writing;
│ │ │ │ + int requested;
│ │ │ │ + block_info const* blocks;
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- piece_index
│ │ │ │ +- the index of the piece in question. blocks_in_piece is the number
│ │ │ │ +of blocks in this particular piece. This number will be the same for
│ │ │ │ +most pieces, but
│ │ │ │ +the last piece may have fewer blocks than the standard pieces.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- blocks_in_piece
│ │ │ │ +- the number of blocks in this piece
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- finished
│ │ │ │ +- the number of blocks that are in the finished state
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- writing
│ │ │ │ +- the number of blocks that are in the writing state
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- requested
│ │ │ │ +- the number of blocks that are in the requested state
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +- blocks
│ │ │ │ +this is an array of blocks_in_piece number of
│ │ │ │ +items. One for each block in the piece.
│ │ │ │ +
│ │ │ │ +
Warning
│ │ │ │ +
This is a pointer that points to an array
│ │ │ │ +that's owned by the session object. The next time
│ │ │ │ +get_download_queue() is called, it will be invalidated.
│ │ │ │ +In the case of piece_info_alert, these pointers point into the alert
│ │ │ │ +object itself, and will be invalidated when the alert destruct.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
torrent_handle
│ │ │ │ +
Declared in "libtorrent/torrent_handle.hpp"
│ │ │ │ +
You will usually have to store your torrent handles somewhere, since it's
│ │ │ │ +the object through which you retrieve information about the torrent and
│ │ │ │ +aborts the torrent.
│ │ │ │ +
│ │ │ │ +
Warning
│ │ │ │ +
Any member function that returns a value or fills in a value has to be
│ │ │ │ +made synchronously. This means it has to wait for the main thread to
│ │ │ │ +complete the query before it can return. This might potentially be
│ │ │ │ +expensive if done from within a GUI thread that needs to stay
│ │ │ │ +responsive. Try to avoid querying for information you don't need, and
│ │ │ │ +try to do it in as few calls as possible. You can get most of the
│ │ │ │ +interesting information about a torrent from the
│ │ │ │ +torrent_handle::status() call.
│ │ │ │ +
│ │ │ │ +
The default constructor will initialize the handle to an invalid state.
│ │ │ │ +Which means you cannot perform any operation on it, unless you first
│ │ │ │ +assign it a valid handle. If you try to perform any operation on an
│ │ │ │ +uninitialized handle, it will throw invalid_handle.
│ │ │ │ +
│ │ │ │ +
Warning
│ │ │ │ +
All operations on a torrent_handle may throw system_error
│ │ │ │ +exception, in case the handle is no longer referring to a torrent.
│ │ │ │ +There is one exception is_valid() will never throw. Since the torrents
│ │ │ │ +are processed by a background thread, there is no guarantee that a
│ │ │ │ +handle will remain valid between two calls.
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +struct torrent_handle
│ │ │ │ +{
│ │ │ │ + friend std::size_t hash_value (torrent_handle const& th);
│ │ │ │ + torrent_handle () noexcept = default;
│ │ │ │ + void add_piece (piece_index_t piece, char const* data, add_piece_flags_t flags = {}) const;
│ │ │ │ + void add_piece (piece_index_t piece, std::vector<char> data, add_piece_flags_t flags = {}) const;
│ │ │ │ + void read_piece (piece_index_t piece) const;
│ │ │ │ + bool have_piece (piece_index_t piece) const;
│ │ │ │ + void post_peer_info () const;
│ │ │ │ + void get_peer_info (std::vector<peer_info>& v) const;
│ │ │ │ + torrent_status status (status_flags_t flags = status_flags_t::all()) const;
│ │ │ │ + void post_status (status_flags_t flags = status_flags_t::all()) const;
│ │ │ │ + std::vector<partial_piece_info> get_download_queue () const;
│ │ │ │ + void get_download_queue (std::vector<partial_piece_info>& queue) const;
│ │ │ │ + void post_download_queue () const;
│ │ │ │ + void set_piece_deadline (piece_index_t index, int deadline, deadline_flags_t flags = {}) const;
│ │ │ │ + void reset_piece_deadline (piece_index_t index) const;
│ │ │ │ + void clear_piece_deadlines () const;
│ │ │ │ + std::vector<std::int64_t> file_progress (file_progress_flags_t flags = {}) const;
│ │ │ │ + void file_progress (std::vector<std::int64_t>& progress, file_progress_flags_t flags = {}) const;
│ │ │ │ + void post_file_progress (file_progress_flags_t flags) const;
│ │ │ │ + std::vector<open_file_state> file_status () const;
│ │ │ │ + void clear_error () const;
│ │ │ │ + void post_trackers () const;
│ │ │ │ + void add_tracker (announce_entry const&) const;
│ │ │ │ + std::vector<announce_entry> trackers () const;
│ │ │ │ + void replace_trackers (std::vector<announce_entry> const&) const;
│ │ │ │ + std::set<std::string> url_seeds () const;
│ │ │ │ + void add_url_seed (std::string const& url) const;
│ │ │ │ + void remove_url_seed (std::string const& url) const;
│ │ │ │ + std::set<std::string> http_seeds () const;
│ │ │ │ + void add_http_seed (std::string const& url) const;
│ │ │ │ + void remove_http_seed (std::string const& url) const;
│ │ │ │ + void add_extension (
│ │ │ │ + std::function<std::shared_ptr<torrent_plugin>(torrent_handle const&, client_data_t)> const& ext
│ │ │ │ + , client_data_t userdata = client_data_t{});
│ │ │ │ + bool set_metadata (span<char const> metadata) const;
│ │ │ │ + bool is_valid () const;
│ │ │ │ + void pause (pause_flags_t flags = {}) const;
│ │ │ │ + void resume () const;
│ │ │ │ + torrent_flags_t flags () const;
│ │ │ │ + void set_flags (torrent_flags_t flags, torrent_flags_t mask) const;
│ │ │ │ + void set_flags (torrent_flags_t flags) const;
│ │ │ │ + void unset_flags (torrent_flags_t flags) const;
│ │ │ │ + void flush_cache () const;
│ │ │ │ + void force_recheck () const;
│ │ │ │ + void save_resume_data (resume_data_flags_t flags = {}) const;
│ │ │ │ + bool need_save_resume_data (resume_data_flags_t flags) const;
│ │ │ │ + bool need_save_resume_data () const;
│ │ │ │ + void queue_position_bottom () const;
│ │ │ │ + void queue_position_down () const;
│ │ │ │ + void queue_position_top () const;
│ │ │ │ + void queue_position_up () const;
│ │ │ │ + queue_position_t queue_position () const;
│ │ │ │ + void queue_position_set (queue_position_t p) const;
│ │ │ │ + void set_ssl_certificate_buffer (std::string const& certificate
│ │ │ │ + , std::string const& private_key
│ │ │ │ + , std::string const& dh_params);
│ │ │ │ + void set_ssl_certificate (std::string const& certificate
│ │ │ │ + , std::string const& private_key
│ │ │ │ + , std::string const& dh_params
│ │ │ │ + , std::string const& passphrase = "");
│ │ │ │ + std::shared_ptr<torrent_info> torrent_file_with_hashes () const;
│ │ │ │ + std::shared_ptr<const torrent_info> torrent_file () const;
│ │ │ │ + std::vector<std::vector<sha256_hash>> piece_layers () const;
│ │ │ │ + void piece_availability (std::vector<int>& avail) const;
│ │ │ │ + void post_piece_availability () const;
│ │ │ │ + void prioritize_pieces (std::vector<std::pair<piece_index_t, download_priority_t>> const& pieces) const;
│ │ │ │ + download_priority_t piece_priority (piece_index_t index) const;
│ │ │ │ + void piece_priority (piece_index_t index, download_priority_t priority) const;
│ │ │ │ + std::vector<download_priority_t> get_piece_priorities () const;
│ │ │ │ + void prioritize_pieces (std::vector<download_priority_t> const& pieces) const;
│ │ │ │ + void prioritize_files (std::vector<download_priority_t> const& files) const;
│ │ │ │ + void file_priority (file_index_t index, download_priority_t priority) const;
│ │ │ │ + download_priority_t file_priority (file_index_t index) const;
│ │ │ │ + std::vector<download_priority_t> get_file_priorities () const;
│ │ │ │ + void force_reannounce (int seconds = 0, int idx = -1, reannounce_flags_t = {}) const;
│ │ │ │ + void force_lsd_announce () const;
│ │ │ │ + void force_dht_announce () const;
│ │ │ │ + void scrape_tracker (int idx = -1) const;
│ │ │ │ + void set_upload_limit (int limit) const;
│ │ │ │ + void set_download_limit (int limit) const;
│ │ │ │ + int download_limit () const;
│ │ │ │ + int upload_limit () const;
│ │ │ │ + void connect_peer (tcp::endpoint const& adr, peer_source_flags_t source = {}
│ │ │ │ + , pex_flags_t flags = pex_encryption | pex_utp | pex_holepunch) const;
│ │ │ │ + void clear_peers ();
│ │ │ │ + void set_max_uploads (int max_uploads) const;
│ │ │ │ + int max_uploads () const;
│ │ │ │ + void set_max_connections (int max_connections) const;
│ │ │ │ + int max_connections () const;
│ │ │ │ + void move_storage (std::string const& save_path
│ │ │ │ + , move_flags_t flags = move_flags_t::always_replace_files
│ │ │ │ + ) const;
│ │ │ │ + void rename_file (file_index_t index, std::string const& new_name) const;
│ │ │ │ + sha1_hash info_hash () const;
│ │ │ │ + info_hash_t info_hashes () const;
│ │ │ │ + bool operator== (const torrent_handle& h) const;
│ │ │ │ + bool operator!= (const torrent_handle& h) const;
│ │ │ │ + bool operator< (const torrent_handle& h) const;
│ │ │ │ + std::uint32_t id () const;
│ │ │ │ + std::shared_ptr<torrent> native_handle () const;
│ │ │ │ + client_data_t userdata () const;
│ │ │ │ + bool in_session () const;
│ │ │ │ +
│ │ │ │ + static constexpr add_piece_flags_t overwrite_existing = 0_bit;
│ │ │ │ + static constexpr status_flags_t query_distributed_copies = 0_bit;
│ │ │ │ + static constexpr status_flags_t query_accurate_download_counters = 1_bit;
│ │ │ │ + static constexpr status_flags_t query_last_seen_complete = 2_bit;
│ │ │ │ + static constexpr status_flags_t query_pieces = 3_bit;
│ │ │ │ + static constexpr status_flags_t query_verified_pieces = 4_bit;
│ │ │ │ + static constexpr status_flags_t query_torrent_file = 5_bit;
│ │ │ │ + static constexpr status_flags_t query_name = 6_bit;
│ │ │ │ + static constexpr status_flags_t query_save_path = 7_bit;
│ │ │ │ + static constexpr deadline_flags_t alert_when_available = 0_bit;
│ │ │ │ + static constexpr file_progress_flags_t piece_granularity = 0_bit;
│ │ │ │ + static constexpr pause_flags_t graceful_pause = 0_bit;
│ │ │ │ + static constexpr resume_data_flags_t flush_disk_cache = 0_bit;
│ │ │ │ + static constexpr resume_data_flags_t save_info_dict = 1_bit;
│ │ │ │ + static constexpr resume_data_flags_t only_if_modified = 2_bit;
│ │ │ │ + static constexpr resume_data_flags_t if_counters_changed = 3_bit;
│ │ │ │ + static constexpr resume_data_flags_t if_download_progress = 4_bit;
│ │ │ │ + static constexpr resume_data_flags_t if_config_changed = 5_bit;
│ │ │ │ + static constexpr resume_data_flags_t if_state_changed = 6_bit;
│ │ │ │ + static constexpr resume_data_flags_t if_metadata_changed = 7_bit;
│ │ │ │ + static constexpr reannounce_flags_t ignore_min_interval = 0_bit;
│ │ │ │ +};
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
torrent_handle()
│ │ │ │ +
│ │ │ │ +torrent_handle () noexcept = default;
│ │ │ │ +
│ │ │ │ +
constructs a torrent handle that does not refer to a torrent.
│ │ │ │ +i.e. is_valid() will return false.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
add_piece()
│ │ │ │ +
│ │ │ │ +void add_piece (piece_index_t piece, char const* data, add_piece_flags_t flags = {}) const;
│ │ │ │ +void add_piece (piece_index_t piece, std::vector<char> data, add_piece_flags_t flags = {}) const;
│ │ │ │ +
│ │ │ │ +
This function will write data to the storage as piece piece,
│ │ │ │ +as if it had been downloaded from a peer.
│ │ │ │ +
By default, data that's already been downloaded is not overwritten by
│ │ │ │ +this buffer. If you trust this data to be correct (and pass the piece
│ │ │ │ +hash check) you may pass the overwrite_existing flag. This will
│ │ │ │ +instruct libtorrent to overwrite any data that may already have been
│ │ │ │ +downloaded with this data.
│ │ │ │ +
Since the data is written asynchronously, you may know that is passed
│ │ │ │ +or failed the hash check by waiting for piece_finished_alert or
│ │ │ │ +hash_failed_alert.
│ │ │ │ +
Adding pieces while the torrent is being checked (i.e. in
│ │ │ │ +torrent_status::checking_files state) is not supported.
│ │ │ │ +
The overload taking a raw pointer to the data is a blocking call. It
│ │ │ │ +won't return until the libtorrent thread has copied the data into its
│ │ │ │ +disk write buffer. data is expected to point to a buffer of as
│ │ │ │ +many bytes as the size of the specified piece. See
│ │ │ │ +file_storage::piece_size().
│ │ │ │ +
The data in the buffer is copied and passed on to the disk IO thread
│ │ │ │ +to be written at a later point.
│ │ │ │ +
The overload taking a std::vector<char> is not blocking, it will
│ │ │ │ +send the buffer to the main thread and return immediately.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
read_piece()
│ │ │ │ +
│ │ │ │ +void read_piece (piece_index_t piece) const;
│ │ │ │ +
│ │ │ │ +
This function starts an asynchronous read operation of the specified
│ │ │ │ +piece from this torrent. You must have completed the download of the
│ │ │ │ +specified piece before calling this function.
│ │ │ │ +
When the read operation is completed, it is passed back through an
│ │ │ │ +alert, read_piece_alert. Since this alert is a response to an explicit
│ │ │ │ +call, it will always be posted, regardless of the alert mask.
│ │ │ │ +
Note that if you read multiple pieces, the read operations are not
│ │ │ │ +guaranteed to finish in the same order as you initiated them.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
have_piece()
│ │ │ │ +
│ │ │ │ +bool have_piece (piece_index_t piece) const;
│ │ │ │ +
│ │ │ │ +
Returns true if this piece has been completely downloaded and written
│ │ │ │ +to disk, and false otherwise.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
post_peer_info() get_peer_info()
│ │ │ │ +
│ │ │ │ +void post_peer_info () const;
│ │ │ │ +void get_peer_info (std::vector<peer_info>& v) const;
│ │ │ │ +
│ │ │ │ +
Query information about connected peers for this torrent. If the
│ │ │ │ +torrent_handle is invalid, it will throw a system_error exception.
│ │ │ │ +
post_peer_info() is asynchronous and will trigger the posting of
│ │ │ │ +a peer_info_alert. The alert contain a list of peer_info objects, one
│ │ │ │ +for each connected peer.
│ │ │ │ +
get_peer_info() is synchronous and takes a reference to a vector
│ │ │ │ +that will be cleared and filled with one entry for each peer
│ │ │ │ +connected to this torrent, given the handle is valid. Each entry in
│ │ │ │ +the vector contains information about that particular peer. See
│ │ │ │ +peer_info.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
post_status() status()
│ │ │ │ +
│ │ │ │ +torrent_status status (status_flags_t flags = status_flags_t::all()) const;
│ │ │ │ +void post_status (status_flags_t flags = status_flags_t::all()) const;
│ │ │ │ +
│ │ │ │ +
status() will return a structure with information about the status
│ │ │ │ +of this torrent. If the torrent_handle is invalid, it will throw
│ │ │ │ +system_error exception. See torrent_status. The flags
│ │ │ │ +argument filters what information is returned in the torrent_status.
│ │ │ │ +Some information in there is relatively expensive to calculate, and if
│ │ │ │ +you're not interested in it (and see performance issues), you can
│ │ │ │ +filter them out.
│ │ │ │ +
The status() function will block until the internal libtorrent
│ │ │ │ +thread responds with the torrent_status object. To avoid blocking,
│ │ │ │ +instead call post_status(). It will trigger posting of a
│ │ │ │ +state_update_alert with a single torrent_status object for this
│ │ │ │ +torrent.
│ │ │ │ +
In order to get regular updates for torrents whose status changes,
│ │ │ │ +consider calling session::post_torrent_updates()`` instead.
│ │ │ │ +
By default everything is included. The flags you can use to decide
│ │ │ │ +what to include are defined in this class.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
get_download_queue() post_download_queue()
│ │ │ │ +
│ │ │ │ +std::vector<partial_piece_info> get_download_queue () const;
│ │ │ │ +void get_download_queue (std::vector<partial_piece_info>& queue) const;
│ │ │ │ +void post_download_queue () const;
│ │ │ │ +
│ │ │ │ +
post_download_queue() triggers a download_queue_alert to be
│ │ │ │ +posted.
│ │ │ │ +get_download_queue() is a synchronous call and returns a vector
│ │ │ │ +with information about pieces that are partially downloaded or not
│ │ │ │ +downloaded but partially requested. See partial_piece_info for the
│ │ │ │ +fields in the returned vector.
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
reset_piece_deadline() clear_piece_deadlines() set_piece_deadline()
│ │ │ │ +
│ │ │ │ +void set_piece_deadline (piece_index_t index, int deadline, deadline_flags_t flags = {}) const;
│ │ │ │ +void reset_piece_deadline (piece_index_t index) const;
│ │ │ │ +void clear_piece_deadlines () const;
│ │ │ │ +
│ │ │ │ +
This function sets or resets the deadline associated with a specific
│ │ │ │ +piece index (index). libtorrent will attempt to download this
│ │ │ │ +entire piece before the deadline expires. This is not necessarily
│ │ │ │ +possible, but pieces with a more recent deadline will always be
│ │ │ │ +prioritized over pieces with a deadline further ahead in time. The
│ │ │ │ +deadline (and flags) of a piece can be changed by calling this
│ │ │ │ +function again.
│ │ │ │ +
If the piece is already downloaded when this call is made, nothing
│ │ │ │ +happens, unless the alert_when_available flag is set, in which case it
│ │ │ │ +will have the same effect as calling read_piece() for index.
│ │ │ │ +
deadline is the number of milliseconds until this piece should be
│ │ │ │ +completed.
│ │ │ │ +
reset_piece_deadline removes the deadline from the piece. If it
│ │ │ │ +hasn't already been downloaded, it will no longer be considered a
│ │ │ │ +priority.
│ │ │ │ +
clear_piece_deadlines() removes deadlines on all pieces in
│ │ │ │ +the torrent. As if reset_piece_deadline() was called on all pieces.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
file_progress() post_file_progress()
│ │ │ │ +
│ │ │ │ +std::vector<std::int64_t> file_progress (file_progress_flags_t flags = {}) const;
│ │ │ │ +void file_progress (std::vector<std::int64_t>& progress, file_progress_flags_t flags = {}) const;
│ │ │ │ +void post_file_progress (file_progress_flags_t flags) const;
│ │ │ │ +
│ │ │ │ +
This function fills in the supplied vector, or returns a vector, with
│ │ │ │ +the number of bytes downloaded of each file in this torrent. The
│ │ │ │ +progress values are ordered the same as the files in the
│ │ │ │ +torrent_info.
│ │ │ │ +
This operation is not very cheap. Its complexity is O(n + mj).
│ │ │ │ +Where n is the number of files, m is the number of currently
│ │ │ │ +downloading pieces and j is the number of blocks in a piece.
│ │ │ │ +
The flags parameter can be used to specify the granularity of the
│ │ │ │ +file progress. If left at the default value of 0, the progress will be
│ │ │ │ +as accurate as possible, but also more expensive to calculate. If
│ │ │ │ +torrent_handle::piece_granularity is specified, the progress will
│ │ │ │ +be specified in piece granularity. i.e. only pieces that have been
│ │ │ │ +fully downloaded and passed the hash check count. When specifying
│ │ │ │ +piece granularity, the operation is a lot cheaper, since libtorrent
│ │ │ │ +already keeps track of this internally and no calculation is required.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
file_status()
│ │ │ │ +
│ │ │ │ +std::vector<open_file_state> file_status () const;
│ │ │ │ +
│ │ │ │ +
This function returns a vector with status about files
│ │ │ │ +that are open for this torrent. Any file that is not open
│ │ │ │ +will not be reported in the vector, i.e. it's possible that
│ │ │ │ +the vector is empty when returning, if none of the files in the
│ │ │ │ +torrent are currently open.
│ │ │ │ +
See open_file_state
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
clear_error()
│ │ │ │ +
│ │ │ │ +void clear_error () const;
│ │ │ │ +
│ │ │ │ +
If the torrent is in an error state (i.e. torrent_status::error is
│ │ │ │ +non-empty), this will clear the error and start the torrent again.
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
add_tracker() trackers() post_trackers() replace_trackers()
│ │ │ │ +
│ │ │ │ +void post_trackers () const;
│ │ │ │ +void add_tracker (announce_entry const&) const;
│ │ │ │ +std::vector<announce_entry> trackers () const;
│ │ │ │ +void replace_trackers (std::vector<announce_entry> const&) const;
│ │ │ │ +
│ │ │ │ +
trackers() returns the list of trackers for this torrent. The
│ │ │ │ +announce entry contains both a string url which specify the
│ │ │ │ +announce url for the tracker as well as an int tier, which is
│ │ │ │ +specifies the order in which this tracker is tried. If you want
│ │ │ │ +libtorrent to use another list of trackers for this torrent, you can
│ │ │ │ +use replace_trackers() which takes a list of the same form as the
│ │ │ │ +one returned from trackers() and will replace it. If you want an
│ │ │ │ +immediate effect, you have to call force_reannounce(). See
│ │ │ │ +announce_entry.
│ │ │ │ +
post_trackers() is the asynchronous version of trackers(). It
│ │ │ │ +will trigger a tracker_list_alert to be posted.
│ │ │ │ +
add_tracker() will look if the specified tracker is already in the
│ │ │ │ +set. If it is, it doesn't do anything. If it's not in the current set
│ │ │ │ +of trackers, it will insert it in the tier specified in the
│ │ │ │ +announce_entry.
│ │ │ │ +
The updated set of trackers will be saved in the resume data, and when
│ │ │ │ +a torrent is started with resume data, the trackers from the resume
│ │ │ │ +data will replace the original ones.
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
url_seeds() remove_url_seed() add_url_seed()
│ │ │ │ +
│ │ │ │ +std::set<std::string> url_seeds () const;
│ │ │ │ +void add_url_seed (std::string const& url) const;
│ │ │ │ +void remove_url_seed (std::string const& url) const;
│ │ │ │ +
│ │ │ │ +
add_url_seed() adds another url to the torrent's list of url
│ │ │ │ +seeds. If the given url already exists in that list, the call has no
│ │ │ │ +effect. The torrent will connect to the server and try to download
│ │ │ │ +pieces from it, unless it's paused, queued, checking or seeding.
│ │ │ │ +remove_url_seed() removes the given url if it exists already.
│ │ │ │ +url_seeds() return a set of the url seeds currently in this
│ │ │ │ +torrent. Note that URLs that fails may be removed automatically from
│ │ │ │ +the list.
│ │ │ │ +
See http seeding for more information.
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
remove_http_seed() add_http_seed() http_seeds()
│ │ │ │ +
│ │ │ │ +std::set<std::string> http_seeds () const;
│ │ │ │ +void add_http_seed (std::string const& url) const;
│ │ │ │ +void remove_http_seed (std::string const& url) const;
│ │ │ │ +
│ │ │ │ +
These functions are identical as the *_url_seed() variants, but
│ │ │ │ +they operate on BEP 17 web seeds instead of BEP 19.
│ │ │ │ +
See http seeding for more information.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
add_extension()
│ │ │ │
│ │ │ │ -struct disk_interface
│ │ │ │ -{
│ │ │ │ - virtual storage_holder new_torrent (storage_params const& p
│ │ │ │ - , std::shared_ptr<void> const& torrent) = 0;
│ │ │ │ - virtual void remove_torrent (storage_index_t) = 0;
│ │ │ │ - virtual bool async_write (storage_index_t storage, peer_request const& r
│ │ │ │ - , char const* buf, std::shared_ptr<disk_observer> o
│ │ │ │ - , std::function<void(storage_error const&)> handler
│ │ │ │ - , disk_job_flags_t flags = {}) = 0;
│ │ │ │ - virtual void async_read (storage_index_t storage, peer_request const& r
│ │ │ │ - , std::function<void(disk_buffer_holder, storage_error const&)> handler
│ │ │ │ - , disk_job_flags_t flags = {}) = 0;
│ │ │ │ - virtual void async_hash (storage_index_t storage, piece_index_t piece, span<sha256_hash> v2
│ │ │ │ - , disk_job_flags_t flags
│ │ │ │ - , std::function<void(piece_index_t, sha1_hash const&, storage_error const&)> handler) = 0;
│ │ │ │ - virtual void async_hash2 (storage_index_t storage, piece_index_t piece, int offset, disk_job_flags_t flags
│ │ │ │ - , std::function<void(piece_index_t, sha256_hash const&, storage_error const&)> handler) = 0;
│ │ │ │ - virtual void async_move_storage (storage_index_t storage, std::string p, move_flags_t flags
│ │ │ │ - , std::function<void(status_t, std::string const&, storage_error const&)> handler) = 0;
│ │ │ │ - virtual void async_release_files (storage_index_t storage
│ │ │ │ - , std::function<void()> handler = std::function<void()>()) = 0;
│ │ │ │ - virtual void async_check_files (storage_index_t storage
│ │ │ │ - , add_torrent_params const* resume_data
│ │ │ │ - , aux::vector<std::string, file_index_t> links
│ │ │ │ - , std::function<void(status_t, storage_error const&)> handler) = 0;
│ │ │ │ - virtual void async_stop_torrent (storage_index_t storage
│ │ │ │ - , std::function<void()> handler = std::function<void()>()) = 0;
│ │ │ │ - virtual void async_rename_file (storage_index_t storage
│ │ │ │ - , file_index_t index, std::string name
│ │ │ │ - , std::function<void(std::string const&, file_index_t, storage_error const&)> handler) = 0;
│ │ │ │ - virtual void async_delete_files (storage_index_t storage, remove_flags_t options
│ │ │ │ - , std::function<void(storage_error const&)> handler) = 0;
│ │ │ │ - virtual void async_set_file_priority (storage_index_t storage
│ │ │ │ - , aux::vector<download_priority_t, file_index_t> prio
│ │ │ │ - , std::function<void(storage_error const&
│ │ │ │ - , aux::vector<download_priority_t, file_index_t>)> handler) = 0;
│ │ │ │ - virtual void async_clear_piece (storage_index_t storage, piece_index_t index
│ │ │ │ - , std::function<void(piece_index_t)> handler) = 0;
│ │ │ │ - virtual void update_stats_counters (counters& c) const = 0;
│ │ │ │ - virtual std::vector<open_file_state> get_status (storage_index_t) const = 0;
│ │ │ │ - virtual void abort (bool wait) = 0;
│ │ │ │ - virtual void submit_jobs () = 0;
│ │ │ │ - virtual void settings_updated () = 0;
│ │ │ │ -
│ │ │ │ - static constexpr disk_job_flags_t force_copy = 0_bit;
│ │ │ │ - static constexpr disk_job_flags_t sequential_access = 3_bit;
│ │ │ │ - static constexpr disk_job_flags_t volatile_read = 4_bit;
│ │ │ │ - static constexpr disk_job_flags_t v1_hash = 5_bit;
│ │ │ │ - static constexpr disk_job_flags_t flush_piece = 7_bit;
│ │ │ │ -};
│ │ │ │ +void add_extension (
│ │ │ │ + std::function<std::shared_ptr<torrent_plugin>(torrent_handle const&, client_data_t)> const& ext
│ │ │ │ + , client_data_t userdata = client_data_t{});
│ │ │ │
│ │ │ │ -
[report issue]
│ │ │ │ -
new_torrent()
│ │ │ │ +
add the specified extension to this torrent. The ext argument is
│ │ │ │ +a function that will be called from within libtorrent's context
│ │ │ │ +passing in the internal torrent object and the specified userdata
│ │ │ │ +pointer. The function is expected to return a shared pointer to
│ │ │ │ +a torrent_plugin instance.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ -
│ │ │ │ -
remove_torrent()
│ │ │ │ +
set_metadata expects the info section of metadata. i.e. The
│ │ │ │ +buffer passed in will be hashed and verified against the info-hash. If
│ │ │ │ +it fails, a metadata_failed_alert will be generated. If it passes,
│ │ │ │ +a metadata_received_alert is generated. The function returns true
│ │ │ │ +if the metadata is successfully set on the torrent, and false
│ │ │ │ +otherwise. If the torrent already has metadata, this function will not
│ │ │ │ +affect the torrent, and false will be returned.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
is_valid()
│ │ │ │
│ │ │ │ -virtual void remove_torrent (storage_index_t) = 0;
│ │ │ │ +bool is_valid () const;
│ │ │ │
│ │ │ │ -
remove the storage with the specified index. This is not expected to
│ │ │ │ -delete any files from disk, just to clean up any resources associated
│ │ │ │ -with the specified storage.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
async_write() async_read()
│ │ │ │ +
Returns true if this handle refers to a valid torrent and false if it
│ │ │ │ +hasn't been initialized or if the torrent it refers to has been
│ │ │ │ +removed from the session AND destructed.
│ │ │ │ +
To tell if the torrent_handle is in the session, use
│ │ │ │ +torrent_handle::in_session(). This will return true before
│ │ │ │ +session_handle::remove_torrent() is called, and false
│ │ │ │ +afterward.
│ │ │ │ +
Clients should only use is_valid() to determine if the result of
│ │ │ │ +session::find_torrent() was successful.
│ │ │ │ +
Unlike other member functions which return a value, is_valid()
│ │ │ │ +completes immediately, without blocking on a result from the
│ │ │ │ +network thread. Also unlike other functions, it never throws
│ │ │ │ +the system_error exception.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
resume() pause()
│ │ │ │
│ │ │ │ -virtual bool async_write (storage_index_t storage, peer_request const& r
│ │ │ │ - , char const* buf, std::shared_ptr<disk_observer> o
│ │ │ │ - , std::function<void(storage_error const&)> handler
│ │ │ │ - , disk_job_flags_t flags = {}) = 0;
│ │ │ │ -virtual void async_read (storage_index_t storage, peer_request const& r
│ │ │ │ - , std::function<void(disk_buffer_holder, storage_error const&)> handler
│ │ │ │ - , disk_job_flags_t flags = {}) = 0;
│ │ │ │ +void pause (pause_flags_t flags = {}) const;
│ │ │ │ +void resume () const;
│ │ │ │
│ │ │ │ -
perform a read or write operation from/to the specified storage
│ │ │ │ -index and the specified request. When the operation completes, call
│ │ │ │ -handler possibly with a disk_buffer_holder, holding the buffer with
│ │ │ │ -the result. Flags may be set to affect the read operation. See
│ │ │ │ -disk_job_flags_t.
│ │ │ │ -
The disk_observer is a callback to indicate that
│ │ │ │ -the store buffer/disk write queue is below the watermark to let peers
│ │ │ │ -start writing buffers to disk again. When async_write() returns
│ │ │ │ -true, indicating the write queue is full, the peer will stop
│ │ │ │ -further writes and wait for the passed-in disk_observer to be
│ │ │ │ -notified before resuming.
│ │ │ │ -
Note that for async_read, the peer_request (r) is not
│ │ │ │ -necessarily aligned to blocks (but it is most of the time). However,
│ │ │ │ -all writes (passed to async_write) are guaranteed to be block
│ │ │ │ -aligned.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
async_hash()
│ │ │ │ +
pause(), and resume() will disconnect all peers and reconnect
│ │ │ │ +all peers respectively. When a torrent is paused, it will however
│ │ │ │ +remember all share ratios to all peers and remember all potential (not
│ │ │ │ +connected) peers. Torrents may be paused automatically if there is a
│ │ │ │ +file error (e.g. disk full) or something similar. See
│ │ │ │ +file_error_alert.
│ │ │ │ +
For possible values of the flags parameter, see pause_flags_t.
│ │ │ │ +
To know if a torrent is paused or not, call
│ │ │ │ +torrent_handle::flags() and check for the
│ │ │ │ +torrent_status::paused flag.
│ │ │ │ +
│ │ │ │ +
Note
│ │ │ │ +
Torrents that are auto-managed may be automatically resumed again. It
│ │ │ │ +does not make sense to pause an auto-managed torrent without making it
│ │ │ │ +not auto-managed first. Torrents are auto-managed by default when added
│ │ │ │ +to the session. For more information, see queuing.
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
set_flags() flags() unset_flags()
│ │ │ │
│ │ │ │ -virtual void async_hash (storage_index_t storage, piece_index_t piece, span<sha256_hash> v2
│ │ │ │ - , disk_job_flags_t flags
│ │ │ │ - , std::function<void(piece_index_t, sha1_hash const&, storage_error const&)> handler) = 0;
│ │ │ │ +torrent_flags_t flags () const;
│ │ │ │ +void set_flags (torrent_flags_t flags, torrent_flags_t mask) const;
│ │ │ │ +void set_flags (torrent_flags_t flags) const;
│ │ │ │ +void unset_flags (torrent_flags_t flags) const;
│ │ │ │
│ │ │ │ -
Compute hash(es) for the specified piece. Unless the v1_hash flag is
│ │ │ │ -set (in flags), the SHA-1 hash of the whole piece does not need
│ │ │ │ -to be computed.
│ │ │ │ -
The v2 span is optional and can be empty, which means v2 hashes
│ │ │ │ -should not be computed. If v2 is non-empty it must be at least large
│ │ │ │ -enough to hold all v2 blocks in the piece, and this function will
│ │ │ │ -fill in the span with the SHA-256 block hashes of the piece.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
async_hash2()
│ │ │ │ +
sets and gets the torrent state flags. See torrent_flags_t.
│ │ │ │ +The set_flags overload that take a mask will affect all
│ │ │ │ +flags part of the mask, and set their values to what the
│ │ │ │ +flags argument is set to. This allows clearing and
│ │ │ │ +setting flags in a single function call.
│ │ │ │ +The set_flags overload that just takes flags, sets all
│ │ │ │ +the specified flags and leave any other flags unchanged.
│ │ │ │ +unset_flags clears the specified flags, while leaving
│ │ │ │ +any other flags unchanged.
│ │ │ │ +
The seed_mode flag is special, it can only be cleared once the
│ │ │ │ +torrent has been added, and it can only be set as part of the
│ │ │ │ +add_torrent_params flags, when adding the torrent.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
flush_cache()
│ │ │ │
│ │ │ │ -virtual void async_hash2 (storage_index_t storage, piece_index_t piece, int offset, disk_job_flags_t flags
│ │ │ │ - , std::function<void(piece_index_t, sha256_hash const&, storage_error const&)> handler) = 0;
│ │ │ │ +void flush_cache () const;
│ │ │ │
│ │ │ │ -
computes the v2 hash (SHA-256) of a single block. The block at
│ │ │ │ -offset in piece piece.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
async_move_storage()
│ │ │ │ +
Instructs libtorrent to flush all the disk caches for this torrent and
│ │ │ │ +close all file handles. This is done asynchronously and you will be
│ │ │ │ +notified that it's complete through cache_flushed_alert.
│ │ │ │ +
Note that by the time you get the alert, libtorrent may have cached
│ │ │ │ +more data for the torrent, but you are guaranteed that whatever cached
│ │ │ │ +data libtorrent had by the time you called
│ │ │ │ +torrent_handle::flush_cache() has been written to disk.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
force_recheck()
│ │ │ │
│ │ │ │ -virtual void async_move_storage (storage_index_t storage, std::string p, move_flags_t flags
│ │ │ │ - , std::function<void(status_t, std::string const&, storage_error const&)> handler) = 0;
│ │ │ │ +void force_recheck () const;
│ │ │ │
│ │ │ │ -
called to request the files for the specified storage/torrent be
│ │ │ │ -moved to a new location. It is the disk I/O object's responsibility
│ │ │ │ -to synchronize this with any currently outstanding disk operations to
│ │ │ │ -the storage. Whether files are replaced at the destination path or
│ │ │ │ -not is controlled by flags (see move_flags_t).
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
async_release_files()
│ │ │ │ +
force_recheck puts the torrent back in a state where it assumes to
│ │ │ │ +have no resume data. All peers will be disconnected and the torrent
│ │ │ │ +will stop announcing to the tracker. The torrent will be added to the
│ │ │ │ +checking queue, and will be checked (all the files will be read and
│ │ │ │ +compared to the piece hashes). Once the check is complete, the torrent
│ │ │ │ +will start connecting to peers again, as normal.
│ │ │ │ +The torrent will be placed last in queue, i.e. its queue position
│ │ │ │ +will be the highest of all torrents in the session.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
save_resume_data()
│ │ │ │
│ │ │ │ -virtual void async_release_files (storage_index_t storage
│ │ │ │ - , std::function<void()> handler = std::function<void()>()) = 0;
│ │ │ │ +void save_resume_data (resume_data_flags_t flags = {}) const;
│ │ │ │
│ │ │ │ -
This is called on disk I/O objects to request they close all open
│ │ │ │ -files for the specified storage/torrent. If file handles are not
│ │ │ │ -pooled/cached, it can be a no-op. For truly asynchronous disk I/O,
│ │ │ │ -this should provide at least one point in time when all files are
│ │ │ │ -closed. It is possible that later asynchronous operations will
│ │ │ │ -re-open some of the files, by the time this completion handler is
│ │ │ │ -called, that's fine.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
async_check_files()
│ │ │ │ +
save_resume_data() asks libtorrent to generate fast-resume data for
│ │ │ │ +this torrent. The fast resume data (stored in an add_torrent_params
│ │ │ │ +object) can be used to resume a torrent in the next session without
│ │ │ │ +having to check all files for which pieces have been downloaded. It
│ │ │ │ +can also be used to save a .torrent file for a torrent_handle.
│ │ │ │ +
This operation is asynchronous, save_resume_data will return
│ │ │ │ +immediately. The resume data is delivered when it's done through a
│ │ │ │ +save_resume_data_alert.
│ │ │ │ +
The operation will fail, and post a save_resume_data_failed_alert
│ │ │ │ +instead, in the following cases:
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +- The torrent is in the process of being removed.
│ │ │ │ +- No torrent state has changed since the last saving of resume
│ │ │ │ +data, and the only_if_modified flag is set.
│ │ │ │ +metadata (see libtorrent's metadata from peers extension)
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
Note that some counters may be outdated by the time you receive the fast resume data
│ │ │ │ +
When saving resume data because of shutting down, make sure not to
│ │ │ │ +remove_torrent() before you receive the save_resume_data_alert.
│ │ │ │ +There's no need to pause the session or torrent when saving resume
│ │ │ │ +data.
│ │ │ │ +
The paused state of a torrent is saved in the resume data, so pausing
│ │ │ │ +all torrents before saving resume data will all torrents be restored
│ │ │ │ +in a paused state.
│ │ │ │ +
│ │ │ │ +
Note
│ │ │ │ +
It is typically a good idea to save resume data whenever a torrent
│ │ │ │ +is completed or paused. If you save resume data for torrents when they are
│ │ │ │ +paused, you can accelerate the shutdown process by not saving resume
│ │ │ │ +data again for those torrents. Completed torrents should have their
│ │ │ │ +resume data saved when they complete and on exit, since their
│ │ │ │ +statistics might be updated.
│ │ │ │ +
│ │ │ │ +
Example code to pause and save resume data for all torrents and wait
│ │ │ │ +for the alerts:
│ │ │ │ +
│ │ │ │ +extern int outstanding_resume_data; std::vector<torrent_handle> handles = ses.get_torrents();
│ │ │ │ +for (torrent_handle const& h : handles) try
│ │ │ │ +{
│ │ │ │ + h.save_resume_data(torrent_handle::only_if_modified);
│ │ │ │ + ++outstanding_resume_data;
│ │ │ │ +}
│ │ │ │ +catch (lt::system_error const& e)
│ │ │ │ +{
│ │ │ │ + }
│ │ │ │ +
│ │ │ │ +while (outstanding_resume_data > 0)
│ │ │ │ +{
│ │ │ │ + alert const* a = ses.wait_for_alert(seconds(30));
│ │ │ │ +
│ │ │ │ + if (a == nullptr) break;
│ │ │ │ +
│ │ │ │ + std::vector<alert*> alerts;
│ │ │ │ + ses.pop_alerts(&alerts);
│ │ │ │ +
│ │ │ │ + for (alert* i : alerts)
│ │ │ │ + {
│ │ │ │ + if (alert_cast<save_resume_data_failed_alert>(i))
│ │ │ │ + {
│ │ │ │ + process_alert(i);
│ │ │ │ + --outstanding_resume_data;
│ │ │ │ + continue;
│ │ │ │ + }
│ │ │ │ +
│ │ │ │ + save_resume_data_alert const* rd = alert_cast<save_resume_data_alert>(i);
│ │ │ │ + if (rd == nullptr)
│ │ │ │ + {
│ │ │ │ + process_alert(i);
│ │ │ │ + continue;
│ │ │ │ + }
│ │ │ │ +
│ │ │ │ + std::ofstream out((rd->params.save_path
│ │ │ │ + + "/" + rd->params.name + ".fastresume").c_str()
│ │ │ │ + , std::ios_base::binary);
│ │ │ │ + std::vector<char> buf = write_resume_data_buf(rd->params);
│ │ │ │ + out.write(buf.data(), buf.size());
│ │ │ │ + --outstanding_resume_data;
│ │ │ │ + }
│ │ │ │ +}
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
Note
│ │ │ │ +
Note how outstanding_resume_data is a global counter in this
│ │ │ │ +example. This is deliberate, otherwise there is a race condition for
│ │ │ │ +torrents that was just asked to save their resume data, they posted
│ │ │ │ +the alert, but it has not been received yet. Those torrents would
│ │ │ │ +report that they don't need to save resume data again, and skipped by
│ │ │ │ +the initial loop, and thwart the counter otherwise.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
need_save_resume_data()
│ │ │ │
│ │ │ │ -virtual void async_check_files (storage_index_t storage
│ │ │ │ - , add_torrent_params const* resume_data
│ │ │ │ - , aux::vector<std::string, file_index_t> links
│ │ │ │ - , std::function<void(status_t, storage_error const&)> handler) = 0;
│ │ │ │ +bool need_save_resume_data (resume_data_flags_t flags) const;
│ │ │ │ +bool need_save_resume_data () const;
│ │ │ │
│ │ │ │ -
this is called when torrents are added to validate their resume data
│ │ │ │ -against the files on disk. This function is expected to do a few things:
│ │ │ │ -
if links is non-empty, it contains a string for each file in the
│ │ │ │ -torrent. The string being a path to an existing identical file. The
│ │ │ │ -default behavior is to create hard links of those files into the
│ │ │ │ -storage of the new torrent (specified by storage). An empty
│ │ │ │ -string indicates that there is no known identical file. This is part
│ │ │ │ -of the "mutable torrent" feature, where files can be reused from
│ │ │ │ -other torrents.
│ │ │ │ -
The resume_data points the resume data passed in by the client.
│ │ │ │ -
If the resume_data->flags field has the seed_mode flag set, all
│ │ │ │ -files/pieces are expected to be on disk already. This should be
│ │ │ │ -verified. Not just the existence of the file, but also that it has
│ │ │ │ -the correct size.
│ │ │ │ -
Any file with a piece set in the resume_data->have_pieces bitmask
│ │ │ │ -should exist on disk, this should be verified. Pad files and files
│ │ │ │ -with zero priority may be skipped.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
async_stop_torrent()
│ │ │ │ +
This function returns true if anything that is stored in the resume
│ │ │ │ +data has changed since the last time resume data was saved.
│ │ │ │ +The overload that takes flags let you ask if specific categories
│ │ │ │ +of properties have changed. These flags have the same behavior as in
│ │ │ │ +the save_resume_data() call.
│ │ │ │ +
This is a blocking call. It will wait for a response from
│ │ │ │ +libtorrent's main thread. A way to avoid blocking is to instead
│ │ │ │ +call save_resume_data() directly, specifying the conditions under
│ │ │ │ +which resume data should be saved.
│ │ │ │ +
│ │ │ │ +
Note
│ │ │ │ +
A torrent's resume data is considered saved as soon as the
│ │ │ │ +save_resume_data_alert is posted. It is important to make sure this
│ │ │ │ +alert is received and handled in order for this function to be
│ │ │ │ +meaningful.
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
queue_position() queue_position_bottom() queue_position_down() queue_position_up() queue_position_top()
│ │ │ │
│ │ │ │ -virtual void async_stop_torrent (storage_index_t storage
│ │ │ │ - , std::function<void()> handler = std::function<void()>()) = 0;
│ │ │ │ +void queue_position_bottom () const;
│ │ │ │ +void queue_position_down () const;
│ │ │ │ +void queue_position_top () const;
│ │ │ │ +void queue_position_up () const;
│ │ │ │ +queue_position_t queue_position () const;
│ │ │ │
│ │ │ │ -
This is called when a torrent is stopped. It gives the disk I/O
│ │ │ │ -object an opportunity to flush any data to disk that's currently kept
│ │ │ │ -cached. This function should at least do the same thing as
│ │ │ │ -async_release_files().
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
async_rename_file()
│ │ │ │ +
Every torrent that is added is assigned a queue position exactly one
│ │ │ │ +greater than the greatest queue position of all existing torrents.
│ │ │ │ +Torrents that are being seeded have -1 as their queue position, since
│ │ │ │ +they're no longer in line to be downloaded.
│ │ │ │ +
When a torrent is removed or turns into a seed, all torrents with
│ │ │ │ +greater queue positions have their positions decreased to fill in the
│ │ │ │ +space in the sequence.
│ │ │ │ +
queue_position() returns the torrent's position in the download
│ │ │ │ +queue. The torrents with the smallest numbers are the ones that are
│ │ │ │ +being downloaded. The smaller number, the closer the torrent is to the
│ │ │ │ +front of the line to be started.
│ │ │ │ +
The queue position is also available in the torrent_status.
│ │ │ │ +
The queue_position_*() functions adjust the torrents position in
│ │ │ │ +the queue. Up means closer to the front and down means closer to the
│ │ │ │ +back of the queue. Top and bottom refers to the front and the back of
│ │ │ │ +the queue respectively.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
queue_position_set()
│ │ │ │
│ │ │ │ -virtual void async_rename_file (storage_index_t storage
│ │ │ │ - , file_index_t index, std::string name
│ │ │ │ - , std::function<void(std::string const&, file_index_t, storage_error const&)> handler) = 0;
│ │ │ │ +void queue_position_set (queue_position_t p) const;
│ │ │ │
│ │ │ │ -
This function is called when the name of a file in the specified
│ │ │ │ -storage has been requested to be renamed. The disk I/O object is
│ │ │ │ -responsible for renaming the file without racing with other
│ │ │ │ -potentially outstanding operations against the file (such as read,
│ │ │ │ -write, move, etc.).
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
async_delete_files()
│ │ │ │ +
updates the position in the queue for this torrent. The relative order
│ │ │ │ +of all other torrents remain intact but their numerical queue position
│ │ │ │ +shifts to make space for this torrent's new position
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
set_ssl_certificate() set_ssl_certificate_buffer()
│ │ │ │
│ │ │ │ -virtual void async_delete_files (storage_index_t storage, remove_flags_t options
│ │ │ │ - , std::function<void(storage_error const&)> handler) = 0;
│ │ │ │ +void set_ssl_certificate_buffer (std::string const& certificate
│ │ │ │ + , std::string const& private_key
│ │ │ │ + , std::string const& dh_params);
│ │ │ │ +void set_ssl_certificate (std::string const& certificate
│ │ │ │ + , std::string const& private_key
│ │ │ │ + , std::string const& dh_params
│ │ │ │ + , std::string const& passphrase = "");
│ │ │ │
│ │ │ │ -
This function is called when some file(s) on disk have been requested
│ │ │ │ -to be removed by the client. storage indicates which torrent is
│ │ │ │ -referred to. See session_handle for remove_flags_t flags
│ │ │ │ -indicating which files are to be removed.
│ │ │ │ -e.g. session_handle::delete_files - delete all files
│ │ │ │ -session_handle::delete_partfile - only delete part file.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
async_set_file_priority()
│ │ │ │ +
For SSL torrents, use this to specify a path to a .pem file to use as
│ │ │ │ +this client's certificate. The certificate must be signed by the
│ │ │ │ +certificate in the .torrent file to be valid.
│ │ │ │ +
The set_ssl_certificate_buffer() overload takes the actual certificate,
│ │ │ │ +private key and DH params as strings, rather than paths to files.
│ │ │ │ +
cert is a path to the (signed) certificate in .pem format
│ │ │ │ +corresponding to this torrent.
│ │ │ │ +
private_key is a path to the private key for the specified
│ │ │ │ +certificate. This must be in .pem format.
│ │ │ │ +
dh_params is a path to the Diffie-Hellman parameter file, which
│ │ │ │ +needs to be in .pem format. You can generate this file using the
│ │ │ │ +openssl command like this: openssl dhparam -outform PEM -out
│ │ │ │ +dhparams.pem 512.
│ │ │ │ +
passphrase may be specified if the private key is encrypted and
│ │ │ │ +requires a passphrase to be decrypted.
│ │ │ │ +
Note that when a torrent first starts up, and it needs a certificate,
│ │ │ │ +it will suspend connecting to any peers until it has one. It's
│ │ │ │ +typically desirable to resume the torrent after setting the SSL
│ │ │ │ +certificate.
│ │ │ │ +
If you receive a torrent_need_cert_alert, you need to call this to
│ │ │ │ +provide a valid cert. If you don't have a cert you won't be allowed to
│ │ │ │ +connect to any peers.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
torrent_file() torrent_file_with_hashes()
│ │ │ │
│ │ │ │ -virtual void async_set_file_priority (storage_index_t storage
│ │ │ │ - , aux::vector<download_priority_t, file_index_t> prio
│ │ │ │ - , std::function<void(storage_error const&
│ │ │ │ - , aux::vector<download_priority_t, file_index_t>)> handler) = 0;
│ │ │ │ +std::shared_ptr<torrent_info> torrent_file_with_hashes () const;
│ │ │ │ +std::shared_ptr<const torrent_info> torrent_file () const;
│ │ │ │
│ │ │ │ -
This is called to set the priority of some or all files. Changing the
│ │ │ │ -priority from or to 0 may involve moving data to and from the
│ │ │ │ -partfile. The disk I/O object is responsible for correctly
│ │ │ │ -synchronizing this work to not race with any potentially outstanding
│ │ │ │ -asynchronous operations affecting these files.
│ │ │ │ -
prio is a vector of the file priority for all files. If it's
│ │ │ │ -shorter than the total number of files in the torrent, they are
│ │ │ │ -assumed to be set to the default priority.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
async_clear_piece()
│ │ │ │ +
torrent_file() returns a pointer to the torrent_info object
│ │ │ │ +associated with this torrent. The torrent_info object may be a copy
│ │ │ │ +of the internal object. If the torrent doesn't have metadata, the
│ │ │ │ +pointer will not be initialized (i.e. a nullptr). The torrent may be
│ │ │ │ +in a state without metadata only if it was started without a .torrent
│ │ │ │ +file, e.g. by being added by magnet link.
│ │ │ │ +
Note that the torrent_info object returned here may be a different
│ │ │ │ +instance than the one added to the session, with different attributes
│ │ │ │ +like piece layers, dht nodes and trackers. A torrent_info object does
│ │ │ │ +not round-trip cleanly when added to a session.
│ │ │ │ +
If you want to save a .torrent file from the torrent_handle, instead
│ │ │ │ +call save_resume_data() and write_torrent_file() the
│ │ │ │ +add_torrent_params object passed back in the alert.
│ │ │ │ +
torrent_file_with_hashes() returns a copy of the internal
│ │ │ │ +torrent_info and piece layer hashes (if it's a v2 torrent). The piece
│ │ │ │ +layers will only be included if they are available. If this torrent
│ │ │ │ +was added from a .torrent file with piece layers or if it's seeding,
│ │ │ │ +the piece layers are available. This function is more expensive than
│ │ │ │ +torrent_file() since it needs to make copies of this information.
│ │ │ │ +
The torrent_file_with_hashes() is here for backwards compatibility
│ │ │ │ +when constructing a create_torrent object from a torrent_info that's
│ │ │ │ +in a session. Prefer save_resume_data() + write_torrent_file().
│ │ │ │ +
Note that a torrent added from a magnet link may not have the full
│ │ │ │ +merkle trees for all files, and hence not have the complete piece
│ │ │ │ +layers. In that state, you cannot create a .torrent file even from
│ │ │ │ +the torrent_info returned from torrent_file_with_hashes(). Once the
│ │ │ │ +torrent completes downloading all files, becoming a seed, you can
│ │ │ │ +make a .torrent file from it.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
piece_layers()
│ │ │ │
│ │ │ │ -virtual void async_clear_piece (storage_index_t storage, piece_index_t index
│ │ │ │ - , std::function<void(piece_index_t)> handler) = 0;
│ │ │ │ +std::vector<std::vector<sha256_hash>> piece_layers () const;
│ │ │ │
│ │ │ │ -
This is called when a piece fails the hash check, to ensure there are
│ │ │ │ -no outstanding disk operations to the piece before blocks are
│ │ │ │ -re-requested from peers to overwrite the existing blocks. The disk I/O
│ │ │ │ -object does not need to perform any action other than synchronize
│ │ │ │ -with all outstanding disk operations to the specified piece before
│ │ │ │ -posting the result back.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
update_stats_counters()
│ │ │ │ +
returns the piece layers for all files in the torrent. If this is a
│ │ │ │ +v1 torrent (and doesn't have any piece layers) it returns an empty
│ │ │ │ +vector. This is a blocking call that will synchronize with the
│ │ │ │ +libtorrent network thread.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
post_piece_availability() piece_availability()
│ │ │ │
│ │ │ │ -virtual void update_stats_counters (counters& c) const = 0;
│ │ │ │ +void piece_availability (std::vector<int>& avail) const;
│ │ │ │ +void post_piece_availability () const;
│ │ │ │
│ │ │ │ -
update_stats_counters() is called to give the disk storage an
│ │ │ │ -opportunity to update gauges in the c stats counters, that aren't
│ │ │ │ -updated continuously as operations are performed. This is called
│ │ │ │ -before a snapshot of the counters are passed to the client.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
get_status()
│ │ │ │ +
The piece availability is the number of peers that we are connected
│ │ │ │ +that has advertised having a particular piece. This is the information
│ │ │ │ +that libtorrent uses in order to prefer picking rare pieces.
│ │ │ │ +
post_piece_availability() will trigger a piece_availability_alert
│ │ │ │ +to be posted.
│ │ │ │ +
piece_availability() fills the specified std::vector<int>
│ │ │ │ +with the availability for each piece in this torrent. libtorrent does
│ │ │ │ +not keep track of availability for seeds, so if the torrent is
│ │ │ │ +seeding the availability for all pieces is reported as 0.
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
get_piece_priorities() piece_priority() prioritize_pieces()
│ │ │ │
│ │ │ │ -virtual std::vector<open_file_state> get_status (storage_index_t) const = 0;
│ │ │ │ +void prioritize_pieces (std::vector<std::pair<piece_index_t, download_priority_t>> const& pieces) const;
│ │ │ │ +download_priority_t piece_priority (piece_index_t index) const;
│ │ │ │ +void piece_priority (piece_index_t index, download_priority_t priority) const;
│ │ │ │ +std::vector<download_priority_t> get_piece_priorities () const;
│ │ │ │ +void prioritize_pieces (std::vector<download_priority_t> const& pieces) const;
│ │ │ │
│ │ │ │ -
Return a list of all the files that are currently open for the
│ │ │ │ -specified storage/torrent. This is is just used for the client to
│ │ │ │ -query the currently open files, and which modes those files are open
│ │ │ │ -in.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
abort()
│ │ │ │ +
These functions are used to set and get the priority of individual
│ │ │ │ +pieces. By default all pieces have priority 4. That means that the
│ │ │ │ +random rarest first algorithm is effectively active for all pieces.
│ │ │ │ +You may however change the priority of individual pieces. There are 8
│ │ │ │ +priority levels. 0 means not to download the piece at all. Otherwise,
│ │ │ │ +lower priority values means less likely to be picked. Piece priority
│ │ │ │ +takes precedence over piece availability. Every piece with priority 7
│ │ │ │ +will be attempted to be picked before a priority 6 piece and so on.
│ │ │ │ +
The default priority of pieces is 4.
│ │ │ │ +
Piece priorities can not be changed for torrents that have not
│ │ │ │ +downloaded the metadata yet. Magnet links won't have metadata
│ │ │ │ +immediately. see the metadata_received_alert.
│ │ │ │ +
piece_priority sets or gets the priority for an individual piece,
│ │ │ │ +specified by index.
│ │ │ │ +
prioritize_pieces takes a vector of integers, one integer per
│ │ │ │ +piece in the torrent. All the piece priorities will be updated with
│ │ │ │ +the priorities in the vector.
│ │ │ │ +The second overload of prioritize_pieces that takes a vector of pairs
│ │ │ │ +will update the priorities of only select pieces, and leave all other
│ │ │ │ +unaffected. Each pair is (piece, priority). That is, the first item is
│ │ │ │ +the piece index and the second item is the priority of that piece.
│ │ │ │ +Invalid entries, where the piece index or priority is out of range, are
│ │ │ │ +not allowed.
│ │ │ │ +
get_piece_priorities returns a vector with one element for each piece
│ │ │ │ +in the torrent. Each element is the current priority of that piece.
│ │ │ │ +
It's possible to cancel the effect of file priorities by setting the
│ │ │ │ +priorities for the affected pieces. Care has to be taken when mixing
│ │ │ │ +usage of file- and piece priorities.
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
prioritize_files() get_file_priorities() file_priority()
│ │ │ │
│ │ │ │ -virtual void abort (bool wait) = 0;
│ │ │ │ +void prioritize_files (std::vector<download_priority_t> const& files) const;
│ │ │ │ +void file_priority (file_index_t index, download_priority_t priority) const;
│ │ │ │ +download_priority_t file_priority (file_index_t index) const;
│ │ │ │ +std::vector<download_priority_t> get_file_priorities () const;
│ │ │ │
│ │ │ │ -
this is called when the session is starting to shut down. The disk
│ │ │ │ -I/O object is expected to flush any outstanding write jobs, cancel
│ │ │ │ -hash jobs and initiate tearing down of any internal threads. If
│ │ │ │ -wait is true, this should be asynchronous. i.e. this call should
│ │ │ │ -not return until all threads have stopped and all jobs have either
│ │ │ │ -been aborted or completed and the disk I/O object is ready to be
│ │ │ │ -destructed.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
submit_jobs()
│ │ │ │ +
index must be in the range [0, number_of_files).
│ │ │ │ +
file_priority() queries or sets the priority of file index.
│ │ │ │ +
prioritize_files() takes a vector that has at as many elements as
│ │ │ │ +there are files in the torrent. Each entry is the priority of that
│ │ │ │ +file. The function sets the priorities of all the pieces in the
│ │ │ │ +torrent based on the vector.
│ │ │ │ +
get_file_priorities() returns a vector with the priorities of all
│ │ │ │ +files.
│ │ │ │ +
The priority values are the same as for piece_priority(). See
│ │ │ │ +download_priority_t.
│ │ │ │ +
Whenever a file priority is changed, all other piece priorities are
│ │ │ │ +reset to match the file priorities. In order to maintain special
│ │ │ │ +priorities for particular pieces, piece_priority() has to be called
│ │ │ │ +again for those pieces.
│ │ │ │ +
You cannot set the file priorities on a torrent that does not yet have
│ │ │ │ +metadata or a torrent that is a seed. file_priority(int, int) and
│ │ │ │ +prioritize_files() are both no-ops for such torrents.
│ │ │ │ +
Since changing file priorities may involve disk operations (of moving
│ │ │ │ +files in- and out of the part file), the internal accounting of file
│ │ │ │ +priorities happen asynchronously. i.e. setting file priorities and then
│ │ │ │ +immediately querying them may not yield the same priorities just set.
│ │ │ │ +To synchronize with the priorities taking effect, wait for the
│ │ │ │ +file_prio_alert.
│ │ │ │ +
When combining file- and piece priorities, the resume file will record
│ │ │ │ +both. When loading the resume data, the file priorities will be applied
│ │ │ │ +first, then the piece priorities.
│ │ │ │ +
Moving data from a file into the part file is currently not
│ │ │ │ +supported. If a file has its priority set to 0 after it has already
│ │ │ │ +been created, it will not be moved into the partfile.
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
force_lsd_announce() force_dht_announce() force_reannounce()
│ │ │ │
│ │ │ │ -virtual void submit_jobs () = 0;
│ │ │ │ +void force_reannounce (int seconds = 0, int idx = -1, reannounce_flags_t = {}) const;
│ │ │ │ +void force_lsd_announce () const;
│ │ │ │ +void force_dht_announce () const;
│ │ │ │
│ │ │ │ -
This will be called after a batch of disk jobs has been issues (via
│ │ │ │ -the async_* ). It gives the disk I/O object an opportunity to
│ │ │ │ -notify any potential condition variables to wake up the disk
│ │ │ │ -thread(s). The async_* calls can of course also notify condition
│ │ │ │ -variables, but doing it in this call allows for batching jobs, by
│ │ │ │ -issuing the notification once for a collection of jobs.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
settings_updated()
│ │ │ │ +
force_reannounce() will force this torrent to do another tracker
│ │ │ │ +request, to receive new peers. The seconds argument specifies how
│ │ │ │ +many seconds from now to issue the tracker announces.
│ │ │ │ +
If the tracker's min_interval has not passed since the last
│ │ │ │ +announce, the forced announce will be scheduled to happen immediately
│ │ │ │ +as the min_interval expires. This is to honor trackers minimum
│ │ │ │ +re-announce interval settings.
│ │ │ │ +
The tracker_index argument specifies which tracker to re-announce.
│ │ │ │ +If set to -1 (which is the default), all trackers are re-announce.
│ │ │ │ +
The flags argument can be used to affect the re-announce. See
│ │ │ │ +ignore_min_interval.
│ │ │ │ +
force_dht_announce will announce the torrent to the DHT
│ │ │ │ +immediately.
│ │ │ │ +
force_lsd_announce will announce the torrent on LSD
│ │ │ │ +immediately.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
scrape_tracker()
│ │ │ │
│ │ │ │ -virtual void settings_updated () = 0;
│ │ │ │ +void scrape_tracker (int idx = -1) const;
│ │ │ │
│ │ │ │ -
This is called to notify the disk I/O object that the settings have
│ │ │ │ -been updated. In the disk io constructor, a settings_interface
│ │ │ │ -reference is passed in. Whenever these settings are updated, this
│ │ │ │ -function is called to allow the disk I/O object to react to any
│ │ │ │ -changed settings relevant to its operations.
│ │ │ │ -
[report issue]
│ │ │ │ -- force_copy
│ │ │ │ -- force making a copy of the cached block, rather than getting a
│ │ │ │ -reference to a block already in the cache. This is used the block is
│ │ │ │ -expected to be overwritten very soon, by async_write()`, and we need
│ │ │ │ -access to the previous content.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -- sequential_access
│ │ │ │ -- hint that there may be more disk operations with sequential access to
│ │ │ │ -the file
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -- volatile_read
│ │ │ │ -- don't keep the read block in cache. This is a hint that this block is
│ │ │ │ -unlikely to be read again anytime soon, and caching it would be
│ │ │ │ -wasteful.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -- v1_hash
│ │ │ │ -- compute a v1 piece hash. This is only used by the async_hash() call.
│ │ │ │ -If this flag is not set in the async_hash() call, the SHA-1 piece
│ │ │ │ -hash does not need to be computed.
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -- flush_piece
│ │ │ │ -- this flag instructs a hash job that we just completed this piece, and
│ │ │ │ -it should be flushed to disk
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
│ │ │ │ -
storage_holder
│ │ │ │ -
Declared in "libtorrent/disk_interface.hpp"
│ │ │ │ -
a unique, owning, reference to the storage of a torrent in a disk io
│ │ │ │ -subsystem (class that implements disk_interface). This is held by the
│ │ │ │ -internal libtorrent torrent object to tie the storage object allocated
│ │ │ │ -for a torrent to the lifetime of the internal torrent object. When a
│ │ │ │ -torrent is removed from the session, this holder is destructed and will
│ │ │ │ -inform the disk object.
│ │ │ │ +
scrape_tracker() will send a scrape request to a tracker. By
│ │ │ │ +default (idx = -1) it will scrape the last working tracker. If
│ │ │ │ +idx is >= 0, the tracker with the specified index will scraped.
│ │ │ │ +
A scrape request queries the tracker for statistics such as total
│ │ │ │ +number of incomplete peers, complete peers, number of downloads etc.
│ │ │ │ +
This request will specifically update the num_complete and
│ │ │ │ +num_incomplete fields in the torrent_status struct once it
│ │ │ │ +completes. When it completes, it will generate a scrape_reply_alert.
│ │ │ │ +If it fails, it will generate a scrape_failed_alert.
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
set_upload_limit() upload_limit() set_download_limit() download_limit()
│ │ │ │
│ │ │ │ -struct storage_holder
│ │ │ │ -{
│ │ │ │ - storage_holder () = default;
│ │ │ │ - storage_holder (storage_index_t idx, disk_interface& disk_io);
│ │ │ │ - ~storage_holder ();
│ │ │ │ - explicit operator bool () const;
│ │ │ │ - operator storage_index_t () const;
│ │ │ │ - void reset ();
│ │ │ │ - storage_holder& operator= (storage_holder const&) = delete;
│ │ │ │ - storage_holder (storage_holder const&) = delete;
│ │ │ │ - storage_holder (storage_holder&& rhs) noexcept;
│ │ │ │ - storage_holder& operator= (storage_holder&& rhs) noexcept;
│ │ │ │ -};
│ │ │ │ +void set_upload_limit (int limit) const;
│ │ │ │ +void set_download_limit (int limit) const;
│ │ │ │ +int download_limit () const;
│ │ │ │ +int upload_limit () const;
│ │ │ │
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
settings_interface
│ │ │ │ -
Declared in "libtorrent/settings_pack.hpp"
│ │ │ │ -
the common interface to settings_pack and the internal representation of
│ │ │ │ -settings.
│ │ │ │ +
set_upload_limit will limit the upload bandwidth used by this
│ │ │ │ +particular torrent to the limit you set. It is given as the number of
│ │ │ │ +bytes per second the torrent is allowed to upload.
│ │ │ │ +set_download_limit works the same way but for download bandwidth
│ │ │ │ +instead of upload bandwidth. Note that setting a higher limit on a
│ │ │ │ +torrent then the global limit
│ │ │ │ +(settings_pack::upload_rate_limit) will not override the global
│ │ │ │ +rate limit. The torrent can never upload more than the global rate
│ │ │ │ +limit.
│ │ │ │ +
upload_limit and download_limit will return the current limit
│ │ │ │ +setting, for upload and download, respectively.
│ │ │ │ +
Local peers are not rate limited by default. see peer classes.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
connect_peer()
│ │ │ │
│ │ │ │ -struct settings_interface
│ │ │ │ -{
│ │ │ │ - virtual void set_int (int name, int val) = 0;
│ │ │ │ - virtual void set_str (int name, std::string val) = 0;
│ │ │ │ - virtual void set_bool (int name, bool val) = 0;
│ │ │ │ - virtual bool has_val (int name) const = 0;
│ │ │ │ - virtual int get_int (int name) const = 0;
│ │ │ │ - virtual bool get_bool (int name) const = 0;
│ │ │ │ - virtual std::string const& get_str (int name) const = 0;
│ │ │ │ -};
│ │ │ │ +void connect_peer (tcp::endpoint const& adr, peer_source_flags_t source = {}
│ │ │ │ + , pex_flags_t flags = pex_encryption | pex_utp | pex_holepunch) const;
│ │ │ │
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
buffer_allocator_interface
│ │ │ │ -
Declared in "libtorrent/disk_buffer_holder.hpp"
│ │ │ │ -
the interface for freeing disk buffers, used by the disk_buffer_holder.
│ │ │ │ -when implementing disk_interface, this must also be implemented in order
│ │ │ │ -to return disk buffers back to libtorrent
│ │ │ │ +
connect_peer() is a way to manually connect to peers that one
│ │ │ │ +believe is a part of the torrent. If the peer does not respond, or is
│ │ │ │ +not a member of this torrent, it will simply be disconnected. No harm
│ │ │ │ +can be done by using this other than an unnecessary connection attempt
│ │ │ │ +is made. If the torrent is uninitialized or in queued or checking
│ │ │ │ +mode, this will throw system_error. The second (optional)
│ │ │ │ +argument will be bitwise ORed into the source mask of this peer.
│ │ │ │ +Typically this is one of the source flags in peer_info. i.e.
│ │ │ │ +tracker, pex, dht etc.
│ │ │ │ +
For possible values of flags, see pex_flags_t.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
clear_peers()
│ │ │ │
│ │ │ │ -struct buffer_allocator_interface
│ │ │ │ -{
│ │ │ │ - virtual void free_disk_buffer (char* b) = 0;
│ │ │ │ -};
│ │ │ │ +void clear_peers ();
│ │ │ │
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
disk_buffer_holder
│ │ │ │ -
Declared in "libtorrent/disk_buffer_holder.hpp"
│ │ │ │ -
The disk buffer holder acts like a unique_ptr that frees a disk buffer
│ │ │ │ -when it's destructed
│ │ │ │ -
If this buffer holder is moved-from, default constructed or reset,
│ │ │ │ -data() will return nullptr.
│ │ │ │ +
This will disconnect all peers and clear the peer list for this
│ │ │ │ +torrent. New peers will have to be acquired before resuming, from
│ │ │ │ +trackers, DHT or local service discovery, for example.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
max_uploads() set_max_uploads()
│ │ │ │
│ │ │ │ -struct disk_buffer_holder
│ │ │ │ -{
│ │ │ │ - disk_buffer_holder (disk_buffer_holder&&) noexcept;
│ │ │ │ - disk_buffer_holder& operator= (disk_buffer_holder&&) & noexcept;
│ │ │ │ - disk_buffer_holder (disk_buffer_holder const&) = delete;
│ │ │ │ - disk_buffer_holder& operator= (disk_buffer_holder const&) = delete;
│ │ │ │ - disk_buffer_holder (buffer_allocator_interface& alloc
│ │ │ │ - , char* buf, int sz) noexcept;
│ │ │ │ - disk_buffer_holder () noexcept = default;
│ │ │ │ - ~disk_buffer_holder ();
│ │ │ │ - char* data () const noexcept;
│ │ │ │ - void reset ();
│ │ │ │ - void swap (disk_buffer_holder& h) noexcept;
│ │ │ │ - bool is_mutable () const noexcept;
│ │ │ │ - explicit operator bool () const noexcept;
│ │ │ │ - std::ptrdiff_t size () const;
│ │ │ │ -};
│ │ │ │ +void set_max_uploads (int max_uploads) const;
│ │ │ │ +int max_uploads () const;
│ │ │ │
│ │ │ │ -
[report issue]
│ │ │ │ -
disk_buffer_holder()
│ │ │ │ +
set_max_uploads() sets the maximum number of peers that's unchoked
│ │ │ │ +at the same time on this torrent. If you set this to -1, there will be
│ │ │ │ +no limit. This defaults to infinite. The primary setting controlling
│ │ │ │ +this is the global unchoke slots limit, set by unchoke_slots_limit in
│ │ │ │ +settings_pack.
│ │ │ │ +
max_uploads() returns the current settings.
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
max_connections() set_max_connections()
│ │ │ │
│ │ │ │ -disk_buffer_holder (buffer_allocator_interface& alloc
│ │ │ │ - , char* buf, int sz) noexcept;
│ │ │ │ +void set_max_connections (int max_connections) const;
│ │ │ │ +int max_connections () const;
│ │ │ │
│ │ │ │ -
construct a buffer holder that will free the held buffer
│ │ │ │ -using a disk buffer pool directly (there's only one
│ │ │ │ -disk_buffer_pool per session)
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
disk_buffer_holder()
│ │ │ │ +
set_max_connections() sets the maximum number of connection this
│ │ │ │ +torrent will open. If all connections are used up, incoming
│ │ │ │ +connections may be refused or poor connections may be closed. This
│ │ │ │ +must be at least 2. The default is unlimited number of connections. If
│ │ │ │ +-1 is given to the function, it means unlimited. There is also a
│ │ │ │ +global limit of the number of connections, set by
│ │ │ │ +connections_limit in settings_pack.
│ │ │ │ +
max_connections() returns the current settings.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
move_storage()
│ │ │ │
│ │ │ │ -disk_buffer_holder () noexcept = default;
│ │ │ │ +void move_storage (std::string const& save_path
│ │ │ │ + , move_flags_t flags = move_flags_t::always_replace_files
│ │ │ │ + ) const;
│ │ │ │
│ │ │ │ -
default construct a holder that does not own any buffer
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
~disk_buffer_holder()
│ │ │ │ +
Moves the file(s) that this torrent are currently seeding from or
│ │ │ │ +downloading to. If the given save_path is not located on the same
│ │ │ │ +drive as the original save path, the files will be copied to the new
│ │ │ │ +drive and removed from their original location. This will block all
│ │ │ │ +other disk IO, and other torrents download and upload rates may drop
│ │ │ │ +while copying the file.
│ │ │ │ +
Since disk IO is performed in a separate thread, this operation is
│ │ │ │ +also asynchronous. Once the operation completes, the
│ │ │ │ +storage_moved_alert is generated, with the new path as the
│ │ │ │ +message. If the move fails for some reason,
│ │ │ │ +storage_moved_failed_alert is generated instead, containing the
│ │ │ │ +error message.
│ │ │ │ +
The flags argument determines the behavior of the copying/moving
│ │ │ │ +of the files in the torrent. see move_flags_t.
│ │ │ │ +
always_replace_files is the default and replaces any file that
│ │ │ │ +exist in both the source directory and the target directory.
│ │ │ │ +
fail_if_exist first check to see that none of the copy operations
│ │ │ │ +would cause an overwrite. If it would, it will fail. Otherwise it will
│ │ │ │ +proceed as if it was in always_replace_files mode. Note that there
│ │ │ │ +is an inherent race condition here. If the files in the target
│ │ │ │ +directory appear after the check but before the copy or move
│ │ │ │ +completes, they will be overwritten. When failing because of files
│ │ │ │ +already existing in the target path, the error of
│ │ │ │ +move_storage_failed_alert is set to
│ │ │ │ +boost::system::errc::file_exists.
│ │ │ │ +
The intention is that a client may use this as a probe, and if it
│ │ │ │ +fails, ask the user which mode to use. The client may then re-issue
│ │ │ │ +the move_storage call with one of the other modes.
│ │ │ │ +
dont_replace always keeps the existing file in the target
│ │ │ │ +directory, if there is one. The source files will still be removed in
│ │ │ │ +that case. Note that it won't automatically re-check files. If an
│ │ │ │ +incomplete torrent is moved into a directory with the complete files,
│ │ │ │ +pause, move, force-recheck and resume. Without the re-checking, the
│ │ │ │ +torrent will keep downloading and files in the new download directory
│ │ │ │ +will be overwritten.
│ │ │ │ +
Files that have been renamed to have absolute paths are not moved by
│ │ │ │ +this function. Keep in mind that files that don't belong to the
│ │ │ │ +torrent but are stored in the torrent's directory may be moved as
│ │ │ │ +well. This goes for files that have been renamed to absolute paths
│ │ │ │ +that still end up inside the save path.
│ │ │ │ +
When copying files, sparse regions are not likely to be preserved.
│ │ │ │ +This makes it proportionally more expensive to move a large torrent
│ │ │ │ +when only few pieces have been downloaded, since the files are then
│ │ │ │ +allocated with zeros in the destination directory.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
rename_file()
│ │ │ │
│ │ │ │ -~disk_buffer_holder ();
│ │ │ │ +void rename_file (file_index_t index, std::string const& new_name) const;
│ │ │ │
│ │ │ │ -
frees disk buffer held by this object
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ +
│ │ │ │ +
info_hashes() info_hash()
│ │ │ │
│ │ │ │ -char* data () const noexcept;
│ │ │ │ +sha1_hash info_hash () const;
│ │ │ │ +info_hash_t info_hashes () const;
│ │ │ │
│ │ │ │ -
return a pointer to the held buffer, if any. Otherwise returns nullptr.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
reset()
│ │ │ │ +
returns the info-hash(es) of the torrent. If this handle is to a
│ │ │ │ +torrent that hasn't loaded yet (for instance by being added) by a
│ │ │ │ +URL, the returned value is undefined.
│ │ │ │ +The info_hash() returns the SHA-1 info-hash for v1 torrents and a
│ │ │ │ +truncated hash for v2 torrents. For the full v2 info-hash, use
│ │ │ │ +info_hashes() instead.
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
operator<() operator==() operator!=()
│ │ │ │
│ │ │ │ -void reset ();
│ │ │ │ +bool operator== (const torrent_handle& h) const;
│ │ │ │ +bool operator!= (const torrent_handle& h) const;
│ │ │ │ +bool operator< (const torrent_handle& h) const;
│ │ │ │
│ │ │ │ -
free the held disk buffer, if any, and clear the holder. This sets the
│ │ │ │ -holder object to a default-constructed state
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
swap()
│ │ │ │ +
comparison operators. The order of the torrents is unspecified
│ │ │ │ +but stable.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
id()
│ │ │ │
│ │ │ │ -void swap (disk_buffer_holder& h) noexcept;
│ │ │ │ +std::uint32_t id () const;
│ │ │ │
│ │ │ │ -
swap pointers of two disk buffer holders.
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
is_mutable()
│ │ │ │ +
returns a unique identifier for this torrent. It's not a dense index.
│ │ │ │ +It's not preserved across sessions.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
native_handle()
│ │ │ │
│ │ │ │ -bool is_mutable () const noexcept;
│ │ │ │ +std::shared_ptr<torrent> native_handle () const;
│ │ │ │
│ │ │ │ -
if this returns true, the buffer may not be modified in place
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
bool()
│ │ │ │ +
This function is intended only for use by plugins and the alert
│ │ │ │ +dispatch function. This type does not have a stable ABI and should
│ │ │ │ +be relied on as little as possible. Accessing the handle returned by
│ │ │ │ +this function is not thread safe outside of libtorrent's internal
│ │ │ │ +thread (which is used to invoke plugin callbacks).
│ │ │ │ +The torrent class is not only eligible for changing ABI across
│ │ │ │ +minor versions of libtorrent, its layout is also dependent on build
│ │ │ │ +configuration. This adds additional requirements on a client to be
│ │ │ │ +built with the exact same build configuration as libtorrent itself.
│ │ │ │ +i.e. the TORRENT_ macros must match between libtorrent and the
│ │ │ │ +client builds.
│ │ │ │ +
[report issue]
│ │ │ │ +
│ │ │ │ +
userdata()
│ │ │ │
│ │ │ │ -explicit operator bool () const noexcept;
│ │ │ │ +client_data_t userdata () const;
│ │ │ │
│ │ │ │ -
implicitly convertible to true if the object is currently holding a
│ │ │ │ -buffer
│ │ │ │ -
[report issue]
│ │ │ │ -
│ │ │ │ -
│ │ │ │ +
│ │ │ │ +
in_session()
│ │ │ │ +
│ │ │ │ +bool in_session () const;
│ │ │ │ +
│ │ │ │ +
Returns true if the torrent is in the session. It returns true before
│ │ │ │ +session::remove_torrent() is called, and false afterward.
│ │ │ │ +
Note that this is a blocking function, unlike torrent_handle::is_valid()
│ │ │ │ +which returns immediately.
│ │ │ │ +
[report issue]
│ │ │ │ +- overwrite_existing
│ │ │ │ +- instruct libtorrent to overwrite any data that may already have been
│ │ │ │ +downloaded with the data of the new piece being added. Using this
│ │ │ │ +flag when adding a piece that is actively being downloaded from other
│ │ │ │ +peers may have some unexpected consequences, as blocks currently
│ │ │ │ +being downloaded from peers may not be replaced.
│ │ │ │
│ │ │ │ -
│ │ │ │ -- write_only
│ │ │ │ -- open the file for writing only
│ │ │ │ +[report issue]
│ │ │ │ +- query_distributed_copies
│ │ │ │ +- calculates distributed_copies, distributed_full_copies and
│ │ │ │ +distributed_fraction.
│ │ │ │
│ │ │ │ -
│ │ │ │ -- read_write
│ │ │ │ -- open the file for reading and writing
│ │ │ │ +[report issue]
│ │ │ │ +- query_accurate_download_counters
│ │ │ │ +- includes partial downloaded blocks in total_done and
│ │ │ │ +total_wanted_done.
│ │ │ │
│ │ │ │ -
│ │ │ │ -- rw_mask
│ │ │ │ -- the mask for the bits determining read or write mode
│ │ │ │ +[report issue]
│ │ │ │ +- query_last_seen_complete
│ │ │ │ +- includes last_seen_complete.
│ │ │ │
│ │ │ │ -
│ │ │ │ -- sparse
│ │ │ │ -- open the file in sparse mode (if supported by the
│ │ │ │ -filesystem).
│ │ │ │ +[report issue]
│ │ │ │ +- query_pieces
│ │ │ │ +- populate the pieces field in torrent_status.
│ │ │ │
│ │ │ │ -
│ │ │ │ -- no_atime
│ │ │ │ -- don't update the access timestamps on the file (if
│ │ │ │ -supported by the operating system and filesystem).
│ │ │ │ -this generally improves disk performance.
│ │ │ │ +[report issue]
│ │ │ │ +- query_verified_pieces
│ │ │ │ +- includes verified_pieces (only applies to torrents in seed
│ │ │ │ +mode).
│ │ │ │
│ │ │ │ -
│ │ │ │ -- random_access
│ │ │ │ -- When this is not set, the kernel is hinted that access to this file will
│ │ │ │ -be made sequentially.
│ │ │ │ +[report issue]
│ │ │ │ +- query_torrent_file
│ │ │ │ +- includes torrent_file, which is all the static information from
│ │ │ │ +the .torrent file.
│ │ │ │
│ │ │ │ -
│ │ │ │ -- mmapped
│ │ │ │ -- the file is memory mapped
│ │ │ │ +[report issue]
│ │ │ │ +- query_name
│ │ │ │ +- includes name, the name of the torrent. This is either derived
│ │ │ │ +from the .torrent file, or from the &dn= magnet link argument
│ │ │ │ +or possibly some other source. If the name of the torrent is not
│ │ │ │ +known, this is an empty string.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +- query_save_path
│ │ │ │ +- includes save_path, the path to the directory the files of the
│ │ │ │ +torrent are saved to.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +- alert_when_available
│ │ │ │ +- used to ask libtorrent to send an alert once the piece has been
│ │ │ │ +downloaded, by passing alert_when_available. When set, the
│ │ │ │ +read_piece_alert alert will be delivered, with the piece data, when
│ │ │ │ +it's downloaded.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +- piece_granularity
│ │ │ │ +- only calculate file progress at piece granularity. This makes
│ │ │ │ +the file_progress() call cheaper and also only takes bytes that
│ │ │ │ +have passed the hash check into account, so progress cannot
│ │ │ │ +regress in this mode.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +- graceful_pause
│ │ │ │ +- will delay the disconnect of peers that we're still downloading
│ │ │ │ +outstanding requests from. The torrent will not accept any more
│ │ │ │ +requests and will disconnect all idle peers. As soon as a peer is done
│ │ │ │ +transferring the blocks that were requested from it, it is
│ │ │ │ +disconnected. This is a graceful shut down of the torrent in the sense
│ │ │ │ +that no downloaded bytes are wasted.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +- flush_disk_cache
│ │ │ │ +- the disk cache will be flushed before creating the resume data.
│ │ │ │ +This avoids a problem with file timestamps in the resume data in
│ │ │ │ +case the cache hasn't been flushed yet.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +- save_info_dict
│ │ │ │ +- the resume data will contain the metadata from the torrent file as
│ │ │ │ +well. This is useful for clients that don't keep .torrent files
│ │ │ │ +around separately, or for torrents that were added via a magnet link.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +- only_if_modified
│ │ │ │ +- this flag has the same behavior as the combination of:
│ │ │ │ +if_counters_changed | if_download_progress | if_config_changed |
│ │ │ │ +if_state_changed | if_metadata_changed
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +- if_counters_changed
│ │ │ │ +- save resume data if any counters has changed since the last time
│ │ │ │ +resume data was saved. This includes upload/download counters, active
│ │ │ │ +time counters and scrape data. A torrent that is not paused will have
│ │ │ │ +its active time counters incremented continuously.
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +- if_download_progress
│ │ │ │ +- save the resume data if any blocks have been downloaded since the
│ │ │ │ +last time resume data was saved. This includes:
│ │ │ │ +* checking existing files on disk
│ │ │ │ +* downloading a block from a peer
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +- if_config_changed
│ │ │ │ +- save the resume data if configuration options changed since last time
│ │ │ │ +the resume data was saved. This includes:
│ │ │ │ +* file- or piece priorities
│ │ │ │ +* upload- and download rate limits
│ │ │ │ +* change max-uploads (unchoke slots)
│ │ │ │ +* change max connection limit
│ │ │ │ +* enable/disable peer-exchange, local service discovery or DHT
│ │ │ │ +* enable/disable apply IP-filter
│ │ │ │ +* enable/disable auto-managed
│ │ │ │ +* enable/disable share-mode
│ │ │ │ +* enable/disable sequential-mode
│ │ │ │ +* files renamed
│ │ │ │ +* storage moved (save_path changed)
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +- if_state_changed
│ │ │ │ +- save the resume data if torrent state has changed since last time the
│ │ │ │ +resume data was saved. This includes:
│ │ │ │ +* upload mode
│ │ │ │ +* paused state
│ │ │ │ +* super-seeding
│ │ │ │ +* seed-mode
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +- if_metadata_changed
│ │ │ │ +- save the resume data if any metadata changed since the last time
│ │ │ │ +resume data was saved. This includes:
│ │ │ │ +* add/remove web seeds
│ │ │ │ +* add/remove trackers
│ │ │ │ +* receiving metadata for a magnet link
│ │ │ │ +
│ │ │ │ +[report issue]
│ │ │ │ +- ignore_min_interval
│ │ │ │ +- by default, force-reannounce will still honor the min-interval
│ │ │ │ +published by the tracker. If this flag is set, it will be ignored
│ │ │ │ +and the tracker is announced immediately.
│ │ │ │
│ │ │ │ +[report issue]
│ │ │ │ +
│ │ │ │ +
│ │ │ │ +
hash_value()
│ │ │ │ +
Declared in "libtorrent/torrent_handle.hpp"
│ │ │ │ +
│ │ │ │ +std::size_t hash_value (torrent_handle const& h);
│ │ │ │ +
│ │ │ │ +
for std::hash (and to support using this type in unordered_map etc.)
│ │ │ │
You have some control over session configuration through the session::apply_settings()
│ │ │ │ member function. To change one or more configuration options, create a settings_pack
│ │ │ │ object and fill it with the settings to be set and pass it in to session::apply_settings().
│ │ │ │
The settings_pack object is a collection of settings updates that are applied
│ │ │ │ to the session when passed to session::apply_settings(). It's empty when
│ │ │ │ constructed.
│ │ │ │
You have control over proxy and authorization settings and also the user-agent
│ │ │ │ @@ -17053,22 +18279,22 @@
│ │ │ │
│ │ │ │ struct settings_pack final : settings_interface
│ │ │ │ {
│ │ │ │ friend void apply_pack_impl (settings_pack const*
│ │ │ │ , aux::session_settings_single_thread&
│ │ │ │ , std::vector<void(aux::session_impl::*)()>*);
│ │ │ │ void set_bool (int name, bool val) override;
│ │ │ │ - void set_str (int name, std::string val) override;
│ │ │ │ - void set_int (int name, int val) override;
│ │ │ │ void set_int (int name, flags::bitfield_flag<Type, Tag> const val);
│ │ │ │ + void set_int (int name, int val) override;
│ │ │ │ + void set_str (int name, std::string val) override;
│ │ │ │ bool has_val (int name) const override;
│ │ │ │ void clear ();
│ │ │ │ void clear (int name);
│ │ │ │ - bool get_bool (int name) const override;
│ │ │ │ std::string const& get_str (int name) const override;
│ │ │ │ + bool get_bool (int name) const override;
│ │ │ │ int get_int (int name) const override;
│ │ │ │ void for_each (Fun&& f) const;
│ │ │ │
│ │ │ │ enum type_bases
│ │ │ │ {
│ │ │ │ string_type_base,
│ │ │ │ int_type_base,
│ │ │ │ @@ -17139,23 +18365,23 @@
│ │ │ │ socks5,
│ │ │ │ socks5_pw,
│ │ │ │ http,
│ │ │ │ http_pw,
│ │ │ │ };
│ │ │ │ };
│ │ │ │
│ │ │ │ -
│ │ │ │
│ │ │ │ -
[report issue]
│ │ │ │ -
set_int() set_bool() set_str()
│ │ │ │ +
│ │ │ │ +
[report issue]
│ │ │ │ +
set_bool() set_str() set_int()
│ │ │ │
│ │ │ │ void set_bool (int name, bool val) override;
│ │ │ │ -void set_str (int name, std::string val) override;
│ │ │ │ -void set_int (int name, int val) override;
│ │ │ │ void set_int (int name, flags::bitfield_flag<Type, Tag> const val);
│ │ │ │ +void set_int (int name, int val) override;
│ │ │ │ +void set_str (int name, std::string val) override;
│ │ │ │
│ │ │ │
set a configuration option in the settings_pack. name is one of
│ │ │ │ the enum values from string_types, int_types or bool_types. They must
│ │ │ │ match the respective type of the set_* function.
│ │ │ │
[report issue]
│ │ │ │
│ │ │ │
has_val()
│ │ │ │ @@ -17181,16 +18407,16 @@
│ │ │ │
clear a specific setting from the pack
│ │ │ │
│ │ │ │
│ │ │ │
[report issue]
│ │ │ │
│ │ │ │
get_str() get_bool() get_int()
│ │ │ │
│ │ │ │ -bool get_bool (int name) const override;
│ │ │ │ std::string const& get_str (int name) const override;
│ │ │ │ +bool get_bool (int name) const override;
│ │ │ │ int get_int (int name) const override;
│ │ │ │
│ │ │ │
queries the current configuration option from the settings_pack.
│ │ │ │ name is one of the enumeration values from string_types, int_types
│ │ │ │ or bool_types. The enum value must match the type of the get_*
│ │ │ │ function. If the specified setting field has not been set, the default
│ │ │ │ value is returned.
│ │ │ │ @@ -17550,19 +18776,19 @@
│ │ │ │
| http_pw |
│ │ │ │ 5 |
│ │ │ │ The server is assumed to be an HTTP proxy that requires user
│ │ │ │ authorization. The username and password will be sent to the proxy. |
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │ -
│ │ │ │ -
[report issue]
│ │ │ │ +
│ │ │ │ +
[report issue]