From e01f628b8e03f6ff27a9bcd548dd6812abc2d9b2 Mon Sep 17 00:00:00 2001 From: Arvid Norberg Date: Wed, 31 Dec 2008 09:31:23 +0000 Subject: [PATCH] added more documentation for create_torrent. #448 --- docs/make_torrent.rst | 89 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 87 insertions(+), 2 deletions(-) diff --git a/docs/make_torrent.rst b/docs/make_torrent.rst index 6598cb127..e33a2893d 100644 --- a/docs/make_torrent.rst +++ b/docs/make_torrent.rst @@ -175,10 +175,12 @@ The ``create_torrent`` class has the following synopsis:: void add_url_seed(std::string const& url); void add_node(std::pair const& node); void add_tracker(std::string const& url, int tier = 0); + void set_priv(bool p); int num_pieces() const; int piece_length() const; int piece_size(int i) const; + bool priv() const; }; create_torrent() @@ -190,14 +192,17 @@ create_torrent() create_torrent(file_storage& fs); create_torrent(torrent_info const& ti); -The contrstructor that does not take a piece_size will calculate +The ``piece_size`` is the size of each piece in bytes. It must +be a multiple of 16 kiB. + +The constructor that does not take a piece_size will calculate a piece size such that the torrent file is roughly 40 kB. The overlad 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 not +the content of the info dictionary (such as ``set_hash()``), will have any affect. generate() @@ -213,4 +218,84 @@ 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. +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()`_. + +add_url_seed() +-------------- + + :: + + void add_url_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. + +add_node() +---------- + + :: + + void add_node(std::pair 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.