move documentation from manual to headers
This commit is contained in:
Arvid Norberg
@@ -209,7 +209,7 @@ def parse_class(lno, lines, filename):
|
||||
|
||||
if l.startswith('//'):
|
||||
if verbose: print 'desc %s' % l
|
||||
l = l.split('//')[1]
|
||||
l = l[2:]
|
||||
if len(l) and l[0] == ' ': l = l[1:]
|
||||
context += l + '\n'
|
||||
continue
|
||||
@@ -299,7 +299,7 @@ def parse_enum(lno, lines, filename):
|
||||
|
||||
if l.startswith('//'):
|
||||
if verbose: print 'desc %s' % l
|
||||
l = l.split('//')[1]
|
||||
l = l[2:]
|
||||
if len(l) and l[0] == ' ': l = l[1:]
|
||||
context += l + '\n'
|
||||
continue
|
||||
@@ -415,7 +415,7 @@ for filename in files:
|
||||
|
||||
if l.startswith('//'):
|
||||
if verbose: print 'desc %s' % l
|
||||
l = l.split('//')[1]
|
||||
l = l[2:]
|
||||
if len(l) and l[0] == ' ': l = l[1:]
|
||||
context += l + '\n'
|
||||
continue
|
||||
|
||||
759
docs/manual.rst
759
docs/manual.rst
@@ -93,765 +93,6 @@ For documentation on these types, please refer to the `asio documentation`_.
|
||||
|
||||
.. _`asio documentation`: http://asio.sourceforge.net/asio-0.3.8/doc/asio/reference.html
|
||||
|
||||
entry
|
||||
=====
|
||||
|
||||
The ``entry`` class represents one node in a bencoded hierarchy. It works as a
|
||||
variant type, it can be either a list, a dictionary (``std::map``), an integer
|
||||
or a string. This is its synopsis::
|
||||
|
||||
class entry
|
||||
{
|
||||
public:
|
||||
|
||||
typedef std::map<std::string, entry> dictionary_type;
|
||||
typedef std::string string_type;
|
||||
typedef std::list<entry> list_type;
|
||||
typedef size_type integer_type;
|
||||
|
||||
enum data_type
|
||||
{
|
||||
int_t,
|
||||
string_t,
|
||||
list_t,
|
||||
dictionary_t,
|
||||
undefined_t
|
||||
};
|
||||
|
||||
data_type type() const;
|
||||
|
||||
entry(dictionary_type const&);
|
||||
entry(string_type const&);
|
||||
entry(list_type const&);
|
||||
entry(integer_type const&);
|
||||
|
||||
entry();
|
||||
entry(data_type t);
|
||||
entry(entry const& e);
|
||||
~entry();
|
||||
|
||||
void operator=(entry const& e);
|
||||
void operator=(dictionary_type const&);
|
||||
void operator=(string_type const&);
|
||||
void operator=(list_type const&);
|
||||
void operator=(integer_type const&);
|
||||
|
||||
integer_type& integer();
|
||||
integer_type const& integer() const;
|
||||
string_type& string();
|
||||
string_type const& string() const;
|
||||
list_type& list();
|
||||
list_type const& list() const;
|
||||
dictionary_type& dict();
|
||||
dictionary_type const& dict() const;
|
||||
|
||||
// these functions requires that the entry
|
||||
// is a dictionary, otherwise they will throw
|
||||
entry& operator[](char const* key);
|
||||
entry& operator[](std::string const& key);
|
||||
entry const& operator[](char const* key) const;
|
||||
entry const& operator[](std::string const& key) const;
|
||||
entry* find_key(char const* key);
|
||||
entry const* find_key(char const* key) const;
|
||||
|
||||
void print(std::ostream& os, int indent = 0) const;
|
||||
};
|
||||
|
||||
*TODO: finish documentation of entry.*
|
||||
|
||||
integer() string() list() dict() type()
|
||||
---------------------------------------
|
||||
|
||||
::
|
||||
|
||||
integer_type& integer();
|
||||
integer_type const& integer() const;
|
||||
string_type& string();
|
||||
string_type const& string() const;
|
||||
list_type& list();
|
||||
list_type const& list() const;
|
||||
dictionary_type& dict();
|
||||
dictionary_type const& dict() const;
|
||||
|
||||
The ``integer()``, ``string()``, ``list()`` and ``dict()`` functions
|
||||
are accessors that return the respective type. If the ``entry`` object isn't of the
|
||||
type you request, the accessor will throw libtorrent_exception_ (which derives from
|
||||
``std::runtime_error``). You can ask an ``entry`` for its type through the
|
||||
``type()`` function.
|
||||
|
||||
The ``print()`` function is there for debug purposes only.
|
||||
|
||||
If you want to create an ``entry`` you give it the type you want it to have in its
|
||||
constructor, and then use one of the non-const accessors to get a reference which you then
|
||||
can assign the value you want it to have.
|
||||
|
||||
The typical code to get info from a torrent file will then look like this::
|
||||
|
||||
entry torrent_file;
|
||||
// ...
|
||||
|
||||
// throws if this is not a dictionary
|
||||
entry::dictionary_type const& dict = torrent_file.dict();
|
||||
entry::dictionary_type::const_iterator i;
|
||||
i = dict.find("announce");
|
||||
if (i != dict.end())
|
||||
{
|
||||
std::string tracker_url = i->second.string();
|
||||
std::cout << tracker_url << "\n";
|
||||
}
|
||||
|
||||
|
||||
The following code is equivalent, but a little bit shorter::
|
||||
|
||||
entry torrent_file;
|
||||
// ...
|
||||
|
||||
// throws if this is not a dictionary
|
||||
if (entry* i = torrent_file.find_key("announce"))
|
||||
{
|
||||
std::string tracker_url = i->string();
|
||||
std::cout << tracker_url << "\n";
|
||||
}
|
||||
|
||||
|
||||
To make it easier to extract information from a torrent file, the class torrent_info_
|
||||
exists.
|
||||
|
||||
|
||||
operator[]
|
||||
----------
|
||||
|
||||
::
|
||||
|
||||
entry& operator[](char const* key);
|
||||
entry& operator[](std::string const& key);
|
||||
entry const& operator[](char const* key) const;
|
||||
entry const& operator[](std::string const& key) const;
|
||||
|
||||
All of these functions requires the entry to be a dictionary, if it isn't they
|
||||
will throw ``libtorrent::type_error``.
|
||||
|
||||
The non-const versions of the ``operator[]`` will return a reference to either
|
||||
the existing element at the given key or, if there is no element with the
|
||||
given key, a reference to a newly inserted element at that key.
|
||||
|
||||
The const version of ``operator[]`` will only return a reference to an
|
||||
existing element at the given key. If the key is not found, it will throw
|
||||
``libtorrent::type_error``.
|
||||
|
||||
|
||||
find_key()
|
||||
----------
|
||||
|
||||
::
|
||||
|
||||
entry* find_key(char const* key);
|
||||
entry const* find_key(char const* key) const;
|
||||
|
||||
These functions requires the entry to be a dictionary, if it isn't they
|
||||
will throw ``libtorrent::type_error``.
|
||||
|
||||
They will look for an element at the given key in the dictionary, if the
|
||||
element cannot be found, they will return 0. If an element with the given
|
||||
key is found, the return a pointer to it.
|
||||
|
||||
|
||||
torrent_info
|
||||
============
|
||||
|
||||
In previous versions of libtorrent, this class was also used for creating
|
||||
torrent files. This functionality has been moved to ``create_torrent``, see
|
||||
make_torrent_.
|
||||
|
||||
The ``torrent_info`` has the following synopsis::
|
||||
|
||||
class torrent_info
|
||||
{
|
||||
public:
|
||||
|
||||
// these constructors throws exceptions on error
|
||||
torrent_info(sha1_hash const& info_hash, int flags = 0);
|
||||
torrent_info(lazy_entry const& torrent_file, int flags = 0);
|
||||
torrent_info(char const* buffer, int size, int flags = 0);
|
||||
torrent_info(std::string const& filename, int flags = 0);
|
||||
torrent_info(std::wstring const& filename, int flags = 0);
|
||||
|
||||
// these constructors sets the error code on error
|
||||
torrent_info(sha1_hash const& info_hash, error_code& ec, int flags = 0);
|
||||
torrent_info(lazy_entry const& torrent_file, error_code& ec, int flags = 0);
|
||||
torrent_info(char const* buffer, int size, error_code& ec, int flags = 0);
|
||||
torrent_info(fs::path const& filename, error_code& ec, int flags = 0);
|
||||
torrent_info(fs::wpath const& filename, error_code& ec, int flags = 0);
|
||||
|
||||
void add_tracker(std::string const& url, int tier = 0);
|
||||
std::vector<announce_entry> const& trackers() const;
|
||||
|
||||
file_storage const& files() const;
|
||||
file_storage const& orig_files() const;
|
||||
|
||||
void remap_files(file_storage const& f);
|
||||
|
||||
void rename_file(int index, std::string const& new_filename);
|
||||
void rename_file(int index, std::wstring const& new_filename);
|
||||
|
||||
typedef file_storage::iterator file_iterator;
|
||||
typedef file_storage::reverse_iterator reverse_file_iterator;
|
||||
|
||||
file_iterator begin_files() const;
|
||||
file_iterator end_files() const;
|
||||
reverse_file_iterator rbegin_files() const;
|
||||
reverse_file_iterator rend_files() const;
|
||||
|
||||
int num_files() const;
|
||||
file_entry const& file_at(int index) const;
|
||||
|
||||
std::vector<file_slice> map_block(int piece, size_type offset
|
||||
, int size) const;
|
||||
peer_request map_file(int file_index, size_type file_offset
|
||||
, int size) const;
|
||||
|
||||
bool priv() const;
|
||||
|
||||
void add_url_seed(std::string const& url);
|
||||
void add_http_seed(std::string const& url);
|
||||
std::vector<web_seed_entry> const& web_seeds() const;
|
||||
|
||||
size_type total_size() const;
|
||||
int piece_length() const;
|
||||
int num_pieces() const;
|
||||
sha1_hash const& info_hash() const;
|
||||
std::string const& name() const;
|
||||
std::string const& comment() const;
|
||||
std::string const& creator() const;
|
||||
|
||||
std::vector<std::pair<std::string, int> > const& nodes() const;
|
||||
void add_node(std::pair<std::string, int> const& node);
|
||||
|
||||
boost::optional<time_t> creation_date() const;
|
||||
|
||||
int piece_size(unsigned int index) const;
|
||||
sha1_hash const& hash_for_piece(unsigned int index) const;
|
||||
char const* hash_for_piece_ptr(unsigned int index) const;
|
||||
|
||||
std::vector<sha1_hash> const& merkle_tree() const;
|
||||
void set_merkle_tree(std::vector<sha1_hash>& h);
|
||||
|
||||
boost::shared_array<char> metadata() const;
|
||||
int metadata_size() const;
|
||||
};
|
||||
|
||||
torrent_info()
|
||||
--------------
|
||||
|
||||
::
|
||||
|
||||
torrent_info(sha1_hash const& info_hash, int flags = 0);
|
||||
torrent_info(lazy_entry const& torrent_file, int flags = 0);
|
||||
torrent_info(char const* buffer, int size, int flags = 0);
|
||||
torrent_info(std::string const& filename, int flags = 0);
|
||||
torrent_info(std::wstring const& filename, int flags = 0);
|
||||
|
||||
torrent_info(sha1_hash const& info_hash, error_code& ec, int flags = 0);
|
||||
torrent_info(lazy_entry const& torrent_file, error_code& ec, int flags = 0);
|
||||
torrent_info(char const* buffer, int size, error_code& ec, int flags = 0);
|
||||
torrent_info(fs::path const& filename, error_code& ec, int flags = 0);
|
||||
torrent_info(fs::wpath const& filename, error_code& ec, int flags = 0);
|
||||
|
||||
The constructor that takes an info-hash will initialize the info-hash to the given value,
|
||||
but leave all other fields empty. This is used internally when downloading torrents without
|
||||
the metadata. The metadata will be created by libtorrent as soon as it has been downloaded
|
||||
from the swarm.
|
||||
|
||||
The constructor that takes a ``lazy_entry`` will create a ``torrent_info`` object from the
|
||||
information found in the given torrent_file. The ``lazy_entry`` represents a tree node in
|
||||
an bencoded file. To load an ordinary .torrent file
|
||||
into a ``lazy_entry``, use `lazy_bdecode()`_.
|
||||
|
||||
The version that takes a buffer pointer and a size will decode it as a .torrent file and
|
||||
initialize the torrent_info object for you.
|
||||
|
||||
The version that takes a filename will simply load the torrent file and decode it inside
|
||||
the constructor, for convenience. This might not be the most suitable for applications that
|
||||
want to be able to report detailed errors on what might go wrong.
|
||||
|
||||
The overloads that takes an ``error_code const&`` never throws if an error occur, they
|
||||
will simply set the error code to describe what went wrong and not fully initialize the
|
||||
torrent_info object. The overloads that do not take the extra error_code_ parameter will
|
||||
always throw if an error occurs. These overloads are not available when building without
|
||||
exception support.
|
||||
|
||||
The ``flags`` argument is currently unused.
|
||||
|
||||
|
||||
add_tracker()
|
||||
-------------
|
||||
|
||||
::
|
||||
|
||||
void add_tracker(std::string const& url, int tier = 0);
|
||||
|
||||
``add_tracker()`` adds a tracker to the announce-list. The ``tier`` determines the order in
|
||||
which the trackers are to be tried. For more information see `trackers()`_.
|
||||
|
||||
files() orig_files()
|
||||
--------------------
|
||||
|
||||
::
|
||||
|
||||
file_storage const& files() const;
|
||||
file_storage const& orig_files() const;
|
||||
|
||||
The ``file_storage`` object contains the information on how to map the pieces to
|
||||
files. It is separated from the ``torrent_info`` object because when creating torrents
|
||||
a storage object needs to be created without having a torrent file. When renaming files
|
||||
in a storage, the storage needs to make its own copy of the ``file_storage`` in order
|
||||
to make its mapping differ from the one in the torrent file.
|
||||
|
||||
``orig_files()`` returns the original (unmodified) file storage for this torrent. This
|
||||
is used by the web server connection, which needs to request files with the original
|
||||
names. Filename may be chaged using ``torrent_info::rename_file()``.
|
||||
|
||||
For more information on the ``file_storage`` object, see the separate document on how
|
||||
to create torrents.
|
||||
|
||||
remap_files()
|
||||
-------------
|
||||
|
||||
::
|
||||
|
||||
void remap_files(file_storage const& f);
|
||||
|
||||
Remaps the file storage to a new file layout. This can be used to, for instance,
|
||||
download all data in a torrent to a single file, or to a number of fixed size
|
||||
sector aligned files, regardless of the number and sizes of the files in the torrent.
|
||||
|
||||
The new specified ``file_storage`` must have the exact same size as the current one.
|
||||
|
||||
rename_file()
|
||||
-------------
|
||||
|
||||
::
|
||||
|
||||
void rename_file(int index, std::string const& new_filename);
|
||||
void rename_file(int index, std::wstring const& new_filename);
|
||||
|
||||
Renames a the file with the specified index to the new name. The new filename is
|
||||
reflected by the ``file_storage`` returned by ``files()`` but not by the one
|
||||
returned by ``orig_files()``.
|
||||
|
||||
If you want to rename the base name of the torrent (for a multifile torrent), you
|
||||
can copy the ``file_storage`` (see `files() orig_files()`_), change the name, and
|
||||
then use `remap_files()`_.
|
||||
|
||||
The ``new_filename`` can both be a relative path, in which case the file name
|
||||
is relative to the ``save_path`` of the torrent. If the ``new_filename`` is
|
||||
an absolute path (i.e. ``is_complete(new_filename) == true``), then the file
|
||||
is detached from the ``save_path`` of the torrent. In this case the file is
|
||||
not moved when move_storage_ is invoked.
|
||||
|
||||
|
||||
begin_files() end_files() rbegin_files() rend_files()
|
||||
-----------------------------------------------------
|
||||
|
||||
::
|
||||
|
||||
file_iterator begin_files() const;
|
||||
file_iterator end_files() const;
|
||||
reverse_file_iterator rbegin_files() const;
|
||||
reverse_file_iterator rend_files() const;
|
||||
|
||||
This class will need some explanation. First of all, to get a list of all files
|
||||
in the torrent, you can use ``begin_files()``, ``end_files()``,
|
||||
``rbegin_files()`` and ``rend_files()``. These will give you standard vector
|
||||
iterators with the type ``internal_file_entry``, which is an internal type.
|
||||
|
||||
You can resolve it into the public representation of a file (``file_entry``)
|
||||
using the ``file_storage::at`` function, which takes an index and an iterator;
|
||||
|
||||
::
|
||||
|
||||
struct file_entry
|
||||
{
|
||||
std::string path;
|
||||
size_type offset;
|
||||
size_type size;
|
||||
size_type file_base;
|
||||
time_t mtime;
|
||||
sha1_hash filehash;
|
||||
bool pad_file:1;
|
||||
bool hidden_attribute:1;
|
||||
bool executable_attribute:1;
|
||||
bool symlink_attribute:1;
|
||||
};
|
||||
|
||||
The ``path`` is the full path of this file. The paths are unicode strings
|
||||
encoded in UTF-8.
|
||||
|
||||
``size`` is the size of the file (in bytes) and ``offset`` is the byte offset
|
||||
of the file within the torrent. i.e. the sum of all the sizes of the files
|
||||
before it in the list.
|
||||
|
||||
``file_base`` is the offset in the file where the storage should start. The normal
|
||||
case is to have this set to 0, so that the storage starts saving data at the start
|
||||
if the file. In cases where multiple files are mapped into the same file though,
|
||||
the ``file_base`` should be set to an offset so that the different regions do
|
||||
not overlap. This is used when mapping "unselected" files into a so-called part
|
||||
file.
|
||||
|
||||
``mtime`` is the modification time of this file specified in posix time.
|
||||
|
||||
``symlink_path`` is the path which this is a symlink to, or empty if this is
|
||||
not a symlink. This field is only used if the ``symlink_attribute`` is set.
|
||||
|
||||
``filehash`` is a sha-1 hash of the content of the file, or zeroes, if no
|
||||
file hash was present in the torrent file. It can be used to potentially
|
||||
find alternative sources for the file.
|
||||
|
||||
``pad_file`` is set to true for files that are not part of the data of the torrent.
|
||||
They are just there to make sure the next file is aligned to a particular byte offset
|
||||
or piece boundry. These files should typically be hidden from an end user. They are
|
||||
not written to disk.
|
||||
|
||||
``hidden_attribute`` is true if the file was marked as hidden (on windows).
|
||||
|
||||
``executable_attribute`` is true if the file was marked as executable (posix)
|
||||
|
||||
``symlink_attribute`` is true if the file was a symlink. If this is the case
|
||||
the ``symlink_index`` refers to a string which specifies the original location
|
||||
where the data for this file was found.
|
||||
|
||||
num_files() file_at()
|
||||
---------------------
|
||||
|
||||
::
|
||||
|
||||
int num_files() const;
|
||||
file_entry const& file_at(int index) const;
|
||||
|
||||
If you need index-access to files you can use the ``num_files()`` and ``file_at()``
|
||||
to access files using indices.
|
||||
|
||||
|
||||
map_block()
|
||||
-----------
|
||||
|
||||
::
|
||||
|
||||
std::vector<file_slice> map_block(int piece, size_type offset
|
||||
, int size) const;
|
||||
|
||||
This function will map a piece index, a byte offset within that piece and
|
||||
a size (in bytes) into the corresponding files with offsets where that data
|
||||
for that piece is supposed to be stored.
|
||||
|
||||
The file slice struct looks like this::
|
||||
|
||||
struct file_slice
|
||||
{
|
||||
int file_index;
|
||||
size_type offset;
|
||||
size_type size;
|
||||
};
|
||||
|
||||
|
||||
The ``file_index`` refers to the index of the file (in the torrent_info).
|
||||
To get the path and filename, use ``file_at()`` 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.
|
||||
|
||||
|
||||
map_file()
|
||||
----------
|
||||
|
||||
::
|
||||
|
||||
peer_request map_file(int file_index, size_type file_offset
|
||||
, int size) const;
|
||||
|
||||
This function will map a range in a specific file into a range in the torrent.
|
||||
The ``file_offset`` parameter is the offset in the file, given in bytes, where
|
||||
0 is the start of the file.
|
||||
The ``peer_request`` structure looks like this::
|
||||
|
||||
struct peer_request
|
||||
{
|
||||
int piece;
|
||||
int start;
|
||||
int length;
|
||||
bool operator==(peer_request const& r) const;
|
||||
};
|
||||
|
||||
``piece`` is the index of the piece in which the range starts.
|
||||
``start`` is the offset within that piece where the range starts.
|
||||
``length`` is the size of the range, in bytes.
|
||||
|
||||
The input range is assumed to be valid within the torrent. ``file_offset``
|
||||
+ ``size`` is not allowed to be greater than the file size. ``file_index``
|
||||
must refer to a valid file, i.e. it cannot be >= ``num_files()``.
|
||||
|
||||
|
||||
add_url_seed() add_http_seed()
|
||||
------------------------------
|
||||
|
||||
::
|
||||
|
||||
void add_url_seed(std::string const& url
|
||||
, std::string const& extern_auth = std::string()
|
||||
, web_seed_entry::headers_t const& extra_headers = web_seed_entry::headers_t());
|
||||
void add_http_seed(std::string const& url
|
||||
, std::string const& extern_auth = std::string()
|
||||
, web_seed_entry::headers_t const& extra_headers = web_seed_entry::headers_t());
|
||||
std::vector<web_seed_entry> const& web_seeds() const;
|
||||
|
||||
``web_seeds()`` returns all url seeds and http seeds in the torrent. Each entry
|
||||
is a ``web_seed_entry`` and may refer to either a url seed or http seed.
|
||||
|
||||
``add_url_seed()`` and ``add_http_seed()`` adds one url to the list of
|
||||
url/http seeds. Currently, the only transport protocol supported for the url
|
||||
is http.
|
||||
|
||||
The ``extern_auth`` argument can be used for other athorization schemese than
|
||||
basic HTTP authorization. If set, it will override any username and password
|
||||
found in the URL itself. The string will be sent as the HTTP authorization header's
|
||||
value (without specifying "Basic").
|
||||
|
||||
The ``extra_headers`` argument defaults to an empty list, but can be used to
|
||||
insert custom HTTP headers in the requests to a specific web seed.
|
||||
|
||||
See `HTTP seeding`_ for more information.
|
||||
|
||||
The ``web_seed_entry`` has the following members::
|
||||
|
||||
struct web_seed_entry
|
||||
{
|
||||
enum type_t { url_seed, http_seed };
|
||||
|
||||
typedef std::vector<std::pair<std::string, std::string> > headers_t;
|
||||
|
||||
web_seed_entry(std::string const& url_, type_t type_
|
||||
, std::string const& auth_ = std::string()
|
||||
, headers_t const& extra_headers_ = headers_t());
|
||||
|
||||
bool operator==(web_seed_entry const& e) const;
|
||||
bool operator<(web_seed_entry const& e) const;
|
||||
|
||||
std::string url;
|
||||
type_t type;
|
||||
std::string auth;
|
||||
headers_t extra_headers;
|
||||
|
||||
// ...
|
||||
};
|
||||
|
||||
|
||||
trackers()
|
||||
----------
|
||||
|
||||
::
|
||||
|
||||
std::vector<announce_entry> const& trackers() const;
|
||||
|
||||
The ``trackers()`` function will return a sorted vector of ``announce_entry``.
|
||||
Each announce entry contains a string, which is the tracker url, and a tier index. The
|
||||
tier index is the high-level priority. No matter which trackers that works or not, the
|
||||
ones with lower tier will always be tried before the one with higher tier number.
|
||||
|
||||
::
|
||||
|
||||
struct announce_entry
|
||||
{
|
||||
announce_entry(std::string const& url);
|
||||
std::string url;
|
||||
|
||||
int next_announce_in() const;
|
||||
int min_announce_in() const;
|
||||
|
||||
int scrape_incomplete;
|
||||
int scrape_complete;
|
||||
int scrape_downloaded;
|
||||
|
||||
error_code last_error;
|
||||
|
||||
std::string message;
|
||||
|
||||
boost::uint8_t tier;
|
||||
boost::uint8_t fail_limit;
|
||||
boost::uint8_t fails;
|
||||
|
||||
enum tracker_source
|
||||
{
|
||||
source_torrent = 1,
|
||||
source_client = 2,
|
||||
source_magnet_link = 4,
|
||||
source_tex = 8
|
||||
};
|
||||
boost::uint8_t source;
|
||||
|
||||
bool verified:1;
|
||||
bool updating:1;
|
||||
bool start_sent:1;
|
||||
bool complete_sent:1;
|
||||
};
|
||||
|
||||
``next_announce_in()`` returns the number of seconds to the next announce on
|
||||
this tracker. ``min_announce_in()`` returns the number of seconds until we are
|
||||
allowed to force another tracker update with this tracker.
|
||||
|
||||
If the last time this tracker was contacted failed, ``last_error`` is the error
|
||||
code describing what error occurred.
|
||||
|
||||
``scrape_incomplete``, ``scrape_complete`` and ``scrape_downloaded`` are either
|
||||
-1 or the scrape information this tracker last responded with. *incomplete* is
|
||||
the current number of downloaders in the swarm, *complete* is the current number
|
||||
of seeds in the swarm and *downloaded* is the cumulative number of completed
|
||||
downloads of this torrent, since the beginning of time (from this tracker's point
|
||||
of view).
|
||||
|
||||
If the last time this tracker was contacted, the tracker returned a warning
|
||||
or error message, ``message`` contains that message.
|
||||
|
||||
``fail_limit`` is the max number of failures to announce to this tracker in
|
||||
a row, before this tracker is not used anymore.
|
||||
|
||||
``fails`` is the number of times in a row we have failed to announce to this
|
||||
tracker.
|
||||
|
||||
``source`` is a bitmask specifying which sources we got this tracker from.
|
||||
|
||||
``verified`` is set to true the first time we receive a valid response
|
||||
from this tracker.
|
||||
|
||||
``updating`` is true while we're waiting for a response from the tracker.
|
||||
|
||||
``start_sent`` is set to true when we get a valid response from an announce
|
||||
with event=started. If it is set, we won't send start in the subsequent
|
||||
announces.
|
||||
|
||||
``complete_sent`` is set to true when we send a event=completed.
|
||||
|
||||
|
||||
total_size() piece_length() piece_size() num_pieces()
|
||||
-----------------------------------------------------
|
||||
|
||||
::
|
||||
|
||||
size_type total_size() const;
|
||||
int piece_length() const;
|
||||
int piece_size(unsigned int index) const;
|
||||
int num_pieces() const;
|
||||
|
||||
|
||||
``total_size()``, ``piece_length()`` and ``num_pieces()`` returns the total
|
||||
number of bytes the torrent-file represents (all the files in it), the number of byte for
|
||||
each piece and the total number of pieces, respectively. The difference between
|
||||
``piece_size()`` and ``piece_length()`` is that ``piece_size()`` takes
|
||||
the piece index as argument and gives you the exact size of that piece. It will always
|
||||
be the same as ``piece_length()`` except in the case of the last piece, which may
|
||||
be smaller.
|
||||
|
||||
|
||||
hash_for_piece() hash_for_piece_ptr() info_hash()
|
||||
-------------------------------------------------
|
||||
|
||||
::
|
||||
|
||||
size_type piece_size(unsigned int index) const;
|
||||
sha1_hash const& hash_for_piece(unsigned int index) const;
|
||||
char const* hash_for_piece_ptr(unsigned int index) const;
|
||||
|
||||
``hash_for_piece()`` takes a piece-index and returns the 20-bytes sha1-hash for that
|
||||
piece and ``info_hash()`` returns the 20-bytes sha1-hash for the info-section of the
|
||||
torrent file. For more information on the ``sha1_hash``, see the big_number_ class.
|
||||
``hash_for_piece_ptr()`` returns a pointer to the 20 byte sha1 digest for the piece.
|
||||
Note that the string is not null-terminated.
|
||||
|
||||
merkle_tree() set_merkle_tree()
|
||||
-------------------------------
|
||||
|
||||
::
|
||||
|
||||
std::vector<sha1_hash> const& merkle_tree() const;
|
||||
void set_merkle_tree(std::vector<sha1_hash>& h);
|
||||
|
||||
``merkle_tree()`` returns a reference to the merkle tree for this torrent, if any.
|
||||
|
||||
``set_merkle_tree()`` moves the passed in merkle tree into the torrent_info object.
|
||||
i.e. ``h`` will not be identical after the call. You need to set the merkle tree for
|
||||
a torrent that you've just created (as a merkle torrent). The merkle tree is retrieved
|
||||
from the ``create_torrent::merkle_tree()`` function, and need to be saved separately
|
||||
from the torrent file itself. Once it's added to libtorrent, the merkle tree will be
|
||||
persisted in the resume data.
|
||||
|
||||
|
||||
name() comment() creation_date() creator()
|
||||
------------------------------------------
|
||||
|
||||
::
|
||||
|
||||
std::string const& name() const;
|
||||
std::string const& comment() const;
|
||||
std::string const& creator() const;
|
||||
boost::optional<time_t> creation_date() const;
|
||||
|
||||
``name()`` returns the name of the torrent.
|
||||
|
||||
``comment()`` returns the comment associated with the torrent. If there's no comment,
|
||||
it will return an empty string. ``creation_date()`` returns the creation date of
|
||||
the torrent as time_t (`posix time`_). If there's no time stamp in the torrent file,
|
||||
the optional object will be uninitialized.
|
||||
|
||||
Both the name and the comment is UTF-8 encoded strings.
|
||||
|
||||
``creator()`` returns the creator string in the torrent. If there is no creator string
|
||||
it will return an empty string.
|
||||
|
||||
.. _`posix time`: http://www.opengroup.org/onlinepubs/009695399/functions/time.html
|
||||
|
||||
priv()
|
||||
------
|
||||
|
||||
::
|
||||
|
||||
bool priv() const;
|
||||
|
||||
``priv()`` returns true if this torrent is private. i.e., it should not be
|
||||
distributed on the trackerless network (the kademlia DHT).
|
||||
|
||||
|
||||
nodes()
|
||||
-------
|
||||
|
||||
::
|
||||
|
||||
std::vector<std::pair<std::string, int> > const& nodes() const;
|
||||
|
||||
If this torrent contains any DHT nodes, they are put in this vector in their original
|
||||
form (host name and port number).
|
||||
|
||||
add_node()
|
||||
----------
|
||||
|
||||
::
|
||||
|
||||
void add_node(std::pair<std::string, int> const& node);
|
||||
|
||||
This is used when creating torrent. Use this to add a known DHT node. It may
|
||||
be used, by the client, to bootstrap into the DHT network.
|
||||
|
||||
|
||||
metadata() metadata_size()
|
||||
--------------------------
|
||||
|
||||
::
|
||||
|
||||
boost::shared_array<char> metadata() const;
|
||||
int metadata_size() const;
|
||||
|
||||
``metadata()`` returns a the raw info section of the torrent file. The size
|
||||
of the metadata is returned by ``metadata_size()``.
|
||||
|
||||
|
||||
torrent_handle
|
||||
==============
|
||||
|
||||
|
||||
Reference in New Issue
Block a user