create_file_entry()

create_file_entry (std::string fn, std::int64_t const sz
      , file_flags_t const f = {}, std::time_t const ts = 0, std::string sl = {});

construct a file entry for the file at relative path fn with size sz. f is the set of file flags that applies to the file, see file_flags_t. ts is an optional modification time (0 to omit). sl is the symlink target, only used when f includes the symlink flag. Symlinks are only allowed to target other files or directories in the torrent.

filename

the path and name of the file. The path is relative to the root of the torrent file.

size

the size of the file

flags

bitmask of file_flags_t (pad-file, hidden, executable, symlink) for this file.

mtime

optional modification time of the file. 0 means "do not record".

symlink

the link target, only considered if the symlink flag is set

create_torrent()

explicit create_torrent (std::vector<create_file_entry> files, 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 files argument is a list of all files to be included in the torrent file. If it has more than one file in it, all files must share a common root directory (which will be the name of the torrent).

If files has a single file without any directory component (i.e. just a filename) it will create a single file torrent. If it has a directory path, it will create a multi-file torrent with a single file. This is in order to preserve the directory path.

deprecated overloads

There are two deprecated constructors that take a file_storage object and a torrent_info object respectively.

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. Instead of using this overload, consider using the overload taking a vector of create_file_entry objects instead. It is more efficient.

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.

generate_buf() generate()

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.

set_comment()

void set_comment (char const* str);

Sets the comment for the torrent. The string str should be utf-8 encoded. The comment in a torrent file is optional.

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.

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.

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.

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.

add_url_seed()

void add_url_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.

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.

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.

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.

set_priv() priv()

void set_priv (bool p);
bool priv () const;

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.

is_v1_only() is_v2_only()

bool is_v2_only () const;
bool is_v1_only () const;

query which protocol versions will be written by this builder. is_v2_only() returns true if no v1 info dict will be written; is_v1_only() returns true if no v2 file tree will be written. A torrent that is neither v1-only nor v2-only is a hybrid v1+v2 torrent.

num_pieces()

int num_pieces () const;

returns the number of pieces in the associated file_storage object.

end_piece()

piece_index_t end_piece () const;

one past-the-end piece index

piece_range()

index_range<piece_index_t> piece_range () const noexcept;

all piece indices in the torrent to be created

end_file()

file_index_t end_file () const;

one past-the-end file index

file_range()

index_range<file_index_t> file_range () const noexcept;

all file indices in the torrent to be created

file_at()

create_file_entry const& file_at (file_index_t f) const;

returns a reference to the create_file_entry at the given file index. Note that this is not necessarily the same entries passed into the constructor, since the layout may have been canonicalized. e.g. file order and padding may have changed.

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.

total_size()

std::int64_t total_size () const;

the total number of bytes of all files and pad files

piece_length() piece_size()

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.

add_similar_torrent() add_collection()

void add_collection (string_view c);
void add_similar_torrent (sha1_hash ih);

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.

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.

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.

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.

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.

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.

no_attributes

passing this flag to list_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.

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.