Author: Arvid Norberg, arvid@libtorrent.org
Version: 1.1.2

home

Storage

file_slice

Declared in "libtorrent/file_storage.hpp"

represents a window of a file in a torrent.

The file_index refers to the index of the file (in the torrent_info). To get the path and filename, use file_path() and give the file_index as argument. The offset is the byte offset in the file where the range starts, and size is the number of bytes this range is. The size + offset will never be greater than the file size.

struct file_slice
{
   int file_index;
   boost::int64_t offset;
   boost::int64_t size;
};
file_index
the index of the file
offset
the offset from the start of the file, in bytes
size
the size of the window, in bytes

file_storage

Declared in "libtorrent/file_storage.hpp"

The file_storage class represents a file list and the piece size. Everything necessary to interpret a regular bittorrent storage file structure.

class file_storage
{
   bool is_valid () const;
   void reserve (int num_files);
   void add_file (std::string const& path, boost::int64_t file_size, int file_flags = 0
      , std::time_t mtime = 0, std::string const& symlink_path = "");
   void add_file_borrow (char const* filename, int filename_len
      , std::string const& path, boost::int64_t file_size
      , boost::uint32_t file_flags = 0, char const* filehash = 0
      , boost::int64_t mtime = 0, std::string const& symlink_path = "");
   void rename_file (int index, std::string const& new_filename);
   std::vector<file_slice> map_block (int piece, boost::int64_t offset
      , int size) const;
   peer_request map_file (int file, boost::int64_t offset, int size) const;
   int num_files () const;
   boost::int64_t total_size () const;
   void set_num_pieces (int n);
   int num_pieces () const;
   void set_piece_length (int l);
   int piece_length () const;
   int piece_size (int index) const;
   std::string const& name () const;
   void set_name (std::string const& n);
   void swap (file_storage& ti);
   void unload ();
   bool is_loaded () const;
   void optimize (int pad_file_limit = -1, int alignment = -1
      , bool tail_padding = false);
   sha1_hash hash (int index) const;
   std::string file_name (int index) const;
   boost::int64_t 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;
   boost::int64_t file_size (int index) const;
   boost::uint32_t file_path_hash (int index, std::string const& save_path) const;
   void all_path_hashes (boost::unordered_set<boost::uint32_t>& table) const;
   std::vector<std::string> const& paths () const;
   int file_flags (int index) const;
   bool file_absolute_path (int index) const;
   int file_index_at_offset (boost::int64_t offset) const;
   char const* file_name_ptr (int index) const;
   int file_name_len (int index) const;
   void apply_pointer_offset (ptrdiff_t off);

   enum flags_t
   {
      pad_file,
      attribute_hidden,
      attribute_executable,
      attribute_symlink,
   };

   enum file_flags_t
   {
      flag_pad_file,
      flag_hidden,
      flag_executable,
      flag_symlink,
   };
};

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

void add_file (std::string const& path, boost::int64_t file_size, int file_flags = 0
      , std::time_t mtime = 0, std::string const& symlink_path = "");
void add_file_borrow (char const* filename, int filename_len
      , std::string const& path, boost::int64_t file_size
      , boost::uint32_t file_flags = 0, char const* filehash = 0
      , boost::int64_t mtime = 0, std::string const& symlink_path = "");

Adds a file to the file storage. The add_file_borrow version expects that filename points to a string of filename_len bytes that 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 NULL, the filename from path is used and not borrowed. In this case filename_len is ignored.

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.

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.

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.

map_block()

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

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 (int file, boost::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 ove 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;

returns the number of files in the file_storage

total_size()

boost::int64_t 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()

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.

swap()

void swap (file_storage& ti);

swap all content of this with ti.

unload()

void unload ();

deallocates most of the memory used by this instance, leaving it only partially usable

is_loaded()

bool is_loaded () const;

returns true when populated with at least one file

optimize()

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

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). tail_padding indicates whether aligned files also are padded at the end to make them end aligned. This is required for mutable torrents, since piece hashes are compared

file_path_hash()

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

returns the crc32 hash of file_path(index)

all_path_hashes()

void all_path_hashes (boost::unordered_set<boost::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()

int file_flags (int index) const;

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

file_absolute_path()

bool file_absolute_path (int 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_offset()

int file_index_at_offset (boost::int64_t 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 terminated! the file_name_len() function returns the length of the filename.

apply_pointer_offset()

void apply_pointer_offset (ptrdiff_t off);

if the backing buffer changed for this storage, this is the pointer offset to add to any pointers to make them point into the new buffer

enum flags_t

Declared in "libtorrent/file_storage.hpp"

name value description
pad_file 1 the file is a pad file. It's required to contain zeroes at it will not be saved to disk. Its purpose is to make the following file start on a piece boundary.
attribute_hidden 2 this file has the hidden attribute set. This is primarily a windows attribute
attribute_executable 4 this file has the executable attribute set.
attribute_symlink 8 this file is a symbolic link. It should have a link target string associated with it.

enum file_flags_t

Declared in "libtorrent/file_storage.hpp"

name value description
flag_pad_file 1 this file is a pad file. The creator of the torrent promises the file is entirely filled with zeroes and does not need to be downloaded. The purpose is just to align the next file to either a block or piece boundary.
flag_hidden 2 this file is hidden (sets the hidden attribute on windows)
flag_executable 4 this file is executable (sets the executable bit on posix like systems)
flag_symlink 8 this file is a symlink. The symlink target is specified in a separate field

storage_params

Declared in "libtorrent/storage_defs.hpp"

see default_storage::default_storage()

struct storage_params
{
   storage_params ();

   file_storage const* files;
   file_storage const* mapped_files;
   std::string path;
   file_pool* pool;
   storage_mode_t mode;
   std::vector<boost::uint8_t> const* priorities;
   torrent_info const* info;
};

default_storage_constructor()

Declared in "libtorrent/storage_defs.hpp"

storage_interface* default_storage_constructor (storage_params 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 (storage_params 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.

zero_storage_constructor()

Declared in "libtorrent/storage_defs.hpp"

storage_interface* zero_storage_constructor (storage_params const&);

enum storage_mode_t

Declared in "libtorrent/storage_defs.hpp"

name value description
storage_mode_allocate 0 All pieces will be written to their final position, all files will be allocated in full when the torrent is first started. This is done with fallocate() and similar calls. This mode minimizes fragmentation.
storage_mode_sparse 1 All pieces will be written to the place where they belong and sparse files will be used. This is the recommended, and default mode.