wornvirtue/premiere-libtorrent
1
0
Fork 0
forked from premiere/premiere-libtorrent
Code Pull Requests Activity

update docs

Browse Source
This commit is contained in:
Arvid Norberg 2013-01-21 19:13:24 +00:00
parent b789e9596a
commit 1b0ddc5560
20 changed files with 493 additions and 413 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

322
docs/building.html
View File

@ -3,7 +3,7 @@
<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.5: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.8.1: http://docutils.sourceforge.net/" />
<title>libtorrent manual</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
@ -49,7 +49,7 @@
<tr><th class="docinfo-name">Author:</th>
<td>Arvid Norberg, <a class="last reference external" href="mailto:arvid&#64;rasterbar.com">arvid&#64;rasterbar.com</a></td></tr>
<tr><th class="docinfo-name">Version:</th>
<td>0.16.0</td></tr>
<td>1.0.0</td></tr>
</tbody>
</table>
<div class="contents topic" id="table-of-contents">
@ -72,8 +72,8 @@
You'll find instructions on how to do this <a class="reference external" href="http://sourceforge.net/svn/?group_id=79942">here</a> (see subversion access).</p>
<p>The build systems supported &quot;out of the box&quot; in libtorrent are boost-build v2
(BBv2) and autotools (for unix-like systems). If you still can't build after
following these instructions, you can usually get help in the <tt class="docutils literal"><span class="pre">#libtorrent</span></tt>
IRC channel on <tt class="docutils literal"><span class="pre">irc.freenode.net</span></tt>.</p>
following these instructions, you can usually get help in the <tt class="docutils literal">#libtorrent</tt>
IRC channel on <tt class="docutils literal">irc.freenode.net</tt>.</p>
<div class="warning">
<p class="first admonition-title">Warning</p>
<p>A common mistake when building and linking against libtorrent is
@ -117,20 +117,20 @@ in order to build libtorrent.</p>
</div>
<div class="section" id="step-2-setup-bbv2">
<h3>Step 2: Setup BBv2</h3>
<p>First you need to build <tt class="docutils literal"><span class="pre">bjam</span></tt>. You do this by opening a terminal (In
windows, run <tt class="docutils literal"><span class="pre">cmd</span></tt>). Change directory to
<p>First you need to build <tt class="docutils literal">bjam</tt>. You do this by opening a terminal (In
windows, run <tt class="docutils literal">cmd</tt>). Change directory to
<tt class="docutils literal"><span class="pre">c:\boost_1_34_0\tools\jam\src</span></tt>. Then run the script called
<tt class="docutils literal"><span class="pre">build.bat</span></tt> or <tt class="docutils literal"><span class="pre">build.sh</span></tt> on a unix system. This will build <tt class="docutils literal"><span class="pre">bjam</span></tt> and
place it in a directory starting with <tt class="docutils literal"><span class="pre">bin.</span></tt> and then have the name of your
platform. Copy the <tt class="docutils literal"><span class="pre">bjam.exe</span></tt> (or <tt class="docutils literal"><span class="pre">bjam</span></tt> on a unix system) to a place
that's in you shell's <tt class="docutils literal"><span class="pre">PATH</span></tt>. On linux systems a place commonly used may be
<tt class="docutils literal"><span class="pre">/usr/local/bin</span></tt> or on windows <tt class="docutils literal"><span class="pre">c:\windows</span></tt> (you can also add directories
to the search paths by modifying the environment variable called <tt class="docutils literal"><span class="pre">PATH</span></tt>).</p>
<p>Now you have <tt class="docutils literal"><span class="pre">bjam</span></tt> installed. <tt class="docutils literal"><span class="pre">bjam</span></tt> can be considered an interpreter
that the boost-build system is implemented on. So boost-build uses <tt class="docutils literal"><span class="pre">bjam</span></tt>.
<tt class="docutils literal">build.bat</tt> or <tt class="docutils literal">build.sh</tt> on a unix system. This will build <tt class="docutils literal">bjam</tt> and
place it in a directory starting with <tt class="docutils literal">bin.</tt> and then have the name of your
platform. Copy the <tt class="docutils literal">bjam.exe</tt> (or <tt class="docutils literal">bjam</tt> on a unix system) to a place
that's in you shell's <tt class="docutils literal">PATH</tt>. On linux systems a place commonly used may be
<tt class="docutils literal">/usr/local/bin</tt> or on windows <tt class="docutils literal"><span class="pre">c:\windows</span></tt> (you can also add directories
to the search paths by modifying the environment variable called <tt class="docutils literal">PATH</tt>).</p>
<p>Now you have <tt class="docutils literal">bjam</tt> installed. <tt class="docutils literal">bjam</tt> can be considered an interpreter
that the boost-build system is implemented on. So boost-build uses <tt class="docutils literal">bjam</tt>.
So, to complete the installation you need to make two more things. You need to
set the environment variable <tt class="docutils literal"><span class="pre">BOOST_BUILD_PATH</span></tt>. This is the path that tells
<tt class="docutils literal"><span class="pre">bjam</span></tt> where it can find boost-build, your configuration file and all the
set the environment variable <tt class="docutils literal">BOOST_BUILD_PATH</tt>. This is the path that tells
<tt class="docutils literal">bjam</tt> where it can find boost-build, your configuration file and all the
toolsets (descriptions used by boost-build to know how to use different
compilers on different platforms). Assuming the boost install path above, set
it to <tt class="docutils literal"><span class="pre">c:\boost_1_34_0\tools\build\v2</span></tt>.</p>
@ -158,7 +158,7 @@ commandline used to invoke g++ after the version number, like this:</p>
using gcc : 3.3 : g++-3.3 ;
using gcc : 4.0 : g++-4.0 ;
</pre>
<p>Another toolset worth mentioning is the <tt class="docutils literal"><span class="pre">darwin</span></tt> toolset (For MacOS X).
<p>Another toolset worth mentioning is the <tt class="docutils literal">darwin</tt> toolset (For MacOS X).
From Tiger (10.4) MacOS X comes with both GCC 3.3 and GCC 4.0. Then you can
use the following toolsets:</p>
<pre class="literal-block">
@ -170,12 +170,12 @@ using darwin : 4.0 : g++-4.0 ;
</div>
<div class="section" id="step-3-building-libtorrent">
<h3>Step 3: Building libtorrent</h3>
<p>When building libtorrent, the <tt class="docutils literal"><span class="pre">Jamfile</span></tt> expects the environment variable
<tt class="docutils literal"><span class="pre">BOOST_ROOT</span></tt> to be set to the boost installation directory. It uses this to
<p>When building libtorrent, the <tt class="docutils literal">Jamfile</tt> expects the environment variable
<tt class="docutils literal">BOOST_ROOT</tt> to be set to the boost installation directory. It uses this to
find the boost libraries it depends on, so they can be built and their headers
files found. So, set this to <tt class="docutils literal"><span class="pre">c:\boost_1_34_0</span></tt>. You only need this if you're
building against a source distribution of boost.</p>
<p>Then the only thing left is simply to invoke <tt class="docutils literal"><span class="pre">bjam</span></tt>. If you want to specify
<p>Then the only thing left is simply to invoke <tt class="docutils literal">bjam</tt>. If you want to specify
a specific toolset to use (compiler) you can just add that to the commandline.
For example:</p>
<pre class="literal-block">
@ -183,19 +183,25 @@ bjam msvc-7.1 boost=source
bjam gcc-3.3 boost=source
bjam darwin-4.0 boost=source
</pre>
<p>If you're building against a system installed boost, specify <tt class="docutils literal"><span class="pre">boost=system</span></tt>.</p>
<p>If you're building against a system installed boost, specify <tt class="docutils literal">boost=system</tt>.</p>
<p>To build different versions you can also just add the name of the build
variant. Some default build variants in BBv2 are <tt class="docutils literal"><span class="pre">release</span></tt>, <tt class="docutils literal"><span class="pre">debug</span></tt>,
<tt class="docutils literal"><span class="pre">profile</span></tt>.</p>
<p>You can build libtorrent as a dll too, by typing <tt class="docutils literal"><span class="pre">link=shared</span></tt>, or
<tt class="docutils literal"><span class="pre">link=static</span></tt> to build a static library.</p>
variant. Some default build variants in BBv2 are <tt class="docutils literal">release</tt>, <tt class="docutils literal">debug</tt>,
<tt class="docutils literal">profile</tt>.</p>
<p>You can build libtorrent as a dll too, by typing <tt class="docutils literal">link=shared</tt>, or
<tt class="docutils literal">link=static</tt> to build a static library.</p>
<p>If you want to explicitly say how to link against the runtime library, you
can set the <tt class="docutils literal"><span class="pre">runtime-link</span></tt> feature on the commandline, either to <tt class="docutils literal"><span class="pre">shared</span></tt>
or <tt class="docutils literal"><span class="pre">static</span></tt>. Most operating systems will only allow linking shared against
can set the <tt class="docutils literal"><span class="pre">runtime-link</span></tt> feature on the commandline, either to <tt class="docutils literal">shared</tt>
or <tt class="docutils literal">static</tt>. Most operating systems will only allow linking shared against
the runtime, but on windows you can do both. Example:</p>
<pre class="literal-block">
bjam msvc-7.1 link=static runtime-link=static boost=source
</pre>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">When building on windows, the path boost-build puts targets in may be too
long. If you get an error message like: &quot;The input line is long&quot;, try to
pass --abbreviate-paths on the bjam command line.</p>
</div>
<div class="warning">
<p class="first admonition-title">Warning</p>
<p class="last">If you link statically to the runtime library, you cannot build libtorrent
@ -209,14 +215,14 @@ errors.</p>
option to strip debug symbols. This option is buggy in Apple's GCC, and
will make the executable crash on startup. On Mac OS X, instead build
your release executables with the <tt class="docutils literal"><span class="pre">debug-symbols=on</span></tt> option, and
later strip your executable with <tt class="docutils literal"><span class="pre">strip</span></tt>.</p>
later strip your executable with <tt class="docutils literal">strip</tt>.</p>
</div>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">Some linux systems requires linking against <tt class="docutils literal"><span class="pre">librt</span></tt> in order to access
<p class="last">Some linux systems requires linking against <tt class="docutils literal">librt</tt> in order to access
the POSIX clock functions. If you get an error complaining about a missing
symbol <tt class="docutils literal"><span class="pre">clock_gettime</span></tt>, you have to give <tt class="docutils literal"><span class="pre">need-librt=yes</span></tt> on the
bjam command line. This will make libtorrent link against <tt class="docutils literal"><span class="pre">librt</span></tt>.</p>
symbol <tt class="docutils literal">clock_gettime</tt>, you have to give <tt class="docutils literal"><span class="pre">need-librt=yes</span></tt> on the
bjam command line. This will make libtorrent link against <tt class="docutils literal">librt</tt>.</p>
</div>
<div class="note">
<p class="first admonition-title">Note</p>
@ -226,14 +232,14 @@ on the bjam command line.</p>
<p>The build targets are put in a directory called bin, and under it they are
sorted in directories depending on the toolset and build variant used.</p>
<p>To build the examples, just change directory to the examples directory and
invoke <tt class="docutils literal"><span class="pre">bjam</span></tt> from there. To build and run the tests, go to the test
directory and run <tt class="docutils literal"><span class="pre">bjam</span></tt>.</p>
<p>Note that if you're building on windows using the <tt class="docutils literal"><span class="pre">msvc</span></tt> toolset, you cannot run it
from a cygwin terminal, you'll have to run it from a <tt class="docutils literal"><span class="pre">cmd</span></tt> terminal. The same goes for
invoke <tt class="docutils literal">bjam</tt> from there. To build and run the tests, go to the test
directory and run <tt class="docutils literal">bjam</tt>.</p>
<p>Note that if you're building on windows using the <tt class="docutils literal">msvc</tt> toolset, you cannot run it
from a cygwin terminal, you'll have to run it from a <tt class="docutils literal">cmd</tt> terminal. The same goes for
cygwin, if you're building with gcc in cygwin you'll have to run it from a cygwin terminal.
Also, make sure the paths are correct in the different environments. In cygwin, the paths
(<tt class="docutils literal"><span class="pre">BOOST_BUILD_PATH</span></tt> and <tt class="docutils literal"><span class="pre">BOOST_ROOT</span></tt>) should be in the typical unix-format (e.g.
<tt class="docutils literal"><span class="pre">/cygdrive/c/boost_1_34_0</span></tt>). In the windows environment, they should have the typical
(<tt class="docutils literal">BOOST_BUILD_PATH</tt> and <tt class="docutils literal">BOOST_ROOT</tt>) should be in the typical unix-format (e.g.
<tt class="docutils literal">/cygdrive/c/boost_1_34_0</tt>). In the windows environment, they should have the typical
windows format (<tt class="docutils literal"><span class="pre">c:/boost_1_34_0</span></tt>).</p>
<div class="note">
<p class="first admonition-title">Note</p>
@ -241,7 +247,7 @@ windows format (<tt class="docutils literal"><span class="pre">c:/boost_1_34_0</
in path names. If you want spaces in your paths, make sure to quote them
with double quotes (&quot;).</p>
</div>
<p>The <tt class="docutils literal"><span class="pre">Jamfile</span></tt> will define <tt class="docutils literal"><span class="pre">NDEBUG</span></tt> when it's building a release build.
<p>The <tt class="docutils literal">Jamfile</tt> will define <tt class="docutils literal">NDEBUG</tt> when it's building a release build.
For more build configuration flags see <a class="reference internal" href="#build-configurations">Build configurations</a>.</p>
<p>Build features:</p>
<table border="1" class="docutils">
@ -255,74 +261,74 @@ For more build configuration flags see <a class="reference internal" href="#buil
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="docutils literal"><span class="pre">boost</span></tt></td>
<tr><td><tt class="docutils literal">boost</tt></td>
<td><ul class="first last simple">
<li><tt class="docutils literal"><span class="pre">system</span></tt> - default. Tells the Jamfile that
<li><tt class="docutils literal">system</tt> - default. Tells the Jamfile that
boost is installed and should be linked against
the system libraries.</li>
<li><tt class="docutils literal"><span class="pre">source</span></tt> - Specifies that boost is to be built
<li><tt class="docutils literal">source</tt> - Specifies that boost is to be built
from source. The environment variable
<tt class="docutils literal"><span class="pre">BOOST_ROOT</span></tt> must be defined to point to the
<tt class="docutils literal">BOOST_ROOT</tt> must be defined to point to the
boost directory.</li>
</ul>
</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">boost-link</span></tt></td>
<td><ul class="first last simple">
<li><tt class="docutils literal"><span class="pre">static</span></tt> - links statically against the boost
<li><tt class="docutils literal">static</tt> - links statically against the boost
libraries.</li>
<li><tt class="docutils literal"><span class="pre">shared</span></tt> - links dynamically against the boost
<li><tt class="docutils literal">shared</tt> - links dynamically against the boost
libraries.</li>
</ul>
</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">logging</span></tt></td>
<tr><td><tt class="docutils literal">logging</tt></td>
<td><ul class="first last simple">
<li><tt class="docutils literal"><span class="pre">none</span></tt> - no logging.</li>
<li><tt class="docutils literal"><span class="pre">default</span></tt> - basic session logging.</li>
<li><tt class="docutils literal"><span class="pre">verbose</span></tt> - verbose peer wire logging.</li>
<li><tt class="docutils literal"><span class="pre">errors</span></tt> - like verbose, but limited to errors.</li>
<li><tt class="docutils literal">none</tt> - no logging.</li>
<li><tt class="docutils literal">default</tt> - basic session logging.</li>
<li><tt class="docutils literal">verbose</tt> - verbose peer wire logging.</li>
<li><tt class="docutils literal">errors</tt> - like verbose, but limited to errors.</li>
</ul>
</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">dht-support</span></tt></td>
<td><ul class="first last simple">
<li><tt class="docutils literal"><span class="pre">on</span></tt> - build with support for tracker less
<li><tt class="docutils literal">on</tt> - build with support for tracker less
torrents and DHT support.</li>
<li><tt class="docutils literal"><span class="pre">logging</span></tt> - build with DHT support and verbose
<li><tt class="docutils literal">logging</tt> - build with DHT support and verbose
logging of the DHT protocol traffic.</li>
<li><tt class="docutils literal"><span class="pre">off</span></tt> - build without DHT support.</li>
<li><tt class="docutils literal">off</tt> - build without DHT support.</li>
</ul>
</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">need-librt</span></tt></td>
<td><ul class="first last simple">
<li><tt class="docutils literal"><span class="pre">no</span></tt> - this platform does not need to link
<li><tt class="docutils literal">no</tt> - this platform does not need to link
against librt to have POSIX time functions.</li>
<li><tt class="docutils literal"><span class="pre">yes</span></tt> - specify this if your linux system
<li><tt class="docutils literal">yes</tt> - specify this if your linux system
requires you to link against librt.a. This is
typically the case on x86 64 bit systems.</li>
</ul>
</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">asserts</span></tt></td>
<tr><td><tt class="docutils literal">asserts</tt></td>
<td><ul class="first last simple">
<li><tt class="docutils literal"><span class="pre">auto</span></tt> - asserts are on if in debug mode</li>
<li><tt class="docutils literal"><span class="pre">on</span></tt> - asserts are on, even in release mode</li>
<li><tt class="docutils literal"><span class="pre">off</span></tt> - asserts are disabled</li>
<li><tt class="docutils literal"><span class="pre">production</span></tt> - assertion failures are logged
to <tt class="docutils literal"><span class="pre">asserts.log</span></tt> in the current working
<li><tt class="docutils literal">auto</tt> - asserts are on if in debug mode</li>
<li><tt class="docutils literal">on</tt> - asserts are on, even in release mode</li>
<li><tt class="docutils literal">off</tt> - asserts are disabled</li>
<li><tt class="docutils literal">production</tt> - assertion failures are logged
to <tt class="docutils literal">asserts.log</tt> in the current working
directory, but won't abort the process.</li>
</ul>
</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">geoip</span></tt></td>
<tr><td><tt class="docutils literal">geoip</tt></td>
<td><ul class="first last simple">
<li><tt class="docutils literal"><span class="pre">off</span></tt> - geo ip lookups disabled</li>
<li><tt class="docutils literal"><span class="pre">static</span></tt> - <a class="reference external" href="http://www.maxmind.com/app/api">MaxMind</a> geo ip lookup code linked
<li><tt class="docutils literal">off</tt> - geo ip lookups disabled</li>
<li><tt class="docutils literal">static</tt> - <a class="reference external" href="http://www.maxmind.com/app/api">MaxMind</a> geo ip lookup code linked
in statically. Note that this code is under
LGPL license.</li>
<li><tt class="docutils literal"><span class="pre">shared</span></tt> - The <a class="reference external" href="http://www.maxmind.com/app/api">MaxMind</a> geo ip lookup library
<li><tt class="docutils literal">shared</tt> - The <a class="reference external" href="http://www.maxmind.com/app/api">MaxMind</a> geo ip lookup library
is expected to be installed on the system and
it will be used.</li>
</ul>
@ -330,24 +336,24 @@ it will be used.</li>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">upnp-logging</span></tt></td>
<td><ul class="first last simple">
<li><tt class="docutils literal"><span class="pre">off</span></tt> - default. Does not log UPnP traffic.</li>
<li><tt class="docutils literal"><span class="pre">on</span></tt> - creates &quot;upnp.log&quot; with the messages
<li><tt class="docutils literal">off</tt> - default. Does not log UPnP traffic.</li>
<li><tt class="docutils literal">on</tt> - creates &quot;upnp.log&quot; with the messages
sent to and received from UPnP devices.</li>
</ul>
</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">encryption</span></tt></td>
<tr><td><tt class="docutils literal">encryption</tt></td>
<td><ul class="first last simple">
<li><tt class="docutils literal"><span class="pre">openssl</span></tt> - links against openssl and
<li><tt class="docutils literal">openssl</tt> - links against openssl and
libcrypto to enable https and encrypted
bittorrent connections.</li>
<li><tt class="docutils literal"><span class="pre">gcrypt</span></tt> - links against libgcrypt to enable
<li><tt class="docutils literal">gcrypt</tt> - links against libgcrypt to enable
encrypted bittorrent connections.</li>
<li><tt class="docutils literal"><span class="pre">tommath</span></tt> - uses a shipped version of
<li><tt class="docutils literal">tommath</tt> - uses a shipped version of
libtommath and a custom rc4 implementation
(based on libtomcrypt). This is the default
option.</li>
<li><tt class="docutils literal"><span class="pre">off</span></tt> - turns off support for encrypted
<li><tt class="docutils literal">off</tt> - turns off support for encrypted
connections. The shipped public domain SHA-1
implementation is used.</li>
</ul>
@ -355,40 +361,40 @@ implementation is used.</li>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">pool-allocators</span></tt></td>
<td><ul class="first last simple">
<li><tt class="docutils literal"><span class="pre">on</span></tt> - default, uses pool allocators for send
<li><tt class="docutils literal">on</tt> - default, uses pool allocators for send
buffers.</li>
<li><tt class="docutils literal"><span class="pre">off</span></tt> - uses <tt class="docutils literal"><span class="pre">malloc()</span></tt> and <tt class="docutils literal"><span class="pre">free()</span></tt>
<li><tt class="docutils literal">off</tt> - uses <tt class="docutils literal">malloc()</tt> and <tt class="docutils literal">free()</tt>
instead. Might be useful to debug buffer issues
with tools like electric fence or libgmalloc.</li>
</ul>
</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">link</span></tt></td>
<tr><td><tt class="docutils literal">link</tt></td>
<td><ul class="first last simple">
<li><tt class="docutils literal"><span class="pre">static</span></tt> - builds libtorrent as a static
<li><tt class="docutils literal">static</tt> - builds libtorrent as a static
library (.a / .lib)</li>
<li><tt class="docutils literal"><span class="pre">shared</span></tt> - builds libtorrent as a shared
<li><tt class="docutils literal">shared</tt> - builds libtorrent as a shared
library (.so / .dll).</li>
</ul>
</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">runtime-link</span></tt></td>
<td><ul class="first last simple">
<li><tt class="docutils literal"><span class="pre">static</span></tt> - links statically against the
<li><tt class="docutils literal">static</tt> - links statically against the
run-time library (if available on your
platform).</li>
<li><tt class="docutils literal"><span class="pre">shared</span></tt> - link dynamically against the
<li><tt class="docutils literal">shared</tt> - link dynamically against the
run-time library (default).</li>
</ul>
</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">variant</span></tt></td>
<tr><td><tt class="docutils literal">variant</tt></td>
<td><ul class="first last simple">
<li><tt class="docutils literal"><span class="pre">debug</span></tt> - builds libtorrent with debug
<li><tt class="docutils literal">debug</tt> - builds libtorrent with debug
information and invariant checks.</li>
<li><tt class="docutils literal"><span class="pre">release</span></tt> - builds libtorrent in release mode
<li><tt class="docutils literal">release</tt> - builds libtorrent in release mode
without invariant checks and with optimization.</li>
<li><tt class="docutils literal"><span class="pre">profile</span></tt> - builds libtorrent with profile
<li><tt class="docutils literal">profile</tt> - builds libtorrent with profile
information.</li>
</ul>
</td>
@ -397,41 +403,41 @@ information.</li>
<td><p class="first">This setting will only have an affect on windows.
Other platforms are expected to support UTF-8.</p>
<ul class="last simple">
<li><tt class="docutils literal"><span class="pre">unicode</span></tt> - The unicode version of the win32
<li><tt class="docutils literal">unicode</tt> - The unicode version of the win32
API is used. This is default.</li>
<li><tt class="docutils literal"><span class="pre">ansi</span></tt> - The ansi version of the win32 API is
<li><tt class="docutils literal">ansi</tt> - The ansi version of the win32 API is
used.</li>
</ul>
</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">invariant-checks</span></tt></td>
<td><p class="first">This setting only affects debug builds (where
<tt class="docutils literal"><span class="pre">NDEBUG</span></tt> is not defined). It defaults to <tt class="docutils literal"><span class="pre">on</span></tt>.</p>
<tt class="docutils literal">NDEBUG</tt> is not defined). It defaults to <tt class="docutils literal">on</tt>.</p>
<ul class="last simple">
<li><tt class="docutils literal"><span class="pre">on</span></tt> - internal invariant checks are enabled.</li>
<li><tt class="docutils literal"><span class="pre">off</span></tt> - internal invariant checks are
<li><tt class="docutils literal">on</tt> - internal invariant checks are enabled.</li>
<li><tt class="docutils literal">off</tt> - internal invariant checks are
disabled. The resulting executable will run
faster than a regular debug build.</li>
<li><tt class="docutils literal"><span class="pre">full</span></tt> - turns on extra expensive invariant
<li><tt class="docutils literal">full</tt> - turns on extra expensive invariant
checks.</li>
</ul>
</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">debug-symbols</span></tt></td>
<td><ul class="first last simple">
<li><tt class="docutils literal"><span class="pre">on</span></tt> - default for debug builds. This setting
<li><tt class="docutils literal">on</tt> - default for debug builds. This setting
is useful for building release builds with
symbols.</li>
<li><tt class="docutils literal"><span class="pre">off</span></tt> - default for release builds.</li>
<li><tt class="docutils literal">off</tt> - default for release builds.</li>
</ul>
</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">deprecated-functions</span></tt></td>
<td><ul class="first last simple">
<li><tt class="docutils literal"><span class="pre">on</span></tt> - default. Includes deprecated functions
<li><tt class="docutils literal">on</tt> - default. Includes deprecated functions
of the API (might produce warnings during build
when deprecated functions are used).</li>
<li><tt class="docutils literal"><span class="pre">off</span></tt> - excludes deprecated functions from the
<li><tt class="docutils literal">off</tt> - excludes deprecated functions from the
API. Generates build errors when deprecated
functions are used.</li>
</ul>
@ -439,45 +445,63 @@ functions are used.</li>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">full-stats</span></tt></td>
<td><ul class="first last simple">
<li><tt class="docutils literal"><span class="pre">on</span></tt> - default, collects stats for IP overhead
<li><tt class="docutils literal">on</tt> - default, collects stats for IP overhead
and DHT and trackers. This uses a little bit
extra memory for each peer and torrent.</li>
<li><tt class="docutils literal"><span class="pre">off</span></tt> - only collects the standard stats for
<li><tt class="docutils literal">off</tt> - only collects the standard stats for
upload and download rate.</li>
</ul>
</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">iconv</span></tt></td>
<tr><td><tt class="docutils literal">iconv</tt></td>
<td><ul class="first last simple">
<li><tt class="docutils literal"><span class="pre">auto</span></tt> - use iconv for string conversions for
<li><tt class="docutils literal">auto</tt> - use iconv for string conversions for
linux and mingw and other posix platforms.</li>
<li><tt class="docutils literal"><span class="pre">on</span></tt> - force use of iconv</li>
<li><tt class="docutils literal"><span class="pre">off</span></tt> - force not using iconv (disables locale
<li><tt class="docutils literal">on</tt> - force use of iconv</li>
<li><tt class="docutils literal">off</tt> - force not using iconv (disables locale
awareness except on windows).</li>
</ul>
</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">asserts</span></tt></td>
<tr><td><tt class="docutils literal">asserts</tt></td>
<td><ul class="first last simple">
<li><tt class="docutils literal"><span class="pre">off</span></tt> - disable all asserts</li>
<li><tt class="docutils literal"><span class="pre">peoduction</span></tt> - enable asserts in release
<li><tt class="docutils literal">off</tt> - disable all asserts</li>
<li><tt class="docutils literal">peoduction</tt> - enable asserts in release
builds, but don't abort, just log them to
<tt class="docutils literal"><span class="pre">extern</span> <span class="pre">char</span> <span class="pre">const*</span> <span class="pre">libtorrent_assert_log</span></tt>.</li>
<li><tt class="docutils literal"><span class="pre">on</span></tt> - enable asserts in debug builds (this is
<tt class="docutils literal">extern char const* libtorrent_assert_log</tt>.</li>
<li><tt class="docutils literal">on</tt> - enable asserts in debug builds (this is
the default). On GNU systems, print a stack
trace of the assert and some more information.</li>
<li><tt class="docutils literal"><span class="pre">system</span></tt> use the libc assert macro</li>
<li><tt class="docutils literal">system</tt> use the libc assert macro</li>
</ul>
</td>
</tr>
<tr><td><tt class="docutils literal">i2p</tt></td>
<td><ul class="first last simple">
<li><tt class="docutils literal">on</tt> - build with I2P support</li>
<li><tt class="docutils literal">off</tt> - build without I2P support</li>
</ul>
</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">boost-date-time</span></tt></td>
<td><ul class="first last simple">
<li><tt class="docutils literal">off</tt> - don't build asio types that depend
on boost.date_time. libtorrent doesn't use them
but if the client does, you need these to be
built.</li>
<li><tt class="docutils literal">on</tt> - build asio types that depend on
boost.date_time.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p>The <tt class="docutils literal"><span class="pre">variant</span></tt> feature is <em>implicit</em>, which means you don't need to specify
<p>The <tt class="docutils literal">variant</tt> feature is <em>implicit</em>, which means you don't need to specify
the name of the feature, just the value.</p>
<p>The logs created when building vlog or log mode are put in a directory called
<tt class="docutils literal"><span class="pre">libtorrent_logs</span></tt> in the current working directory.</p>
<tt class="docutils literal">libtorrent_logs</tt> in the current working directory.</p>
<p>When building the example client on windows, you need to build with
<tt class="docutils literal"><span class="pre">link=static</span></tt> otherwise you may get unresolved external symbols for some
<tt class="docutils literal">link=static</tt> otherwise you may get unresolved external symbols for some
boost.program-options symbols.</p>
<p>For more information, see the <a class="reference external" href="http://www.boost.org/tools/build/v2/index.html">Boost build v2 documentation</a>, or more
specifically <a class="reference external" href="http://www.boost.org/doc/html/bbv2/reference.html#bbv2.advanced.builtins.features">the section on builtin features</a>.</p>
@ -485,7 +509,7 @@ specifically <a class="reference external" href="http://www.boost.org/doc/html/b
</div>
<div class="section" id="building-with-autotools">
<h2>building with autotools</h2>
<p>First of all, you need to install <tt class="docutils literal"><span class="pre">automake</span></tt> and <tt class="docutils literal"><span class="pre">autoconf</span></tt>. Many
<p>First of all, you need to install <tt class="docutils literal">automake</tt> and <tt class="docutils literal">autoconf</tt>. Many
unix/linux systems comes with these preinstalled.</p>
<p>The prerequisites for building libtorrent are boost.thread, boost.date_time
and boost.filesystem. Those are the <em>compiled</em> boost libraries needed. The
@ -493,7 +517,7 @@ headers-only libraries needed include (but is not necessarily limited to)
boost.bind, boost.ref, boost.multi_index, boost.optional, boost.lexical_cast,
boost.integer, boost.iterator, boost.tuple, boost.array, boost.function,
boost.smart_ptr, boost.preprocessor, boost.static_assert.</p>
<p>If you want to build the <tt class="docutils literal"><span class="pre">client_test</span></tt> example, you'll also need boost.regex
<p>If you want to build the <tt class="docutils literal">client_test</tt> example, you'll also need boost.regex
and boost.program_options.</p>
<div class="section" id="step-1-generating-the-build-system">
<h3>Step 1: Generating the build system</h3>
@ -508,7 +532,7 @@ you may skip directly to <a class="reference internal" href="#step-2-running-con
<div class="section" id="step-2-running-configure">
<h3>Step 2: Running configure</h3>
<p>In your shell, change directory to the libtorrent directory and run
<tt class="docutils literal"><span class="pre">./configure</span></tt>. This will look for libraries and C++ features that libtorrent
<tt class="docutils literal">./configure</tt>. This will look for libraries and C++ features that libtorrent
is dependent on. If something is missing or can't be found it will print an
error telling you what failed.</p>
<p>The most likely problem you may encounter is that the configure script won't
@ -518,10 +542,10 @@ system on your platform. Usually libraries and headers are installed in
standard directories where the compiler will find them, but sometimes that
may not be the case. For example when installing boost on darwin using
darwinports (the package system based on BSD ports) all libraries are
installed to <tt class="docutils literal"><span class="pre">/opt/local/lib</span></tt> and headers are installed to
<tt class="docutils literal"><span class="pre">/opt/local/include</span></tt>. By default the compiler will not look in these
directories. You have to set the enviornment variables <tt class="docutils literal"><span class="pre">LDFLAGS</span></tt> and
<tt class="docutils literal"><span class="pre">CXXFLAGS</span></tt> in order to make the compiler find those libs. In this example
installed to <tt class="docutils literal">/opt/local/lib</tt> and headers are installed to
<tt class="docutils literal">/opt/local/include</tt>. By default the compiler will not look in these
directories. You have to set the enviornment variables <tt class="docutils literal">LDFLAGS</tt> and
<tt class="docutils literal">CXXFLAGS</tt> in order to make the compiler find those libs. In this example
you'd set them like this:</p>
<pre class="literal-block">
export LDFLAGS=-L/opt/local/lib
@ -539,7 +563,7 @@ library in this case. For more information about these options, run:</p>
./configure --help
</pre>
<p>On gentoo the boost libraries that are built with multi-threading support have
the suffix <tt class="docutils literal"><span class="pre">mt</span></tt>.</p>
the suffix <tt class="docutils literal">mt</tt>.</p>
<p>You know that the boost libraries were found if you see the following output
from the configure script:</p>
<pre class="literal-block">
@ -575,10 +599,10 @@ with the following option:</p>
</div>
<div class="section" id="id7">
<h3>Step 3: Building libtorrent</h3>
<p>Once the configure script is run successfully, you just type <tt class="docutils literal"><span class="pre">make</span></tt> and
<p>Once the configure script is run successfully, you just type <tt class="docutils literal">make</tt> and
libtorrent, the examples and the tests will be built.</p>
<p>When libtorrent is built it may be a good idea to run the tests, you do this
by running <tt class="docutils literal"><span class="pre">make</span> <span class="pre">check</span></tt>.</p>
by running <tt class="docutils literal">make check</tt>.</p>
<p>If you want to build a release version (without debug info, asserts and
invariant checks), you have to rerun the configure script and rebuild, like this:</p>
<pre class="literal-block">
@ -611,7 +635,7 @@ defines you can use to control the build.</p>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="docutils literal"><span class="pre">NDEBUG</span></tt></td>
<tr><td><tt class="docutils literal">NDEBUG</tt></td>
<td>If you define this macro, all asserts,
invariant checks and general debug code will be
removed. Since there is quite a lot of code in
@ -622,100 +646,100 @@ files. Potential problems is different
compilation units having different views of
structs and class layouts and sizes.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">TORRENT_LOGGING</span></tt></td>
<tr><td><tt class="docutils literal">TORRENT_LOGGING</tt></td>
<td>This macro will enable logging of the session
events, such as tracker announces and incoming
connections (as well as blocked connections).</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">TORRENT_DISABLE_GEO_IP</span></tt></td>
<tr><td><tt class="docutils literal">TORRENT_DISABLE_GEO_IP</tt></td>
<td>This is defined by default by the Jamfile. It
disables the GeoIP features, and avoids linking
against LGPL:ed code.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">TORRENT_VERBOSE_LOGGING</span></tt></td>
<tr><td><tt class="docutils literal">TORRENT_VERBOSE_LOGGING</tt></td>
<td>If you define this macro, every peer connection
will log its traffic to a log file as well as
the session log.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">TORRENT_STORAGE_DEBUG</span></tt></td>
<tr><td><tt class="docutils literal">TORRENT_STORAGE_DEBUG</tt></td>
<td>This will enable extra expensive invariant
checks in the storage, including logging of
piece sorting.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">TORRENT_UPNP_LOGGING</span></tt></td>
<tr><td><tt class="docutils literal">TORRENT_UPNP_LOGGING</tt></td>
<td>Generates a &quot;upnp.log&quot; file with the UPnP
traffic. This is very useful when debugging
support for various UPnP routers.
support for various UPnP routers.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">TORRENT_DISK_STATS</span></tt></td>
<tr><td><tt class="docutils literal">TORRENT_DISK_STATS</tt></td>
<td>This will create a log of all disk activity
which later can parsed and graphed using
<tt class="docutils literal"><span class="pre">parse_disk_log.py</span></tt>.</td>
<tt class="docutils literal">parse_disk_log.py</tt>.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">TORRENT_STATS</span></tt></td>
<tr><td><tt class="docutils literal">TORRENT_STATS</tt></td>
<td>This will generate a log with transfer rates,
downloading torrents, seeding torrents, peers,
connecting peers and disk buffers in use. The
log can be parsed and graphed with
<tt class="docutils literal"><span class="pre">parse_session_stats.py</span></tt>.</td>
<tt class="docutils literal">parse_session_stats.py</tt>.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">UNICODE</span></tt></td>
<tr><td><tt class="docutils literal">UNICODE</tt></td>
<td>If building on windows this will make sure the
UTF-8 strings in pathnames are converted into
UTF-16 before they are passed to the file
operations.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">TORRENT_DISABLE_POOL_ALLOCATOR</span></tt></td>
<tr><td><tt class="docutils literal">TORRENT_DISABLE_POOL_ALLOCATOR</tt></td>
<td>Disables use of <tt class="docutils literal"><span class="pre">boost::pool&lt;&gt;</span></tt>.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">TORRENT_LINKING_SHARED</span></tt></td>
<tr><td><tt class="docutils literal">TORRENT_LINKING_SHARED</tt></td>
<td>If this is defined when including the
libtorrent headers, the classes and functions
will be tagged with <tt class="docutils literal"><span class="pre">__declspec(dllimport)</span></tt>
will be tagged with <tt class="docutils literal">__declspec(dllimport)</tt>
on msvc and default visibility on GCC 4 and
later. Set this in your project if you're
linking against libtorrent as a shared library.
(This is set by the Jamfile when
<tt class="docutils literal"><span class="pre">link=shared</span></tt> is set).</td>
<tt class="docutils literal">link=shared</tt> is set).</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">TORRENT_BUILDING_SHARED</span></tt></td>
<tr><td><tt class="docutils literal">TORRENT_BUILDING_SHARED</tt></td>
<td>If this is defined, the functions and classes
in libtorrent are marked with
<tt class="docutils literal"><span class="pre">__declspec(dllexport)</span></tt> on msvc, or with
<tt class="docutils literal">__declspec(dllexport)</tt> on msvc, or with
default visibility on GCC 4 and later. This
should be defined when building libtorrent as
a shared library. (This is set by the Jamfile
when <tt class="docutils literal"><span class="pre">link=shared</span></tt> is set).</td>
when <tt class="docutils literal">link=shared</tt> is set).</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">TORRENT_DISABLE_DHT</span></tt></td>
<tr><td><tt class="docutils literal">TORRENT_DISABLE_DHT</tt></td>
<td>If this is defined, the support for trackerless
torrents will be disabled.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">TORRENT_DHT_VERBOSE_LOGGING</span></tt></td>
<tr><td><tt class="docutils literal">TORRENT_DHT_VERBOSE_LOGGING</tt></td>
<td>This will enable verbose logging of the DHT
protocol traffic.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">TORRENT_DISABLE_ENCRYPTION</span></tt></td>
<tr><td><tt class="docutils literal">TORRENT_DISABLE_ENCRYPTION</tt></td>
<td>This will disable any encryption support and
the dependencies of a crypto library.
Encryption support is the peer connection
encrypted supported by clients such as
uTorrent, Azureus and KTorrent.
If this is not defined, either
<tt class="docutils literal"><span class="pre">TORRENT_USE_OPENSSL</span></tt> or
<tt class="docutils literal"><span class="pre">TORRENT_USE_GCRYPT</span></tt> must be defined.</td>
<tt class="docutils literal">TORRENT_USE_OPENSSL</tt> or
<tt class="docutils literal">TORRENT_USE_GCRYPT</tt> must be defined.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">_UNICODE</span></tt></td>
<tr><td><tt class="docutils literal">_UNICODE</tt></td>
<td>On windows, this will cause the file IO
use wide character API, to properly support
non-ansi characters.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">TORRENT_DISABLE_RESOLVE_COUNTRIES</span></tt></td>
<tr><td><tt class="docutils literal">TORRENT_DISABLE_RESOLVE_COUNTRIES</tt></td>
<td>Defining this will disable the ability to
resolve countries of origin for peer IPs.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">TORRENT_DISABLE_INVARIANT_CHECKS</span></tt></td>
<tr><td><tt class="docutils literal">TORRENT_DISABLE_INVARIANT_CHECKS</tt></td>
<td>This will disable internal invariant checks in
libtorrent. The invariant checks can sometime
be quite expensive, they typically don't scale
@ -723,30 +747,30 @@ very well. This option can be used to still
build in debug mode, with asserts enabled, but
make the resulting executable faster.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">TORRENT_EXPENSIVE_INVARIANT_CHECKS</span></tt></td>
<tr><td><tt class="docutils literal">TORRENT_EXPENSIVE_INVARIANT_CHECKS</tt></td>
<td>This will enable extra expensive invariant
checks. Useful for finding particular bugs
or for running before releases.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">TORRENT_NO_DEPRECATE</span></tt></td>
<tr><td><tt class="docutils literal">TORRENT_NO_DEPRECATE</tt></td>
<td>This will exclude all deprecated functions from
the header files and cpp files.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">TORRENT_PRODUCTION_ASSERTS</span></tt></td>
<tr><td><tt class="docutils literal">TORRENT_PRODUCTION_ASSERTS</tt></td>
<td>Define to either 0 or 1. Enables assert logging
in release builds.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">TORRENT_NO_ASSERTS</span></tt></td>
<tr><td><tt class="docutils literal">TORRENT_NO_ASSERTS</tt></td>
<td>Disables all asserts.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">TORRENT_USE_SYSTEM_ASSERTS</span></tt></td>
<tr><td><tt class="docutils literal">TORRENT_USE_SYSTEM_ASSERTS</tt></td>
<td>Uses the libc assert macro rather then the
custom one.</td>
</tr>
</tbody>
</table>
<p>If you experience that libtorrent uses unreasonable amounts of cpu, it will
definitely help to define <tt class="docutils literal"><span class="pre">NDEBUG</span></tt>, since it will remove the invariant checks
definitely help to define <tt class="docutils literal">NDEBUG</tt>, since it will remove the invariant checks
within the library.</p>
</div>
<div class="section" id="building-openssl-for-windows">

24
docs/client_test.html
View File

@ -3,7 +3,7 @@
<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.5: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.8.1: http://docutils.sourceforge.net/" />
<title>client_test example program</title>
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
<link rel="stylesheet" type="text/css" href="../../css/rst.css" />
@ -51,30 +51,30 @@ client_test &lt;filename1.torrent&gt; &lt;filename2.torrent&gt; ...
<p>You can start any number of torrent downloads/seeds via the commandline.
If one argument starts with <tt class="docutils literal"><span class="pre">http://</span></tt> it is interpreted as a tracker
announce url, and it expects an info-hash as the next argument. The info-hash
has to be hex-encoded. For example: <tt class="docutils literal"><span class="pre">2410d4554d5ed856d69f426c38791673c59f4418</span></tt>.
has to be hex-encoded. For example: <tt class="docutils literal">2410d4554d5ed856d69f426c38791673c59f4418</tt>.
If you pass an announce url and info-hash, a torrent-less download is started.
It relies on that at least one peer on the tracker is running a libtorrent based
client and has the metadata (.torrent file). The metadata extension in
libtorrent will then download it from that peer (or from those peers if more
than one).</p>
<p>While running, the <tt class="docutils literal"><span class="pre">client_test</span></tt> sample will look something like this:</p>
<p>While running, the <tt class="docutils literal">client_test</tt> sample will look something like this:</p>
<img alt="client_test.png" src="client_test.png" />
<p>The commands available in the client are:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">q</span></tt> quits the client (there will be a delay while the client waits
<li><tt class="docutils literal">q</tt> quits the client (there will be a delay while the client waits
for tracker responses)</li>
<li><tt class="docutils literal"><span class="pre">l</span></tt> toggle log. Will display the log at the bottom, informing about
<li><tt class="docutils literal">l</tt> toggle log. Will display the log at the bottom, informing about
tracker and peer events.</li>
<li><tt class="docutils literal"><span class="pre">i</span></tt> toggles torrent info. Will show the peer list for each torrent.</li>
<li><tt class="docutils literal"><span class="pre">d</span></tt> toggle download info. Will show the block list for each torrent,
<li><tt class="docutils literal">i</tt> toggles torrent info. Will show the peer list for each torrent.</li>
<li><tt class="docutils literal">d</tt> toggle download info. Will show the block list for each torrent,
showing downloaded and requested blocks.</li>
<li><tt class="docutils literal"><span class="pre">p</span></tt> pause all torrents.</li>
<li><tt class="docutils literal"><span class="pre">u</span></tt> unpause all torrents.</li>
<li><tt class="docutils literal"><span class="pre">r</span></tt> force tracker reannounce for all torrents.</li>
<li><tt class="docutils literal"><span class="pre">f</span></tt> toggle show file progress. Displays a list of all files and the
<li><tt class="docutils literal">p</tt> pause all torrents.</li>
<li><tt class="docutils literal">u</tt> unpause all torrents.</li>
<li><tt class="docutils literal">r</tt> force tracker reannounce for all torrents.</li>
<li><tt class="docutils literal">f</tt> toggle show file progress. Displays a list of all files and the
download progress for each file.</li>
</ul>
<p>The list at the bottom (shown if you press <tt class="docutils literal"><span class="pre">d</span></tt>) shows which blocks has
<p>The list at the bottom (shown if you press <tt class="docutils literal">d</tt>) shows which blocks has
been requested from which peer. The green background means that it has been
downloaded. It shows that fast peers will prefer to request whole pieces
instead of dowloading parts of pieces. It may make it easier to determine

12
docs/contributing.html
View File

@ -3,7 +3,7 @@
<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.5: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.8.1: http://docutils.sourceforge.net/" />
<title>libtorrent manual</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
@ -49,7 +49,7 @@
<tr><th class="docinfo-name">Author:</th>
<td>Arvid Norberg, <a class="last reference external" href="mailto:arvid&#64;rasterbar.com">arvid&#64;rasterbar.com</a></td></tr>
<tr><th class="docinfo-name">Version:</th>
<td>0.16.0</td></tr>
<td>1.0.0</td></tr>
</tbody>
</table>
<div class="contents topic" id="table-of-contents">
@ -69,9 +69,9 @@ enumerated on this page, please contact <a class="reference external" href="mail
<dd><p class="first">This is not just limited to finding bugs and ways to reproduce crashes, but also
sub-optimal behavior is certain scenarios and finding ways to reproduce those. Please
report any issue to the bug tracker at <a class="reference external" href="http://code.google.com/p/libtorrent/issues/entry">google code</a>.</p>
<p class="last">New features that need testing are streaming (<tt class="docutils literal"><span class="pre">set_piece_deadline()</span></tt>), the different
<p class="last">New features that need testing are streaming (<tt class="docutils literal">set_piece_deadline()</tt>), the different
choking algorithms (especially the new BitTyrant choker), the disk cache options (such
as <tt class="docutils literal"><span class="pre">explicit_cache</span></tt>).</p>
as <tt class="docutils literal">explicit_cache</tt>).</p>
</dd>
</dl>
</li>
@ -90,13 +90,15 @@ descriptions on how to configure libtorrent for various situations for instance.
<dt>Code</dt>
<dd><p class="first">Contributing code for new features or bug-fixes is highly welcome. If you're interested
in adding a feature but not sure where to start, please contact the <a class="reference external" href="http://lists.sourceforge.net/lists/listinfo/libtorrent-discuss">mailing list</a> or
<tt class="docutils literal"><span class="pre">#libtorrent</span></tt> &#64; <tt class="docutils literal"><span class="pre">irc.freenode.net</span></tt>.</p>
<tt class="docutils literal">#libtorrent</tt> &#64; <tt class="docutils literal">irc.freenode.net</tt>.</p>
<p class="last">New features might be better support for integrating with other services, new choking
algorithms, seeding policies, ports to new platforms etc.</p>
</dd>
</dl>
</li>
</ol>
<p>For an overview of the internals of libtorrent, see the <a class="reference external" href="hacking.html">hacking</a> page.</p>
<p>For outstanding things to do, see the <a class="reference external" href="todo.html">todo list</a>.</p>
</div>
</div>
<div id="footer">

8
docs/contributing.rst
View File

@ -43,3 +43,11 @@ enumerated on this page, please contact arvid@rasterbar.com or the `mailing list
New features might be better support for integrating with other services, new choking
algorithms, seeding policies, ports to new platforms etc.
For an overview of the internals of libtorrent, see the hacking_ page.
For outstanding things to do, see the `todo list`_.
.. _hacking: hacking.html
.. _`todo list`: todo.html

22
docs/dht_extensions.html
View File

@ -3,7 +3,7 @@
<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.5: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.8.1: http://docutils.sourceforge.net/" />
<title></title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
@ -55,8 +55,8 @@
<p>libtorrent implements a few extensions to the Mainline DHT protocol.</p>
<div class="section" id="get-peers-response">
<h2>get_peers response</h2>
<p>libtorrent always responds with <tt class="docutils literal"><span class="pre">nodes</span></tt> to a get_peers request. If it has
peers for the specified info-hash, it will return <tt class="docutils literal"><span class="pre">values</span></tt> as well. This is
<p>libtorrent always responds with <tt class="docutils literal">nodes</tt> to a get_peers request. If it has
peers for the specified info-hash, it will return <tt class="docutils literal">values</tt> as well. This is
because just because some peer announced to us, doesn't mean that we are
among the 8 closest nodes of the info hash. libtorrent also keeps traversing
nodes using get_peers until it has found the 8 closest ones, and then announces
@ -65,7 +65,7 @@ to those nodes.</p>
<div class="section" id="forward-compatibility">
<h2>forward compatibility</h2>
<p>In order to support future DHT messages, any message which is not recognized
but has either an <tt class="docutils literal"><span class="pre">info_hash</span></tt> or <tt class="docutils literal"><span class="pre">target</span></tt> argument is interpreted as
but has either an <tt class="docutils literal">info_hash</tt> or <tt class="docutils literal">target</tt> argument is interpreted as
find node for that target. i.e. it returns nodes. This allows future messages
to be properly forwarded by clients that don't understand them instead of
being blocked.</p>
@ -85,16 +85,16 @@ as a binary number describing the client version.</p>
</colgroup>
<tbody valign="top">
<tr><td>uTorrent</td>
<td><tt class="docutils literal"><span class="pre">UT</span></tt></td>
<td><tt class="docutils literal">UT</tt></td>
</tr>
<tr><td>libtorrent</td>
<td><tt class="docutils literal"><span class="pre">LT</span></tt></td>
<td><tt class="docutils literal">LT</tt></td>
</tr>
<tr><td>MooPolice</td>
<td><tt class="docutils literal"><span class="pre">MP</span></tt></td>
<td><tt class="docutils literal">MP</tt></td>
</tr>
<tr><td>GetRight</td>
<td><tt class="docutils literal"><span class="pre">GR</span></tt></td>
<td><tt class="docutils literal">GR</tt></td>
</tr>
</tbody>
</table>
@ -102,12 +102,12 @@ as a binary number describing the client version.</p>
<div class="section" id="ipv6-support">
<h2>IPv6 support</h2>
<p><strong>This extension is superseeded by</strong> <a class="reference external" href="http://bittorrent.org/beps/bep_0032.html">BEP 32</a>.</p>
<p>The DHT messages that don't support IPv6 are the <tt class="docutils literal"><span class="pre">nodes</span></tt> replies.
<p>The DHT messages that don't support IPv6 are the <tt class="docutils literal">nodes</tt> replies.
They encode all the contacts as 6 bytes packed together in sequence in a
string. The problem is that IPv6 endpoints cannot be encoded as 6 bytes, but
needs 18 bytes. The extension libtorrent applies is to add another key, called
<tt class="docutils literal"><span class="pre">nodes2</span></tt>.</p>
<p><tt class="docutils literal"><span class="pre">nodes2</span></tt> may be present in replies that contains a <tt class="docutils literal"><span class="pre">nodes</span></tt> key. It is encoded
<tt class="docutils literal">nodes2</tt>.</p>
<p><tt class="docutils literal">nodes2</tt> may be present in replies that contains a <tt class="docutils literal">nodes</tt> key. It is encoded
as a list of strings. Each string represents one contact and is encoded as 20
bytes node-id and then a variable length encoded IP address (6 bytes in IPv4 case
and 18 bytes in IPv6 case).</p>

60
docs/dht_rss.html
View File

@ -3,7 +3,7 @@
<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.5: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.8.1: http://docutils.sourceforge.net/" />
<title>BitTorrent extension for DHT RSS feeds</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
@ -49,7 +49,7 @@
<tr><th class="docinfo-name">Author:</th>
<td>Arvid Norberg, <a class="last reference external" href="mailto:arvid&#64;rasterbar.com">arvid&#64;rasterbar.com</a></td></tr>
<tr><th class="docinfo-name">Version:</th>
<td>Draft</td></tr>
<td>1.0.0</td></tr>
</tbody>
</table>
<div class="contents topic" id="table-of-contents">
@ -92,7 +92,7 @@ key against the target ID it is stored under, as well as the validity of
the signatures of each individual item.</p>
<p>As with normal DHT announces, the write-token mechanism is used to
prevent IP spoof attacks.</p>
<p>There are two new proposed messages, <tt class="docutils literal"><span class="pre">announce_item</span></tt> and <tt class="docutils literal"><span class="pre">get_item</span></tt>.
<p>There are two new proposed messages, <tt class="docutils literal">announce_item</tt> and <tt class="docutils literal">get_item</tt>.
Every valid item that is announced, should be stored.</p>
<div class="section" id="terminology">
<h1>terminology</h1>
@ -122,31 +122,31 @@ key = SHA1(name + key)
| sig |
+---------+
</pre>
<p>The <tt class="docutils literal"><span class="pre">next</span></tt> pointer is at least 20 byte ID in the DHT key space pointing to where the next
<p>The <tt class="docutils literal">next</tt> pointer is at least 20 byte ID in the DHT key space pointing to where the next
item in the list is announced. The list is terminated with an ID of all zeroes.</p>
<p>The ID an items is announced to is determined by the SHA1 hash of the bencoded representation
of the item iteself. This contains all fields in the item, except the signature.
The only mandatory fields in an item are <tt class="docutils literal"><span class="pre">next</span></tt>, <tt class="docutils literal"><span class="pre">key</span></tt> and <tt class="docutils literal"><span class="pre">sig</span></tt>.</p>
<p>The <tt class="docutils literal"><span class="pre">key</span></tt> field MUST match the public key of the list head node. The <tt class="docutils literal"><span class="pre">sig</span></tt> field
MUST be the signature of the bencoded representation of <tt class="docutils literal"><span class="pre">item</span></tt> or <tt class="docutils literal"><span class="pre">head</span></tt> (whichever
The only mandatory fields in an item are <tt class="docutils literal">next</tt>, <tt class="docutils literal">key</tt> and <tt class="docutils literal">sig</tt>.</p>
<p>The <tt class="docutils literal">key</tt> field MUST match the public key of the list head node. The <tt class="docutils literal">sig</tt> field
MUST be the signature of the bencoded representation of <tt class="docutils literal">item</tt> or <tt class="docutils literal">head</tt> (whichever
is included in the message).</p>
<p>All subscribers MUST verify that the item is announced under the correct DHT key
and MUST verify the signature is valid and MUST verify the public key is the same
as the list-head. If a node fails any of these checks, it must be ignored and the
chain of items considered terminated.</p>
<p>Each item holds a bencoded dictionary with arbitrary keys, except two mandatory keys:
<tt class="docutils literal"><span class="pre">next</span></tt> and <tt class="docutils literal"><span class="pre">key</span></tt>. The signature <tt class="docutils literal"><span class="pre">sig</span></tt> is transferred outside of this dictionary
<tt class="docutils literal">next</tt> and <tt class="docutils literal">key</tt>. The signature <tt class="docutils literal">sig</tt> is transferred outside of this dictionary
and is the signature of all of it. An implementation should stora any arbitrary keys that
are announced to an item, within reasonable restriction such as nesting, size and numeric
range of integers.</p>
</div>
<div class="section" id="skip-lists">
<h1>skip lists</h1>
<p>The <tt class="docutils literal"><span class="pre">next</span></tt> key stored in the list head and the items is a string of at least length
<p>The <tt class="docutils literal">next</tt> key stored in the list head and the items is a string of at least length
20 bytes, it may be any length divisible by 20. Each 20 bytes are the ID of the next
item in the list, the item 2 hops away, 4 hops away, 8 hops away, and so on. For
simplicity, only the first ID (1 hop) in the <tt class="docutils literal"><span class="pre">next</span></tt> field is illustrated above.</p>
<p>A publisher of an item SHOULD include as many IDs in the <tt class="docutils literal"><span class="pre">next</span></tt> field as the remaining
simplicity, only the first ID (1 hop) in the <tt class="docutils literal">next</tt> field is illustrated above.</p>
<p>A publisher of an item SHOULD include as many IDs in the <tt class="docutils literal">next</tt> field as the remaining
size of the list warrants, within reason.</p>
<p>These skip lists allow for parallelized lookups of items and also makes it more efficient
to search for specific items. It also mitigates breaking lists missing some items.</p>
@ -158,7 +158,7 @@ n Item0 Item1 Item2 Item3 Item4 Item5 Item6 Item7 Item8 Item9 Ite
40 O--------------------------&gt;
60 O------------------------------------------------------&gt;
</pre>
<p><em>n</em> refers to the byte offset into the <tt class="docutils literal"><span class="pre">next</span></tt> field.</p>
<p><em>n</em> refers to the byte offset into the <tt class="docutils literal">next</tt> field.</p>
</div>
<div class="section" id="list-head">
<h1>list-head</h1>
@ -166,27 +166,27 @@ n Item0 Item1 Item2 Item3 Item4 Item5 Item6 Item7 Item8 Item9 Ite
DHT key. This is required to prepend new items to the linked list. To authenticate
that only the original publisher can update the head, the whole linked list head
is signed. In order to avoid a malicious node to overwrite the list head with an old
version, the sequence number <tt class="docutils literal"><span class="pre">seq</span></tt> must be monotonically increasing for each update,
version, the sequence number <tt class="docutils literal">seq</tt> must be monotonically increasing for each update,
and a node hosting the list node MUST not downgrade a list head from a higher sequence
number to a lower one, only upgrade.</p>
<p>The list head's DHT key (which it is announced to) MUST be the SHA1 hash of the name
(<tt class="docutils literal"><span class="pre">n</span></tt>) and <tt class="docutils literal"><span class="pre">key</span></tt> fields concatenated.</p>
(<tt class="docutils literal">n</tt>) and <tt class="docutils literal">key</tt> fields concatenated.</p>
<p>Any node MUST reject any list head which is announced under any other ID.</p>
</div>
<div class="section" id="messages">
<h1>messages</h1>
<p>These are the messages to deal with linked lists.</p>
<p>The <tt class="docutils literal"><span class="pre">id</span></tt> field in these messages has the same semantics as the standard DHT messages,
<p>The <tt class="docutils literal">id</tt> field in these messages has the same semantics as the standard DHT messages,
i.e. the node ID of the node sending the message, to maintain the structure of the DHT
network.</p>
<p>The <tt class="docutils literal"><span class="pre">token</span></tt> field also has the same semantics as the standard DHT message <tt class="docutils literal"><span class="pre">get_peers</span></tt>
and <tt class="docutils literal"><span class="pre">announce_peer</span></tt>, when requesting an item and to write an item respectively.</p>
<p><tt class="docutils literal"><span class="pre">nodes</span></tt> and <tt class="docutils literal"><span class="pre">nodes6</span></tt> has the same semantics as in its <tt class="docutils literal"><span class="pre">get_peers</span></tt> response.</p>
<p>The <tt class="docutils literal">token</tt> field also has the same semantics as the standard DHT message <tt class="docutils literal">get_peers</tt>
and <tt class="docutils literal">announce_peer</tt>, when requesting an item and to write an item respectively.</p>
<p><tt class="docutils literal">nodes</tt> and <tt class="docutils literal">nodes6</tt> has the same semantics as in its <tt class="docutils literal">get_peers</tt> response.</p>
<div class="section" id="requesting-items">
<h2>requesting items</h2>
<p>This message can be used to request both a list head and a list item. When requesting
a list head, the <tt class="docutils literal"><span class="pre">n</span></tt> (name) field MUST be specified. When requesting a list item the
<tt class="docutils literal"><span class="pre">n</span></tt> field is not required.</p>
a list head, the <tt class="docutils literal">n</tt> (name) field MUST be specified. When requesting a list item the
<tt class="docutils literal">n</tt> field is not required.</p>
<pre class="literal-block">
{
&quot;a&quot;:
@ -201,9 +201,9 @@ a list head, the <tt class="docutils literal"><span class="pre">n</span></tt> (n
&quot;y&quot;: &quot;q&quot;,
}
</pre>
<p>When requesting a list-head the <tt class="docutils literal"><span class="pre">target</span></tt> MUST always be SHA-1(<em>feed_name</em> + <em>public_key</em>).
<tt class="docutils literal"><span class="pre">target</span></tt> is the target node ID the item was written to.</p>
<p>The <tt class="docutils literal"><span class="pre">n</span></tt> field is the name of the list. If specified, It MUST be UTF-8 encoded string
<p>When requesting a list-head the <tt class="docutils literal">target</tt> MUST always be SHA-1(<em>feed_name</em> + <em>public_key</em>).
<tt class="docutils literal">target</tt> is the target node ID the item was written to.</p>
<p>The <tt class="docutils literal">n</tt> field is the name of the list. If specified, It MUST be UTF-8 encoded string
and it MUST match the name of the feed in the receiving node.</p>
</div>
<div class="section" id="request-item-response">
@ -251,10 +251,10 @@ and it MUST match the name of the feed in the receiving node.</p>
&quot;y&quot;: &quot;r&quot;,
}
</pre>
<p>A client receiving a <tt class="docutils literal"><span class="pre">get_item</span></tt> response MUST verify the signature in the <tt class="docutils literal"><span class="pre">sig</span></tt>
field against the bencoded representation of the <tt class="docutils literal"><span class="pre">item</span></tt> field, using the <tt class="docutils literal"><span class="pre">key</span></tt> as
the public key. The <tt class="docutils literal"><span class="pre">key</span></tt> MUST match the public key of the feed.</p>
<p>The <tt class="docutils literal"><span class="pre">item</span></tt> dictionary MAY contain arbitrary keys, and all keys MUST be stored for
<p>A client receiving a <tt class="docutils literal">get_item</tt> response MUST verify the signature in the <tt class="docutils literal">sig</tt>
field against the bencoded representation of the <tt class="docutils literal">item</tt> field, using the <tt class="docutils literal">key</tt> as
the public key. The <tt class="docutils literal">key</tt> MUST match the public key of the feed.</p>
<p>The <tt class="docutils literal">item</tt> dictionary MAY contain arbitrary keys, and all keys MUST be stored for
items.</p>
</div>
<div class="section" id="announcing-items">
@ -337,7 +337,7 @@ the storing node no longer is in the set of the 8 closest nodes.</p>
</div>
<div class="section" id="rss-feeds">
<h1>RSS feeds</h1>
<p>For RSS feeds, following keys are mandatory in the list item's <tt class="docutils literal"><span class="pre">item</span></tt> dictionary.</p>
<p>For RSS feeds, following keys are mandatory in the list item's <tt class="docutils literal">item</tt> dictionary.</p>
<dl class="docutils">
<dt>ih</dt>
<dd>The torrent's info hash</dd>
@ -348,7 +348,7 @@ the storing node no longer is in the set of the 8 closest nodes.</p>
</dl>
<div class="section" id="example">
<h2>example</h2>
<p>This is an example of an <tt class="docutils literal"><span class="pre">announce_item</span></tt> message:</p>
<p>This is an example of an <tt class="docutils literal">announce_item</tt> message:</p>
<pre class="literal-block">
{
&quot;a&quot;:
@ -374,7 +374,7 @@ the storing node no longer is in the set of the 8 closest nodes.</p>
}
</pre>
<p>Strings are printed in hex for printability, but actual encoding is binary.</p>
<p>Note that <tt class="docutils literal"><span class="pre">target</span></tt> is in fact SHA1 hash of the same data the signature <tt class="docutils literal"><span class="pre">sig</span></tt>
<p>Note that <tt class="docutils literal">target</tt> is in fact SHA1 hash of the same data the signature <tt class="docutils literal">sig</tt>
is the signature of, i.e.:</p>
<pre class="literal-block">
d9:info-hash20:7ea94c240691311dc0916a2a91eb7c3db2c6f3e43:key64:6bc1de5443d1

2
docs/dht_sec.html
View File

@ -49,7 +49,7 @@
<tr><th class="docinfo-name">Author:</th>
<td>Arvid Norberg, <a class="last reference external" href="mailto:arvid&#64;rasterbar.com">arvid&#64;rasterbar.com</a></td></tr>
<tr><th class="docinfo-name">Version:</th>
<td>Draft</td></tr>
<td>1.0.0</td></tr>
</tbody>
</table>
<div class="contents topic" id="table-of-contents">

14
docs/dht_store.html
View File

@ -3,7 +3,7 @@
<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.9.1: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.8.1: http://docutils.sourceforge.net/" />
<title>BitTorrent extension for arbitrary DHT store</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
@ -49,7 +49,7 @@
<tr><th class="docinfo-name">Author:</th>
<td>Arvid Norberg, <a class="last reference external" href="mailto:arvid&#64;rasterbar.com">arvid&#64;rasterbar.com</a></td></tr>
<tr><th class="docinfo-name">Version:</th>
<td>Draft</td></tr>
<td>1.0.0</td></tr>
</tbody>
</table>
<div class="contents topic" id="table-of-contents">
@ -109,7 +109,9 @@ hash table internally, or in separate ones and potentially do two lookups for <t
requests.</p>
<p>The <tt class="docutils literal">v</tt> field is the <em>value</em> to be stored. It is allowed to be any bencoded type (list,
dict, string or integer). When it's being hashed (for verifying its signature or to calculate
its key), its flattened, bencoded, form is used.</p>
its key), its flattened, bencoded, form is used. It is important to use the exact
bencoded representation as it appeared in the message. decoding and then re-encoding
bencoded structures is not necessarily an identity operation.</p>
<p>Storing nodes SHOULD reject <tt class="docutils literal">put</tt> requests where the bencoded form of <tt class="docutils literal">v</tt> is longer
than 767 bytes.</p>
</div>
@ -117,6 +119,8 @@ than 767 bytes.</p>
<h1>immutable items</h1>
<p>Immutable items are stored under their SHA-1 hash, and since they cannot be modified,
there is no need to authenticate the origin of them. This makes immutable items simple.</p>
<p>A node making a lookup SHOULD verify the data it receives from the network, to verify
that its hash matches the target that was looked up.</p>
<div class="section" id="put-message">
<h2>put message</h2>
<p>Request:</p>
@ -182,7 +186,9 @@ is the SHA-1 hash of the public key (as it appears in the <tt class="docutils li
<p>In order to avoid a malicious node to overwrite the list head with an old
version, the sequence number <tt class="docutils literal">seq</tt> must be monotonically increasing for each update,
and a node hosting the list node MUST not downgrade a list head from a higher sequence
number to a lower one, only upgrade.</p>
number to a lower one, only upgrade. The sequence number SHOULD not exceed <tt class="docutils literal">MAX_INT64</tt>,
(i.e. <tt class="docutils literal">0x7fffffffffffffff</tt>. A client MAY reject any message with a sequence number
exceeding this.</p>
<p>The signature is a 2048 bit RSA signature of the SHA-1 hash of the bencoded sequence
number and <tt class="docutils literal">v</tt> key. e.g. something like this:: <tt class="docutils literal">3:seqi4e1:v12:Hello world!</tt>.</p>
<div class="section" id="id1">

6
docs/examples.html
View File

@ -3,7 +3,7 @@
<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.5: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.8.1: http://docutils.sourceforge.net/" />
<title>libtorrent Examples</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
@ -64,9 +64,9 @@
<div class="section" id="examples">
<h1>examples</h1>
<p>Except for the example programs in this manual, there's also a bigger example
of a (little bit) more complete client, <tt class="docutils literal"><span class="pre">client_test</span></tt>. There are separate
of a (little bit) more complete client, <tt class="docutils literal">client_test</tt>. There are separate
instructions for how to use it <a class="reference external" href="client_test.html">here</a> if you'd like to try it. Note that building
<tt class="docutils literal"><span class="pre">client_test</span></tt> also requires boost.regex and boost.program_options library.</p>
<tt class="docutils literal">client_test</tt> also requires boost.regex and boost.program_options library.</p>
<div class="section" id="dump-torrent">
<h2>dump_torrent</h2>
<p>This is an example of a program that will take a torrent-file as a parameter and

36
docs/extension_protocol.html
View File

@ -3,7 +3,7 @@
<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.5: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.8.1: http://docutils.sourceforge.net/" />
<title></title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com Ludvig Strigeus, ludde&#64;utorrent.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
@ -76,7 +76,7 @@ support 1 new message:</p>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="docutils literal"><span class="pre">extended</span></tt></td>
<tr><td><tt class="docutils literal">extended</tt></td>
<td>20</td>
</tr>
</tbody>
@ -86,7 +86,7 @@ prefix and a single byte identifying the message (the single byte being 20
in this case). At the start of the payload of the message, is a single byte
message identifier. This identifier can refer to different extension messages
and only one ID is specified, 0. If the ID is 0, the message is a handshake
message which is described below. The layout of a general <tt class="docutils literal"><span class="pre">extended</span></tt> message
message which is described below. The layout of a general <tt class="docutils literal">extended</tt> message
follows (including the message headers used by the bittorrent protocol):</p>
<table border="1" class="docutils">
<colgroup>
@ -206,7 +206,7 @@ imaginable.</p>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="docutils literal"><span class="pre">m</span></tt></td>
<tr><td><tt class="docutils literal">m</tt></td>
<td><table border="1" class="first last docutils">
<colgroup>
<col width="88%" />
@ -217,26 +217,26 @@ imaginable.</p>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="docutils literal"><span class="pre">LT_metadata</span></tt></td>
<tr><td><tt class="docutils literal">LT_metadata</tt></td>
<td>1</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">ut_pex</span></tt></td>
<tr><td><tt class="docutils literal">ut_pex</tt></td>
<td>2</td>
</tr>
</tbody>
</table>
</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">p</span></tt></td>
<tr><td><tt class="docutils literal">p</tt></td>
<td>6881</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">v</span></tt></td>
<td>&quot;µTorrent 1.2&quot;</td>
<tr><td><tt class="docutils literal">v</tt></td>
<td>&quot;uTorrent 1.2&quot;</td>
</tr>
</tbody>
</table>
<p>and in the encoded form:</p>
<p><tt class="docutils literal"><span class="pre">d1:md11:LT_metadatai1e6:µT_PEXi2ee1:pi6881e1:v13:\xc2\xb5Torrent</span> <span class="pre">1.2e</span></tt></p>
<p><tt class="docutils literal">d1:md11:LT_metadatai1e6:ut_pexi2ee1:pi6881e1:v12:uTorrent 1.2e</tt></p>
<p>To make sure the extension names do not collide by mistake, they should be
prefixed with the two (or one) character code that is used to identify the
client that introduced the extension. This applies for both the names of
@ -250,18 +250,18 @@ the sending client should not be disconnected. An implementation may choose
to ignore the subsequent handshake messages (or parts of them).</p>
<p>Subsequent handshake messages can be used to enable/disable extensions
without restarting the connection. If a peer supports changing extensions
at run time, it should note that the <tt class="docutils literal"><span class="pre">m</span></tt> dictionary is additive.
at run time, it should note that the <tt class="docutils literal">m</tt> dictionary is additive.
It's enough that it contains the actual <em>CHANGES</em> to the extension list.
To disable the support for <tt class="docutils literal"><span class="pre">LT_metadata</span></tt> at run-time, without affecting
To disable the support for <tt class="docutils literal">LT_metadata</tt> at run-time, without affecting
any other extensions, this message should be sent:
<tt class="docutils literal"><span class="pre">d11:LT_metadatai0ee</span></tt>.
<tt class="docutils literal">d11:LT_metadatai0ee</tt>.
As specified above, the value 0 is used to turn off an extension.</p>
<p>The extension IDs must be stored for every peer, becuase every peer may have
different IDs for the same extension.</p>
<p>This specification, deliberately, does not specify any extensions such as
peer-exchange or metadata exchange. This protocol is merely a transport
for the actual extensions to the bittorrent protocol and the extensions
named in the example above (such as <tt class="docutils literal"><span class="pre">p</span></tt>) are just examples of possible
named in the example above (such as <tt class="docutils literal">p</tt>) are just examples of possible
extensions.</p>
</div>
<div class="section" id="rationale">
@ -271,17 +271,17 @@ is to avoid having a global registry of message IDs. Instead the names of the
extension messages requires unique names, which is much easier to do without
a global registry. The convention is to use a two letter prefix on the
extension message names, the prefix would identify the client first
implementing the extension message. e.g. <tt class="docutils literal"><span class="pre">LT_metadata</span></tt> is implemented by
libtorrent, and hence it has the <tt class="docutils literal"><span class="pre">LT</span></tt> prefix.</p>
implementing the extension message. e.g. <tt class="docutils literal">LT_metadata</tt> is implemented by
libtorrent, and hence it has the <tt class="docutils literal">LT</tt> prefix.</p>
<p>If the client supporting the extensions can decide which numbers the messages
it receives will have, it means they are constants within that client. i.e.
they can be used in <tt class="docutils literal"><span class="pre">switch</span></tt> statements. It's easy for the other end to
they can be used in <tt class="docutils literal">switch</tt> statements. It's easy for the other end to
store an array with the ID's we expect for each message and use that for
lookups each time it sends an extension message.</p>
<p>The reason for having a dictionary instead of having an array (using
implicitly assigned index numbers to the extensions) is that if a client
want to disable some extensions, the ID numbers would change, and it wouldn't
be able to use constants (and hence, not use them in a <tt class="docutils literal"><span class="pre">switch</span></tt>). If the
be able to use constants (and hence, not use them in a <tt class="docutils literal">switch</tt>). If the
messages IDs would map directly to bittorrent message IDs, It would also make
it possible to map extensions in the handshake to existing extensions with
fixed message IDs.</p>

16
docs/features.html
View File

@ -3,7 +3,7 @@
<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.5: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.8.1: http://docutils.sourceforge.net/" />
<title>libtorrent manual</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
@ -49,7 +49,7 @@
<tr><th class="docinfo-name">Author:</th>
<td>Arvid Norberg, <a class="last reference external" href="mailto:arvid&#64;rasterbar.com">arvid&#64;rasterbar.com</a></td></tr>
<tr><th class="docinfo-name">Version:</th>
<td>0.16.0</td></tr>
<td>1.0.0</td></tr>
</tbody>
</table>
<div class="contents topic" id="table-of-contents">
@ -105,8 +105,8 @@ uTorrent interpretation).</li>
<li>supports lt_trackers extension, to exchange trackers between peers</li>
<li><a class="reference external" href="manual.html#http-seeding">HTTP seeding</a>, as specified in <a class="reference external" href="http://bittorrent.org/beps/bep_0017.html">BEP 17</a> and <a class="reference external" href="http://bittorrent.org/beps/bep_0019.html">BEP 19</a>.</li>
<li>supports the udp-tracker protocol. (<a class="reference external" href="http://bittorrent.org/beps/bep_0015.html">BEP 15</a>).</li>
<li>supports the <tt class="docutils literal"><span class="pre">no_peer_id=1</span></tt> extension that will ease the load off trackers.</li>
<li>supports the <tt class="docutils literal"><span class="pre">compact=1</span></tt> tracker parameter.</li>
<li>supports the <tt class="docutils literal">no_peer_id=1</tt> extension that will ease the load off trackers.</li>
<li>supports the <tt class="docutils literal">compact=1</tt> tracker parameter.</li>
<li>super seeding/initial seeding (<a class="reference external" href="http://bittorrent.org/beps/bep_0016.html">BEP 16</a>).</li>
<li>private torrents (<a class="reference external" href="http://bittorrent.org/beps/bep_0027.html">BEP 27</a>).</li>
<li>upload-only extension (<a class="reference external" href="http://bittorrent.org/beps/bep_0021.html">BEP 21</a>).</li>
@ -239,14 +239,14 @@ to keep copying to a minimum on such machines. This mostly applies to embedded s
for payload data is received directly into a page aligned disk buffer. If the connection
is encrypted, the buffer is decrypted in-place. The buffer is then moved into the disk
cache without being copied. Once all the blocks for a piece have been received, or the
cache needs to be flushed, all the blocks are passed directly to <tt class="docutils literal"><span class="pre">writev()</span></tt> to flush
cache needs to be flushed, all the blocks are passed directly to <tt class="docutils literal">writev()</tt> to flush
them in a single syscall. This means a single copy into user space memory, and a single
copy back into kernel memory, as illustrated by this figure:</p>
<img alt="write_disk_buffers.png" src="write_disk_buffers.png" style="width: 100%;" />
<p>When seeding and uploading in general, unnecessary copying is avoided by caching blocks
in aligned buffers, that are copied once into the peer's send buffer. The peer's send buffer
is not guaranteed to be aligned, even though it is most of the time. The send buffer is
then encrypted with the peer specific key and chained onto the <tt class="docutils literal"><span class="pre">iovec</span></tt> for sending.
then encrypted with the peer specific key and chained onto the <tt class="docutils literal">iovec</tt> for sending.
This means there is one user space copy in order to allow unaligned peer requests and
peer-specific encryption. This is illustrated by the following figure:</p>
<img alt="read_disk_buffers.png" src="read_disk_buffers.png" style="width: 100%;" />
@ -305,7 +305,7 @@ peers.</p>
<img alt="merkle_tree.png" src="merkle_tree.png" />
<p>The root hash is built by hashing all the piece hashes pair-wise, until they all collapse
down to the root.</p>
<img align="right" alt="storage.png" class="align-right" src="storage.png" />
<img alt="storage.png" class="align-right" src="storage.png" />
</div>
<div class="section" id="customizable-file-storage">
<h2>customizable file storage</h2>
@ -313,7 +313,7 @@ down to the root.</p>
client can replace the default way to store files on disk.</p>
<p>When implementing a bittorrent cache, it doesn't matter how the data is stored on disk, as
long as it can be retrieved and seeded. In that case a new storage class can be implemented
(inheriting from the <tt class="docutils literal"><span class="pre">storage_interface</span></tt> class) that avoids the unnecessary step of mapping
(inheriting from the <tt class="docutils literal">storage_interface</tt> class) that avoids the unnecessary step of mapping
slots to files and offsets. The storage can ignore the file boundaries and just store the
entire torrent in a single file (which will end up being all the files concatenated). The main
advantage of this, other than a slight cpu performance gain, is that all file operations would

4
docs/index.html
View File

@ -3,7 +3,7 @@
<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.5: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.8.1: http://docutils.sourceforge.net/" />
<title></title>
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
<link rel="stylesheet" type="text/css" href="../../css/rst.css" />
@ -106,7 +106,7 @@ the library.</p>
<div class="section" id="feedback">
<h2>Feedback</h2>
<p>There's a <a class="reference external" href="http://lists.sourceforge.net/lists/listinfo/libtorrent-discuss">mailing list</a>, general libtorrent discussion.</p>
<p>You can usually find me as hydri in <tt class="docutils literal"><span class="pre">#libtorrent</span></tt> on <tt class="docutils literal"><span class="pre">irc.freenode.net</span></tt>.</p>
<p>You can usually find me as hydri in <tt class="docutils literal">#libtorrent</tt> on <tt class="docutils literal">irc.freenode.net</tt>.</p>
</div>
<div class="section" id="license">
<h2>license</h2>

66
docs/libtorrent_plugins.html
View File

@ -3,7 +3,7 @@
<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.5: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.8.1: http://docutils.sourceforge.net/" />
<title></title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
@ -103,7 +103,7 @@ also need to have a mutex on your own shared data within the plugin, to make
sure it is not accessed at the same time from the libtorrent thread (through a
callback). See <a class="reference external" href="http://www.boost.org/doc/html/mutex.html">boost thread's mutex</a>. If you need to send out a message from
another thread, it is advised to use an internal queue, and do the actual
sending in <tt class="docutils literal"><span class="pre">tick()</span></tt>.</p>
sending in <tt class="docutils literal">tick()</tt>.</p>
<p>Since the plugin interface gives you easy access to internal structures, it
is not supported as a stable API. Plugins should be considered spcific to a
specific version of libtorrent. Although, in practice the internals mostly
@ -113,12 +113,12 @@ don't change that dramatically.</p>
<div class="section" id="plugin-interface">
<h1>plugin interface</h1>
<p>The plugin interface consists of three base classes that the plugin may
implement. These are called <tt class="docutils literal"><span class="pre">plugin</span></tt>, <tt class="docutils literal"><span class="pre">torrent_plugin</span></tt> and <tt class="docutils literal"><span class="pre">peer_plugin</span></tt>.
They are found in the <tt class="docutils literal"><span class="pre">&lt;libtorrent/extensions.hpp&gt;</span></tt> header.</p>
implement. These are called <tt class="docutils literal">plugin</tt>, <tt class="docutils literal">torrent_plugin</tt> and <tt class="docutils literal">peer_plugin</tt>.
They are found in the <tt class="docutils literal">&lt;libtorrent/extensions.hpp&gt;</tt> header.</p>
<p>These plugins are instantiated for each session, torrent and possibly each peer,
respectively.</p>
<p>For plugins that only need per torrent state, it is enough to only implement
<tt class="docutils literal"><span class="pre">torrent_plugin</span></tt> and pass a constructor function or function object to
<tt class="docutils literal">torrent_plugin</tt> and pass a constructor function or function object to
<tt class="docutils literal"><span class="pre">session::add_extension()</span></tt> or <tt class="docutils literal"><span class="pre">torrent_handle::add_extension()</span></tt> (if the
torrent has already been started and you want to hook in the extension at
run-time).</p>
@ -132,10 +132,10 @@ is the userdata passed to <tt class="docutils literal"><span class="pre">session
<p>The function should return a <tt class="docutils literal"><span class="pre">boost::shared_ptr&lt;torrent_plugin&gt;</span></tt> which
may or may not be 0. If it is a null pointer, the extension is simply ignored
for this torrent. If it is a valid pointer (to a class inheriting
<tt class="docutils literal"><span class="pre">torrent_plugin</span></tt>), it will be associated with this torrent and callbacks
<tt class="docutils literal">torrent_plugin</tt>), it will be associated with this torrent and callbacks
will be made on torrent events.</p>
<p>For more elaborate plugins which require session wide state, you would
implement <tt class="docutils literal"><span class="pre">plugin</span></tt>, construct an object (in a <tt class="docutils literal"><span class="pre">boost::shared_ptr</span></tt>) and pass
implement <tt class="docutils literal">plugin</tt>, construct an object (in a <tt class="docutils literal"><span class="pre">boost::shared_ptr</span></tt>) and pass
it in to <tt class="docutils literal"><span class="pre">session::add_extension()</span></tt>.</p>
</div>
<div class="section" id="plugin">
@ -156,7 +156,7 @@ struct plugin
</div>
<div class="section" id="torrent-plugin">
<h1>torrent_plugin</h1>
<p>The synopsis for <tt class="docutils literal"><span class="pre">torrent_plugin</span></tt> follows:</p>
<p>The synopsis for <tt class="docutils literal">torrent_plugin</tt> follows:</p>
<pre class="literal-block">
struct torrent_plugin
{
@ -194,15 +194,15 @@ boost::shared_ptr&lt;peer_plugin&gt; new_connection(peer_connection*);
</pre>
<p>This function is called each time a new peer is connected to the torrent. You
may choose to ignore this by just returning a default constructed
<tt class="docutils literal"><span class="pre">shared_ptr</span></tt> (in which case you don't need to override this member
<tt class="docutils literal">shared_ptr</tt> (in which case you don't need to override this member
function).</p>
<p>If you need an extension to the peer connection (which most plugins do) you
are supposed to return an instance of your <tt class="docutils literal"><span class="pre">peer_plugin</span></tt> class. Which in
are supposed to return an instance of your <tt class="docutils literal">peer_plugin</tt> class. Which in
turn will have its hook functions called on event specific to that peer.</p>
<p>The <tt class="docutils literal"><span class="pre">peer_connection</span></tt> will be valid as long as the <tt class="docutils literal"><span class="pre">shared_ptr</span></tt> is being
<p>The <tt class="docutils literal">peer_connection</tt> will be valid as long as the <tt class="docutils literal">shared_ptr</tt> is being
held by the torrent object. So, it is generally a good idea to not keep a
<tt class="docutils literal"><span class="pre">shared_ptr</span></tt> to your own peer_plugin. If you want to keep references to it,
use <tt class="docutils literal"><span class="pre">weak_ptr</span></tt>.</p>
<tt class="docutils literal">shared_ptr</tt> to your own peer_plugin. If you want to keep references to it,
use <tt class="docutils literal">weak_ptr</tt>.</p>
<p>If this function throws an exception, the connection will be closed.</p>
</div>
<div class="section" id="on-piece-pass-on-piece-fail">
@ -212,9 +212,9 @@ void on_piece_pass(int index);
void on_piece_failed(int index);
</pre>
<p>These hooks are called when a piece passes the hash check or fails the hash
check, respectively. The <tt class="docutils literal"><span class="pre">index</span></tt> is the piece index that was downloaded.
check, respectively. The <tt class="docutils literal">index</tt> is the piece index that was downloaded.
It is possible to access the list of peers that participated in sending the
piece through the <tt class="docutils literal"><span class="pre">torrent</span></tt> and the <tt class="docutils literal"><span class="pre">piece_picker</span></tt>.</p>
piece through the <tt class="docutils literal">torrent</tt> and the <tt class="docutils literal">piece_picker</tt>.</p>
</div>
<div class="section" id="tick">
<h2>tick()</h2>
@ -232,11 +232,11 @@ bool on_resume();
</pre>
<p>These hooks are called when the torrent is paused and unpaused respectively.
The return value indicates if the event was handled. A return value of
<tt class="docutils literal"><span class="pre">true</span></tt> indicates that it was handled, and no other plugin after this one
<tt class="docutils literal">true</tt> indicates that it was handled, and no other plugin after this one
will have this hook function called, and the standard handler will also not be
invoked. So, returning true effectively overrides the standard behavior of
pause or unpause.</p>
<p>Note that if you call <tt class="docutils literal"><span class="pre">pause()</span></tt> or <tt class="docutils literal"><span class="pre">resume()</span></tt> on the torrent from your
<p>Note that if you call <tt class="docutils literal">pause()</tt> or <tt class="docutils literal">resume()</tt> on the torrent from your
handler it will recurse back into your handler, so in order to invoke the
standard handler, you have to keep your own state on whether you want standard
behavior or overridden behavior.</p>
@ -264,7 +264,7 @@ virtual void on_add_peer(tcp::endpoint const&amp; ip
</pre>
<p>This function is called whenever we hear about a peer from any peer source,
such as the tracker, PEX, DHT or Local peer discovery.</p>
<p><tt class="docutils literal"><span class="pre">src</span></tt> is a bitmask of <tt class="docutils literal"><span class="pre">peer_info::peer_source_flags</span></tt>:</p>
<p><tt class="docutils literal">src</tt> is a bitmask of <tt class="docutils literal"><span class="pre">peer_info::peer_source_flags</span></tt>:</p>
<pre class="literal-block">
enum peer_source_flags
{
@ -276,14 +276,14 @@ enum peer_source_flags
incoming = 0x20
};
</pre>
<p><tt class="docutils literal"><span class="pre">flags</span></tt> is a bitmask of:</p>
<p><tt class="docutils literal">flags</tt> is a bitmask of:</p>
<pre class="literal-block">
enum flags_t {
first_time = 1,
filtered = 2
};
</pre>
<p>If the <tt class="docutils literal"><span class="pre">filtered</span></tt> flag is set, it means the peer wasn't added to the
<p>If the <tt class="docutils literal">filtered</tt> flag is set, it means the peer wasn't added to the
peer list because of and IP filter, port filter, reserved ports filter.</p>
</div>
</div>
@ -336,18 +336,18 @@ struct disk_buffer_holder
char* buffer();
};
</pre>
<p>The disk buffer holder acts like a <tt class="docutils literal"><span class="pre">scoped_ptr</span></tt> that frees a disk buffer
when it's destructed, unless it's released. <tt class="docutils literal"><span class="pre">release</span></tt> returns the disk
<p>The disk buffer holder acts like a <tt class="docutils literal">scoped_ptr</tt> that frees a disk buffer
when it's destructed, unless it's released. <tt class="docutils literal">release</tt> returns the disk
buffer and transferres ownership and responsibility to free it to the caller.</p>
<p>A disk buffer is freed by passing it to <tt class="docutils literal"><span class="pre">session_impl::free_disk_buffer()</span></tt>.</p>
<p><tt class="docutils literal"><span class="pre">buffer()</span></tt> returns the pointer without transferring responsibility. If
this buffer has been released, <tt class="docutils literal"><span class="pre">buffer()</span></tt> will return 0.</p>
<p><tt class="docutils literal">buffer()</tt> returns the pointer without transferring responsibility. If
this buffer has been released, <tt class="docutils literal">buffer()</tt> will return 0.</p>
</div>
<div class="section" id="custom-alerts">
<h1>custom alerts</h1>
<p>Since plugins are running within internal libtorrent threads, one convenient
way to communicate with the client is to post custom alerts.</p>
<p>The expected interface of any alert, apart from deriving from the <tt class="docutils literal"><span class="pre">alert</span></tt>
<p>The expected interface of any alert, apart from deriving from the <tt class="docutils literal">alert</tt>
base class, looks like this:</p>
<pre class="literal-block">
const static int alert_type = <em>&lt;unique alert ID&gt;</em>;
@ -363,19 +363,19 @@ virtual int category() const { return static_category; }
virtual char const* what() const { return <em>&lt;string literal of the name of this alert&gt;</em>; }
</pre>
<p>The <tt class="docutils literal"><span class="pre">alert_type</span></tt> is used for the type-checking in <tt class="docutils literal"><span class="pre">alert_cast</span></tt>. It must not collide with
<p>The <tt class="docutils literal">alert_type</tt> is used for the type-checking in <tt class="docutils literal">alert_cast</tt>. It must not collide with
any other alert. The built-in alerts in libtorrent will not use alert type IDs greater than
<tt class="docutils literal"><span class="pre">user_alert_id</span></tt>. When defining your own alert, make sure it's greater than this constant.</p>
<p><tt class="docutils literal"><span class="pre">type()</span></tt> is the run-time equivalence of the <tt class="docutils literal"><span class="pre">alert_type</span></tt>.</p>
<p>The <tt class="docutils literal"><span class="pre">message()</span></tt> virtual function is expected to construct a useful string representation
<tt class="docutils literal">user_alert_id</tt>. When defining your own alert, make sure it's greater than this constant.</p>
<p><tt class="docutils literal">type()</tt> is the run-time equivalence of the <tt class="docutils literal">alert_type</tt>.</p>
<p>The <tt class="docutils literal">message()</tt> virtual function is expected to construct a useful string representation
of the alert and the event or data it represents. Something convenient to put in a log file
for instance.</p>
<p><tt class="docutils literal"><span class="pre">clone()</span></tt> is used internally to copy alerts. The suggested implementation of simply
allocating a new instance as a copy of <tt class="docutils literal"><span class="pre">*this</span></tt> is all that's expected.</p>
<p><tt class="docutils literal">clone()</tt> is used internally to copy alerts. The suggested implementation of simply
allocating a new instance as a copy of <tt class="docutils literal">*this</tt> is all that's expected.</p>
<p>The static category is required for checking wether or not the category for a specific alert
is enabled or not, without instantiating the alert. The <tt class="docutils literal"><span class="pre">category</span></tt> virtual function is
is enabled or not, without instantiating the alert. The <tt class="docutils literal">category</tt> virtual function is
the run-time equivalence.</p>
<p>The <tt class="docutils literal"><span class="pre">what()</span></tt> virtual function may simply be a string literal of the class name of
<p>The <tt class="docutils literal">what()</tt> virtual function may simply be a string literal of the class name of
your alert.</p>
<p>For more information, see the alert section in the <a class="reference external" href="manual.html">main manual</a>.</p>
</div>

118
docs/make_torrent.html
View File

@ -3,7 +3,7 @@
<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.5: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.8.1: http://docutils.sourceforge.net/" />
<title>creating torrents</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
@ -49,7 +49,7 @@
<tr><th class="docinfo-name">Author:</th>
<td>Arvid Norberg, <a class="last reference external" href="mailto:arvid&#64;rasterbar.com">arvid&#64;rasterbar.com</a></td></tr>
<tr><th class="docinfo-name">Version:</th>
<td>0.16.0</td></tr>
<td>1.0.0</td></tr>
</tbody>
</table>
<div class="contents topic" id="table-of-contents">
@ -61,7 +61,7 @@
<li><a class="reference internal" href="#set-piece-hashes" id="id5">set_piece_hashes()</a></li>
<li><a class="reference internal" href="#file-storage" id="id6">file_storage</a><ul>
<li><a class="reference internal" href="#add-file" id="id7">add_file()</a></li>
<li><a class="reference internal" href="#hash-symlink-mtime-file-index" id="id8">hash() symlink() mtime() file_index()</a></li>
<li><a class="reference internal" href="#hash-symlink-mtime-file-path-file-size-pad-file-at" id="id8">hash() symlink() mtime() file_path() file_size() pad_file_at()</a></li>
<li><a class="reference internal" href="#file-base-set-file-base" id="id9">file_base() set_file_base()</a></li>
</ul>
</li>
@ -101,7 +101,7 @@ traverse, step one can be time consuming.</p>
<p>Typically step 3 is by far the most time consuming step, since it
requires to read all the bytes from all the files in the torrent.</p>
<p>All of these classes and functions are declared by including
<tt class="docutils literal"><span class="pre">libtorrent/create_torrent.hpp</span></tt>.</p>
<tt class="docutils literal">libtorrent/create_torrent.hpp</tt>.</p>
</div>
<div class="section" id="high-level-example">
<h1>high level example</h1>
@ -139,11 +139,11 @@ void add_files(file_storage&amp; fs, std::wstring const&amp; path
, boost::uint32_t flags = 0);
</pre>
</blockquote>
<p>Adds the file specified by <tt class="docutils literal"><span class="pre">path</span></tt> to the <tt class="docutils literal"><span class="pre">file_storage</span></tt> object. In case <tt class="docutils literal"><span class="pre">path</span></tt>
<p>Adds the file specified by <tt class="docutils literal">path</tt> to the <tt class="docutils literal">file_storage</tt> object. In case <tt class="docutils literal">path</tt>
refers to a diretory, files will be added recursively from the directory.</p>
<p>If specified, the predicate <tt class="docutils literal"><span class="pre">p</span></tt> is called once for every file and directory that
is encountered. files for which <tt class="docutils literal"><span class="pre">p</span></tt> returns true are added, and directories for
which <tt class="docutils literal"><span class="pre">p</span></tt> returns true are traversed. <tt class="docutils literal"><span class="pre">p</span></tt> must have the following signature:</p>
<p>If specified, the predicate <tt class="docutils literal">p</tt> is called once for every file and directory that
is encountered. files for which <tt class="docutils literal">p</tt> returns true are added, and directories for
which <tt class="docutils literal">p</tt> returns true are traversed. <tt class="docutils literal">p</tt> must have the following signature:</p>
<pre class="literal-block">
bool Pred(std::string const&amp; p);
</pre>
@ -155,7 +155,7 @@ bool Pred(std::wstring const&amp; p);
directory. If no predicate is specified, all files are added, and all directories
are traveresed.</p>
<p>The &quot;..&quot; directory is never traversed.</p>
<p>The <tt class="docutils literal"><span class="pre">flags</span></tt> argument should be the same as the flags passed to the <a class="reference internal" href="#create-torrent">create_torrent</a>
<p>The <tt class="docutils literal">flags</tt> argument should be the same as the flags passed to the <a class="reference internal" href="#create-torrent">create_torrent</a>
constructor.</p>
</div>
<div class="section" id="set-piece-hashes">
@ -182,18 +182,18 @@ void set_piece_hashes(create_torrent&amp; t, std::wstring const&amp; p
</pre>
</blockquote>
<p>This function will assume that the files added to the torrent file exists at path
<tt class="docutils literal"><span class="pre">p</span></tt>, read those files and hash the content and set the hashes in the <tt class="docutils literal"><span class="pre">create_torrent</span></tt>
object. The optional function <tt class="docutils literal"><span class="pre">f</span></tt> is called in between every hash that is set. <tt class="docutils literal"><span class="pre">f</span></tt>
<tt class="docutils literal">p</tt>, read those files and hash the content and set the hashes in the <tt class="docutils literal">create_torrent</tt>
object. The optional function <tt class="docutils literal">f</tt> is called in between every hash that is set. <tt class="docutils literal">f</tt>
must have the following signature:</p>
<pre class="literal-block">
void Fun(int);
</pre>
<p>The overloads that don't take an <tt class="docutils literal"><span class="pre">error_code&amp;</span></tt> may throw an exception in case of a
<p>The overloads that don't take an <tt class="docutils literal">error_code&amp;</tt> may throw an exception in case of a
file error, the other overloads sets the error code to reflect the error, if any.</p>
</div>
<div class="section" id="file-storage">
<h1>file_storage</h1>
<p>The <tt class="docutils literal"><span class="pre">file_storage</span></tt> class represents a file list and the piece
<p>The <tt class="docutils literal">file_storage</tt> class represents a file list and the piece
size. Everything necessary to interpret a regular bittorrent storage
file structure. Its synopsis:</p>
<pre class="literal-block">
@ -238,12 +238,30 @@ public:
int piece_length() const;
int piece_size(int index) const;
// index accessors
sha1_hash const&amp; hash(int index) const;
std::string const&amp; symlink(int index) const;
time_t mtime(int index) const;
int file_index(int index) const;
size_type file_base(int index) const;
void set_file_base(int index, size_type off);
std::string file_path(int index) const;
std::string file_name(int index) const;
size_type file_size(int index) const;
bool pad_file_at(int index) const;
size_type file_offset(int index) const;
// iterator accessors
sha1_hash hash(internal_file_entry const&amp; fe) const;
std::string const&amp; symlink(internal_file_entry const&amp; fe) const;
time_t mtime(internal_file_entry const&amp; fe) const;
int file_index(internal_file_entry const&amp; fe) const;
size_type file_base(internal_file_entry const&amp; fe) const;
void set_file_base(internal_file_entry const&amp; fe, size_type off);
std::string file_path(internal_file_entry const&amp; fe) const;
std::string file_name(internal_file_entry const&amp; fe) const;
size_type file_size(internal_file_entry const&amp; fe) const;
bool pad_file_at(internal_file_entry const&amp; fe) const;
size_type file_offset(internal_file_entry const&amp; fe) const;
void set_name(std::string const&amp; n);
void set_name(std::wstring const&amp; n);
@ -261,7 +279,7 @@ void add_file(std::string const&amp; p, size_type size, int flags = 0);
void add_file(std::wstring const&amp; p, size_type size, int flags = 0);
</pre>
</blockquote>
<p>Adds a file to the file storage. The <tt class="docutils literal"><span class="pre">flags</span></tt> argument sets attributes on the file.
<p>Adds a file to the file storage. The <tt class="docutils literal">flags</tt> argument sets attributes on the file.
The file attributes is an extension and may not work in all bittorrent clients.
The possible arreibutes are:</p>
<pre class="literal-block">
@ -273,29 +291,34 @@ attribute_executable
In a multi-file file storage (torrent), all files must share the same root directory.</p>
<p>That is, the first path element of all files must be the same.
This shared path element is also set to the name of the torrent. It
can be changed by calling <tt class="docutils literal"><span class="pre">set_name</span></tt>.</p>
can be changed by calling <tt class="docutils literal">set_name</tt>.</p>
<p>The built in functions to traverse a directory to add files will
make sure this requirement is fulfilled.</p>
</div>
<div class="section" id="hash-symlink-mtime-file-index">
<h2>hash() symlink() mtime() file_index()</h2>
<div class="section" id="hash-symlink-mtime-file-path-file-size-pad-file-at">
<h2>hash() symlink() mtime() file_path() file_size() pad_file_at()</h2>
<blockquote>
<pre class="literal-block">
sha1_hash hash(int index) const;
std::string const&amp; symlink(int index) const;
time_t mtime(int index) const;
int file_index(int index) const;
std::string file_path(int index) const;
size_type file_size(int index) const;
bool pad_file_at(int index) const;
</pre>
</blockquote>
<p>These functions are used to query the symlink, file hash,
modification time and the file-index from a file index.</p>
<p>The file hash is a sha-1 hash of the file, or 0 if none was
<p>These functions are used to query attributes of files at
a given index.</p>
<p>The <tt class="docutils literal">file_hash()</tt> is a sha-1 hash of the file, or 0 if none was
provided in the torrent file. This can potentially be used to
join a bittorrent network with other file sharing networks.</p>
<p>The modification time is the posix time when a file was last
modified when the torrent was created, or 0 if it was not provided.</p>
<p>The file index of a file is simply a 0 based index of the
file as they are ordered in the torrent file.</p>
<p>The <tt class="docutils literal">mtime()</tt> is the modification time is the posix
time when a file was last modified when the torrent
was created, or 0 if it was not included in the torrent file.</p>
<p><tt class="docutils literal">file_path()</tt> returns the full path to a file.</p>
<p><tt class="docutils literal">file_size()</tt> returns the size of a file.</p>
<p><tt class="docutils literal">pad_file_at()</tt> returns true if the file at the given
index is a pad-file.</p>
</div>
<div class="section" id="file-base-set-file-base">
<h2>file_base() set_file_base()</h2>
@ -315,7 +338,7 @@ different file bases, so that they don't overlap.
</div>
<div class="section" id="create-torrent">
<h1>create_torrent</h1>
<p>The <tt class="docutils literal"><span class="pre">create_torrent</span></tt> class has the following synopsis:</p>
<p>The <tt class="docutils literal">create_torrent</tt> class has the following synopsis:</p>
<pre class="literal-block">
struct create_torrent
{
@ -327,7 +350,7 @@ struct create_torrent
, calculate_file_hashes = 16
};
create_torrent(file_storage&amp; fs, int piece_size = 0, int pad_size_limit = -1
, int flags = optimize);
, int flags = optimize, int alignment = 0x4000);
create_torrent(torrent_info const&amp; ti);
entry generate() const;
@ -363,25 +386,25 @@ enum {
, calculate_file_hashes = 16
};
create_torrent(file_storage&amp; fs, int piece_size = 0, int pad_size_limit = -1
, int flags = optimize);
, int flags = optimize, int alignment = 0x4000);
create_torrent(torrent_info const&amp; ti);
</pre>
</blockquote>
<p>The <tt class="docutils literal"><span class="pre">piece_size</span></tt> is the size of each piece in bytes. It must
<p>The <tt class="docutils literal">piece_size</tt> is the size of each piece in bytes. It must
be a multiple of 16 kiB. If a piece size of 0 is specified, a
piece_size will be calculated such that the torrent file is roughly 40 kB.</p>
<p>If a <tt class="docutils literal"><span class="pre">pad_size_limit</span></tt> is specified (other than -1), any file larger than
<p>If a <tt class="docutils literal">pad_size_limit</tt> is specified (other than -1), any file larger than
the specified number of bytes will be preceeded by a pad file to align it
with the start of a piece. The pad_file_limit is ignored unless the
<tt class="docutils literal"><span class="pre">optimize</span></tt> flag is passed. Typically it doesn't make sense to set this
<tt class="docutils literal">optimize</tt> flag is passed. Typically it doesn't make sense to set this
any lower than 4kiB.</p>
<p>The overload that takes a <tt class="docutils literal"><span class="pre">torrent_info</span></tt> object will make a verbatim
<p>The overload that takes a <tt class="docutils literal">torrent_info</tt> object will make a verbatim
copy of its info dictionary (to preserve the info-hash). The copy of
the info dictionary will be used by <tt class="docutils literal"><span class="pre">generate()</span></tt>. This means
the info dictionary will be used by <tt class="docutils literal">generate()</tt>. This means
that none of the member functions of create_torrent that affects
the content of the info dictionary (such as <tt class="docutils literal"><span class="pre">set_hash()</span></tt>), will
the content of the info dictionary (such as <tt class="docutils literal">set_hash()</tt>), will
have any affect.</p>
<p>The <tt class="docutils literal"><span class="pre">flags</span></tt> arguments specifies options for the torrent creation. It can
<p>The <tt class="docutils literal">flags</tt> arguments specifies options for the torrent creation. It can
be any combination of the following flags:</p>
<dl class="docutils">
<dt>optimize</dt>
@ -395,7 +418,7 @@ not grow with more pieces. When this option is specified, it is
recommended to have a fairly small piece size, say 64 kiB.
When creating merkle torrents, the full hash tree is also generated
and should be saved off separately. It is accessed through the
<tt class="docutils literal"><span class="pre">merkle_tree()</span></tt> function.</dd>
<tt class="docutils literal">merkle_tree()</tt> function.</dd>
<dt>modification_time</dt>
<dd>This will include the file modification time as part of the torrent.
This is not enabled by default, as it might cause problems when you
@ -414,6 +437,9 @@ the piece hashes, also calculate the file hashes and add those associated
with each file. Note that unless you use the <a class="reference internal" href="#set-piece-hashes">set_piece_hashes()</a> function,
this flag will have no effect.</dd>
</dl>
<p><tt class="docutils literal">alignment</tt> is used when pad files are enabled. This is the size eligible
files are aligned to. The default is the default bittorrent block size of
16 kiB. It is common to align to the piece size of the torrent.</p>
</div>
<div class="section" id="generate">
<h2>generate()</h2>
@ -427,7 +453,7 @@ generate the flat file, use the bencode() function.</p>
<p>It may be useful to add custom entries to the torrent file before bencoding it
and saving it to disk.</p>
<p>If anything goes wrong during torrent generation, this function will return
an empty <tt class="docutils literal"><span class="pre">entry</span></tt> structure. You can test for this condition by querying the
an empty <tt class="docutils literal">entry</tt> structure. You can test for this condition by querying the
type of the entry:</p>
<pre class="literal-block">
file_storage fs;
@ -442,7 +468,7 @@ if (e.type() == entry::undefined_t)
}
</pre>
<p>For instance, you cannot generate a torrent with 0 files in it. If you don't add
any files to the <tt class="docutils literal"><span class="pre">file_storage</span></tt>, torrent generation will fail.</p>
any files to the <tt class="docutils literal">file_storage</tt>, torrent generation will fail.</p>
</div>
<div class="section" id="set-comment">
<h2>set_comment()</h2>
@ -451,7 +477,7 @@ any files to the <tt class="docutils literal"><span class="pre">file_storage</sp
void set_comment(char const* str);
</pre>
</blockquote>
<p>Sets the comment for the torrent. The string <tt class="docutils literal"><span class="pre">str</span></tt> should be utf-8 encoded.
<p>Sets the comment for the torrent. The string <tt class="docutils literal">str</tt> should be utf-8 encoded.
The comment in a torrent file is optional.</p>
</div>
<div class="section" id="set-creator">
@ -461,7 +487,7 @@ The comment in a torrent file is optional.</p>
void set_creator(char const* str);
</pre>
</blockquote>
<p>Sets the creator of the torrent. The string <tt class="docutils literal"><span class="pre">str</span></tt> should be utf-8 encoded.
<p>Sets the creator of the torrent. The string <tt class="docutils literal">str</tt> should be utf-8 encoded.
This is optional.</p>
</div>
<div class="section" id="set-hash">
@ -471,7 +497,7 @@ This is optional.</p>
void set_hash(int index, sha1_hash const&amp; h);
</pre>
</blockquote>
<p>This sets the SHA-1 hash for the specified piece (<tt class="docutils literal"><span class="pre">index</span></tt>). You are required
<p>This sets the SHA-1 hash for the specified piece (<tt class="docutils literal">index</tt>). You are required
to set the hash for every piece in the torrent before generating it. If you have
the files on disk, you can use the high level convenience function to do this.
See <a class="reference internal" href="#set-piece-hashes">set_piece_hashes()</a>.</p>
@ -483,7 +509,7 @@ See <a class="reference internal" href="#set-piece-hashes">set_piece_hashes()</a
void set_file_hash(int index, sha1_hash const&amp; h);
</pre>
</blockquote>
<p>This sets the sha1 hash for this file. This hash will end up under the key <tt class="docutils literal"><span class="pre">sha1</span></tt>
<p>This sets the sha1 hash for this file. This hash will end up under the key <tt class="docutils literal">sha1</tt>
associated with this file (for multi-file torrents) or in the root info dictionary
for single-file torrents.</p>
</div>
@ -500,7 +526,7 @@ single file torrent, this should be an HTTP url, pointing to a file with identic
content as the file of the torrent. For a multi-file torrent, it should point to
a directory containing a directory with the same name as this torrent, and all the
files of the torrent in it.</p>
<p>The second function, <tt class="docutils literal"><span class="pre">add_http_seed()</span></tt> adds an HTTP seed instead.</p>
<p>The second function, <tt class="docutils literal">add_http_seed()</tt> adds an HTTP seed instead.</p>
</div>
<div class="section" id="add-node">
<h2>add_node()</h2>
@ -539,6 +565,8 @@ void set_root_cert(std::string const&amp; pem);
torrent an <em>SSL torrent</em>. An SSL torrent requires that each peer has a valid certificate
signed by this root certificate. For SSL torrents, all peers are connecting over SSL
connections. For more information on SSL torrents, see the <a class="reference external" href="manual.html#ssl-torrents">manual</a>.</p>
<p>The string is not the path to the cert, it's the actual content of the certificate,
loaded into a std::string.</p>
</div>
<div class="section" id="set-priv-priv">
<h2>set_priv() priv()</h2>
@ -558,7 +586,7 @@ std::vector&lt;sha1_hash&gt; const&amp; merkle_tree() const;
</pre>
</blockquote>
<p>This function returns the merkle hash tree, if the torrent was created as a merkle
torrent. The tree is created by <tt class="docutils literal"><span class="pre">generate()</span></tt> and won't be valid until that function
torrent. The tree is created by <tt class="docutils literal">generate()</tt> and won't be valid until that function
has been called. When creating a merkle tree torrent, the actual tree itself has to
be saved off separately and fed into libtorrent the first time you start seeding it,
through the <tt class="docutils literal"><span class="pre">torrent_info::set_merkle_tree()</span></tt> function. From that point onwards, the

30
docs/manual.html
View File

@ -3,7 +3,7 @@
<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.9.1: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.8.1: http://docutils.sourceforge.net/" />
<title>libtorrent API Documentation</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
@ -49,7 +49,7 @@
<tr><th class="docinfo-name">Author:</th>
<td>Arvid Norberg, <a class="last reference external" href="mailto:arvid&#64;rasterbar.com">arvid&#64;rasterbar.com</a></td></tr>
<tr><th class="docinfo-name">Version:</th>
<td>0.16.4</td></tr>
<td>1.0.0</td></tr>
</tbody>
</table>
<div class="contents topic" id="table-of-contents">
@ -612,6 +612,9 @@ configuration options on torrents before starting them.</p>
<p>If you pass in resume data, the paused state of the torrent when the resume data
was saved will override the paused state you pass in here. You can override this
by setting <tt class="docutils literal">flag_override_resume_data</tt>.</p>
<p>If the torrent is auto-managed (<tt class="docutils literal">flag_auto_managed</tt>), the torrent may be resumed
at any point, regardless of how it paused. If it's important to manually control
when the torrent is paused and resumed, don't make it auto managed.</p>
<p>If <tt class="docutils literal">flag_auto_managed</tt> is set, the torrent will be queued, started and seeded
automatically by libtorrent. When this is set, the torrent should also be started
as paused. The default queue order is the order the torrents were added. They
@ -638,6 +641,9 @@ which means it will not make any piece requests. This state is typically entered
on disk I/O errors, and if the torrent is also auto managed, it will be taken out
of this state periodically. This mode can be used to avoid race conditions when
adjusting priorities of pieces before allowing the torrent to start downloading.</p>
<p>If the torrent is auto-managed (<tt class="docutils literal">flag_auto_managed</tt>), the torrent will eventually
be taken out of upload-mode, regardless of how it got there. If it's important to
manually control when the torrent leaves upload mode, don't make it auto managed.</p>
<p><tt class="docutils literal">flag_share_mode</tt> determines if the torrent should be added in <em>share mode</em> or not.
Share mode indicates that we are not interested in downloading the torrent, but
merlely want to improve our share ratio (i.e. increase it). A torrent started in
@ -1369,6 +1375,7 @@ struct dht_settings
bool restrict_routing_ips;
bool restrict_search_ips;
bool extended_routing_table;
bool aggressive_lookups;
};
</pre>
<p><tt class="docutils literal">max_peers_reply</tt> is the maximum number of peers the node will send in
@ -1401,6 +1408,11 @@ standard size of 8. All other buckets have size 8 still.</p>
which port the DHT would listen on and send messages from. This field is deprecated
and ignored. libtorrent always tries to open the UDP socket on the same port
as the TCP socket.</p>
<p><tt class="docutils literal">aggressive_lookups</tt> slightly changes the lookup behavior in terms of how
many outstanding requests we keep. Instead of having branch factor be a hard
limit, we always keep <em>branch factor</em> outstanding requests to the closest nodes.
i.e. every time we get results back with closer nodes, we query them right away.
It lowers the lookup times at the cost of more outstanding queries.</p>
<p><tt class="docutils literal">is_dht_running()</tt> returns true if the DHT support has been started and false
otherwise.</p>
</div>
@ -6321,7 +6333,7 @@ struct peer_disconnected_alert: peer_alert
<div class="section" id="invalid-request-alert">
<h2>invalid_request_alert</h2>
<p>This is a debug alert that is generated by an incoming invalid piece request.
<tt class="docutils literal">ìp</tt> is the address of the peer and the <tt class="docutils literal">request</tt> is the actual incoming
<tt class="docutils literal">ip</tt> is the address of the peer and the <tt class="docutils literal">request</tt> is the actual incoming
request from the peer.</p>
<pre class="literal-block">
struct invalid_request_alert: peer_alert
@ -7908,13 +7920,13 @@ std::string error_code_to_string(boost::system::error_code const&amp; ec)
static const char const* swedish[] =
{
&quot;inget fel&quot;,
&quot;en fil i torrenten kolliderar med en fil från en annan torrent&quot;,
&quot;en fil i torrenten kolliderar med en fil fran en annan torrent&quot;,
&quot;hash check misslyckades&quot;,
&quot;torrent filen är inte en dictionary&quot;,
&quot;'info'-nyckeln saknas eller är korrupt i torrentfilen&quot;,
&quot;'info'-fältet är inte en dictionary&quot;,
&quot;'piece length' fältet saknas eller är korrupt i torrentfilen&quot;,
&quot;torrentfilen saknar namnfältet&quot;,
&quot;torrent filen ar inte en dictionary&quot;,
&quot;'info'-nyckeln saknas eller ar korrupt i torrentfilen&quot;,
&quot;'info'-faltet ar inte en dictionary&quot;,
&quot;'piece length' faltet saknas eller ar korrupt i torrentfilen&quot;,
&quot;torrentfilen saknar namnfaltet&quot;,
&quot;ogiltigt namn i torrentfilen (kan vara en attack)&quot;,
// ... more strings here
};

62
docs/projects.html
View File

@ -3,7 +3,7 @@
<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.5: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.8.1: http://docutils.sourceforge.net/" />
<title>projects using libtorrent</title>
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
<link rel="stylesheet" type="text/css" href="../../css/rst.css" />
@ -45,20 +45,20 @@
<p>These are some of the public projects that uses libtorrent. If you want your
project listed here, let <a class="reference external" href="mailto:arvid&#64;rasterbar.com">me</a> know.</p>
<div class="entry container">
<a class="reference external image-reference" href="http://www.fireaddons.com/"><img align="right" alt="firetorrent.png" class="align-right" src="firetorrent.png" /></a>
<a class="reference external image-reference" href="http://www.fireaddons.com/"><img alt="firetorrent.png" class="align-right" src="firetorrent.png" /></a>
<p><strong>firetorrent</strong></p>
<p><a class="reference external" href="http://www.fireaddons.com/">firetorrent</a> is a single click torrent downloader plugin
for Firefox and Wyzo.</p>
</div>
<div class="entry container">
<a class="reference external image-reference" href="http://www.tonidoplug.com/"><img align="right" alt="tonidoplug.png" class="align-right" src="tonidoplug.png" /></a>
<a class="reference external image-reference" href="http://www.tonidoplug.com/"><img alt="tonidoplug.png" class="align-right" src="tonidoplug.png" /></a>
<p><strong>tonidoplug</strong></p>
<p><a class="reference external" href="http://www.tonidoplug.com/">Tonidoplug</a> is a tiny, low-power, low-cost home server and
NAS device powered by Tonido software that allows you to access
your apps, files, music and media from anywhere.</p>
</div>
<div class="entry container">
<a class="reference external image-reference" href="http://www.mac-downloader.com/"><img align="right" alt="folx.png" class="align-right" src="folx.png" /></a>
<a class="reference external image-reference" href="http://www.mac-downloader.com/"><img alt="folx.png" class="align-right" src="folx.png" /></a>
<p><strong>Folx</strong></p>
<p><a class="reference external" href="http://www.mac-downloader.com/">Folx</a> is a torrent client and download manager for Mac OS X.
The Free version of Folx has all the basic functionality of the torrent
@ -68,7 +68,7 @@ for torrent files just from Folx interface. So there is no need to
browse through multiple torrent trackers searching for particular file.</p>
</div>
<div class="entry container">
<a class="reference external image-reference" href="http://www.qbittorrent.org/"><img align="right" alt="qbittorrent_thumb.jpg" class="align-right" src="qbittorrent_thumb.jpg" /></a>
<a class="reference external image-reference" href="http://www.qbittorrent.org/"><img alt="qbittorrent_thumb.jpg" class="align-right" src="qbittorrent_thumb.jpg" /></a>
<p><strong>qBittorrent</strong></p>
<p><a class="reference external" href="http://www.qbittorrent.org/">qBittorrent</a> is a QT bittorrent
client available for linux (likely
@ -76,7 +76,7 @@ portable to most other desktops as
well). Written by Christophe Dumez.</p>
</div>
<div class="entry container">
<a class="reference external image-reference" href="http://www.limewire.com/"><img align="right" alt="limewire.png" class="align-right" src="limewire.png" /></a>
<a class="reference external image-reference" href="http://www.limewire.com/"><img alt="limewire.png" class="align-right" src="limewire.png" /></a>
<p><strong>Limewire</strong></p>
<p><a class="reference external" href="http://www.limewire.com/">LimeWire</a> is the world's most popular peer-to-peer file-sharing
program. With over 70 million unique monthly users, the software
@ -86,21 +86,21 @@ BitTorrent protocol and the Gnutella network to provide an
unparalleled searches and download speed to the user</p>
</div>
<div class="entry container">
<a class="reference external image-reference" href="http://deluge-torrent.org/"><img align="right" alt="deluge.png" class="align-right" src="deluge.png" /></a>
<a class="reference external image-reference" href="http://deluge-torrent.org/"><img alt="deluge.png" class="align-right" src="deluge.png" /></a>
<p><strong>deluge torrent</strong></p>
<p><a class="reference external" href="http://deluge-torrent.org/">deluge Torrent</a> is a more full-featured yet still lightweight bittorrent
client. It has the ability to automatically resume partial downloads and
background to the system tray.</p>
</div>
<div class="entry container">
<a class="reference external image-reference" href="http://excito.com/bubba/about-bubba.html"><img align="right" alt="bubba.png" class="align-right" src="bubba.png" /></a>
<a class="reference external image-reference" href="http://excito.com/bubba/about-bubba.html"><img alt="bubba.png" class="align-right" src="bubba.png" /></a>
<p><strong>bubba</strong></p>
<p><a class="reference external" href="http://excito.com/bubba/about-bubba.html">Bubba</a> is a mini-sized server, designed to fit your home better than
an always running PC. Boasting Torrent downloader, DAAP streaming,
Web, E-mail, printer and FTP server etc.</p>
</div>
<div class="entry container">
<a class="reference external image-reference" href="http://btg.berlios.de//"><img align="right" alt="btg_thumb.jpg" class="align-right" src="btg_thumb.jpg" /></a>
<a class="reference external image-reference" href="http://btg.berlios.de//"><img alt="btg_thumb.jpg" class="align-right" src="btg_thumb.jpg" /></a>
<p><strong>btg</strong></p>
<p><a class="reference external" href="http://btg.berlios.de//">btg</a> is a unix bittorrent client
which is run as a daemon. It has
@ -110,32 +110,32 @@ connects to the daemon. One GUI
(ncurses) and one web interface
(accessable through a web browser).
Written by Michael Wojciechowski
and Johan Ström.</p>
and Johan Strom.</p>
</div>
<div class="entry container">
<a class="reference external image-reference" href="http://www.tvblob.com"><img align="right" alt="tvblob.jpg" class="align-right" src="tvblob.jpg" /></a>
<a class="reference external image-reference" href="http://www.tvblob.com"><img alt="tvblob.jpg" class="align-right" src="tvblob.jpg" /></a>
<p><strong>tvblob</strong></p>
<p>The <a class="reference external" href="http://www.tvblob.com">BLOBbox</a> represents the ability to harness all of the content available
on the web, without any filtering or pre-selection by a third party ¿ just
on the web, without any filtering or pre-selection by a third party just
like surfing the web.</p>
<p>This means that anyone will have the ability to reach viewers via the Internet
directly on TV, without them having to connect a PC.</p>
</div>
<div class="entry container">
<a class="reference external image-reference" href="http://www.binarynotions.com/halite-bittorrent-client"><img align="right" alt="halite_thumb.png" class="align-right" src="halite_thumb.png" /></a>
<a class="reference external image-reference" href="http://www.binarynotions.com/halite-bittorrent-client"><img alt="halite_thumb.png" class="align-right" src="halite_thumb.png" /></a>
<p><strong>halite BitTorrent</strong></p>
<p><a class="reference external" href="http://www.binarynotions.com/halite-bittorrent-client">Halite</a> is a windows bittorrent client controllabel via an xml-rpc
interface.</p>
</div>
<div class="entry container">
<a class="reference external image-reference" href="http://www.freedownloadmanager.org/"><img align="right" alt="fdm.png" class="align-right" src="fdm.png" /></a>
<a class="reference external image-reference" href="http://www.freedownloadmanager.org/"><img alt="fdm.png" class="align-right" src="fdm.png" /></a>
<p><strong>Free download manager</strong></p>
<p><a class="reference external" href="http://www.freedownloadmanager.org/">FDM</a> is a powerful, easy-to-use and absolutely free download accelerator and
manager. Moreover, FDM is 100% safe, open-source software distributed under
GPL License.</p>
</div>
<div class="entry container">
<a class="reference external image-reference" href="http://us.zyxel.com/Products/details.aspx?PC1IndexFlag=20050125090459&amp;CategoryGroupNo=758BFE64-3A95-463C-9E1E-3D30E3B58D9C"><img align="right" alt="zyxel.png" class="align-right" src="zyxel.png" /></a>
<a class="reference external image-reference" href="http://us.zyxel.com/Products/details.aspx?PC1IndexFlag=20050125090459&amp;CategoryGroupNo=758BFE64-3A95-463C-9E1E-3D30E3B58D9C"><img alt="zyxel.png" class="align-right" src="zyxel.png" /></a>
<p><strong>ZyXEL NSA-220</strong></p>
<p><a class="reference external" href="http://us.zyxel.com/Products/details.aspx?PC1IndexFlag=20050125090459&amp;CategoryGroupNo=758BFE64-3A95-463C-9E1E-3D30E3B58D9C">ZyXEL</a> NSA220 makes it easy to store, protect and share files between users
on your home network. The built-in DLNA server works with many set top boxes
@ -145,32 +145,32 @@ download video and audio podcasts as well as allow you to download bittorrent
files without needing to leave your computer on.</p>
</div>
<div class="entry container">
<a class="reference external image-reference" href="http://torrent2exe.com"><img align="right" alt="t2e.jpg" class="align-right" src="t2e.jpg" /></a>
<a class="reference external image-reference" href="http://torrent2exe.com"><img alt="t2e.jpg" class="align-right" src="t2e.jpg" /></a>
<p><strong>Torrent2Exe</strong></p>
<p><a class="reference external" href="http://torrent2exe.com">Torrent2Exe</a> Torrent2exe is a small BitTorrent client. Its basic idea is to
let users download a custom-built EXE program with the torrent file
integrated into it.</p>
</div>
<div class="entry container">
<a class="reference external image-reference" href="https://sourceforge.net/projects/flush/"><img align="right" alt="flush.jpg" class="align-right" src="flush.jpg" /></a>
<a class="reference external image-reference" href="https://sourceforge.net/projects/flush/"><img alt="flush.jpg" class="align-right" src="flush.jpg" /></a>
<p><strong>Flush</strong></p>
<p><a class="reference external" href="https://sourceforge.net/projects/flush/">Flush</a> is a GTK-based BitTorrent client.</p>
</div>
<div class="entry container">
<a class="reference external image-reference" href="http://pump.vipeers.com/"><img align="right" alt="pump.png" class="align-right" src="pump.png" /></a>
<a class="reference external image-reference" href="http://pump.vipeers.com/"><img alt="pump.png" class="align-right" src="pump.png" /></a>
<p><strong>Pump</strong></p>
<p><a class="reference external" href="http://pump.vipeers.com/">Pump</a> Pump brings together all the main features you need in order to find
content online and enjoy it on your PC and on your Mobile.</p>
</div>
<div class="entry container">
<a class="reference external image-reference" href="http://lincetorrent.sourceforge.net/"><img align="right" alt="lince.png" class="align-right" src="lince.png" /></a>
<a class="reference external image-reference" href="http://lincetorrent.sourceforge.net/"><img alt="lince.png" class="align-right" src="lince.png" /></a>
<p><strong>Lince</strong></p>
<p><a class="reference external" href="http://lincetorrent.sourceforge.net/">Lince</a> is a bittorrent client using libtorrent to handle bittorrent protocol
and gtkmm for the interface, it has been designed to be a light and full
featured client.</p>
</div>
<div class="entry container">
<a class="reference external image-reference" href="http://electricsheep.org"><img align="right" alt="electric_sheep_thumb.jpg" class="align-right" src="electric_sheep_thumb.jpg" /></a>
<a class="reference external image-reference" href="http://electricsheep.org"><img alt="electric_sheep_thumb.jpg" class="align-right" src="electric_sheep_thumb.jpg" /></a>
<p><strong>electric sheep</strong></p>
<p><a class="reference external" href="http://electricsheep.org">electric sheep</a> is a screensaver
which collectively generates
@ -178,50 +178,50 @@ animations and lets the users
vote which one to live on.</p>
</div>
<div class="entry container">
<a class="reference external image-reference" href="http://getmiro.com"><img align="right" alt="miro.jpg" class="align-right" src="miro.jpg" /></a>
<a class="reference external image-reference" href="http://getmiro.com"><img alt="miro.jpg" class="align-right" src="miro.jpg" /></a>
<p><strong>Miro</strong></p>
<p><a class="reference external" href="http://getmiro.com">Miro</a> is a free application for channels of internet video (also known as
video podcasts and video rss). Miro is designed to be easy to use and to give
you an elegant fullscreen viewing experience.</p>
</div>
<div class="entry container">
<a class="reference external image-reference" href="http://tvitty.com"><img align="right" alt="tvitty.jpg" class="align-right" src="tvitty.jpg" /></a>
<a class="reference external image-reference" href="http://tvitty.com"><img alt="tvitty.jpg" class="align-right" src="tvitty.jpg" /></a>
<p><strong>Tvitty</strong></p>
<p><a class="reference external" href="http://tvitty.com">tvitty</a> is a bittorrent client for Vista Media Center, which allows
searching and downloading of torrents directly on your TV.</p>
</div>
<div class="entry container">
<a class="reference external image-reference" href="http://fatrat.dolezel.info"><img align="right" alt="fatrat.png" class="align-right" src="fatrat.png" /></a>
<a class="reference external image-reference" href="http://fatrat.dolezel.info"><img alt="fatrat.png" class="align-right" src="fatrat.png" /></a>
<p><strong>FatRat</strong></p>
<p><a class="reference external" href="http://fatrat.dolezel.info">FatRat</a> is an open source download manager for Linux/Unix systems written in
C++ with the help of the Trolltech Qt 4 library. It's simple to use and
install.</p>
</div>
<div class="entry container">
<a class="reference external image-reference" href="http://leechcraft.org/"><img align="right" alt="leechcraft.png" class="align-right" src="leechcraft.png" /></a>
<a class="reference external image-reference" href="http://leechcraft.org/"><img alt="leechcraft.png" class="align-right" src="leechcraft.png" /></a>
<p><strong>LeechCraft</strong></p>
<p><a class="reference external" href="http://leechcraft.org/">LeechCraft</a> LeechCraft is a free open source cross-platform extensible
software, which primary goal is support of file sharing networks and
protocols like HTTP and FTP</p>
</div>
<div class="entry container">
<a class="reference external image-reference" href="http://www.moopolice.de"><img align="right" alt="moopolice_thumb.gif" class="align-right" src="moopolice_thumb.gif" /></a>
<a class="reference external image-reference" href="http://www.moopolice.de"><img alt="moopolice_thumb.gif" class="align-right" src="moopolice_thumb.gif" /></a>
<p><strong>MooPolice</strong></p>
<p><a class="reference external" href="http://www.moopolice.de">MooPolice</a> is a windows bittorrent
client with a quite unique look.</p>
</div>
<div class="entry container">
<a class="reference external image-reference" href="http://code.google.com/p/linkage/"><img align="right" alt="Linkage.png" class="align-right" src="Linkage.png" /></a>
<a class="reference external image-reference" href="http://code.google.com/p/linkage/"><img alt="Linkage.png" class="align-right" src="Linkage.png" /></a>
<p><strong>Linkage</strong></p>
<p><a class="reference external" href="http://code.google.com/p/linkage/">Linkage</a> is a gtkmm client that aims to be middle weight.</p>
</div>
<div class="entry container">
<a class="reference external image-reference" href="http://www.bitrocket.org/"><img align="right" alt="bitrocket_thumb.png" class="align-right" src="bitrocket_thumb.png" /></a>
<a class="reference external image-reference" href="http://www.bitrocket.org/"><img alt="bitrocket_thumb.png" class="align-right" src="bitrocket_thumb.png" /></a>
<p><strong>BitRocket</strong></p>
<p><a class="reference external" href="http://www.bitrocket.org/">BitRocket</a> is a MacOS X bittorrent client.</p>
</div>
<div class="entry container">
<a class="reference external image-reference" href="http://www.bitscast.com/software/"><img align="right" alt="bitscast_thumb.png" class="align-right" src="bitscast_thumb.png" /></a>
<a class="reference external image-reference" href="http://www.bitscast.com/software/"><img alt="bitscast_thumb.png" class="align-right" src="bitscast_thumb.png" /></a>
<p><strong>BitsCast</strong></p>
<p>RSS reader, podcast subscriber,
video feed downloader, bittorrent
@ -229,17 +229,17 @@ feed downloader. See <a class="reference external" href="http://www.bitscast.com
homepage for more info.</p>
</div>
<div class="entry container">
<a class="reference external image-reference" href="http://code.google.com/p/bitfox/"><img align="right" alt="bitfox.png" class="align-right" src="bitfox.png" /></a>
<a class="reference external image-reference" href="http://code.google.com/p/bitfox/"><img alt="bitfox.png" class="align-right" src="bitfox.png" /></a>
<p><strong>Bitfox</strong></p>
<p><a class="reference external" href="http://code.google.com/p/bitfox/">Bitfox</a> is a firefox plugin integrating bittorrent downloads in firefox.</p>
</div>
<div class="entry container">
<a class="reference external image-reference" href="http://bitslug.sourceforge.net/"><img align="right" alt="bitslug_thumb.png" class="align-right" src="bitslug_thumb.png" /></a>
<a class="reference external image-reference" href="http://bitslug.sourceforge.net/"><img alt="bitslug_thumb.png" class="align-right" src="bitslug_thumb.png" /></a>
<p><strong>BitSlug</strong></p>
<p><a class="reference external" href="http://bitslug.sourceforge.net/">BitSlug</a> is a MacOSX cocoa client.</p>
</div>
<div class="entry container">
<a class="reference external image-reference" href="http://www.int64.org/arctic.html"><img align="right" alt="arctic_thumb.png" class="align-right" src="arctic_thumb.png" /></a>
<a class="reference external image-reference" href="http://www.int64.org/arctic.html"><img alt="arctic_thumb.png" class="align-right" src="arctic_thumb.png" /></a>
<p><strong>Arctic Torrent</strong></p>
<p><a class="reference external" href="http://www.int64.org/arctic.html">Arctic Torrent</a> is a light-weight
bittorrent client for windows.

26
docs/python_binding.html
View File

@ -3,7 +3,7 @@
<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.5: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.8.1: http://docutils.sourceforge.net/" />
<title>libtorrent python binding</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
@ -67,12 +67,12 @@
which is a python module that can be imported in a python program.</p>
<div class="section" id="building-using-setup-py">
<h2>building using setup.py</h2>
<p>There is a <tt class="docutils literal"><span class="pre">setup.py</span></tt> shipped with libtorrent that can be used on windows.
On windows the setup.py will invoke <tt class="docutils literal"><span class="pre">bjam</span></tt> and assume that you have boost
sources at <tt class="docutils literal"><span class="pre">$BOOST_PATH</span></tt>. The resulting executable is self-contained, it does
<p>There is a <tt class="docutils literal">setup.py</tt> shipped with libtorrent that can be used on windows.
On windows the setup.py will invoke <tt class="docutils literal">bjam</tt> and assume that you have boost
sources at <tt class="docutils literal">$BOOST_PATH</tt>. The resulting executable is self-contained, it does
not depend any boost or libtorrent dlls.</p>
<p>On other systems, the setup.py is generated by running
<tt class="docutils literal"><span class="pre">./configure</span> <span class="pre">--enable-python-binding</span></tt>.</p>
<tt class="docutils literal">./configure <span class="pre">--enable-python-binding</span></tt>.</p>
<p>To build the Python bindings do:</p>
<ol class="arabic">
<li><p class="first">Run:</p>
@ -104,8 +104,8 @@ using python : 2.6 : /usr/bin/python2.6 : /usr/include/python2.6 : /usr/lib/pyth
<p>The bindings require <em>at least</em> python version 2.2.</p>
<p>For more information on how to install and set up boost-build, see the
<a class="reference external" href="building.html#step-2-setup-bbv2">building libtorrent</a> section.</p>
<p>Once you have boost-build set up, you cd to the <tt class="docutils literal"><span class="pre">bindings/python</span></tt>
directory and invoke <tt class="docutils literal"><span class="pre">bjam</span></tt> with the apropriate settings. For the available
<p>Once you have boost-build set up, you cd to the <tt class="docutils literal">bindings/python</tt>
directory and invoke <tt class="docutils literal">bjam</tt> with the apropriate settings. For the available
build variants, see <a class="reference external" href="building.html#step-3-building-libtorrent">libtorrent build options</a>.</p>
<p>For example:</p>
<pre class="literal-block">
@ -124,7 +124,7 @@ the <a class="reference external" href="manual.html">main library reference</a>.
<dl class="docutils">
<dt>asio::tcp::endpoint</dt>
<dd>The endpoint type is represented as a tuple of a string (as the address) and an int for
the port number. E.g. <tt class="docutils literal"><span class="pre">('127.0.0.1',</span> <span class="pre">6881)</span></tt> represents the localhost port 6881.</dd>
the port number. E.g. <tt class="docutils literal">('127.0.0.1', 6881)</tt> represents the localhost port 6881.</dd>
<dt>libtorrent::time_duration</dt>
<dd>The time duration is represented as a number of seconds in a regular integer.</dd>
</dl>
@ -139,13 +139,13 @@ a list of entries.</p>
</ul>
<p><tt class="docutils literal"><span class="pre">create_torrent::add_node()</span></tt> takes two arguments, one string and one integer,
instead of a pair. The string is the address and the integer is the port.</p>
<p><tt class="docutils literal"><span class="pre">session::set_settings()</span></tt> not only accepts a <tt class="docutils literal"><span class="pre">session_settings</span></tt> object, but also
a dictionary with keys matching the names of the members of the <tt class="docutils literal"><span class="pre">session_settings</span></tt> struct.
When calling <tt class="docutils literal"><span class="pre">set_settings</span></tt>, the dictionary does not need to have every settings set,
<p><tt class="docutils literal"><span class="pre">session::set_settings()</span></tt> not only accepts a <tt class="docutils literal">session_settings</tt> object, but also
a dictionary with keys matching the names of the members of the <tt class="docutils literal">session_settings</tt> struct.
When calling <tt class="docutils literal">set_settings</tt>, the dictionary does not need to have every settings set,
keys that are not present, are set to their default value.</p>
<p>For backwards compatibility, <tt class="docutils literal"><span class="pre">session::settings()</span></tt> still returns a <tt class="docutils literal"><span class="pre">session_settings</span></tt>
<p>For backwards compatibility, <tt class="docutils literal"><span class="pre">session::settings()</span></tt> still returns a <tt class="docutils literal">session_settings</tt>
struct. To get a python dictionary of the settings, call <tt class="docutils literal"><span class="pre">session::get_settings</span></tt>.</p>
<p>For an example python program, see <tt class="docutils literal"><span class="pre">client.py</span></tt> in the <tt class="docutils literal"><span class="pre">bindings/python</span></tt>
<p>For an example python program, see <tt class="docutils literal">client.py</tt> in the <tt class="docutils literal">bindings/python</tt>
directory.</p>
<p>A very simple example usage of the module would be something like this:</p>
<pre class="literal-block">

12
docs/running_tests.html
View File

@ -3,7 +3,7 @@
<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.5: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.8.1: http://docutils.sourceforge.net/" />
<title>libtorrent manual</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
@ -62,7 +62,7 @@
<div class="section" id="running-and-building-tests">
<h1>running and building tests</h1>
<p>Some of the tests of libtorrent are not self contained. For instance, in
order to test the <tt class="docutils literal"><span class="pre">http_connection</span></tt> class in libtorrent, the test requires
order to test the <tt class="docutils literal">http_connection</tt> class in libtorrent, the test requires
<a class="reference external" href="http://www.lighttpd.net">lighty</a>. This document outlines the requirements of the tests as well as
describes how to set up your environment to be able to run them.</p>
</div>
@ -90,9 +90,9 @@ lighttpd -V
tool to use to test libtorrent's support for SOCKS4, SOCKS5, HTTPS and
HTTP proxies.</p>
<p>You can download prebuilt binaries for the most common platforms on
<a class="reference external" href="http://www.delegate.org/delegate/download/">deletate's download page</a>. Make sure to name the executable <tt class="docutils literal"><span class="pre">delegated</span></tt>
and put it in a place where a shell can pick it up, in its <tt class="docutils literal"><span class="pre">PATH</span></tt>. For
instance <tt class="docutils literal"><span class="pre">/bin</span></tt>.</p>
<a class="reference external" href="http://www.delegate.org/delegate/download/">deletate's download page</a>. Make sure to name the executable <tt class="docutils literal">delegated</tt>
and put it in a place where a shell can pick it up, in its <tt class="docutils literal">PATH</tt>. For
instance <tt class="docutils literal">/bin</tt>.</p>
</div>
<div class="section" id="openssl">
<h1>OpenSSL</h1>
@ -104,7 +104,7 @@ echo -e &quot;AU\ntest province\ntest city\ntest company\ntest department\n\
tester\ntest&#64;test.com&quot; | openssl req -new -x509 -keyout server.pem \
-out server.pem -days 365 -nodes
</pre>
<p>This will write <tt class="docutils literal"><span class="pre">server.pem</span></tt> which is referenced in the lighty
<p>This will write <tt class="docutils literal">server.pem</tt> which is referenced in the lighty
confiuration file.</p>
<p>OpenSSL comes installed with most Linux and BSD distros, including Mac OS X.
You can download it from <a class="reference external" href="http://www.openssl.org/">the openssl homepage</a>.</p>

56
docs/tuning.html
View File

@ -3,7 +3,7 @@
<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.5: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.8.1: http://docutils.sourceforge.net/" />
<title>libtorrent manual</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
@ -49,7 +49,7 @@
<tr><th class="docinfo-name">Author:</th>
<td>Arvid Norberg, <a class="last reference external" href="mailto:arvid&#64;rasterbar.com">arvid&#64;rasterbar.com</a></td></tr>
<tr><th class="docinfo-name">Version:</th>
<td>0.16.0</td></tr>
<td>1.0.0</td></tr>
</tbody>
</table>
<div class="contents topic" id="table-of-contents">
@ -90,7 +90,7 @@
<div class="section" id="tuning-libtorrent">
<h1>tuning libtorrent</h1>
<p>libtorrent expose most constants used in the bittorrent engine for
customization through the <tt class="docutils literal"><span class="pre">session_settings</span></tt>. This makes it possible to
customization through the <tt class="docutils literal">session_settings</tt>. This makes it possible to
test and tweak the parameters for certain algorithms to make a client
that fits a wide range of needs. From low memory embedded devices to
servers seeding thousands of torrents. The default settings in libtorrent
@ -102,7 +102,7 @@ and how parameters are likely to affect it.</p>
<div class="section" id="reducing-memory-footprint">
<h1>reducing memory footprint</h1>
<p>These are things you can do to reduce the memory footprint of libtorrent. You get
some of this by basing your default <tt class="docutils literal"><span class="pre">session_settings</span></tt> on the <tt class="docutils literal"><span class="pre">min_memory_usage()</span></tt>
some of this by basing your default <tt class="docutils literal">session_settings</tt> on the <tt class="docutils literal">min_memory_usage()</tt>
setting preset function.</p>
<p>Keep in mind that lowering memory usage will affect performance, always profile
and benchmark your settings to determine if it's worth the trade-off.</p>
@ -218,12 +218,12 @@ reduce the executable size with up to 45%. In order to build without exception
support, you need to patch parts of boost.</p>
<p>Also make sure to optimize for size when compiling.</p>
<p>Another way of reducing the executable size is to disable code that isn't used.
There are a number of <tt class="docutils literal"><span class="pre">TORRENT_*</span></tt> macros that control which features are included
There are a number of <tt class="docutils literal">TORRENT_*</tt> macros that control which features are included
in libtorrent. If these macros are used to strip down libtorrent, make sure the same
macros are defined when building libtorrent as when linking against it. If these
are different the structures will look different from the libtorrent side and from
the client side and memory corruption will follow.</p>
<p>One, probably, safe macro to define is <tt class="docutils literal"><span class="pre">TORRENT_NO_DEPRECATE</span></tt> which removes all
<p>One, probably, safe macro to define is <tt class="docutils literal">TORRENT_NO_DEPRECATE</tt> which removes all
deprecated functions and struct members. As long as no deprecated functions are
relied upon, this should be a simple way to eliminate a little bit of code.</p>
<p>For all available options, see the <a class="reference external" href="building.html">building libtorrent</a> secion.</p>
@ -307,7 +307,7 @@ other peer will ever request the same block while it's still in the cache, the r
cache can be set to be <em>volatile</em>. This means that every block that is requested out of
the read cache is removed immediately. This saves a significant amount of cache space
which can be used as read-ahead for other peers. This mode should <strong>never</strong> be combined
with either <tt class="docutils literal"><span class="pre">explicit_read_cache</span></tt> or <tt class="docutils literal"><span class="pre">suggest_read_cache</span></tt>, since those uses opposite
with either <tt class="docutils literal">explicit_read_cache</tt> or <tt class="docutils literal">suggest_read_cache</tt>, since those uses opposite
strategies for the read cache. You don't want to on one hand attract peers to request
the same pieces, and on the other hand assume that they won't request the same pieces
and drop them when the first peer requests it. To enable volatile read cache, set
@ -337,7 +337,7 @@ enough to not draining the socket's send buffer before the disk operation comple
<p>The watermark is bound to a max value, to avoid buffer sizes growing out of control.
The default max send buffer size might not be enough to sustain very high upload rates,
and you might have to increase it. It's specified in bytes in
<tt class="docutils literal"><span class="pre">session_settings::send_buffer_watermark</span></tt>. The <tt class="docutils literal"><span class="pre">high_performance_seed()</span></tt> preset
<tt class="docutils literal"><span class="pre">session_settings::send_buffer_watermark</span></tt>. The <tt class="docutils literal">high_performance_seed()</tt> preset
sets this value to 5 MB.</p>
</div>
<div class="section" id="peers">
@ -372,18 +372,18 @@ libtorrent that return some value have to block your thread while posting a mess
the main network thread and then wait for a response (calls that don't return any data
will simply post the message and then immediately return). The time this takes might
become significant once you reach a few hundred torrents (depending on how many calls
you make to each torrent and how often). <tt class="docutils literal"><span class="pre">get_torrent_status</span></tt> lets you query the
you make to each torrent and how often). <tt class="docutils literal">get_torrent_status</tt> lets you query the
status of all torrents in a single call. This will actually loop through all torrents
and run a provided predicate function to determine whether or not to include it in
the returned vector. If you have a lot of torrents, you might want to update the status
of only certain torrents. For instance, you might only be interested in torrents that
are being downloaded.</p>
<p>The intended use of these functions is to start off by calling <tt class="docutils literal"><span class="pre">get_torrent_status</span></tt>
to get a list of all torrents that match your criteria. Then call <tt class="docutils literal"><span class="pre">refresh_torrent_status</span></tt>
<p>The intended use of these functions is to start off by calling <tt class="docutils literal">get_torrent_status</tt>
to get a list of all torrents that match your criteria. Then call <tt class="docutils literal">refresh_torrent_status</tt>
on that list. This will only refresh the status for the torrents in your list, and thus
ignore all other torrents you might be running. This may save a significant amount of
time, especially if the number of torrents you're interested in is small. In order to
keep your list of interested torrents up to date, you can either call <tt class="docutils literal"><span class="pre">get_torrent_status</span></tt>
keep your list of interested torrents up to date, you can either call <tt class="docutils literal">get_torrent_status</tt>
from time to time, to include torrents you might have become interested in since the last
time. In order to stop refreshing a certain torrent, simply remove it from the list.</p>
<p>A more efficient way however, would be to subscribe to status alert notifications, and
@ -400,7 +400,7 @@ preprocessor symbols when building.</p>
gnuplot and python).</p>
<div class="section" id="disk-metrics">
<h2>disk metrics</h2>
<p>To enable disk I/O instrumentation, define <tt class="docutils literal"><span class="pre">TORRENT_DISK_STATS</span></tt> when building. When built
<p>To enable disk I/O instrumentation, define <tt class="docutils literal">TORRENT_DISK_STATS</tt> when building. When built
with this configuration libtorrent will create three log files, measuring various aspects of
the disk I/O. The following table is an overview of these files and what they measure.</p>
<table border="1" class="docutils">
@ -414,19 +414,19 @@ the disk I/O. The following table is an overview of these files and what they me
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="docutils literal"><span class="pre">disk_io_thread.log</span></tt></td>
<tr><td><tt class="docutils literal">disk_io_thread.log</tt></td>
<td>This is a log of which operation the disk I/O thread is
engaged in, with timestamps. This tells you what the thread
is spending its time doing.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">disk_buffers.log</span></tt></td>
<tr><td><tt class="docutils literal">disk_buffers.log</tt></td>
<td>This log keeps track of what the buffers allocated from the
disk buffer pool are used for. There are 5 categories.
receive buffer, send buffer, write cache, read cache and
temporary hash storage. This is key when optimizing memory
usage.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">disk_access.log</span></tt></td>
<tr><td><tt class="docutils literal">disk_access.log</tt></td>
<td>This is a low level log of read and write operations, with
timestamps and file offsets. The file offsets are byte
offsets in the torrent (not in any particular file, in the
@ -440,12 +440,12 @@ to do.</td>
<div class="section" id="disk-io-thread-log">
<h3>disk_io_thread.log</h3>
<p>The structure of this log is simple. For each line, there are two columns, a timestamp and
the operation that was started. There is a special operation called <tt class="docutils literal"><span class="pre">idle</span></tt> which means
the operation that was started. There is a special operation called <tt class="docutils literal">idle</tt> which means
it looped back to the top and started waiting for new jobs. If there are more jobs to
handle immediately, the <tt class="docutils literal"><span class="pre">idle</span></tt> state is still there, but the timestamp is the same as the
handle immediately, the <tt class="docutils literal">idle</tt> state is still there, but the timestamp is the same as the
next job that is handled.</p>
<p>Some operations have a 3:rd column with an optional parameter. <tt class="docutils literal"><span class="pre">read</span></tt> and <tt class="docutils literal"><span class="pre">write</span></tt> tells
you the number of bytes that were requested to be read or written. <tt class="docutils literal"><span class="pre">flushing</span></tt> tells you
<p>Some operations have a 3:rd column with an optional parameter. <tt class="docutils literal">read</tt> and <tt class="docutils literal">write</tt> tells
you the number of bytes that were requested to be read or written. <tt class="docutils literal">flushing</tt> tells you
the number of bytes that were flushed from the disk cache.</p>
<p>This is an example excerpt from a log:</p>
<pre class="literal-block">
@ -458,8 +458,8 @@ the number of bytes that were flushed from the disk cache.</p>
8255 idle
8431 read 16384
</pre>
<p>The script to parse this log and generate a graph is called <tt class="docutils literal"><span class="pre">parse_disk_log.py</span></tt>. It takes
the log file as the first command line argument, and produces a file: <tt class="docutils literal"><span class="pre">disk_io.png</span></tt>.
<p>The script to parse this log and generate a graph is called <tt class="docutils literal">parse_disk_log.py</tt>. It takes
the log file as the first command line argument, and produces a file: <tt class="docutils literal">disk_io.png</tt>.
The time stamp is in milliseconds since start.</p>
<p>You can pass in a second, optional, argument to specify the window size it will average
the time measurements over. The default is 5 seconds. For long test runs, it might be interesting
@ -488,8 +488,8 @@ in use for this particular key. For example:</p>
24910 receive buffer: 3
</pre>
<p>The time stamp is in milliseconds since start.</p>
<p>To generate a graph, use <tt class="docutils literal"><span class="pre">parse_disk_buffer_log.py</span></tt>. It takes the log file as the first
command line argument. It generates <tt class="docutils literal"><span class="pre">disk_buffer.png</span></tt>.</p>
<p>To generate a graph, use <tt class="docutils literal">parse_disk_buffer_log.py</tt>. It takes the log file as the first
command line argument. It generates <tt class="docutils literal">disk_buffer.png</tt>.</p>
<img alt="disk_buffer_sample.png" src="disk_buffer_sample.png" />
<p>This is an example graph generated by the parse script.</p>
</div>
@ -516,16 +516,16 @@ started, and the second one is where the operation ended.</p>
36766 read_end 367263744
</pre>
<p>The disk access log does not have any good visualization tool yet. There is however a gnuplot
file, <tt class="docutils literal"><span class="pre">disk_access.gnuplot</span></tt> which assumes <tt class="docutils literal"><span class="pre">disk_access.log</span></tt> is in the current directory.</p>
file, <tt class="docutils literal">disk_access.gnuplot</tt> which assumes <tt class="docutils literal">disk_access.log</tt> is in the current directory.</p>
<img alt="disk_access.png" src="disk_access.png" />
<p>The density of the disk seeks tells you how hard the drive has to work.</p>
</div>
</div>
<div class="section" id="session-stats">
<h2>session stats</h2>
<p>By defining <tt class="docutils literal"><span class="pre">TORRENT_STATS</span></tt> libtorrent will write a log file called <tt class="docutils literal"><span class="pre">session_stats/&lt;pid&gt;.&lt;sequence&gt;.log</span></tt> which
is in a format ready to be passed directly into gnuplot. The parser script <tt class="docutils literal"><span class="pre">parse_session_stats.py</span></tt>
generates a report in <tt class="docutils literal"><span class="pre">session_stats_report/index.html</span></tt>.</p>
<p>By defining <tt class="docutils literal">TORRENT_STATS</tt> libtorrent will write a log file called <tt class="docutils literal"><span class="pre">session_stats/&lt;pid&gt;.&lt;sequence&gt;.log</span></tt> which
is in a format ready to be passed directly into gnuplot. The parser script <tt class="docutils literal">parse_session_stats.py</tt>
generates a report in <tt class="docutils literal">session_stats_report/index.html</tt>.</p>
<p>The first line in the log contains all the field names, separated by colon:</p>
<pre class="literal-block">
second:upload rate:download rate:downloading torrents:seeding torrents:peers...

10
docs/utp.html
View File

@ -3,7 +3,7 @@
<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.5: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.8.1: http://docutils.sourceforge.net/" />
<title>libtorrent manual</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
@ -49,7 +49,7 @@
<tr><th class="docinfo-name">Author:</th>
<td>Arvid Norberg, <a class="last reference external" href="mailto:arvid&#64;rasterbar.com">arvid&#64;rasterbar.com</a></td></tr>
<tr><th class="docinfo-name">Version:</th>
<td>0.16.0</td></tr>
<td>1.0.0</td></tr>
</tbody>
</table>
<div class="contents topic" id="table-of-contents">
@ -168,7 +168,7 @@ is higher than the target, cwnd is decreased proportional to (delay - target_del
<pre class="literal-block">
cwnd += gain * (target_delay - delay)
</pre>
<a class="reference external image-reference" href="cwnd.png"><img align="right" alt="cwnd_thumb.png" class="align-right" src="cwnd_thumb.png" /></a>
<a class="reference external image-reference" href="cwnd.png"><img alt="cwnd_thumb.png" class="align-right" src="cwnd_thumb.png" /></a>
<p>Similarly to TCP, this is scaled so that the increase is evened out over one RTT.</p>
<p>The linear controller will adjust the cwnd more for delays that are far off the
target, and less for delays that are close to the target. This makes it converge
@ -192,7 +192,7 @@ the packet). It does this by always comparing all measurements to a
baseline measurement, to cancel out any fixed delay. By focusing on the
variable delay along a link, it will specifically detect points where
there might be congestion, since those points will have buffers.</p>
<a class="reference external image-reference" href="delays.png"><img align="right" alt="delays_thumb.png" class="align-right" src="delays_thumb.png" /></a>
<a class="reference external image-reference" href="delays.png"><img alt="delays_thumb.png" class="align-right" src="delays_thumb.png" /></a>
<p>Delay on the return link is explicitly not included in the delay measurement.
This is because in a peer-to-peer application, the other end is likely to also
be connected via a modem, with the same send buffer restrictions as we assume
@ -284,7 +284,7 @@ with jumbo frames.</p>
</div>
<div class="section" id="clock-drift">
<h2>clock drift</h2>
<a class="reference external image-reference" href="our_delay_base.png"><img align="right" alt="our_delay_base_thumb.png" class="align-right" src="our_delay_base_thumb.png" /></a>
<a class="reference external image-reference" href="our_delay_base.png"><img alt="our_delay_base_thumb.png" class="align-right" src="our_delay_base_thumb.png" /></a>
<p>Clock drift is clocks progressing at different rates. It's different from clock
skew which means clocks set to different values (but which may progress at the same
rate).</p>