add_file()

void add_file(file_entry const& e);
void add_file(std::string const& p, size_type size, int flags = 0);
void add_file(std::wstring const& p, size_type size, int flags = 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. The possible arreibutes are:

pad_file
attribute_hidden
attribute_executable

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.

hash() symlink() mtime() file_index()

sha1_hash hash(internal_file_entry const& fe) const;
std::string const& symlink(internal_file_entry const& fe) const;
time_t mtime(internal_file_entry const& fe) const;
int file_index(internal_file_entry const& fe) const;

These functions are used to query the symlink, file hash, modification time and the file-index from a internal_file_entry, which typically would be acquired from an iterator.

For these functions to function, the file entry must be an actual object from this same file_storage object. It may not be a copy.

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 modification time is the posix time when a file was last modified when the torrent was created, or 0 if it was not provided.

The file index of a file is simply a 0 based index of the file as they are ordered in the torrent file.

file_base() set_file_base()

size_type file_base(internal_file_entry const& fe) const;
void set_file_base(internal_file_entry const& fe, size_type off);

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.

create_torrent()

enum {
        optimize = 1
        , merkle = 2
        , modification_time = 4
        , symlink = 8
        , calculate_file_hashes = 16
};
create_torrent(file_storage& fs, int piece_size = 0, int pad_size_limit = -1
        , int flags = optimize);
create_torrent(torrent_info const& ti);

The piece_size is the size of each piece in bytes. It must be a multiple of 16 kiB. If a piece size of 0 is specified, a piece_size will be calculated such that the torrent file is roughly 40 kB.

If a pad_size_limit is specified (other than -1), any file larger than the specified number of bytes will be preceeded by a pad file to align it with the start of a piece. The pad_file_limit is ignored unless the optimize flag is passed. Typically it doesn't make sense to set this any lower than 4kiB.

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

The flags arguments specifies options for the torrent creation. It can be any combination of the following flags:

optimize

This will insert pad files to align the files to piece boundaries, for optimized disk-I/O.

merkle

This will create a merkle hash tree torrent. A merkle torrent cannot be opened in clients that don't specifically support merkle torrents. The benefit is that the resulting torrent file will be much smaller and not grow with more pieces. When this option is specified, it is recommended to have a fairly small piece size, say 64 kiB. When creating merkle torrents, the full hash tree is also generated and should be saved off separately. It is accessed through the merkle_tree() function.

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.

symlink

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.

calculate_file_hashes

If this is set, the set_piece_hashes() function will, as it calculates the piece hashes, also calculate the file hashes and add those associated with each file. Note that unless you use the set_piece_hashes() function, this flag will have no effect.

generate()

entry generate() const;

This function will generate the .torrent file as a bencode tree. In order to generate the flat file, use the bencode() function.

It may be useful to add custom entries to the torrent file before bencoding it and saving it to disk.

If anything goes wrong during torrent generation, this function will return an empty entry structure. You can test for this condition by querying the type of the entry:

file_storage fs;
// add file ...
create_torrent t(fs);
// add trackers and piece hashes ...
e = t.generate();

if (e.type() == entry::undefined_t)
{
        // something went wrong
}

For instance, you cannot generate a torrent with 0 files in it. If you don't add any files to the file_storage, torrent generation will fail.

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

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

set_file_hash()

void set_file_hash(int index, sha1_hash const& h);

This sets the sha1 hash for this file. This hash will end up under the key sha1 associated with this file (for multi-file torrents) or in the root info dictionary for single-file torrents.

add_url_seed() add_http_seed()

void add_url_seed(std::string const& url);
void add_http_seed(std::string const& 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.

The second function, add_http_seed() adds an HTTP seed instead.

add_node()

void add_node(std::pair<std::string, int> const& 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(std::string const& 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_priv() priv()

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

Sets and queries the private flag of the torrent.

merkle_tree()

std::vector<sha1_hash> const& merkle_tree() const;

This function returns the merkle hash tree, if the torrent was created as a merkle torrent. The tree is created by generate() and won't be valid until that function has been called. When creating a merkle tree torrent, the actual tree itself has to be saved off separately and fed into libtorrent the first time you start seeding it, through the torrent_info::set_merkle_tree() function. From that point onwards, the tree will be saved in the resume data.