premiere
/
premiere-libtorrent
2
2
Fork 1
Code Issues Pull Requests Releases Wiki Activity

move documentation from manual to headers

This commit is contained in:
Arvid Norberg 2013-07-26 06:11:10 +00:00
parent 13d6a20aec
commit 7cbd54b327
6 changed files with 314 additions and 801 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
docs/gen_reference_doc.py
View File

@ -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
View File

@ -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
==============

69
include/libtorrent/entry.hpp
View File

@ -83,8 +83,9 @@ namespace libtorrent
type_error(const char* error): std::runtime_error(error) {}
};
class 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.
class TORRENT_EXPORT entry
{
public:
@ -127,6 +128,47 @@ namespace libtorrent
void operator=(list_type const&);
void operator=(integer_type 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.
//
// 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.
integer_type& integer();
const integer_type& integer() const;
string_type& string();
@ -138,19 +180,34 @@ namespace libtorrent
void swap(entry& e);
// these functions requires that the entry
// is a dictionary, otherwise they will throw
entry& operator[](char const* key);
// 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``.
entry& operator[](char const* key);
entry& operator[](std::string const& key);
#ifndef BOOST_NO_EXCEPTIONS
const entry& operator[](char const* key) const;
const entry& operator[](std::string const& key) const;
#endif
// 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.
entry* find_key(char const* key);
entry const* find_key(char const* key) const;
entry* find_key(std::string const& key);
entry const* find_key(std::string const& key) const;
#if (defined TORRENT_VERBOSE_LOGGING || defined TORRENT_DEBUG) && TORRENT_USE_IOSTREAM
void print(std::ostream& os, int indent = 0) const;
#endif

56
include/libtorrent/file_storage.hpp
View File

@ -51,19 +51,53 @@ namespace libtorrent
file_entry();
~file_entry();
// the full path of this file. The paths are unicode strings
// encoded in UTF-8.
std::string path;
size_type offset; // the offset of this file inside the torrent
size_type size; // the size of this file
// the offset in the file where the storage starts.
// This is always 0 unless parts of the torrent is
// compressed into a single file, such as a so-called part file.
// the offset of this file inside the torrent
size_type offset;
// 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.
size_type size;
// 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.
size_type file_base;
// the modification time of this file specified in posix time.
std::time_t mtime;
// 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.
sha1_hash filehash;
// 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.
bool pad_file:1;
// true if the file was marked as hidden (on windows).
bool hidden_attribute:1;
// true if the file was marked as executable (posix)
bool executable_attribute:1;
// 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.
bool symlink_attribute:1;
// 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.
std::string symlink_path;
};
@ -154,10 +188,22 @@ namespace libtorrent
int path_index;
};
// 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_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.
struct TORRENT_EXPORT file_slice
{
// the index of the file
int file_index;
// the offset from the start of the file, in bytes
size_type offset;
// the size of the window, in bytes
size_type size;
};

3
include/libtorrent/peer_request.hpp
View File

@ -37,8 +37,11 @@ namespace libtorrent
{
struct TORRENT_EXTRA_EXPORT peer_request
{
// the index of the piece in which the range starts.
int piece;
// the offset within that piece where the range starts.
int start;
// the size of the range, in bytes.
int length;
bool operator==(peer_request const& r) const
{ return piece == r.piece && start == r.start && length == r.length; }

222
include/libtorrent/torrent_info.hpp
View File

@ -80,6 +80,8 @@ namespace libtorrent
TORRENT_EXTRA_EXPORT int merkle_get_sibling(int);
TORRENT_EXTRA_EXPORT void trim_path_element(std::string& path_element);
// this class holds information about one bittorrent tracker, as it
// relates to a specific torrent.
struct TORRENT_EXPORT announce_entry
{
announce_entry(std::string const& u);
@ -98,6 +100,12 @@ namespace libtorrent
// this error code specifies what error occurred
error_code last_error;
// 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.
int next_announce_in() const;
int min_announce_in() const;
@ -109,48 +117,60 @@ namespace libtorrent
// TODO: include the number of peers received from this tracker, at last announce
// these 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 this tracker has returned scrape data, these fields are filled
// in with valid numbers. Otherwise they are set to -1.
// the number of current downloaders
int scrape_incomplete;
// the number of current seeds
int scrape_complete;
// the cumulative number of completed downloads, ever
int scrape_downloaded;
// the tier this tracker belongs to
boost::uint8_t tier;
// the number of times this tracker can fail
// in a row before it's removed. 0 means unlimited
// the max number of failures to announce to this tracker in
// a row, before this tracker is not used anymore. 0 means unlimited
boost::uint8_t fail_limit;
// the number of times in a row this tracker has failed
// the number of times in a row we have failed to announce to this
// tracker.
boost::uint8_t fails:7;
// true if we're currently trying to announce with
// this tracker
// true while we're waiting for a response from the tracker.
bool updating:1;
// flags for the source bitmask, each indicating where
// we heard about this tracker
enum tracker_source
{
// the tracker was part of the .torrent file
source_torrent = 1,
// the tracker was added programatically via the add_troacker()_ function
source_client = 2,
// the tracker was part of a magnet link
source_magnet_link = 4,
// the tracker was received from the swarm via tracker exchange
source_tex = 8
};
// where did we get this tracker from
// a bitmask specifying which sources we got this tracker from.
boost::uint8_t source:4;
// is set to true if we have ever received a response from
// this tracker
// set to true the first time we receive a valid response
// from this tracker.
bool verified:1;
// this is true if event start has been sent to the tracker
// 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.
bool start_sent:1;
// this is true if event completed has been sent to the tracker
// set to true when we send a event=completed.
bool complete_sent:1;
// this is false the stats sent to this tracker will be 0
@ -203,9 +223,18 @@ namespace libtorrent
return type < e.type;
}
// The URL of the web seed
std::string url;
// The type of web seed (see type_t)
type_t type;
// Optional authentication. If this is set, it's passed
// in as HTTP basic auth to the web seed. The format is:
// username:password.
std::string auth;
// Any extra HTTP headers that need to be passed to the web seed
headers_t extra_headers;
// if this is > now, we can't reconnect yet
@ -221,6 +250,8 @@ namespace libtorrent
// callback remove it
bool removed;
// if the hostname of the web seed has been resolved,
// this is its IP address
tcp::endpoint endpoint;
// this is the peer_info field used for the
@ -235,6 +266,7 @@ namespace libtorrent
typedef libtorrent_exception invalid_torrent_file;
#endif
// This class represents the information stored in a .torrent file
class TORRENT_EXPORT torrent_info : public intrusive_ptr_base<torrent_info>
{
public:
@ -243,6 +275,30 @@ namespace libtorrent
void check_invariant() const;
#endif
// 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.
#ifndef BOOST_NO_EXCEPTIONS
torrent_info(lazy_entry const& torrent_file, int flags = 0);
torrent_info(char const* buffer, int size, int flags = 0);
@ -251,7 +307,6 @@ namespace libtorrent
torrent_info(std::wstring const& filename, int flags = 0);
#endif // TORRENT_USE_WSTRING
#endif
torrent_info(torrent_info const& t, int flags = 0);
torrent_info(sha1_hash const& info_hash, int flags = 0);
torrent_info(lazy_entry const& torrent_file, error_code& ec, int flags = 0);
@ -263,15 +318,39 @@ namespace libtorrent
~torrent_info();
// 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.
file_storage const& files() const { return m_files; }
file_storage const& orig_files() const { return m_orig_files ? *m_orig_files : m_files; }
// 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.
void rename_file(int index, std::string const& new_filename)
{
copy_on_write();
m_files.rename_file(index, new_filename);
}
#if TORRENT_USE_WSTRING
void rename_file(int index, std::wstring const& new_filename)
{
@ -280,8 +359,21 @@ namespace libtorrent
}
#endif // TORRENT_USE_WSTRING
// 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.
void remap_files(file_storage const& f);
// ``add_tracker()`` adds a tracker to the announce-list. The ``tier`` determines the order in
// which the trackers are to be tried.
//
// 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.
// For more information, see announce_entry_.
void add_tracker(std::string const& url, int tier = 0);
std::vector<announce_entry> const& trackers() const { return m_urls; }
@ -293,37 +385,80 @@ namespace libtorrent
std::vector<std::string> http_seeds() const TORRENT_DEPRECATED;
#endif // TORRENT_NO_DEPRECATE
void add_url_seed(std::string const& url
// ``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.
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
{ return m_web_seeds; }
// ``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.
size_type total_size() const { return m_files.total_size(); }
int piece_length() const { return m_files.piece_length(); }
int num_pieces() const { return m_files.num_pieces(); }
const sha1_hash& info_hash() const { return m_info_hash; }
const std::string& name() const { return m_files.name(); }
typedef file_storage::iterator file_iterator;
typedef file_storage::reverse_iterator reverse_file_iterator;
// 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.
file_iterator begin_files() const { return m_files.begin(); }
file_iterator end_files() const { return m_files.end(); }
reverse_file_iterator rbegin_files() const { return m_files.rbegin(); }
reverse_file_iterator rend_files() const { return m_files.rend(); }
// If you need index-access to files you can use the ``num_files()`` and ``file_at()``
// to access files using indices.
int num_files() const { return m_files.num_files(); }
file_entry file_at(int index) const { return m_files.at(index); }
file_iterator file_at_offset(size_type offset) const
{ return m_files.file_at_offset(offset); }
// 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. See file_slice_.
std::vector<file_slice> map_block(int piece, size_type offset, int size) const
{ return m_files.map_block(piece, offset, size); }
// 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. See peer_request_.
//
// 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()``.
peer_request map_file(int file, size_type offset, int size) const
{ return m_files.map_file(file, offset, size); }
@ -343,19 +478,20 @@ namespace libtorrent
bool is_valid() const { return m_files.is_valid(); }
// returns true if this torrent is private. i.e., it should not be
// distributed on the trackerless network (the kademlia DHT).
bool priv() const { return m_private; }
bool is_i2p() const { return m_i2p; }
// ``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.
int piece_size(int index) const { return m_files.piece_size(index); }
sha1_hash hash_for_piece(int index) const
{ return sha1_hash(hash_for_piece_ptr(index)); }
std::vector<sha1_hash> const& merkle_tree() const { return m_merkle_tree; }
void set_merkle_tree(std::vector<sha1_hash>& h)
{ TORRENT_ASSERT(h.size() == m_merkle_tree.size() ); m_merkle_tree.swap(h); }
char const* hash_for_piece_ptr(int index) const
{
TORRENT_ASSERT(index >= 0);
@ -375,19 +511,48 @@ namespace libtorrent
}
}
boost::optional<time_t> creation_date() const;
// ``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.
std::vector<sha1_hash> const& merkle_tree() const { return m_merkle_tree; }
void set_merkle_tree(std::vector<sha1_hash>& h)
{ TORRENT_ASSERT(h.size() == m_merkle_tree.size() ); m_merkle_tree.swap(h); }
// ``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
const std::string& name() const { return m_files.name(); }
boost::optional<time_t> creation_date() const;
const std::string& creator() const
{ return m_created_by; }
const std::string& comment() const
{ return m_comment; }
// dht nodes to add to the routing table/bootstrap from
typedef std::vector<std::pair<std::string, int> > nodes_t;
// If this torrent contains any DHT nodes, they are put in this vector in their original
// form (host name and port number).
nodes_t const& nodes() const
{ return m_nodes; }
// 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.
void add_node(std::pair<std::string, int> const& node)
{ m_nodes.push_back(node); }
@ -406,11 +571,12 @@ namespace libtorrent
void swap(torrent_info& ti);
// ``metadata()`` returns a the raw info section of the torrent file. The size
// of the metadata is returned by ``metadata_size()``.
int metadata_size() const { return m_info_section_size; }
boost::shared_array<char> metadata() const
{ return m_info_section; }
int metadata_size() const { return m_info_section_size; }
bool add_merkle_nodes(std::map<int, sha1_hash> const& subtree
, int piece);
std::map<int, sha1_hash> build_merkle_list(int piece) const;