storage_params()

storage_params (file_storage const& f, lt::renamed_files const& mf
      , string_view sp, string_view pfd, storage_mode_t const sm
      , aux::vector<download_priority_t, file_index_t> const& prio
      , sha1_hash const& ih, bool v1_torrent, bool v2_torrent);

constructs a parameter pack from the layout, save path, mode, per-file priorities, info-hash and protocol-version flags. v1 indicates that the torrent has v1 metadata (a SHA-1 info-hash); v2 that it has v2 metadata (BEP 52). A hybrid torrent has both set.

files

the file layout (sizes, paths, flags) of the torrent

renamed_files

rename overlay applied on top of files; on-disk paths resolved through this object take precedence over the originals

path

the directory where the torrent's files are stored

part_file_dir

directory in which the part file is created. If empty, the part file is placed under path.

mode

the storage allocation mode (sparse vs. pre-allocated)

priorities

per-file download priorities, indexed by file index

info_hash

the SHA-1 info-hash of the torrent (zero for v2-only torrents)

v1 v2

indicates which BitTorrent protocol version(s) this storage is for. v1 is true if the torrent has v1 metadata; v2 is true if the torrent has v2 metadata (BEP 52). A hybrid torrent has both flags set.

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 not.

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.

add_file_borrow() add_file()

void add_file_borrow (string_view filename
      , std::string const& path, std::int64_t file_size
      , file_flags_t file_flags = {}, std::int64_t mtime = 0
      , string_view symlink_path = string_view()
      , char const* root_hash = nullptr);
void add_file (std::string const& path, std::int64_t file_size
      , file_flags_t file_flags = {}
      , std::time_t mtime = 0, string_view symlink_path = string_view()
      , char const* root_hash = nullptr);

Adds a file to the file storage. The add_file_borrow version expects that filename is the file name (without a path) of the file that's being added. This memory is borrowed, i.e. it is the caller's responsibility to make sure it stays valid throughout the lifetime of this file_storage object or any copy of it. The same thing applies to filehash, which is an optional pointer to a 20 byte binary SHA-1 hash of the file.

if filename is empty, the filename from path is used and not borrowed.

The path argument is the full path (in the torrent file) to the file to add. Note that this is not supposed to be an absolute path, but it is expected to include the name of the torrent as the first path element.

file_size is the size of the file in bytes.

The file_flags argument sets attributes on the file. The file attributes is an extension and may not work in all bittorrent clients.

For possible file attributes, see file_storage::flags_t.

The mtime argument is optional and can be set to 0. If non-zero, it is the posix time of the last modification time of this file.

symlink_path is the path the file is a symlink to. To make this a symlink you also need to set the file_storage::flag_symlink file flag.

root_hash is an optional pointer to a 32 byte SHA-256 hash, being the merkle tree root hash for this file. This is only used for v2 torrents. If the root hash is specified for one file, it has to be specified for all, otherwise this function will fail. Note that the buffer root_hash points to must out-live the file_storage object, it will not be copied. This parameter is only used when loading torrents, that already have their file hashes computed. When creating torrents, the file hashes will be computed by the piece hashes.

If more files than one are added, certain restrictions to their paths apply. In a multi-file file storage (torrent), all files must share 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.

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 = {}, 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
      , file_flags_t file_flags = {}
      , std::time_t mtime = 0, string_view symlink_path = string_view()
      , char const* root_hash = nullptr);

these overloads report failures through the ec reference rather than throwing. add_file_borrow() does not copy the filename string; it is borrowed by reference and the caller must keep it alive for the lifetime of this file_storage object. This is useful when constructing the file list from a memory-mapped .torrent file.

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

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.

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

num_files()

int num_files () const noexcept;

returns the number of files in the file_storage

end_file()

file_index_t end_file () const noexcept;

returns the index of the one-past-end file in the file storage

file_range()

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.

total_size()

std::int64_t total_size () const;

returns the total number of bytes all the files in this torrent spans including pad files

size_on_disk()

std::int64_t size_on_disk () const;

returns the sum of all non pad file sizes

num_pieces() set_num_pieces()

void set_num_pieces (int n);
int num_pieces () const;

set and get the number of pieces in the torrent

end_piece()

piece_index_t end_piece () const;

returns the index of the one-past-end piece in the file storage

last_piece()

piece_index_t last_piece () const;

returns the index of the last piece in the torrent. The last piece is special in that it may be smaller than the other pieces (and the other pieces are all the same size).

piece_range()

index_range<piece_index_t> piece_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 pieces in the file_storage.

piece_length() set_piece_length()

int piece_length () const;
void set_piece_length (int l);

set and get the size of each piece in this torrent. It must be a power of two and at least 16 kiB.

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 for the last piece, which may be shorter.

piece_size2()

int piece_size2 (piece_index_t index) const;

Returns the size of the given piece. If the piece spans multiple files, only the first file is considered part of the piece. This is used for v2 torrents, where all files are piece aligned and padded. i.e. The pad files are not considered part of the piece for this purpose.

blocks_in_piece2()

int blocks_in_piece2 (piece_index_t index) const;

returns the number of blocks in the specified piece, for v2 torrents.

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)

name() set_name()

void set_name (std::string const& n);
std::string const& name () const;

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.

swap()

void swap (file_storage& ti) noexcept;

swap all content of this with ti.

file_offset() symlink() root() mtime() root_ptr() file_path() pad_file_at() file_size() file_name()

std::time_t mtime (file_index_t index) const;
std::string symlink (file_index_t index) const;
string_view file_name (file_index_t index) const;
std::int64_t file_offset (file_index_t index) const;
std::int64_t file_size (file_index_t index) const;
bool pad_file_at (file_index_t index) const;
char const* root_ptr (file_index_t const index) const;
sha256_hash root (file_index_t index) const;
std::string file_path (file_index_t index, std::string const& save_path = "") const;

These functions are used to query attributes of files at a given index.

root() returns the SHA-256 merkle tree root of the specified file, in case this is a v2 torrent. Otherwise returns zeros. root_ptr() returns a pointer to the SHA-256 merkle tree root hash for the specified file. The pointer points into storage referred to when the file was added, it is not owned by this object. Torrents that are not v2 torrents return nullptr.

The mtime() is the modification time is the posix time when a file was last modified when the torrent was created, or 0 if it was not included in the torrent file.

file_path() returns the full path to a file.

file_size() returns the size of a file.

pad_file_at() returns true if the file at the given 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.

symlink() returns the path the file at index is a symlink to. If the file is not a symlink, the returned string is empty.

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).

file_num_pieces() file_piece_range() file_num_blocks()

int file_num_blocks (file_index_t index) const;
int file_num_pieces (file_index_t index) const;
index_range<piece_index_t::diff_type> file_piece_range (file_index_t) 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.

file_first_piece_node() file_first_block_node()

int file_first_block_node (file_index_t index) const;
int file_first_piece_node (file_index_t index) const;

index of first piece node in the merkle tree

file_path_hash()

std::uint32_t file_path_hash (file_index_t index, std::string const& save_path) const;

returns the crc32 hash of file_path(index)

all_path_hashes()

void all_path_hashes (std::unordered_set<std::uint32_t>& table) const;

this will add the CRC32 hash of all directory entries to the table. No filename will be included, just directories. Every depth of directories are added separately to allow test for collisions with files at all levels. i.e. if one path in the torrent is foo/bar/baz, the CRC32 hashes for foo, foo/bar and foo/bar/baz will be added to the set.

file_flags()

file_flags_t file_flags (file_index_t index) const;

returns a bitmask of flags from file_flags_t that apply to file at index.

file_absolute_path()

bool file_absolute_path (file_index_t index) const;

returns true if the file at the specified index has been renamed to have an absolute path, i.e. is not anchored in the save path of the torrent.

file_index_at_piece() last_file_index_at_piece() file_index_at_offset()

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 last_file_index_at_piece (piece_index_t piece) const;

returns the index of the file at the given offset or piece in the torrent

file_index_for_root()

file_index_t file_index_for_root (sha256_hash const& root_hash) const;

finds the file with the given root hash and returns its index if there is no file with the root hash, file_index_t{-1} is returned

last_piece_index_at_file() piece_index_at_file()

piece_index_t piece_index_at_file (file_index_t f) const;
piece_index_t last_piece_index_at_file (file_index_t f) const;

returns the first or last piece index of the given file in the torrent

sanitize_symlinks()

void sanitize_symlinks ();

validate any symlinks, to ensure they all point to other files or directories inside this storage. Any invalid symlinks are updated to point to themselves.

v2()

bool v2 () const;

returns true if this torrent contains v2 metadata.

flag_pad_file

the file is a pad file. It's required to contain zeros at it will not be saved to disk. Its purpose is to make the following file start on a piece boundary.

flag_hidden

this file has the hidden attribute set. This is primarily a windows attribute

flag_executable

this file has the executable attribute set.

flag_symlink

this file is a symbolic link. It should have a link target string associated with it.

file_name() file_absolute_path() file_path()

std::string file_path (file_storage const& fs, file_index_t index, std::string const& save_path = "") const;
string_view file_name (file_storage const& fs, file_index_t index) const;
bool file_absolute_path (file_storage const& fs, file_index_t index) const;

returns information about the file at index in fs, honoring any rename recorded in this object. file_path() returns the full on-disk path (prepending save_path to relative paths). file_name() returns just the leaf filename. file_absolute_path() returns true if the recorded rename is an absolute path (in which case save_path is ignored).

rename_file()

void rename_file (file_storage const& fs, file_index_t index, std::string const& new_filename);

records that the file at index in fs should be renamed to new_filename on disk. The underlying file_storage is not modified.

export_filenames() import_filenames()

void import_filenames (file_storage const& fs, std::map<file_index_t, std::string> const& renamed_files);
std::map<file_index_t, std::string> export_filenames (file_storage const& fs) const;

bulk import or export the set of file renames recorded in this object. import_filenames() adds the given renames (dropping entries whose file index is out of range). export_filenames() returns the current renames as a map suitable for serializing and later passing back to import_filenames().

filenames()

filenames (file_storage const& fs, renamed_files const& rf);

construct a view over fs with the renames recorded in rf applied. Both references must outlive the view.

file_flags()

file_flags_t file_flags (file_index_t const index) const;

returns the file flags for the file at index

end_file()

file_index_t end_file () const noexcept;

one past-the-end file index

pad_file_at()

bool pad_file_at (file_index_t const index) const;

returns true if the file at index is a pad file

file_size() file_offset()

std::int64_t file_size (file_index_t const index) const;
std::int64_t file_offset (file_index_t const index) const;

returns the file size or file offset for the file at index. The file offset is in the torrent space, of all files in the torrent, in the order they are defined.

file_absolute_path() file_path()

std::string file_path (file_index_t const index, std::string const& save_path = "") const;
bool file_absolute_path (file_index_t const index) const;

returns the on-disk path for the file at index, applying any rename recorded in the underlying renamed_files. If save_path is non-empty it is prepended to relative paths. file_absolute_path() returns true if the recorded rename is an absolute path (in which case save_path is ignored).

symlink()

std::string symlink (file_index_t const index) const;

If the file at index is a symbolic link, its link target is returned. otherwise an empty string.

file_range()

index_range<file_index_t> file_range () const noexcept;

all file indices in the underlying file_storage. Convenient in range-for loops.

num_pieces() end_piece() num_files()

piece_index_t end_piece () const;
int num_files () const noexcept;
int num_pieces () const;

the number of files in the underlying file_storage, the number of pieces, and the one-past-the-end piece index.

map_block()

std::vector<file_slice> map_block (piece_index_t const piece, std::int64_t const offset
      , std::int64_t const size) const;

returns the list of file slices that make up the piece at piece, starting at offset into the piece and covering size bytes. Each entry identifies one file and the byte range within it that contributes to the requested block.

map_file()

peer_request map_file (file_index_t const file, std::int64_t const offset, int const size) const;

inverse of map_block(): maps a byte range within the file at file (starting at offset, of length size) to a peer_request identifying the piece, piece-offset and length in torrent space.

root()

sha256_hash root (file_index_t const index) const;

returns the v2 merkle root (pieces root) for the file at index. Returns a zero hash for v1-only torrents.

piece_length()

int piece_length () const;

the piece size, in bytes. All pieces have this size except the last, which may be shorter.