Version: | 2.0.13

home

Table of contents

- read_resume_data()
- write_resume_data() write_resume_data_buf()
- write_torrent_file() write_torrent_file_buf()
- write_torrent_flags_t

[report issue]

# read_resume_data()

Declared in "libtorrent/read_resume_data.hpp"

    add_torrent_params read_resume_data (bdecode_node const& rd
       , int piece_limit = 0x200000);
    add_torrent_params read_resume_data (bdecode_node const& rd
       , error_code& ec, int piece_limit = 0x200000);
    add_torrent_params read_resume_data (span<char const> buffer
       , error_code& ec, load_torrent_limits const& cfg = {});
    add_torrent_params read_resume_data (span<char const> buffer
       , load_torrent_limits const& cfg = {});

these functions are used to parse resume data and populate the appropriate fields in an add_torrent_params object. This object can then be used to add the actual torrent_info object to and pass to session::add_torrent() or session::async_add_torrent().

If the client wants to override any field that was loaded from the resume data, e.g. save_path, those fields must be changed after loading resume data but before adding the torrent.

The `piece_limit` parameter determines the largest number of pieces allowed in the torrent that may be loaded as part of the resume data, if it contains an `info` field. The overloads that take a flat buffer are instead configured with limits on torrent sizes via load_torrent limits.

In order to support large torrents, it may also be necessary to raise the settings_pack::max_piece_count setting and pass a higher limit to calls to torrent_info::parse_info_section().

Warning

Resume data is assumed to be trusted input, written by the same client on the same machine. Many fields parsed here directly control behavior that affects the host system or the network: `save_path` and `mapped_files` determine where files are written on disk (and may be absolute paths), the embedded `info` dict can substitute a different torrent than the caller expects, and `trackers`, `url-list` and `httpseeds` cause outbound network requests to URLs taken verbatim from the resume data. A malicious resume file can therefore write to arbitrary filesystem locations the process has access to, and cause requests to attacker-controlled hosts.

Client applications are responsible for protecting resume files from tampering. At minimum, store them with filesystem permissions that prevent other users on the system from modifying them, and do not load resume data received from untrusted sources (e.g. downloaded, synced from a shared location, or supplied by a peer) without independently validating or overriding the security-sensitive fields after parsing.

[report issue]

# write_resume_data() write_resume_data_buf()

Declared in "libtorrent/write_resume_data.hpp"

    entry write_resume_data (add_torrent_params const& atp);
    std::vector<char> write_resume_data_buf (add_torrent_params const& atp);

this function turns the resume data in an `add_torrent_params` object into a bencoded structure

[report issue]

# write_torrent_file() write_torrent_file_buf()

Declared in "libtorrent/write_resume_data.hpp"

    std::vector<char> write_torrent_file_buf (add_torrent_params const& atp
       , write_torrent_flags_t flags);
    entry write_torrent_file (add_torrent_params const& atp);
    entry write_torrent_file (add_torrent_params const& atp, write_torrent_flags_t flags);

writes only the fields to create a .torrent file. This function may fail with a `std::system_error` exception if:

- The add_torrent_params object passed to this function does not contain the info dictionary (the `ti` field)
- The piece layers are not complete for all files that need them

The `write_torrent_file_buf()` overload returns the torrent file in bencoded buffer form. This overload may be faster at the expense of lost flexibility to add custom fields.

[report issue]

# write_torrent_flags_t

Declared in "libtorrent/write_resume_data.hpp"

allow_missing_piece_layer
  this makes write_torrent_file() not fail when attempting to write a v2 torrent file that does not have all the piece layers

no_http_seeds
  don't include http seeds in the torrent file, even if some are present in the add_torrent_params object

include_dht_nodes
  When set, DHT nodes from the add_torrent_params objects are included in the resulting .torrent file