docs/make_torrent.rst

   1 =================
   2 creating torrents
   3 =================
   4
   5 :Author: Arvid Norberg, arvid@rasterbar.com
   6
   7 .. contents:: Table of contents
   8   :depth: 2
   9   :backlinks: none
  10
  11 overview
  12 ========
  13
  14 This section describes the functions and classes that are used
  15 to create torrent files. It is a layered API with low level classes
  16 and higher level convenience functions. A torrent is created in 4
  17 steps:
  18
  19 1. first the files that will be part of the torrent are determined.
  20 2. the torrent properties are set, such as tracker url, web seeds,
  21    DHT nodes etc.
  22 3. Read through all the files in the torrent, SHA-1 all the data
  23    and set the piece hashes.
  24 4. The torrent is bencoded into a file or buffer.
  25
  26 If there are a lot of files and or deep directoy hierarchies to
  27 traverse, step one can be time consuming.
  28
  29 Typically step 3 is by far the most time consuming step, since it
  30 requires to read all the bytes from all the files in the torrent.
  31
  32 All of these classes and functions are declared by including
  33 ``libtorrent/create_torrent.hpp``.
  34
  35 high level example
  36 ==================
  37
  38 ::
  39
  40         file_storage fs;
  41
  42         // recursively adds files in directories
  43         add_files(fs, "./my_torrent");
  44
  45         create_torrent t(fs);
  46         t.add_tracker("http://my.tracker.com/announce");
  47         t.set_creator("libtorrent example");
  48
  49         // reads the files and calculates the hashes
  50         set_piece_hashes(t, ".");
  51
  52         ofstream out("my_torrent.torrent", std::ios_base::binary);
  53         bencode(std::ostream_iterator<char>(out), t.generate());
  54
  55 add_files
  56 =========
  57
  58         ::
  59
  60                 template <class Pred>
  61                 void add_files(file_storage& fs, boost::filesystem::path const& path, Pred p);
  62
  63                 void add_files(file_storage& fs, boost::filesystem::path const& path);
  64
  65 Adds the file specified by ``path`` to the ``file_storage`` object. In case ``path``
  66 refers to a diretory, files will be added recursively from the directory.
  67
  68 If specified, the predicate ``p`` is called once for every file and directory that
  69 is encountered. files for which ``p`` returns true are added, and directories for
  70 which ``p`` returns true are traversed. ``p`` must have the following signature::
  71
  72         bool Pred(boost::filesystem::path const& p);
  73
  74 The path that is passed in to the predicate is the full path of the file or
  75 directory. If no predicate is specified, all files are added, and all directories
  76 are traveresed.
  77
  78 The ".." directory is never traversed.
  79
  80 set_piece_hashes()
  81 ==================
  82
  83         ::
  84
  85                 template <class Fun>
  86                 void set_piece_hashes(create_torrent& t, boost::filesystem::path const& p, Fun f);
  87
  88                 void set_piece_hashes(create_torrent& t, boost::filesystem::path const& p);
  89
  90 This function will assume that the files added to the torrent file exists at path
  91 ``p``, read those files and hash the content and set the hashes in the ``create_torrent``
  92 object. The optional function ``f`` is called in between every hash that is set. ``f``
  93 must have the following signature::
  94
  95         void Fun(int);
  96
  97 file_storage
  98 ============
  99
 100 The ``file_storage`` class represents a file list and the piece
 101 size. Everything necessary to interpret a regular bittorrent storage
 102 file structure. Its synopsis::
 103
 104         class file_storage
 105         {
 106         public:
 107
 108                 bool is_valid() const;
 109
 110                 void add_file(file_entry const& e);
 111                 void add_file(fs::path const& p, size_type size);
 112                 void rename_file(int index, std::string const& new_filename);
 113
 114                 std::vector<file_slice> map_block(int piece, size_type offset
 115                         , int size) const;
 116                 peer_request map_file(int file, size_type offset, int size) const;
 117
 118                 typedef std::vector<file_entry>::const_iterator iterator;
 119                 typedef std::vector<file_entry>::const_reverse_iterator reverse_iterator;
 120
 121                 iterator begin() const;
 122                 iterator end() const;
 123                 reverse_iterator rbegin();
 124                 reverse_iterator rend() const;
 125                 int num_files() const;
 126
 127                 file_entry const& at(int index) const;
 128
 129                 size_type total_size() const;
 130                 void set_num_pieces(int n);
 131                 int num_pieces() const;
 132                 void set_piece_length(int l);
 133                 int piece_length() const;
 134                 int piece_size(int index) const;
 135
 136                 void set_name(std::string const& n);
 137                 const std::string& name() const;
 138
 139                 void swap(file_storage& ti);
 140         }
 141
 142
 143 create_torrent
 144 ==============
 145
 146 The ``create_torrent`` class has the following synopsis::
 147
 148
 149         struct create_torrent
 150         {
 151                 create_torrent(file_storage& fs, int piece_size);
 152                 create_torrent(file_storage& fs);
 153
 154                 entry generate() const;
 155
 156                 file_storage const& files() const;
 157
 158                 void set_comment(char const* str);
 159                 void set_creator(char const* str);
 160                 void set_hash(int index, sha1_hash const& h);
 161                 void add_url_seed(std::string const& url);
 162                 void add_node(std::pair<std::string, int> const& node);
 163                 void add_tracker(std::string const& url, int tier = 0);
 164
 165                 int num_pieces() const;
 166                 int piece_length() const;
 167                 int piece_size(int i) const;
 168         };
 169
 170 create_torrent()
 171 ----------------
 172
 173         ::
 174
 175                 create_torrent(file_storage& fs, int piece_size);
 176                 create_torrent(file_storage& fs);
 177
 178 The contrstructor that does not take a piece_size will calculate
 179 a piece size such that the torrent file is roughly 40 kB.
 180
 181 generate()
 182 ----------
 183
 184         ::
 185
 186                 entry generate() const;
 187
 188 This function will generate the .torrent file as a bencode tree. In order to
 189 generate the flat file, use the bencode() function.
 190
 191 It may be useful to add custom entries to the torrent file before bencoding it
 192 and saving it to disk.
 193
 194