1567 lines
79 KiB
HTML
Executable File
1567 lines
79 KiB
HTML
Executable File
<?xml version="1.0" encoding="utf-8" ?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
<meta name="generator" content="Docutils 0.3.1: http://docutils.sourceforge.net/" />
|
|
<title>libtorrent manual</title>
|
|
<link rel="stylesheet" href="style.css" type="text/css" />
|
|
</head>
|
|
<body>
|
|
<div class="document" id="libtorrent-manual">
|
|
<h1 class="title">libtorrent manual</h1>
|
|
<div class="contents topic" id="contents">
|
|
<p class="topic-title"><a name="contents">Contents</a></p>
|
|
<ul class="simple">
|
|
<li><a class="reference" href="#introduction" id="id10" name="id10">introduction</a></li>
|
|
<li><a class="reference" href="#building" id="id11" name="id11">building</a><ul>
|
|
<li><a class="reference" href="#release-and-debug-builds" id="id12" name="id12">release and debug builds</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#using" id="id13" name="id13">using</a></li>
|
|
<li><a class="reference" href="#session" id="id14" name="id14">session</a></li>
|
|
<li><a class="reference" href="#parsing-torrent-files" id="id15" name="id15">parsing torrent files</a></li>
|
|
<li><a class="reference" href="#entry" id="id16" name="id16">entry</a></li>
|
|
<li><a class="reference" href="#torrent-info" id="id17" name="id17">torrent_info</a></li>
|
|
<li><a class="reference" href="#torrent-handle" id="id18" name="id18">torrent_handle</a><ul>
|
|
<li><a class="reference" href="#status" id="id19" name="id19">status()</a></li>
|
|
<li><a class="reference" href="#get-download-queue" id="id20" name="id20">get_download_queue()</a></li>
|
|
<li><a class="reference" href="#get-peer-info" id="id21" name="id21">get_peer_info()</a></li>
|
|
<li><a class="reference" href="#get-torrent-info" id="id22" name="id22">get_torrent_info()</a></li>
|
|
<li><a class="reference" href="#is-valid" id="id23" name="id23">is_valid()</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#address" id="id24" name="id24">address</a></li>
|
|
<li><a class="reference" href="#http-settings" id="id25" name="id25">http_settings</a></li>
|
|
<li><a class="reference" href="#big-number" id="id26" name="id26">big_number</a></li>
|
|
<li><a class="reference" href="#hasher" id="id27" name="id27">hasher</a></li>
|
|
<li><a class="reference" href="#fingerprint" id="id28" name="id28">fingerprint</a><ul>
|
|
<li><a class="reference" href="#identify-client" id="id29" name="id29">identify_client</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#alerts" id="id30" name="id30">alerts</a><ul>
|
|
<li><a class="reference" href="#listen-failed-alert" id="id31" name="id31">listen_failed_alert</a></li>
|
|
<li><a class="reference" href="#file-error-alert" id="id32" name="id32">file_error_alert</a></li>
|
|
<li><a class="reference" href="#tracker-alert" id="id33" name="id33">tracker_alert</a></li>
|
|
<li><a class="reference" href="#hash-failed-alert" id="id34" name="id34">hash_failed_alert</a></li>
|
|
<li><a class="reference" href="#peer-error-alert" id="id35" name="id35">peer_error_alert</a></li>
|
|
<li><a class="reference" href="#invalid-request-alert" id="id36" name="id36">invalid_request_alert</a></li>
|
|
<li><a class="reference" href="#torrent-finished-alert" id="id37" name="id37">torrent_finished_alert</a></li>
|
|
<li><a class="reference" href="#dispatcher" id="id38" name="id38">dispatcher</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#exceptions" id="id39" name="id39">exceptions</a><ul>
|
|
<li><a class="reference" href="#invalid-handle" id="id40" name="id40">invalid_handle</a></li>
|
|
<li><a class="reference" href="#duplicate-torrent" id="id41" name="id41">duplicate_torrent</a></li>
|
|
<li><a class="reference" href="#invalid-encoding" id="id42" name="id42">invalid_encoding</a></li>
|
|
<li><a class="reference" href="#type-error" id="id43" name="id43">type_error</a></li>
|
|
<li><a class="reference" href="#invalid-torrent-file" id="id44" name="id44">invalid_torrent_file</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#examples" id="id45" name="id45">examples</a><ul>
|
|
<li><a class="reference" href="#dump-torrent" id="id46" name="id46">dump_torrent</a></li>
|
|
<li><a class="reference" href="#simple-client" id="id47" name="id47">simple client</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#fast-resume" id="id48" name="id48">fast resume</a><ul>
|
|
<li><a class="reference" href="#file-format" id="id49" name="id49">file format</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#extensions" id="id50" name="id50">extensions</a></li>
|
|
<li><a class="reference" href="#filenames-checks" id="id51" name="id51">filenames checks</a></li>
|
|
<li><a class="reference" href="#aknowledgements" id="id52" name="id52">aknowledgements</a></li>
|
|
</ul>
|
|
</div>
|
|
<div class="section" id="introduction">
|
|
<h1><a name="introduction">introduction</a></h1>
|
|
<p>libtorrent is a C++ library that aims to be a good alternative to all the
|
|
other bittorrent implementations around. It is a
|
|
library and not a full featured client, although it comes with a working
|
|
example client.</p>
|
|
<p>The main goals of libtorrent are:</p>
|
|
<blockquote>
|
|
<ul class="simple">
|
|
<li>to be cpu efficient</li>
|
|
<li>to be memory efficient</li>
|
|
<li>to be very easy to use</li>
|
|
</ul>
|
|
</blockquote>
|
|
<p>libtorrent is not finished. It is an ongoing project (including this documentation).
|
|
The current state includes the following features:</p>
|
|
<blockquote>
|
|
<ul class="simple">
|
|
<li>multitracker extension support (as <a class="reference" href="http://home.elp.rr.com/tur/multitracker-spec.txt">described by TheShadow</a>)</li>
|
|
<li>serves multiple torrents on a single port and a single thread</li>
|
|
<li>supports http proxies and proxy authentication</li>
|
|
<li>gzipped tracker-responses</li>
|
|
<li>piece picking on block-level (as opposed to piece-level) like in <a class="reference" href="http://azureus.sourceforge.net">Azureus</a></li>
|
|
<li>queues torrents for file check, instead of checking all of them in parallel.</li>
|
|
<li>uses separate threads for checking files and for main downloader, with a fool-proof
|
|
thread-safe library interface. (i.e. There's no way for the user to cause a deadlock).</li>
|
|
<li>can limit the upload bandwidth usage and the maximum number of unchoked peers</li>
|
|
<li>piece-wise file allocation</li>
|
|
<li>implements fair trade. User settable trade-ratio, must at least be 1:1,
|
|
but one can choose to trade 1 for 2 or any other ratio that isn't unfair to the other
|
|
party.</li>
|
|
<li>fast resume support, a way to get rid of the costly piece check at the start
|
|
of a resumed torrent. Saves the storage state, piece_picker state as well as all local
|
|
peers in a separate fast-resume file.</li>
|
|
<li>supports the extension protocol <a class="reference" href="http://nolar.com/azureus/extended.htm">described by Nolar</a>. See <a class="reference" href="#extensions">extensions</a>.</li>
|
|
<li>supports files > 2 gigabytes (currently only on windows).</li>
|
|
<li>supports the <tt class="literal"><span class="pre">no_peer_id=1</span></tt> extension that will ease the load off trackers.</li>
|
|
<li>supports the <a class="reference" href="udp_tracker_protocol.html">udp-tracker protocol</a>.</li>
|
|
<li>possibility to limit the number of connections.</li>
|
|
<li>delays have messages if there's no other outgoing traffic to the peer, and doesn't
|
|
send have messages to peers that already has the piece. This saves bandwidth.</li>
|
|
<li>does not have any requirements on the piece order in a torrent that it resumes. This
|
|
means it can resume a torrent downloaded by any client.</li>
|
|
<li>adjusts the length of the request queue depending on download rate.</li>
|
|
</ul>
|
|
</blockquote>
|
|
<p>Functions that are yet to be implemented:</p>
|
|
<blockquote>
|
|
<ul class="simple">
|
|
<li>large file support on linux and Mac OS X.</li>
|
|
<li>better identification of peers that send bad data</li>
|
|
<li>ip-filters</li>
|
|
<li>file-level priority</li>
|
|
</ul>
|
|
</blockquote>
|
|
<p>libtorrent is portable at least among windows, macosx, and UNIX-systems. It uses boost.thread,
|
|
boost.filesystem, boost.date_time and various other boost libraries as well as zlib.</p>
|
|
<p>libtorrent has been successfully compiled and tested on:</p>
|
|
<blockquote>
|
|
<ul class="simple">
|
|
<li>Windows 2000 vc7.1</li>
|
|
<li>Linux x86 (debian) GCC 3.0.4, GCC 3.2.3</li>
|
|
<li>Windows 2000, msvc6 sp5 (does not support 64-bit values due to problems with operator<<(ostream&, __int64))</li>
|
|
</ul>
|
|
</blockquote>
|
|
<p>Fails on:</p>
|
|
<blockquote>
|
|
<ul class="simple">
|
|
<li>Linux x86 (Debian) GCC 2.95.4 (<tt class="literal"><span class="pre">std::ios_base</span></tt> is missing)</li>
|
|
<li>Cygwin GCC 3.3.1 (compiles but crashes)</li>
|
|
</ul>
|
|
</blockquote>
|
|
<p>libtorrent is released under the <a class="reference" href="http://www.opensource.org/licenses/bsd-license.php">BSD-license</a>.</p>
|
|
</div>
|
|
<div class="section" id="building">
|
|
<h1><a name="building">building</a></h1>
|
|
<p>To build libtorrent you need <a class="reference" href="http://www.boost.org">boost</a> and bjam installed.
|
|
Then you can use <tt class="literal"><span class="pre">bjam</span></tt> to build libtorrent.</p>
|
|
<!-- http://sourceforge.net/project/showfiles.php?group_id=7586&package_id=80982 -->
|
|
<p>To make bjam work, you need to set the environment variable <tt class="literal"><span class="pre">BOOST_ROOT</span></tt> to the
|
|
path where boost is installed (e.g. c:\boost_1_30_2 on windows). Then you can just run
|
|
<tt class="literal"><span class="pre">bjam</span></tt> in the libtorrent directory.</p>
|
|
<p>The Jamfile doesn't work yet. On unix-systems you can use the makefile however. You
|
|
first have to build boost.thread and boost.filesystem. You do this by, in the directory
|
|
'boost-1.30.2/tools/build/jam_src' run the build script <tt class="literal"><span class="pre">./build.sh</span></tt>. This should
|
|
produce at least one folder with the 'bin' prefix (and the rest of the name describes
|
|
your platform). Put the files in that folder somewhere in your path.</p>
|
|
<p>You can then invoke <tt class="literal"><span class="pre">bjam</span></tt> in the directories 'boost-1.30.2/libs/thread/build',
|
|
'boost-1.30.2/libs/date_time/build' and 'boost-1.30.2/libs/filesystem/build'. That will
|
|
produce the needed libraries. Put these libraries in the libtorrent root directory.
|
|
You then have to modify the makefile to use you prefered compiler and to have the
|
|
correct path to your boost istallation.</p>
|
|
<p>Then the makefile should be able to do the rest.</p>
|
|
<p>When building (with boost 1.30.2) on linux and solaris however, I found that I had to make the following
|
|
modifications to the boost.date-time library. In the file:
|
|
'boost-1.30.2/boost/date_time/gregorian_calendar.hpp' line 59. Prepend 'boost/date_time/'
|
|
to the include path.</p>
|
|
<p>And the second modification was in the file:
|
|
'boost-1.30.2/boost/date_time/microsec_time_clock.hpp' add the following include at the top
|
|
of the file:</p>
|
|
<pre class="literal-block">
|
|
#include "boost/cstdint.hpp"
|
|
</pre>
|
|
<p>In developer studio, you may have to set the compiler options "force conformance in for
|
|
loop scope" and "treat wchar_t as built-in type" to Yes.</p>
|
|
<p>TODO: more detailed build instructions.</p>
|
|
<div class="section" id="release-and-debug-builds">
|
|
<h2><a name="release-and-debug-builds">release and debug builds</a></h2>
|
|
<p>If you just invoke the makefile you'll get a debug build. In debug the libtorrent vill
|
|
have pretty expensive invariant checks and asserts built into it. If you want to disable
|
|
such checks (you want to do that in a release build) you can see the table below for which
|
|
defines you can use to control the build.</p>
|
|
<table border class="table">
|
|
<colgroup>
|
|
<col width="39%" />
|
|
<col width="61%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr><th>macro</th>
|
|
<th>description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<tr><td><tt class="literal"><span class="pre">NDEBUG</span></tt></td>
|
|
<td>If you define this macro, all asserts,
|
|
invariant checks and general debug code will be
|
|
removed. This option takes precedence over
|
|
other debug settings.</td>
|
|
</tr>
|
|
<tr><td><tt class="literal"><span class="pre">TORRENT_VERBOSE_LOGGING</span></tt></td>
|
|
<td>If you define this macro, every peer connection
|
|
will log its traffic to a log file.
|
|
This setting requires a debug build, i.e.
|
|
if you set <tt class="literal"><span class="pre">NDEBUG</span></tt> aswell, no logs will be
|
|
written.</td>
|
|
</tr>
|
|
<tr><td><tt class="literal"><span class="pre">TORRENT_STORAGE_DEBUG</span></tt></td>
|
|
<td>This will enable extra expensive invariant
|
|
checks in the storage, including logging of
|
|
piece sorting.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>If you experience that libtorrent uses unreasonable amounts of cpu, it will definately help to
|
|
define <tt class="literal"><span class="pre">NDEBUG</span></tt>.</p>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="using">
|
|
<h1><a name="using">using</a></h1>
|
|
<p>The interface of libtorrent consists of a few classes. The main class is
|
|
the <tt class="literal"><span class="pre">session</span></tt>, it contains the main loop that serves all torrents.</p>
|
|
<p>The basic usage is as follows:</p>
|
|
<ul>
|
|
<li><p class="first">conststruct a session</p>
|
|
</li>
|
|
<li><p class="first">parse .torrent-files and add them to the session</p>
|
|
</li>
|
|
<li><dl class="first">
|
|
<dt>main loop</dt>
|
|
<dd><ul class="first last simple">
|
|
<li>query the torrent_handles for progress</li>
|
|
<li>query the session for information</li>
|
|
<li>add and remove torrents from the session at run-time</li>
|
|
</ul>
|
|
</dd>
|
|
</dl>
|
|
</li>
|
|
<li><p class="first">destruct all torrent_handles</p>
|
|
</li>
|
|
<li><p class="first">destruct session object</p>
|
|
</li>
|
|
</ul>
|
|
<p>Each class and function is described in this manual.</p>
|
|
</div>
|
|
<div class="section" id="session">
|
|
<h1><a name="session">session</a></h1>
|
|
<p>The <tt class="literal"><span class="pre">session</span></tt> class has the following synopsis:</p>
|
|
<pre class="literal-block">
|
|
class session: public boost::noncopyable
|
|
{
|
|
session(std::pair<int, int> listen_port_range, const fingerprint& print);
|
|
session(std::pair<int, int> listen_port_range);
|
|
|
|
torrent_handle add_torrent(
|
|
const torrent_info& t
|
|
, const boost::filesystem::path& save_path
|
|
, const entry& resume_data = entry());
|
|
|
|
void remove_torrent(const torrent_handle& h);
|
|
|
|
void set_http_settings(const http_settings& settings);
|
|
void set_upload_rate_limit(int bytes_per_second);
|
|
|
|
std::auto_ptr<alert> pop_alert();
|
|
void set_severity_level(alert::severity_t s);
|
|
|
|
};
|
|
</pre>
|
|
<p>Once it's created, it will spawn the main thread that will do all the work.
|
|
The main thread will be idle as long it doesn't have any torrents to participate in.
|
|
You add torrents through the <tt class="literal"><span class="pre">add_torrent()</span></tt>-function where you give an
|
|
object representing the information found in the torrent file and the path where you
|
|
want to save the files. The <tt class="literal"><span class="pre">save_path</span></tt> will be prepended to the directory-
|
|
structure in the torrent-file. <tt class="literal"><span class="pre">add_torrent</span></tt> will throw <a class="reference" href="#duplicate-torrent">duplicate_torrent</a> exception
|
|
if the torrent already exists in the session.</p>
|
|
<p>The optional last parameter, <tt class="literal"><span class="pre">resume_data</span></tt> can be given if up to date fast-resume data
|
|
is available. The fast-resume data can be acquired from a running torrent by calling
|
|
<tt class="literal"><span class="pre">torrent_handle::write_resume_data()</span></tt>. See <a class="reference" href="#fast-resume">fast resume</a>.</p>
|
|
<p><tt class="literal"><span class="pre">remove_torrent()</span></tt> will close all peer connections associated with the torrent and tell
|
|
the tracker that we've stopped participating in the swarm.</p>
|
|
<p>If the torrent you are trying to add already exists in the session (is either queued
|
|
for checking, being checked or downloading) <tt class="literal"><span class="pre">add_torrent()</span></tt> will throw
|
|
<a class="reference" href="#duplicate-torrent">duplicate_torrent</a> which derives from <tt class="literal"><span class="pre">std::exception</span></tt>.</p>
|
|
<p>The difference between the two constructors is that one of them takes a fingerprint
|
|
as argument. If this is ommited, the client will get a default fingerprint stating
|
|
the version of libtorrent. The fingerprint is a short string that will be used in
|
|
the peer-id to identify the client and the client's version. For more details see the
|
|
fingerprint class.</p>
|
|
<p><tt class="literal"><span class="pre">set_upload_rate_limit()</span></tt> set the maximum number of bytes allowed to be
|
|
sent to peers per second. This bandwidth is distributed among all the peers. If
|
|
you don't want to limit upload rate, you can set this to -1 (the default).</p>
|
|
<p>The destructor of session will notify all trackers that our torrents has been shut down.
|
|
If some trackers are down, they will timout. All this before the destructor of session
|
|
returns. So, it's adviced that any kind of interface (such as windows) are closed before
|
|
destructing the sessoin object. Because it can take a few second for it to finish. The
|
|
timeout can be set with <tt class="literal"><span class="pre">set_http_settings()</span></tt>.</p>
|
|
<p>The <a class="reference" href="#torrent-handle">torrent_handle</a> returned by <tt class="literal"><span class="pre">add_torrent</span></tt> can be used to retrieve information
|
|
about the torrent's progress, its peers etc. It is also used to abort a torrent.</p>
|
|
<p>The constructor takes a range of listen ports as argument, if the first port is busy it will
|
|
increase the port number by one and try again. If it still fails it will continue
|
|
increasing the port number until it succeeds or has reached the end of the range. If it
|
|
fails with all ports, a <a class="reference" href="#listen-failed-alert">listen_failed_alert</a> will be posted and the session thread will
|
|
exit. The only thing you can do with your session if this alert is posted is to destruct
|
|
it and possibly try again or change the port range.</p>
|
|
<p>For information about the <tt class="literal"><span class="pre">pop_alert()</span></tt> function, see <a class="reference" href="#alerts">alerts</a>.</p>
|
|
</div>
|
|
<div class="section" id="parsing-torrent-files">
|
|
<h1><a name="parsing-torrent-files">parsing torrent files</a></h1>
|
|
<p>The torrent files are <a class="reference" href="http://wiki.theory.org/index.php/BitTorrentSpecification">bencoded</a>. There are two functions in libtorrent that can encode and decode
|
|
bencoded data. They are:</p>
|
|
<pre class="literal-block">
|
|
template<class InIt> entry bdecode(InIt start, InIt end);
|
|
template<class OutIt> void bencode(OutIt out, const entry& e);
|
|
</pre>
|
|
<p>The <a class="reference" href="#entry">entry</a> class is the internal representation of the bencoded data
|
|
and it can be used to retreive information, an <a class="reference" href="#entry">entry</a> can also be build by
|
|
the program and given to <tt class="literal"><span class="pre">bencode()</span></tt> to encode it into the <tt class="literal"><span class="pre">OutIt</span></tt>
|
|
iterator.</p>
|
|
<p>The <tt class="literal"><span class="pre">OutIt</span></tt> and <tt class="literal"><span class="pre">InIt</span></tt> are iterators
|
|
(<tt class="literal"><span class="pre">InputIterator_</span></tt> and <tt class="literal"><span class="pre">OutputIterator_</span></tt> respectively). They
|
|
are templates and are usually instantiated as <tt class="literal"><span class="pre">ostream_iterator_</span></tt>,
|
|
<tt class="literal"><span class="pre">back_insert_iterator_</span></tt> or <tt class="literal"><span class="pre">istream_iterator_</span></tt>. These
|
|
functions will assume that the iterator refers to a character
|
|
(<tt class="literal"><span class="pre">char</span></tt>). So, if you want to encode entry <tt class="literal"><span class="pre">e</span></tt> into a buffer
|
|
in memory, you can do it like this:</p>
|
|
<pre class="literal-block">
|
|
std::vector<char> buffer;
|
|
bencode(std::back_insert_iterator<std::vector<char> >(buf), e);
|
|
</pre>
|
|
<p>If you want to decode a torrent file from a buffer in memory, you can do it like this:</p>
|
|
<pre class="literal-block">
|
|
std::vector<char> buffer;
|
|
// ...
|
|
entry e = bdecode(buf.begin(), buf.end());
|
|
</pre>
|
|
<p>Or, if you have a raw char buffer:</p>
|
|
<pre class="literal-block">
|
|
const char* buf;
|
|
// ...
|
|
entry e = bdecode(buf, buf + data_size);
|
|
</pre>
|
|
<p>Now we just need to know how to retrieve information from the <a class="reference" href="#entry">entry</a>.</p>
|
|
<p>If <tt class="literal"><span class="pre">bdecode()</span></tt> encounters invalid encoded data in the range given to it
|
|
it will throw <a class="reference" href="#invalid-encoding">invalid_encoding</a>.</p>
|
|
</div>
|
|
<div class="section" id="entry">
|
|
<h1><a name="entry">entry</a></h1>
|
|
<p>The <tt class="literal"><span class="pre">entry</span></tt> class represents one node in a bencoded hierarchy. It works as a
|
|
variant type, it can be either a list, a dictionary (<tt class="literal"><span class="pre">std::map</span></tt>), an integer
|
|
or a string. This is its synopsis:</p>
|
|
<pre class="literal-block">
|
|
class entry
|
|
{
|
|
public:
|
|
|
|
typedef std::map<std::string, entry> dictionary_type;
|
|
typedef std::string string_type;
|
|
typedef std::vector<entry> list_type;
|
|
typedef implementation-defined integer_type;
|
|
|
|
enum data_type
|
|
{
|
|
int_t,
|
|
string_t,
|
|
list_t,
|
|
dictionary_t,
|
|
undefined_t
|
|
};
|
|
|
|
data_type type() const;
|
|
|
|
entry(const dictionary_type&);
|
|
entry(const string_type&);
|
|
entry(const list_type&);
|
|
entry(const integer_type&);
|
|
|
|
entry();
|
|
entry(data_type t);
|
|
entry(const entry& e);
|
|
|
|
~entry();
|
|
|
|
void operator=(const entry& e);
|
|
void operator=(const dictionary_type&);
|
|
void operator=(const string_type&);
|
|
void operator=(const list_type&);
|
|
void operator=(const integer_type&);
|
|
|
|
integer_type& integer()
|
|
const integer_type& integer() const;
|
|
string_type& string();
|
|
const string_type& string() const;
|
|
list_type& list();
|
|
const list_type& list() const;
|
|
dictionary_type& dict();
|
|
const dictionary_type& dict() const;
|
|
|
|
void print(std::ostream& os, int indent = 0) const;
|
|
};
|
|
</pre>
|
|
<p>The <tt class="literal"><span class="pre">integer()</span></tt>, <tt class="literal"><span class="pre">string()</span></tt>, <tt class="literal"><span class="pre">list()</span></tt> and <tt class="literal"><span class="pre">dict()</span></tt> functions
|
|
are accessorts that return the respecive type. If the <tt class="literal"><span class="pre">entry</span></tt> object isn't of the
|
|
type you request, the accessor will throw <a class="reference" href="#type-error">type_error</a> (which derives from
|
|
<tt class="literal"><span class="pre">std::runtime_error</span></tt>). You can ask an <tt class="literal"><span class="pre">entry</span></tt> for its type through the
|
|
<tt class="literal"><span class="pre">type()</span></tt> function.</p>
|
|
<p>The <tt class="literal"><span class="pre">print()</span></tt> function is there for debug purposes only.</p>
|
|
<p>If you want to create an <tt class="literal"><span class="pre">entry</span></tt> 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.</p>
|
|
<p>The typical code to get info from a torrent file will then look like this:</p>
|
|
<pre class="literal-block">
|
|
entry torrent_file;
|
|
// ...
|
|
|
|
const entry::dictionary_type& 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";
|
|
}
|
|
</pre>
|
|
<p>To make it easier to extract information from a torren file, the class <tt class="literal"><span class="pre">torrent_info</span></tt>
|
|
exists.</p>
|
|
</div>
|
|
<div class="section" id="torrent-info">
|
|
<h1><a name="torrent-info">torrent_info</a></h1>
|
|
<p>The <tt class="literal"><span class="pre">torrent_info</span></tt> has the following synopsis:</p>
|
|
<pre class="literal-block">
|
|
class torrent_info
|
|
{
|
|
public:
|
|
|
|
torrent_info(const entry& torrent_file)
|
|
|
|
typedef std::vector>file>::const_iterator file_iterator;
|
|
typedef std::vector<file>::const_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;
|
|
const file& file_at(int index) const;
|
|
|
|
const std::vector<announce_entry>& trackers() const;
|
|
|
|
int prioritize_tracker(int index);
|
|
|
|
entry::integer_type total_size() const;
|
|
entry::integer_type piece_length() const;
|
|
int num_pieces() const;
|
|
const sha1_hash& info_hash() const;
|
|
const std::stirng& name() const;
|
|
const std::string& comment() const;
|
|
boost::posiz_time::ptime creation_date() const;
|
|
|
|
|
|
void print(std::ostream& os) const;
|
|
|
|
entry::integer_type piece_size(unsigned int index) const;
|
|
const sha1_hash& hash_for_piece(unsigned int index) const;
|
|
};
|
|
</pre>
|
|
<p>This class will need some explanation. First of all, to get a list of all files
|
|
in the torrent, you can use <tt class="literal"><span class="pre">begin_files()</span></tt>, <tt class="literal"><span class="pre">end_files()</span></tt>,
|
|
<tt class="literal"><span class="pre">rbegin_files()</span></tt> and <tt class="literal"><span class="pre">rend_files()</span></tt>. These will give you standard vector
|
|
iterators with the type <tt class="literal"><span class="pre">file_entry</span></tt>.</p>
|
|
<pre class="literal-block">
|
|
struct file_entry
|
|
{
|
|
std::string path;
|
|
std::string filename;
|
|
entry::integer_type size;
|
|
};
|
|
</pre>
|
|
<p>If you need index-access to files you can use the <tt class="literal"><span class="pre">num_files()</span></tt> and <tt class="literal"><span class="pre">file_at()</span></tt>
|
|
to access files using indices.</p>
|
|
<p>The <tt class="literal"><span class="pre">print()</span></tt> function is there for debug purposes only. It will print the info from
|
|
the torrent file to the given outstream.</p>
|
|
<p><tt class="literal"><span class="pre">name()</span></tt> returns the name of the torrent.</p>
|
|
<p>The <tt class="literal"><span class="pre">trackers()</span></tt> function will return a sorted vector of <tt class="literal"><span class="pre">announce_entry</span></tt>.
|
|
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.</p>
|
|
<pre class="literal-block">
|
|
struct announce_entry
|
|
{
|
|
std::string url;
|
|
int tier;
|
|
};
|
|
</pre>
|
|
<p>The <tt class="literal"><span class="pre">prioritize_tracker()</span></tt> is used internally to move a tracker to the front
|
|
of its tier group. i.e. It will never be moved pass a tracker with a different tier
|
|
number. For more information about how multiple trackers are dealt with, see the
|
|
<a class="reference" href="http://home.elp.rr.com/tur/multitracker-spec.txt">specification</a>.</p>
|
|
<p><tt class="literal"><span class="pre">total_size()</span></tt>, <tt class="literal"><span class="pre">piece_length()</span></tt> and <tt class="literal"><span class="pre">num_pieces()</span></tt> 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
|
|
<tt class="literal"><span class="pre">piece_size()</span></tt> and <tt class="literal"><span class="pre">piece_length()</span></tt> is that <tt class="literal"><span class="pre">piece_size()</span></tt> takes
|
|
the piece index as argument and gives you the exact size of that piece. It will always
|
|
be the same as <tt class="literal"><span class="pre">piece_length()</span></tt> except in the case of the last piece, which may
|
|
be smaller.</p>
|
|
<p><tt class="literal"><span class="pre">hash_for_piece()</span></tt> takes a piece-index and returns the 20-bytes sha1-hash for that
|
|
piece and <tt class="literal"><span class="pre">info_hash()</span></tt> returns the 20-bytes sha1-hash for the info-section of the
|
|
torrent file. For more information on the <tt class="literal"><span class="pre">sha1_hash</span></tt>, see the <a class="reference" href="#big-number">big_number</a> class.</p>
|
|
<p><tt class="literal"><span class="pre">comment()</span></tt> returns the comment associated with the torrent. If there's no comment,
|
|
it will return an empty string. <tt class="literal"><span class="pre">creation_date()</span></tt> returns a <a class="reference" href="http://www.boost.org/libs/date_time/doc/class_ptime.html">boost::posix_time::ptime</a>
|
|
object, representing the time when this torrent file was created. If there's no timestamp
|
|
in the torrent file, this will return a date of january 1:st 1970.</p>
|
|
</div>
|
|
<div class="section" id="torrent-handle">
|
|
<h1><a name="torrent-handle">torrent_handle</a></h1>
|
|
<p>You will usually have to store your torrent handles somewhere, since it's the
|
|
object through which you retrieve infromation about the torrent and aborts the torrent.
|
|
Its declaration looks like this:</p>
|
|
<pre class="literal-block">
|
|
struct torrent_handle
|
|
{
|
|
torrent_handle();
|
|
|
|
torrent_status status();
|
|
void get_download_queue(std::vector<partial_piece_info>& queue);
|
|
void get_peer_info(std::vector<peer_info>& v);
|
|
const torrent_info& get_torrent_info();
|
|
bool is_valid();
|
|
|
|
entry write_resume_data();
|
|
void force_reannounce();
|
|
void connect_peer(const address& adr) const;
|
|
void set_ratio(float ratio);
|
|
|
|
boost::filsystem::path save_path() const;
|
|
|
|
void set_max_uploads(int max_uploads);
|
|
void set_max_connections(int max_connections);
|
|
|
|
sha1_hash info_hash() const;
|
|
|
|
bool operator==(const torrent_handle&) const;
|
|
bool operator!=(const torrent_handle&) const;
|
|
bool operator<(const torrent_handle&) const;
|
|
};
|
|
</pre>
|
|
<p>The default constructor will initialize the handle to an invalid state. Which means you cannot
|
|
perform any operation on it, unless you first assign it a valid handle. If you try to perform
|
|
any operation on an uninitialized handle, it will throw <tt class="literal"><span class="pre">invalid_handle</span></tt>.</p>
|
|
<p><tt class="literal"><span class="pre">save_path()</span></tt> returns the path that was given to <tt class="literal"><span class="pre">add_torrent()</span></tt> when this torrent
|
|
was started.</p>
|
|
<p><tt class="literal"><span class="pre">force_reannounce()</span></tt> will force this torrent to do another tracker request, to receive new
|
|
peers. If the torrent is invalid, queued or in checking mode, this functions will throw
|
|
<a class="reference" href="#invalid-handle">invalid_handle</a>.</p>
|
|
<p><tt class="literal"><span class="pre">connect_peer()</span></tt> is a way to manually connect to peers that one believe is a part of the
|
|
torrent. If the peer does not respond, or is not a member of this torrent, it will simply
|
|
be disconnected. No harm can be done by using this other than an unnecessary connection
|
|
attempt is made. If the torrent is uninitialized or in queued or checking mode, this
|
|
will throw <a class="reference" href="#invalid-handle">invalid_handle</a>.</p>
|
|
<p><tt class="literal"><span class="pre">set_ratio()</span></tt> sets the desired download / upload ratio. If set to 0, it is considered being
|
|
infinite. i.e. the client will always upload as much as it can, no matter how much it gets back
|
|
in return. With this setting it will work much like the standard clients.</p>
|
|
<p>Besides 0, the ration can be set to any number greater than or equal to 1. It means how much to
|
|
attempt to upload in return for each download. e.g. if set to 2, the client will try to upload
|
|
2 bytes for every byte received. The default setting for this is 0, which will make it work
|
|
as a standard client.</p>
|
|
<p><tt class="literal"><span class="pre">info_hash()</span></tt> returns the info hash for the torrent.</p>
|
|
<p><tt class="literal"><span class="pre">set_max_uploads()</span></tt> sets the maximum number of peers that's unchoked at the same time on this
|
|
torrent. If you set this to -1, there will be no limit.</p>
|
|
<p><tt class="literal"><span class="pre">set_max_connections()</span></tt> sets the maximum number of connection this torrent will open. If all
|
|
connections are used up, incoming connections may be refused or poor connections may be closed.
|
|
This must be at least 2. The default is unlimited number of connections. If -1 is given to the
|
|
function, it means unlimited.</p>
|
|
<p><tt class="literal"><span class="pre">write_resume_data()</span></tt> generates fast-resume data and returns it as an entry. This entry
|
|
is suitable for being bencoded. For more information about how fast-resume works, see <a class="reference" href="#fast-resume">fast resume</a>.
|
|
It may throw <a class="reference" href="#invalid-handle">invalid_handle</a> if the torrent handle is invalid.</p>
|
|
<div class="section" id="status">
|
|
<h2><a name="status">status()</a></h2>
|
|
<p><tt class="literal"><span class="pre">status()</span></tt> will return a structure with information about the status of this
|
|
torrent. If the <a class="reference" href="#torrent-handle">torrent_handle</a> is invalid, it will throw <a class="reference" href="#invalid-handle">invalid_handle</a> exception.
|
|
It contains the following fields:</p>
|
|
<pre class="literal-block">
|
|
struct torrent_status
|
|
{
|
|
enum state_t
|
|
{
|
|
invalid_handle,
|
|
queued_for_checking,
|
|
checking_files,
|
|
connecting_to_tracker,
|
|
downloading,
|
|
seeding
|
|
};
|
|
|
|
state_t state;
|
|
float progress;
|
|
boost::posix_time::time_duration next_announce;
|
|
boost::posix_time::time_duration announce_interval;
|
|
|
|
std::string current_tracker;
|
|
|
|
size_type total_download;
|
|
size_type total_upload;
|
|
|
|
size_type total_payload_download;
|
|
size_type total_payload_upload;
|
|
|
|
float download_rate;
|
|
float upload_rate;
|
|
|
|
int num_peers;
|
|
|
|
const std::vector<bool>* pieces;
|
|
size_type total_done;
|
|
};
|
|
</pre>
|
|
<p><tt class="literal"><span class="pre">progress</span></tt> is a value in the range [0, 1], that represents the progress of the
|
|
torrent's current task. It may be checking files or downloading. The torrent's
|
|
current task is in the <tt class="literal"><span class="pre">state</span></tt> member, it will be one of the following:</p>
|
|
<table border class="table">
|
|
<colgroup>
|
|
<col width="31%" />
|
|
<col width="69%" />
|
|
</colgroup>
|
|
<tbody valign="top">
|
|
<tr><td><tt class="literal"><span class="pre">queued_for_checking</span></tt></td>
|
|
<td>The torrent is in the queue for being checked. But there
|
|
currently is another torrent that are being checked.
|
|
This torrent will wait for its turn.</td>
|
|
</tr>
|
|
<tr><td><tt class="literal"><span class="pre">checking_files</span></tt></td>
|
|
<td>The torrent has not started its download yet, and is
|
|
currently checking existing files.</td>
|
|
</tr>
|
|
<tr><td><tt class="literal"><span class="pre">connecting_to_tracker</span></tt></td>
|
|
<td>The torrent has sent a request to the tracker and is
|
|
currently waiting for a response</td>
|
|
</tr>
|
|
<tr><td><tt class="literal"><span class="pre">downloading</span></tt></td>
|
|
<td>The torrent is being downloaded. This is the state
|
|
most torrents will be in most of the time. The progress
|
|
meter will tell how much of the files that has been
|
|
downloaded.</td>
|
|
</tr>
|
|
<tr><td><tt class="literal"><span class="pre">seeding</span></tt></td>
|
|
<td>In this state the torrent has finished downloading and
|
|
is a pure seeder.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p><tt class="literal"><span class="pre">next_announce</span></tt> is the time until the torrent will announce itself to the tracker. And
|
|
<tt class="literal"><span class="pre">announce_interval</span></tt> is the time the tracker want us to wait until we announce ourself
|
|
again the next time.</p>
|
|
<p><tt class="literal"><span class="pre">current_tracker</span></tt> is the URL of the last working tracker. If no tracker request has
|
|
been successful yet, it's set to an empty string.</p>
|
|
<p><tt class="literal"><span class="pre">total_download</span></tt> and <tt class="literal"><span class="pre">total_upload</span></tt> is the number of bytes downloaded and
|
|
uploaded to all peers, accumulated, <em>this session</em> only.</p>
|
|
<p><tt class="literal"><span class="pre">total_payload_download</span></tt> and <tt class="literal"><span class="pre">total_payload_upload</span></tt> counts the amount of bytes
|
|
send and received this session, but only the actual oayload data (i.e the interesting
|
|
data), these counters ignore any protocol overhead.</p>
|
|
<p><tt class="literal"><span class="pre">pieces</span></tt> is the bitmask that represents which pieces we have (set to true) and
|
|
the pieces we don't have. It's a pointer and may be set to 0 if the torrent isn't
|
|
downloading or seeding.</p>
|
|
<p><tt class="literal"><span class="pre">download_rate</span></tt> and <tt class="literal"><span class="pre">upload_rate</span></tt> are the total rates for all peers for this
|
|
torrent. These will usually have better precision than summing the rates from
|
|
all peers. The rates are given as the number of bytes per second.</p>
|
|
<p><tt class="literal"><span class="pre">num_peers</span></tt> is the number of peers this torrent currently is connected to.</p>
|
|
<p><tt class="literal"><span class="pre">total_done</span></tt> is the total number of bytes of the file(s) that we have.</p>
|
|
</div>
|
|
<div class="section" id="get-download-queue">
|
|
<h2><a name="get-download-queue">get_download_queue()</a></h2>
|
|
<p><tt class="literal"><span class="pre">get_download_queue()</span></tt> takes a non-const reference to a vector which it will fill with
|
|
information about pieces that are partially downloaded or not downloaded at all but partially
|
|
requested. The entry in the vector (<tt class="literal"><span class="pre">partial_piece_info</span></tt>) looks like this:</p>
|
|
<pre class="literal-block">
|
|
struct partial_piece_info
|
|
{
|
|
enum { max_blocks_per_piece };
|
|
int piece_index;
|
|
int blocks_in_piece;
|
|
std::bitset<max_blocks_per_piece> requested_blocks;
|
|
std::bitset<max_blocks_per_piece> finished_blocks;
|
|
peer_id peer[max_blocks_per_piece];
|
|
int num_downloads[max_blocks_per_piece];
|
|
};
|
|
</pre>
|
|
<p><tt class="literal"><span class="pre">piece_index</span></tt> is the index of the piece in question. <tt class="literal"><span class="pre">blocks_in_piece</span></tt> is the
|
|
number of blocks in this particular piece. This number will be the same for most pieces, but
|
|
the last piece may have fewer blocks than the standard pieces.</p>
|
|
<p><tt class="literal"><span class="pre">requested_blocks</span></tt> is a bitset with one bit per block in the piece. If a bit is set, it
|
|
means that that block has been requested, but not necessarily fully downloaded yet. To know
|
|
from whom the block has been requested, have a look in the <tt class="literal"><span class="pre">peer</span></tt> array. The bit-index
|
|
in the <tt class="literal"><span class="pre">requested_blocks</span></tt> and <tt class="literal"><span class="pre">finished_blocks</span></tt> correspons to the array-index into
|
|
<tt class="literal"><span class="pre">peers</span></tt> and <tt class="literal"><span class="pre">num_downloads</span></tt>. The array of peers is contains the id of the
|
|
peer the piece was requested from. If a piece hasn't been requested (the bit in
|
|
<tt class="literal"><span class="pre">requested_blocks</span></tt> is not set) the peer array entry will be undefined.</p>
|
|
<p>The <tt class="literal"><span class="pre">finished_blocks</span></tt> is a bitset where each bit says if the block is fully downloaded
|
|
or not. And the <tt class="literal"><span class="pre">num_downloads</span></tt> array says how many times that block has been downloaded.
|
|
When a piece fails a hash verification, single blocks may be redownloaded to see if the hash teast
|
|
may pass then.</p>
|
|
</div>
|
|
<div class="section" id="get-peer-info">
|
|
<h2><a name="get-peer-info">get_peer_info()</a></h2>
|
|
<p><tt class="literal"><span class="pre">get_peer_info()</span></tt> takes a reference to a vector that will be cleared and filled
|
|
with one entry for each peer connected to this torrent, given the handle is valid. If the
|
|
<a class="reference" href="#torrent-handle">torrent_handle</a> is invalid, it will throw <a class="reference" href="#invalid-handle">invalid_handle</a> exception. Each entry in
|
|
the vector contains information about that particular peer. It contains the following
|
|
fields:</p>
|
|
<pre class="literal-block">
|
|
struct peer_info
|
|
{
|
|
enum
|
|
{
|
|
interesting = 0x1,
|
|
choked = 0x2,
|
|
remote_interested = 0x4,
|
|
remote_choked = 0x8,
|
|
supports_extensions = 0x10,
|
|
local_connection = 0x20
|
|
};
|
|
unsigned int flags;
|
|
address ip;
|
|
float up_speed;
|
|
float down_speed;
|
|
size_type total_download;
|
|
size_type total_upload;
|
|
peer_id id;
|
|
std::vector<bool> pieces;
|
|
int upload_limit;
|
|
int upload_ceiling;
|
|
|
|
size_type load_balancing;
|
|
|
|
int download_queue_length;
|
|
int upload_queue_length;
|
|
|
|
int downloading_piece_index;
|
|
int downloading_block_index;
|
|
int downloading_progress;
|
|
int downloading_total;
|
|
};
|
|
</pre>
|
|
<p>The <tt class="literal"><span class="pre">flags</span></tt> attribute tells you in which state the peer is. It is set to
|
|
any combination of the enums above. The following table describes each flag:</p>
|
|
<table border class="table">
|
|
<colgroup>
|
|
<col width="31%" />
|
|
<col width="69%" />
|
|
</colgroup>
|
|
<tbody valign="top">
|
|
<tr><td><tt class="literal"><span class="pre">interesting</span></tt></td>
|
|
<td>we are interested in pieces from this peer.</td>
|
|
</tr>
|
|
<tr><td><tt class="literal"><span class="pre">choked</span></tt></td>
|
|
<td><strong>we</strong> have choked this peer.</td>
|
|
</tr>
|
|
<tr><td><tt class="literal"><span class="pre">remote_interested</span></tt>
|
|
<tt class="literal"><span class="pre">remote_choked</span></tt></td>
|
|
<td>means the same thing but that the peer is interested
|
|
in pieces from us and the peer has choked <strong>us</strong>.</td>
|
|
</tr>
|
|
<tr><td><tt class="literal"><span class="pre">support_extensions</span></tt></td>
|
|
<td>means that this peer supports the <a class="reference" href="http://nolar.com/azureus/extended.htm">extension protocol
|
|
as described by nolar</a>.</td>
|
|
</tr>
|
|
<tr><td><tt class="literal"><span class="pre">local_connection</span></tt></td>
|
|
<td>The connection was initiated by us, the peer has a
|
|
listen port open, and that port is the same is in the
|
|
<a class="reference" href="#address">address</a> of this peer. If this flag is not set, this
|
|
peer connection was opened by this peer connecting to
|
|
us.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>The <tt class="literal"><span class="pre">ip</span></tt> field is the IP-address to this peer. Its type is a wrapper around the
|
|
actual address and the port number. See <a class="reference" href="#address">address</a> class.</p>
|
|
<p><tt class="literal"><span class="pre">up_speed</span></tt> and <tt class="literal"><span class="pre">down_speed</span></tt> is the current upload and download speed
|
|
we have to and from this peer. These figures are updated aproximately once every second.</p>
|
|
<p><tt class="literal"><span class="pre">total_download</span></tt> and <tt class="literal"><span class="pre">total_upload</span></tt> are the total number of bytes downloaded
|
|
from and uploaded to this peer. These numbers do not include the protocol chatter, but only
|
|
the payload data.</p>
|
|
<p><tt class="literal"><span class="pre">id</span></tt> is the peer's id as used in the bit torrent protocol. This id can be used to
|
|
extract 'fingerprints' from the peer. Sometimes it can tell you which client the peer
|
|
is using. See <a class="reference" href="#identify-client">identify_client</a></p>
|
|
<p><tt class="literal"><span class="pre">pieces</span></tt> is a vector of booleans that has as many entries as there are pieces
|
|
in the torrent. Each boolean tells you if the peer has that piece (if it's set to true)
|
|
or if the peer miss that piece (set to false).</p>
|
|
<p><tt class="literal"><span class="pre">upload_limit</span></tt> is the number of bytes per second we are allowed to send to this
|
|
peer every second. It may be -1 if there's no limit. The upload limits of all peers
|
|
should sum up to the upload limit set by <tt class="literal"><span class="pre">session::set_upload_limit</span></tt>.</p>
|
|
<p><tt class="literal"><span class="pre">upload_ceiling</span></tt> is the current maximum allowed upload rate given the cownload
|
|
rate and share ratio. If the global upload rate is inlimited, the <tt class="literal"><span class="pre">upload_limit</span></tt>
|
|
for every peer will be the same as their <tt class="literal"><span class="pre">upload_ceiling</span></tt>.</p>
|
|
<p><tt class="literal"><span class="pre">load_balancing</span></tt> is a measurment of the balancing of free download (that we get)
|
|
and free upload that we give. Every peer gets a certain amount of free upload, but
|
|
this member says how much <em>extra</em> free upload this peer has got. If it is a negative
|
|
number it means that this was a peer from which we have got this amount of free
|
|
download.</p>
|
|
<p><tt class="literal"><span class="pre">download_queue_length</span></tt> is the number of piece-requests we have sent to this peer
|
|
that hasn't been answered with a piece yet.</p>
|
|
<p><tt class="literal"><span class="pre">upload_queue_length</span></tt> is the number of piece-requests we have received from this peer
|
|
that we haven't answered with a piece yet.</p>
|
|
<p>You can know which piece, and which part of that piece, that is currently being
|
|
downloaded from a specific peer by looking at the next four members.
|
|
<tt class="literal"><span class="pre">downloading_piece_index</span></tt> is the index of the piece that is currently being downloaded.
|
|
This may be set to -1 if there's currently no piece downloading from this peer. If it is
|
|
>= 0, the other three members are valid. <tt class="literal"><span class="pre">downloading_block_index</span></tt> is the index of the
|
|
block (or sub-piece) that is being downloaded. <tt class="literal"><span class="pre">downloading_progress</span></tt> is the number
|
|
of bytes of this block we have received from the peer, and <tt class="literal"><span class="pre">downloading_total</span></tt> is
|
|
the total number of bytes in this block.</p>
|
|
</div>
|
|
<div class="section" id="get-torrent-info">
|
|
<h2><a name="get-torrent-info">get_torrent_info()</a></h2>
|
|
<p>Returns a const reference to the <a class="reference" href="#torrent-info">torrent_info</a> object associated with this torrent.
|
|
This reference is valid as long as the <a class="reference" href="#torrent-handle">torrent_handle</a> is valid, no longer. If the
|
|
<a class="reference" href="#torrent-handle">torrent_handle</a> is invalid, <a class="reference" href="#invalid-handle">invalid_handle</a> exception will be thrown.</p>
|
|
</div>
|
|
<div class="section" id="is-valid">
|
|
<h2><a name="is-valid">is_valid()</a></h2>
|
|
<p>Returns true if this handle refers to a valid torrent and false if it hasn't been initialized
|
|
or if the torrent it refers to has been aborted.</p>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="address">
|
|
<h1><a name="address">address</a></h1>
|
|
<p>The <tt class="literal"><span class="pre">address</span></tt> class represents a name of a network endpoint (usually referred to as
|
|
IP-address) and a port number. This is the same thing as a <tt class="literal"><span class="pre">sockaddr_in</span></tt> would contain.
|
|
Its declaration looks like this:</p>
|
|
<pre class="literal-block">
|
|
class address
|
|
{
|
|
public:
|
|
address();
|
|
address(unsigned char a
|
|
, unsigned char b
|
|
, unsigned char c
|
|
, unsigned char d
|
|
, unsigned short port);
|
|
address(unsigned int addr, unsigned short port);
|
|
address(const std::string& addr, unsigned short port);
|
|
address(const address& a);
|
|
~address();
|
|
|
|
std::string as_string() const;
|
|
unsigned int ip() const;
|
|
unsigned short port() const;
|
|
|
|
bool operator<(const address& a) const;
|
|
bool operator!=(const address& a) const;
|
|
bool operator==(const address& a) const;
|
|
};
|
|
</pre>
|
|
<p>It is less-than comparable to make it possible to use it as a key in a map. <tt class="literal"><span class="pre">as_string()</span></tt> may block
|
|
while it does the DNS lookup, it returns a string that points to the address represented by the object.</p>
|
|
<p><tt class="literal"><span class="pre">ip()</span></tt> will return the 32-bit ip-address as an integer. <tt class="literal"><span class="pre">port()</span></tt> returns the port number.</p>
|
|
</div>
|
|
<div class="section" id="http-settings">
|
|
<h1><a name="http-settings">http_settings</a></h1>
|
|
<p>You have some control over tracker requests through the <tt class="literal"><span class="pre">http_settings</span></tt> object. You
|
|
create it and fill it with your settings and the use <tt class="literal"><span class="pre">session::set_http_settings()</span></tt>
|
|
to apply them. You have control over proxy and authorization settings and also the user-agent
|
|
that will be sent to the tracker. The user-agent is a good way to identify your client.</p>
|
|
<pre class="literal-block">
|
|
struct http_settings
|
|
{
|
|
http_settings();
|
|
std::string proxy_ip;
|
|
int proxy_port;
|
|
std::string proxy_login;
|
|
std::string proxy_password;
|
|
std::string user_agent;
|
|
int tracker_timeout;
|
|
int tracker_maximum_response_length;
|
|
};
|
|
</pre>
|
|
<p><tt class="literal"><span class="pre">proxy_ip</span></tt> may be a hostname or ip to a http proxy to use. If this is
|
|
an empty string, no http proxy will be used.</p>
|
|
<p><tt class="literal"><span class="pre">proxy_port</span></tt> is the port on which the http proxy listens. If <tt class="literal"><span class="pre">proxy_ip</span></tt>
|
|
is empty, this will be ignored.</p>
|
|
<p><tt class="literal"><span class="pre">proxy_login</span></tt> should be the login username for the http proxy, if this
|
|
empty, the http proxy will be trid to be used without authentication.</p>
|
|
<p><tt class="literal"><span class="pre">proxy_password</span></tt> the password string for the http proxy.</p>
|
|
<p><tt class="literal"><span class="pre">user_agent</span></tt> this is the client identification to the tracker. It will
|
|
be followed by the string "(libtorrent)" to identify that this library
|
|
is being used. This should be set to your client's name and version number.</p>
|
|
<p><tt class="literal"><span class="pre">tracker_timeout</span></tt> is the number of seconds the tracker connection will
|
|
wait until it considers the tracker to have timed-out. Default value is 10
|
|
seconds.</p>
|
|
<p><tt class="literal"><span class="pre">tracker_maximum_response_length</span></tt> is the maximum number of bytes in a
|
|
tracker response. If a response size passes this number it will be rejected
|
|
and the connection will be closed. On gzipped responses this size is measured
|
|
on the uncompressed data. So, if you get 20 bytes of gzip response that'll
|
|
expand to 2 megs, it will be interrupted before the entire response has been
|
|
uncompressed (given your limit is lower than 2 megs). Default limit is
|
|
1 megabyte.</p>
|
|
</div>
|
|
<div class="section" id="big-number">
|
|
<h1><a name="big-number">big_number</a></h1>
|
|
<p>Both the <tt class="literal"><span class="pre">peer_id</span></tt> and <tt class="literal"><span class="pre">sha1_hash</span></tt> types are typedefs of the class
|
|
<tt class="literal"><span class="pre">big_number</span></tt>. It represents 20 bytes of data. Its synopsis follows:</p>
|
|
<pre class="literal-block">
|
|
class big_number
|
|
{
|
|
public:
|
|
bool operator==(const big_number& n) const;
|
|
bool operator!=(const big_number& n) const;
|
|
bool operator<(const big_number& n) const;
|
|
|
|
const unsigned char* begin() const;
|
|
const unsigned char* end() const;
|
|
|
|
unsigned char* begin();
|
|
unsigned char* end();
|
|
};
|
|
</pre>
|
|
<p>The iterators gives you access to individual bytes.</p>
|
|
</div>
|
|
<div class="section" id="hasher">
|
|
<h1><a name="hasher">hasher</a></h1>
|
|
<p>This class creates sha1-hashes. Its declaration looks like this:</p>
|
|
<pre class="literal-block">
|
|
class hasher
|
|
{
|
|
public:
|
|
hasher();
|
|
|
|
void update(const char* data, unsigned int len);
|
|
sha1_hash final();
|
|
void reset();
|
|
};
|
|
</pre>
|
|
<p>You use it by first instantiating it, then call <tt class="literal"><span class="pre">update()</span></tt> to feed it
|
|
with data. i.e. you don't have to keep the entire buffer of which you want to
|
|
create the hash in memory. You can feed the hasher parts of it at a time. When
|
|
You have fed the hasher with all the data, you call <tt class="literal"><span class="pre">final()</span></tt> and it
|
|
will return the sha1-hash of the data.</p>
|
|
<p>If you want to reuse the hasher object once you have created a hash, you have to
|
|
call <tt class="literal"><span class="pre">reset()</span></tt> to reinitialize it.</p>
|
|
<p>The sha1-algorithm used was implemented by Steve Reid and released as public domain.
|
|
For more info, see <tt class="literal"><span class="pre">src/sha1.c</span></tt>.</p>
|
|
</div>
|
|
<div class="section" id="fingerprint">
|
|
<h1><a name="fingerprint">fingerprint</a></h1>
|
|
<p>The fingerprint class represents information about a client and its version. It is used
|
|
to encode this information into the client's peer id.</p>
|
|
<p>This is the class declaration:</p>
|
|
<pre class="literal-block">
|
|
struct fingerprint
|
|
{
|
|
fingerprint(const char* id_string, int major, int minor, int revision, int tag);
|
|
|
|
std::string to_string() const;
|
|
|
|
char id[2];
|
|
char major_version;
|
|
char minor_version;
|
|
char revision_version;
|
|
char tag_version;
|
|
|
|
};
|
|
</pre>
|
|
<p>The constructor takes a <tt class="literal"><span class="pre">const</span> <span class="pre">char*</span></tt> that should point to a string constant containing
|
|
exactly two characters. These are the characters that should be unique for your client. Make
|
|
sure not to clash with anybody else. Here are some taken id's:</p>
|
|
<table border class="table">
|
|
<colgroup>
|
|
<col width="30%" />
|
|
<col width="70%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr><th>id chars</th>
|
|
<th>client</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<tr><td>'AZ'</td>
|
|
<td>Azureus</td>
|
|
</tr>
|
|
<tr><td>'LT'</td>
|
|
<td>libtorrent (default)</td>
|
|
</tr>
|
|
<tr><td>'BX'</td>
|
|
<td>BittorrentX</td>
|
|
</tr>
|
|
<tr><td>'MT'</td>
|
|
<td>Moonlight Torrent</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>The <tt class="literal"><span class="pre">major</span></tt>, <tt class="literal"><span class="pre">minor</span></tt>, <tt class="literal"><span class="pre">revision</span></tt> and <tt class="literal"><span class="pre">tag</span></tt> parameters are used to identify the
|
|
version of your client. All these numbers must be within the range [0, 9].</p>
|
|
<p><tt class="literal"><span class="pre">to_string()</span></tt> will generate the actual string put in the peer-id, and return it.</p>
|
|
<div class="section" id="identify-client">
|
|
<h2><a name="identify-client">identify_client</a></h2>
|
|
<p>There's a function, in the header <tt class="literal"><span class="pre">libtorrent/identify_client.hpp</span></tt>, that can be used
|
|
to extract a string describing a client version from its peer-id. It has the following
|
|
declaration:</p>
|
|
<pre class="literal-block">
|
|
std::string identify_client(const peer_id& id);
|
|
</pre>
|
|
<p>It will recognize most clients that have this kind of identification in the peer-id.</p>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="alerts">
|
|
<h1><a name="alerts">alerts</a></h1>
|
|
<p>The <tt class="literal"><span class="pre">pop_alert()</span></tt> function on session is the interface for retrieving
|
|
alerts, warnings, messages and errors from libtorrent. If there hasn't
|
|
occured any errors (matching your severity level) <tt class="literal"><span class="pre">pop_alert()</span></tt> will
|
|
return a zero pointer. If there has been some error, it will return a pointer
|
|
to an alert object describing it. You can then use the alert object and query
|
|
it for information about the error or message. To retrieve any alerts, you have
|
|
to select a severity level using <tt class="literal"><span class="pre">session::set_severity_level()</span></tt>. It defaults to
|
|
<tt class="literal"><span class="pre">alert::none</span></tt>, which means that you don't get any messages at all, ever.
|
|
You have the following levels to select among:</p>
|
|
<table border class="table">
|
|
<colgroup>
|
|
<col width="19%" />
|
|
<col width="81%" />
|
|
</colgroup>
|
|
<tbody valign="top">
|
|
<tr><td><tt class="literal"><span class="pre">none</span></tt></td>
|
|
<td>No alert will ever have this severity level, which
|
|
effectively filters all messages.</td>
|
|
</tr>
|
|
<tr><td><tt class="literal"><span class="pre">fatal</span></tt></td>
|
|
<td>Fatal errors will have this severity level. Examples can
|
|
be disk full or something else that will make it
|
|
impossible to continue normal execution.</td>
|
|
</tr>
|
|
<tr><td><tt class="literal"><span class="pre">critical</span></tt></td>
|
|
<td>Signals errors that requires user interaction or
|
|
messages that almost never should be ignored. For
|
|
example, a chat message received from another peer is
|
|
announced as severity <tt class="literal"><span class="pre">critical</span></tt>.</td>
|
|
</tr>
|
|
<tr><td><tt class="literal"><span class="pre">warning</span></tt></td>
|
|
<td>Messages with the warning severity can be a tracker that
|
|
times out or responds with invalid data. It will be
|
|
retried automatically, and the possible next tracker in
|
|
a multitracker sequence will be tried. It does not
|
|
require any user interaction.</td>
|
|
</tr>
|
|
<tr><td><tt class="literal"><span class="pre">info</span></tt></td>
|
|
<td>Events that can be considered normal, but still deserves
|
|
an event. This could be a piece hash that fails.</td>
|
|
</tr>
|
|
<tr><td><tt class="literal"><span class="pre">debug</span></tt></td>
|
|
<td>This will include alot of debug events that can be used
|
|
both for debugging libtorrent but also when debugging
|
|
other clients that are connected to libtorrent. It will
|
|
report strange behaviors among the connected peers.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>When setting a severity level, you will receive messages of that severity and all
|
|
messages that are more sever. If you set <tt class="literal"><span class="pre">alert::none</span></tt> (the default) you will not recieve
|
|
any events at all.</p>
|
|
<p>When you set a severuty level other than <tt class="literal"><span class="pre">none</span></tt>, you have the responsibility to call
|
|
<tt class="literal"><span class="pre">pop_alert()</span></tt> from time to time. If you don't do that, the alert queue will just grow.</p>
|
|
<p>When you get an alert, you can use <tt class="literal"><span class="pre">typeid()</span></tt> or <tt class="literal"><span class="pre">dynamic_cast<></span></tt> to get more detailed
|
|
information on exactly which type it is. i.e. what kind of error it is. You can also use a
|
|
<a class="reference" href="#dispatcher">dispatcher</a> mechanism that's available in libtorrent.</p>
|
|
<p>The <tt class="literal"><span class="pre">alert</span></tt> class is the base class that specific messages are derived from. This
|
|
is its synopsis:</p>
|
|
<pre class="literal-block">
|
|
class alert
|
|
{
|
|
public:
|
|
|
|
enum severity_t { debug, info, warning, critital, fatal, none };
|
|
|
|
alert(severity_t severity, const std::string& msg);
|
|
virtual ~alert();
|
|
|
|
const std::string& msg() const;
|
|
severity_t severity() const;
|
|
|
|
virtual std::auto_ptr<alert> clone() const = 0;
|
|
};
|
|
</pre>
|
|
<p>This means that all alerts have at least a string describing it. They also
|
|
have a severity leve that can be used to sort them or present them to the
|
|
user in different ways.</p>
|
|
<p>The specific alerts, that all derives from <tt class="literal"><span class="pre">alert</span></tt>, are:</p>
|
|
<div class="section" id="listen-failed-alert">
|
|
<h2><a name="listen-failed-alert">listen_failed_alert</a></h2>
|
|
<p>This alert is generated when none of the ports, given in the port range, to
|
|
<a class="reference" href="#session">session</a> can be opened for listening. Without a listening port the session
|
|
object will exit its thread. This alert is generated as severity level <tt class="literal"><span class="pre">fatal</span></tt>.</p>
|
|
<pre class="literal-block">
|
|
struct listen_failed_alert: alert
|
|
{
|
|
listen_failed_alert(const std::string& msg);
|
|
virtual std::auto_ptr<alert> clone() const;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="file-error-alert">
|
|
<h2><a name="file-error-alert">file_error_alert</a></h2>
|
|
<p>If the storage fails to read or write files that it needs access to, this alert is
|
|
generated and the torrent is aborted. It is generated as severity level <tt class="literal"><span class="pre">fatal</span></tt>.</p>
|
|
<pre class="literal-block">
|
|
struct file_error_alert: alert
|
|
{
|
|
file_error_alert(
|
|
const torrent_handle& h
|
|
, const std::string& msg);
|
|
|
|
virtual std::auto_ptr<alert> clone() const;
|
|
|
|
torrent_handle handle;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="tracker-alert">
|
|
<h2><a name="tracker-alert">tracker_alert</a></h2>
|
|
<p>This alert is generated on tracker time outs, premature disconnects, invalid response or
|
|
a HTTP response other than "200 OK". From the alert you can get the handle to the torrent
|
|
the tracker belongs to. This alert is generated as severity level <tt class="literal"><span class="pre">warning</span></tt>.</p>
|
|
<pre class="literal-block">
|
|
struct tracker_alert: alert
|
|
{
|
|
tracker_alert(const torrent_handle& h, const std::string& msg);
|
|
virtual std::auto_ptr<alert> clone() const;
|
|
|
|
torrent_handle handle;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="hash-failed-alert">
|
|
<h2><a name="hash-failed-alert">hash_failed_alert</a></h2>
|
|
<p>This alert is generated when a finished piece fails its hash check. You can get the handle
|
|
to the torrent which got the failed piece and the index of the piece itself from the alert.
|
|
This alert is generated as severity level <tt class="literal"><span class="pre">info</span></tt>.</p>
|
|
<pre class="literal-block">
|
|
struct hash_failed_alert: alert
|
|
{
|
|
hash_failed_alert(
|
|
const torrent_handle& h
|
|
, int index
|
|
, const std::string& msg);
|
|
|
|
virtual std::auto_ptr<alert> clone() const;
|
|
|
|
torrent_handle handle;
|
|
int piece_index;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="peer-error-alert">
|
|
<h2><a name="peer-error-alert">peer_error_alert</a></h2>
|
|
<p>This alert is generated when a peer sends invalid data over the peer-peer protocol. The peer
|
|
will be disconnected, but you get its ip address from the alert, to identify it. This alert
|
|
is generated as severity level <tt class="literal"><span class="pre">debug</span></tt>.</p>
|
|
<pre class="literal-block">
|
|
struct peer_error_alert: alert
|
|
{
|
|
peer_error_alert(const address& pid, const std::string& msg);
|
|
virtual std::auto_ptr<alert> clone() const;
|
|
|
|
address ip;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="invalid-request-alert">
|
|
<h2><a name="invalid-request-alert">invalid_request_alert</a></h2>
|
|
<p>This is a debug alert that is generated by an incoming invalid piece request. The <tt class="literal"><span class="pre">handle</span></tt>
|
|
is a handle to the torrent the peer is a member of. <tt class="literal"><span class="pre">ìp</span></tt> is the address of the peer and the
|
|
<tt class="literal"><span class="pre">request</span></tt> is the actual incoming request from the peer. The alert is generated as severity level
|
|
<tt class="literal"><span class="pre">debug</span></tt>.</p>
|
|
<pre class="literal-block">
|
|
struct invalid_request_alert: alert
|
|
{
|
|
invalid_request_alert(
|
|
const peer_request& r
|
|
, const torrent_handle& h
|
|
, const address& send
|
|
, const std::string& msg);
|
|
|
|
virtual std::auto_ptr<alert> clone() const;
|
|
|
|
torrent_handle handle;
|
|
address ip;
|
|
peer_request request;
|
|
};
|
|
|
|
|
|
struct peer_request
|
|
{
|
|
int piece;
|
|
int start;
|
|
int length;
|
|
bool operator==(const peer_request& r);
|
|
};
|
|
</pre>
|
|
<p>The <tt class="literal"><span class="pre">peer_request</span></tt> contains the values the client sent in its <tt class="literal"><span class="pre">request</span></tt> message. <tt class="literal"><span class="pre">piece</span></tt> is
|
|
the index of the piece it want data from, <tt class="literal"><span class="pre">start</span></tt> is the offset within the piece where the data
|
|
should be read, and <tt class="literal"><span class="pre">length</span></tt> is the amount of data it wants.</p>
|
|
</div>
|
|
<div class="section" id="torrent-finished-alert">
|
|
<h2><a name="torrent-finished-alert">torrent_finished_alert</a></h2>
|
|
<p>This alert is generated when a torrent switches from being a downloader to a seed.
|
|
It will only be generated once per torrent. It contains a torrent_handle to the
|
|
torrent in question. This alert is generated as severity level <tt class="literal"><span class="pre">info</span></tt>.</p>
|
|
<pre class="literal-block">
|
|
struct torrent_finished_alert: alert
|
|
{
|
|
torrent_finished_alert(
|
|
const torrent_handle& h
|
|
, const std::string& msg);
|
|
|
|
virtual std::auto_ptr<alert> clone() const;
|
|
|
|
torrent_handle handle;
|
|
};
|
|
</pre>
|
|
<!-- chat_message_alert
|
|
- - - - - - - - - - - - - - - - - -
|
|
|
|
This alert is generated when you receive a chat message from another peer. Chat messages
|
|
are supported as an extension ("chat"). It is generated as severity level ``critical``,
|
|
even though it doesn't necessarily require any user intervention, it's high priority
|
|
since you would almost never want to ignore such a message. The alert class contain
|
|
a torrent_handle_ to the torrent in which the sender-peer is a member and the ip
|
|
of the sending peer.
|
|
|
|
::
|
|
|
|
struct chat_message_alert: alert
|
|
{
|
|
chat_message_alert(const torrent_handle& h
|
|
, const address& sender
|
|
, const std::string& msg);
|
|
|
|
virtual std::auto_ptr<alert> clone() const;
|
|
|
|
torrent_handle handle;
|
|
address ip;
|
|
}; -->
|
|
</div>
|
|
<div class="section" id="dispatcher">
|
|
<h2><a name="dispatcher">dispatcher</a></h2>
|
|
<p>TODO: describe the dispatcher mechanism</p>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="exceptions">
|
|
<h1><a name="exceptions">exceptions</a></h1>
|
|
<p>There are a number of exceptions that can be thrown from different places in libtorrent,
|
|
here's a complete list with description.</p>
|
|
<div class="section" id="invalid-handle">
|
|
<h2><a name="invalid-handle">invalid_handle</a></h2>
|
|
<p>This exception is thrown when querying information from a <a class="reference" href="#torrent-handle">torrent_handle</a> that hasn't
|
|
been initialized or that has become invalid.</p>
|
|
<pre class="literal-block">
|
|
struct invalid_handle: std::exception
|
|
{
|
|
const char* what() const throw();
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="duplicate-torrent">
|
|
<h2><a name="duplicate-torrent">duplicate_torrent</a></h2>
|
|
<p>This is thrown by <tt class="literal"><span class="pre">session::add_torrent()</span></tt> if the torrent already has been added to
|
|
the session.</p>
|
|
<pre class="literal-block">
|
|
struct duplicate_torrent: std::exception
|
|
{
|
|
const char* what() const throw();
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="invalid-encoding">
|
|
<h2><a name="invalid-encoding">invalid_encoding</a></h2>
|
|
<p>This is thrown by <tt class="literal"><span class="pre">bdecode()</span></tt> if the input data is not a valid bencoding.</p>
|
|
<pre class="literal-block">
|
|
struct invalid_encoding: std::exception
|
|
{
|
|
const char* what() const throw();
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="type-error">
|
|
<h2><a name="type-error">type_error</a></h2>
|
|
<p>This is thrown from the accessors of <tt class="literal"><span class="pre">entry</span></tt> if the data type of the <tt class="literal"><span class="pre">entry</span></tt> doesn't
|
|
match the type you want to extract from it.</p>
|
|
<pre class="literal-block">
|
|
struct type_error: std::runtime_error
|
|
{
|
|
type_error(const char* error);
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="invalid-torrent-file">
|
|
<h2><a name="invalid-torrent-file">invalid_torrent_file</a></h2>
|
|
<p>This exception is thrown from the constructor of <tt class="literal"><span class="pre">torrent_info</span></tt> if the given bencoded information
|
|
doesn't meet the requirements on what information has to be present in a torrent file.</p>
|
|
<pre class="literal-block">
|
|
struct invalid_torrent_file: std::exception
|
|
{
|
|
const char* what() const throw();
|
|
};
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="examples">
|
|
<h1><a name="examples">examples</a></h1>
|
|
<div class="section" id="dump-torrent">
|
|
<h2><a name="dump-torrent">dump_torrent</a></h2>
|
|
<p>This is an example of a program that will take a torrent-file as a parameter and
|
|
print information about it to std out:</p>
|
|
<pre class="literal-block">
|
|
#include <iostream>
|
|
#include <fstream>
|
|
#include <iterator>
|
|
#include <exception>
|
|
#include <iomanip>
|
|
|
|
#include "libtorrent/entry.hpp"
|
|
#include "libtorrent/bencode.hpp"
|
|
#include "libtorrent/torrent_info.hpp"
|
|
|
|
|
|
int main(int argc, char* argv[])
|
|
{
|
|
using namespace libtorrent;
|
|
|
|
if (argc != 2)
|
|
{
|
|
std::cerr << "usage: dump_torrent torrent-file\n";
|
|
return 1;
|
|
}
|
|
|
|
try
|
|
{
|
|
std::ifstream in(argv[1], std::ios_base::binary);
|
|
in.unsetf(std::ios_base::skipws);
|
|
entry e = bdecode(std::istream_iterator<char>(in), std::istream_iterator<char>());
|
|
torrent_info t(e);
|
|
|
|
// print info about torrent
|
|
std::cout << "\n\n----- torrent file info -----\n\n";
|
|
std::cout << "trackers:\n";
|
|
for (std::vector<announce_entry>::const_iterator i = t.trackers().begin();
|
|
i != t.trackers().end();
|
|
++i)
|
|
{
|
|
std::cout << i->tier << ": " << i->url << "\n";
|
|
}
|
|
|
|
std::cout << "number of pieces: " << t.num_pieces() << "\n";
|
|
std::cout << "piece length: " << t.piece_length() << "\n";
|
|
std::cout << "files:\n";
|
|
for (torrent_info::file_iterator i = t.begin_files();
|
|
i != t.end_files();
|
|
++i)
|
|
{
|
|
std::cout << " " << std::setw(11) << i->size
|
|
<< " " << i->path << " " << i->filename << "\n";
|
|
}
|
|
|
|
}
|
|
catch (std::exception& e)
|
|
{
|
|
std::cout << e.what() << "\n";
|
|
}
|
|
|
|
return 0;
|
|
}
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="simple-client">
|
|
<h2><a name="simple-client">simple client</a></h2>
|
|
<p>This is a simple client. It doesn't have much output to keep it simple:</p>
|
|
<pre class="literal-block">
|
|
#include <iostream>
|
|
#include <fstream>
|
|
#include <iterator>
|
|
#include <exception>
|
|
|
|
#include <boost/format.hpp>
|
|
#include <boost/date_time/posix_time/posix_time.hpp>
|
|
|
|
#include "libtorrent/entry.hpp"
|
|
#include "libtorrent/bencode.hpp"
|
|
#include "libtorrent/session.hpp"
|
|
#include "libtorrent/http_settings.hpp"
|
|
|
|
int main(int argc, char* argv[])
|
|
{
|
|
using namespace libtorrent;
|
|
|
|
if (argc != 2)
|
|
{
|
|
std::cerr << "usage: ./simple_cient torrent-file\n"
|
|
"to stop the client, press return.\n";
|
|
return 1;
|
|
}
|
|
|
|
try
|
|
{
|
|
session s(std::make_pair(6881, 6889));
|
|
|
|
std::ifstream in(argv[1], std::ios_base::binary);
|
|
in.unsetf(std::ios_base::skipws);
|
|
entry e = bdecode(std::istream_iterator<char>(in), std::istream_iterator<char>());
|
|
torrent_info t(e);
|
|
s.add_torrent(t, "");
|
|
|
|
// wait for the user to end
|
|
char a;
|
|
std::cin.unsetf(std::ios_base::skipws);
|
|
std::cin >> a;
|
|
}
|
|
catch (std::exception& e)
|
|
{
|
|
std::cout << e.what() << "\n";
|
|
}
|
|
return 0;
|
|
}
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="fast-resume">
|
|
<h1><a name="fast-resume">fast resume</a></h1>
|
|
<p>The fast resume mechanism is a way to remember which pieces are downloaded and where they
|
|
are put between sessions. You can generate fast resume data by calling
|
|
<tt class="literal"><span class="pre">torrent_handle::write_resume_data()</span></tt> on <a class="reference" href="#torrent-handle">torrent_handle</a>. You can then save this data
|
|
to disk and use it when resuming the torrent. libtorrent will not check the piece hashes
|
|
then, and rely on the information given in the fast-resume data. The fast-resume data
|
|
also contains information about which blocks, in the unfinished pieces, were downloaded,
|
|
so it will not have to start from scratch on the partially downloaded pieces.</p>
|
|
<p>To use the fast-resume data you simply give it to <tt class="literal"><span class="pre">session::add_torrent()</span></tt>, and it
|
|
will skip the time consuming checks. It may have to do the checking anyway, if the
|
|
fast-resume data is corrupt or doesn't fit the storage for that torrent, then it will
|
|
not trust the fast-resume data and just do the checking.</p>
|
|
<div class="section" id="file-format">
|
|
<h2><a name="file-format">file format</a></h2>
|
|
<p>The file format is a bencoded dictionary containing the following fields:</p>
|
|
<table border class="table">
|
|
<colgroup>
|
|
<col width="26%" />
|
|
<col width="74%" />
|
|
</colgroup>
|
|
<tbody valign="top">
|
|
<tr><td><tt class="literal"><span class="pre">file-format</span></tt></td>
|
|
<td>string: "libtorrent resume file"</td>
|
|
</tr>
|
|
<tr><td><tt class="literal"><span class="pre">file-version</span></tt></td>
|
|
<td>integer: 1</td>
|
|
</tr>
|
|
<tr><td><tt class="literal"><span class="pre">info-hash</span></tt></td>
|
|
<td>string, the info hash of the torrent this data is saved for.</td>
|
|
</tr>
|
|
<tr><td><tt class="literal"><span class="pre">blocks</span> <span class="pre">per</span> <span class="pre">piece</span></tt></td>
|
|
<td>integer, the number of blocks per piece. Must be: piece_size
|
|
/ (16 * 1024). Clamped to be within the range [1, 256]. It
|
|
is the number of blocks per (normal sized) piece. Usually
|
|
each block is 16 * 1024 bytes in size. But if piece size is
|
|
greater than 4 megabytes, the block size will increase.</td>
|
|
</tr>
|
|
<tr><td><tt class="literal"><span class="pre">slots</span></tt></td>
|
|
<td><p class="first">list of integers. The list mappes slots ti piece indices. It
|
|
tells which piece is on which slot. If piece index is -2 it
|
|
means it is free, that there's no piece there. If it is -1,
|
|
means the slot isn't allocated on disk yet. The pieces have
|
|
to meet the following requirement:</p>
|
|
<p class="last">If there's a slot at the position of the piece index,
|
|
the piece must be located in that slot.</p>
|
|
</td>
|
|
</tr>
|
|
<tr><td><tt class="literal"><span class="pre">peers</span></tt></td>
|
|
<td><p class="first">list of dictionaries. Each dictionary has the following
|
|
layout:</p>
|
|
<table border class="table">
|
|
<colgroup>
|
|
<col width="18%" />
|
|
<col width="82%" />
|
|
</colgroup>
|
|
<tbody valign="top">
|
|
<tr><td><tt class="literal"><span class="pre">ip</span></tt></td>
|
|
<td>string, the ip address of the peer.</td>
|
|
</tr>
|
|
<tr><td><tt class="literal"><span class="pre">port</span></tt></td>
|
|
<td>integer, the listen port of the peer</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p class="last">These are the local peers we were connected to when this
|
|
fast-resume data was saved.</p>
|
|
</td>
|
|
</tr>
|
|
<tr><td><tt class="literal"><span class="pre">unfinished</span></tt></td>
|
|
<td><p class="first">list of dictionaries. Each dictionary represents an
|
|
piece, and has the following layout:</p>
|
|
<table border class="last table">
|
|
<colgroup>
|
|
<col width="23%" />
|
|
<col width="77%" />
|
|
</colgroup>
|
|
<tbody valign="top">
|
|
<tr><td><tt class="literal"><span class="pre">piece</span></tt></td>
|
|
<td>integer, the index of the piece this entry
|
|
refers to.</td>
|
|
</tr>
|
|
<tr><td><tt class="literal"><span class="pre">bitmask</span></tt></td>
|
|
<td>string, a binary bitmask representing the
|
|
blocks that have been downloaded in this
|
|
piece.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="extensions">
|
|
<h1><a name="extensions">extensions</a></h1>
|
|
<p>These extensions all operates within the <a class="reference" href="http://nolar.com/azureus/extended.html">extension protocol</a>. The
|
|
name of the extension is the name used in the extension-list packets,
|
|
and the payload is the data in the extended message (not counting the
|
|
length-prefix, message-id nor extension-id).</p>
|
|
<p>The extension protocol is currently disabled, since it may not be compatible
|
|
with future versions of bittorrent.</p>
|
|
<!-- These are the extensions that are currently implemented. -->
|
|
<!-- chat messages -->
|
|
<!-- - - - - - - - - - - - - - -->
|
|
<!-- Extension name: "chat" -->
|
|
<!-- The payload in the packet is a bencoded dictionary with any -->
|
|
<!-- combination of the following entries: -->
|
|
<!-- +- - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+
|
|
| "msg" | This is a string that contains a message that |
|
|
| | should be displayed to the user. |
|
|
+- - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+
|
|
| "ctrl" | This is a control string that can tell a client that |
|
|
| | it is ignored (to make the user aware of that) and |
|
|
| | it can also tell a client that it is no longer ignored.|
|
|
| | These notifications are encoded as the strings: |
|
|
| | "ignored" and "not ignored". |
|
|
| | Any unrecognized strings should be ignored. |
|
|
+- - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+ -->
|
|
</div>
|
|
<div class="section" id="filenames-checks">
|
|
<h1><a name="filenames-checks">filenames checks</a></h1>
|
|
<p>Boost.Filesystem will by default check all its paths to make sure they conform
|
|
to filename requirements on many platforms. If you don't want this check, you can
|
|
set it to either only check for native filesystem requirements or turn it off
|
|
alltogether. You can use: <tt class="literal"><span class="pre">boost::filesystem::path::default_name_check(boost::filesystem::native)</span></tt>
|
|
for example. For more information, see the <a class="reference" href="http://www.boost.org/libs/filesystem/doc/index.htm">Boost.Filesystem docs</a>.</p>
|
|
</div>
|
|
<div class="section" id="aknowledgements">
|
|
<h1><a name="aknowledgements">aknowledgements</a></h1>
|
|
<p>Written by Arvid Norberg. Copyright (c) 2003</p>
|
|
<p>Contributions by Magnus Jonsson and Daniel Wallin</p>
|
|
<p>Thanks to Reimond Retz for bugfixes, suggestions and testing</p>
|
|
<p>Project is hosted by sourceforge.</p>
|
|
<p><a class="reference" href="http://sourceforge.net"><img alt="sf_logo" src="http://sourceforge.net/sflogo.php?group_id=7994" /></a></p>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html>
|