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

void add_file (std::string const& p, size_type size, int flags = 0
      , std::time_t mtime = 0, std::string const& s_p = "");
void add_file (file_entry const& e, char const* filehash = 0);

Adds a file to the file storage. The 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.

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 built in functions to traverse a directory to add files will make sure this requirement is fulfilled.

rename_file()

void rename_file (int 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.

rename_file_borrow()

void rename_file_borrow (int index, char const* new_filename, int len);

this is a low-level function that sets the name of a file by making it reference a buffer that is not owned by the file_storage. it's an optimization used when loading .torrent files, to not duplicate names in memory.

map_block()

std::vector<file_slice> map_block (int piece, size_type offset
      , int 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().

map_file()

peer_request map_file (int file, size_type 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 ove map_block().

num_files()

int num_files () const;

returns the number of files in the file_storage

at()

file_entry at (int index) const;

returns a file_entry with information about the file at index. Index must be in the range [0, num_files() ).

total_size()

size_type total_size () const;

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

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

piece_length() set_piece_length()

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

set and get the size of each piece in this torrent. This size is typically an even power of 2. It doesn't have to be though. It should be divisible by 16kiB however.

piece_size()

int piece_size (int 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.

set_name() name()

void set_name (std::string const& n);
const std::string& 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);

swap all content of this with ti.

optimize()

void optimize (int pad_file_limit = -1, int alignment = -1);

if pad_file_limit >= 0, files larger than that limit will be padded, default is to not add any padding (-1). The alignment specifies the alignment files should be padded to. This defaults to the piece size (-1) but it may also make sense to set it to 16 kiB, or something divisible by 16 kiB. If pad_file_limit is 0, every file will be padded (except empty ones).

mtime() hash() symlink() file_name() pad_file_at() file_size() file_path() file_offset()

size_type file_size (int index) const;
sha1_hash hash (int index) const;
std::string file_name (int index) const;
size_type file_offset (int index) const;
time_t mtime (int index) const;
bool pad_file_at (int index) const;
std::string const& symlink (int index) const;
std::string file_path (int index, std::string const& save_path = "") const;

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

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

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.

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

int file_flags (int index) const;

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

file_base() set_file_base()

void set_file_base (int index, size_type off);
size_type file_base (int index) const;

The file base of a file is the offset within the file on the filsystem where it starts to write. For the most part, this is always 0. It's possible to map several files (in the torrent) into a single file on the filesystem by making them all point to the same filename, but with different file bases, so that they don't overlap. torrent_info::remap_files() can be used to use a new file layout.

file_index_at_offset()

int file_index_at_offset (size_type offset) const;

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

file_name_len() file_name_ptr()

char const* file_name_ptr (int index) const;
int file_name_len (int index) const;

low-level function. returns a pointer to the internal storage for the filename. This string may not be null terinated! the file_name_len() function returns the length of the filename.

enum flags_t

Declared in "libtorrent/file_storage.hpp"

enum file_flags_t

Declared in "libtorrent/file_storage.hpp"

default_storage_constructor()

Declared in "libtorrent/storage_defs.hpp"

storage_interface* default_storage_constructor (
   file_storage const&, file_storage const* mapped, std::string const&, file_pool&
   , std::vector<boost::uint8_t> const&);

the constructor function for the regular file storage. This is the default value for add_torrent_params::storage.

disabled_storage_constructor()

Declared in "libtorrent/storage_defs.hpp"

storage_interface* disabled_storage_constructor (
   file_storage const&, file_storage const* mapped, std::string const&, file_pool&
   , std::vector<boost::uint8_t> const&);

the constructor function for the disabled storage. This can be used for testing and benchmarking. It will throw away any data written to it and return garbage for anything read from it.

enum storage_mode_t

Declared in "libtorrent/storage_defs.hpp"