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

update docs

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"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <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> <title>libtorrent manual</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" /> <meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" /> <link rel="stylesheet" type="text/css" href="../../css/base.css" />
@ -49,7 +49,7 @@
<tr><th class="docinfo-name">Author:</th> <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> <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> <tr><th class="docinfo-name">Version:</th>
<td>0.16.0</td></tr> <td>1.0.0</td></tr>
</tbody> </tbody>
</table> </table>
<div class="contents topic" id="table-of-contents"> <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> 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 <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 (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> following these instructions, you can usually get help in the <tt class="docutils literal">#libtorrent</tt>
IRC channel on <tt class="docutils literal"><span class="pre">irc.freenode.net</span></tt>.</p> IRC channel on <tt class="docutils literal">irc.freenode.net</tt>.</p>
<div class="warning"> <div class="warning">
<p class="first admonition-title">Warning</p> <p class="first admonition-title">Warning</p>
<p>A common mistake when building and linking against libtorrent is <p>A common mistake when building and linking against libtorrent is
@ -117,20 +117,20 @@ in order to build libtorrent.</p>
</div> </div>
<div class="section" id="step-2-setup-bbv2"> <div class="section" id="step-2-setup-bbv2">
<h3>Step 2: Setup BBv2</h3> <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 <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"><span class="pre">cmd</span></tt>). Change directory to 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">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 <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"><span class="pre">bin.</span></tt> and then have the name of your 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"><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 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"><span class="pre">PATH</span></tt>. On linux systems a place commonly used may be 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"><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 <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"><span class="pre">PATH</span></tt>).</p> 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"><span class="pre">bjam</span></tt> installed. <tt class="docutils literal"><span class="pre">bjam</span></tt> can be considered an interpreter <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"><span class="pre">bjam</span></tt>. 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 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 set the environment variable <tt class="docutils literal">BOOST_BUILD_PATH</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 <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 toolsets (descriptions used by boost-build to know how to use different
compilers on different platforms). Assuming the boost install path above, set 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> 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 : 3.3 : g++-3.3 ;
using gcc : 4.0 : g++-4.0 ; using gcc : 4.0 : g++-4.0 ;
</pre> </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 From Tiger (10.4) MacOS X comes with both GCC 3.3 and GCC 4.0. Then you can
use the following toolsets:</p> use the following toolsets:</p>
<pre class="literal-block"> <pre class="literal-block">
@ -170,12 +170,12 @@ using darwin : 4.0 : g++-4.0 ;
</div> </div>
<div class="section" id="step-3-building-libtorrent"> <div class="section" id="step-3-building-libtorrent">
<h3>Step 3: Building libtorrent</h3> <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 <p>When building libtorrent, the <tt class="docutils literal">Jamfile</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 <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 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 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> 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. a specific toolset to use (compiler) you can just add that to the commandline.
For example:</p> For example:</p>
<pre class="literal-block"> <pre class="literal-block">
@ -183,19 +183,25 @@ bjam msvc-7.1 boost=source
bjam gcc-3.3 boost=source bjam gcc-3.3 boost=source
bjam darwin-4.0 boost=source bjam darwin-4.0 boost=source
</pre> </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 <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>, variant. Some default build variants in BBv2 are <tt class="docutils literal">release</tt>, <tt class="docutils literal">debug</tt>,
<tt class="docutils literal"><span class="pre">profile</span></tt>.</p> <tt class="docutils literal">profile</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 <p>You can build libtorrent as a dll too, by typing <tt class="docutils literal">link=shared</tt>, or
<tt class="docutils literal"><span class="pre">link=static</span></tt> to build a static library.</p> <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 <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> 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"><span class="pre">static</span></tt>. Most operating systems will only allow linking shared against 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> the runtime, but on windows you can do both. Example:</p>
<pre class="literal-block"> <pre class="literal-block">
bjam msvc-7.1 link=static runtime-link=static boost=source bjam msvc-7.1 link=static runtime-link=static boost=source
</pre> </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"> <div class="warning">
<p class="first admonition-title">Warning</p> <p class="first admonition-title">Warning</p>
<p class="last">If you link statically to the runtime library, you cannot build libtorrent <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 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 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 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>
<div class="note"> <div class="note">
<p class="first admonition-title">Note</p> <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 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 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"><span class="pre">librt</span></tt>.</p> bjam command line. This will make libtorrent link against <tt class="docutils literal">librt</tt>.</p>
</div> </div>
<div class="note"> <div class="note">
<p class="first admonition-title">Note</p> <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 <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> 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 <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 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"><span class="pre">bjam</span></tt>.</p> 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"><span class="pre">msvc</span></tt> toolset, you cannot run it <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"><span class="pre">cmd</span></tt> terminal. The same goes for 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. 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 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">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"><span class="pre">/cygdrive/c/boost_1_34_0</span></tt>). In the windows environment, they should have the typical <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> windows format (<tt class="docutils literal"><span class="pre">c:/boost_1_34_0</span></tt>).</p>
<div class="note"> <div class="note">
<p class="first admonition-title">Note</p> <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 in path names. If you want spaces in your paths, make sure to quote them
with double quotes (&quot;).</p> with double quotes (&quot;).</p>
</div> </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> For more build configuration flags see <a class="reference internal" href="#build-configurations">Build configurations</a>.</p>
<p>Build features:</p> <p>Build features:</p>
<table border="1" class="docutils"> <table border="1" class="docutils">
@ -255,74 +261,74 @@ For more build configuration flags see <a class="reference internal" href="#buil
</tr> </tr>
</thead> </thead>
<tbody valign="top"> <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"> <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 boost is installed and should be linked against
the system libraries.</li> 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 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> boost directory.</li>
</ul> </ul>
</td> </td>
</tr> </tr>
<tr><td><tt class="docutils literal"><span class="pre">boost-link</span></tt></td> <tr><td><tt class="docutils literal"><span class="pre">boost-link</span></tt></td>
<td><ul class="first last simple"> <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> 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> libraries.</li>
</ul> </ul>
</td> </td>
</tr> </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"> <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">none</tt> - no logging.</li>
<li><tt class="docutils literal"><span class="pre">default</span></tt> - basic session logging.</li> <li><tt class="docutils literal">default</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">verbose</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">errors</tt> - like verbose, but limited to errors.</li>
</ul> </ul>
</td> </td>
</tr> </tr>
<tr><td><tt class="docutils literal"><span class="pre">dht-support</span></tt></td> <tr><td><tt class="docutils literal"><span class="pre">dht-support</span></tt></td>
<td><ul class="first last simple"> <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> 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> 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> </ul>
</td> </td>
</tr> </tr>
<tr><td><tt class="docutils literal"><span class="pre">need-librt</span></tt></td> <tr><td><tt class="docutils literal"><span class="pre">need-librt</span></tt></td>
<td><ul class="first last simple"> <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> 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 requires you to link against librt.a. This is
typically the case on x86 64 bit systems.</li> typically the case on x86 64 bit systems.</li>
</ul> </ul>
</td> </td>
</tr> </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"> <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">auto</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">on</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">off</tt> - asserts are disabled</li>
<li><tt class="docutils literal"><span class="pre">production</span></tt> - assertion failures are logged <li><tt class="docutils literal">production</tt> - assertion failures are logged
to <tt class="docutils literal"><span class="pre">asserts.log</span></tt> in the current working to <tt class="docutils literal">asserts.log</tt> in the current working
directory, but won't abort the process.</li> directory, but won't abort the process.</li>
</ul> </ul>
</td> </td>
</tr> </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"> <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">off</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">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 in statically. Note that this code is under
LGPL license.</li> 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 is expected to be installed on the system and
it will be used.</li> it will be used.</li>
</ul> </ul>
@ -330,24 +336,24 @@ it will be used.</li>
</tr> </tr>
<tr><td><tt class="docutils literal"><span class="pre">upnp-logging</span></tt></td> <tr><td><tt class="docutils literal"><span class="pre">upnp-logging</span></tt></td>
<td><ul class="first last simple"> <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">off</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">on</tt> - creates &quot;upnp.log&quot; with the messages
sent to and received from UPnP devices.</li> sent to and received from UPnP devices.</li>
</ul> </ul>
</td> </td>
</tr> </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"> <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 libcrypto to enable https and encrypted
bittorrent connections.</li> 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> 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 libtommath and a custom rc4 implementation
(based on libtomcrypt). This is the default (based on libtomcrypt). This is the default
option.</li> 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 connections. The shipped public domain SHA-1
implementation is used.</li> implementation is used.</li>
</ul> </ul>
@ -355,40 +361,40 @@ implementation is used.</li>
</tr> </tr>
<tr><td><tt class="docutils literal"><span class="pre">pool-allocators</span></tt></td> <tr><td><tt class="docutils literal"><span class="pre">pool-allocators</span></tt></td>
<td><ul class="first last simple"> <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> 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 instead. Might be useful to debug buffer issues
with tools like electric fence or libgmalloc.</li> with tools like electric fence or libgmalloc.</li>
</ul> </ul>
</td> </td>
</tr> </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"> <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> 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> library (.so / .dll).</li>
</ul> </ul>
</td> </td>
</tr> </tr>
<tr><td><tt class="docutils literal"><span class="pre">runtime-link</span></tt></td> <tr><td><tt class="docutils literal"><span class="pre">runtime-link</span></tt></td>
<td><ul class="first last simple"> <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 run-time library (if available on your
platform).</li> 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> run-time library (default).</li>
</ul> </ul>
</td> </td>
</tr> </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"> <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> 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> 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> information.</li>
</ul> </ul>
</td> </td>
@ -397,41 +403,41 @@ information.</li>
<td><p class="first">This setting will only have an affect on windows. <td><p class="first">This setting will only have an affect on windows.
Other platforms are expected to support UTF-8.</p> Other platforms are expected to support UTF-8.</p>
<ul class="last simple"> <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> 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> used.</li>
</ul> </ul>
</td> </td>
</tr> </tr>
<tr><td><tt class="docutils literal"><span class="pre">invariant-checks</span></tt></td> <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 <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"> <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">on</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">off</tt> - internal invariant checks are
disabled. The resulting executable will run disabled. The resulting executable will run
faster than a regular debug build.</li> 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> checks.</li>
</ul> </ul>
</td> </td>
</tr> </tr>
<tr><td><tt class="docutils literal"><span class="pre">debug-symbols</span></tt></td> <tr><td><tt class="docutils literal"><span class="pre">debug-symbols</span></tt></td>
<td><ul class="first last simple"> <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 is useful for building release builds with
symbols.</li> 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> </ul>
</td> </td>
</tr> </tr>
<tr><td><tt class="docutils literal"><span class="pre">deprecated-functions</span></tt></td> <tr><td><tt class="docutils literal"><span class="pre">deprecated-functions</span></tt></td>
<td><ul class="first last simple"> <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 of the API (might produce warnings during build
when deprecated functions are used).</li> 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 API. Generates build errors when deprecated
functions are used.</li> functions are used.</li>
</ul> </ul>
@ -439,45 +445,63 @@ functions are used.</li>
</tr> </tr>
<tr><td><tt class="docutils literal"><span class="pre">full-stats</span></tt></td> <tr><td><tt class="docutils literal"><span class="pre">full-stats</span></tt></td>
<td><ul class="first last simple"> <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 and DHT and trackers. This uses a little bit
extra memory for each peer and torrent.</li> 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> upload and download rate.</li>
</ul> </ul>
</td> </td>
</tr> </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"> <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> 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">on</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">off</tt> - force not using iconv (disables locale
awareness except on windows).</li> awareness except on windows).</li>
</ul> </ul>
</td> </td>
</tr> </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"> <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">off</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">peoduction</tt> - enable asserts in release
builds, but don't abort, just log them to 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> <tt class="docutils literal">extern char const* libtorrent_assert_log</tt>.</li>
<li><tt class="docutils literal"><span class="pre">on</span></tt> - enable asserts in debug builds (this is <li><tt class="docutils literal">on</tt> - enable asserts in debug builds (this is
the default). On GNU systems, print a stack the default). On GNU systems, print a stack
trace of the assert and some more information.</li> 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> </ul>
</td> </td>
</tr> </tr>
</tbody> </tbody>
</table> </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> 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 <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 <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> 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 <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> 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>
<div class="section" id="building-with-autotools"> <div class="section" id="building-with-autotools">
<h2>building with autotools</h2> <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> unix/linux systems comes with these preinstalled.</p>
<p>The prerequisites for building libtorrent are boost.thread, boost.date_time <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 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.bind, boost.ref, boost.multi_index, boost.optional, boost.lexical_cast,
boost.integer, boost.iterator, boost.tuple, boost.array, boost.function, boost.integer, boost.iterator, boost.tuple, boost.array, boost.function,
boost.smart_ptr, boost.preprocessor, boost.static_assert.</p> 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> and boost.program_options.</p>
<div class="section" id="step-1-generating-the-build-system"> <div class="section" id="step-1-generating-the-build-system">
<h3>Step 1: Generating the build system</h3> <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"> <div class="section" id="step-2-running-configure">
<h3>Step 2: Running configure</h3> <h3>Step 2: Running configure</h3>
<p>In your shell, change directory to the libtorrent directory and run <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 is dependent on. If something is missing or can't be found it will print an
error telling you what failed.</p> error telling you what failed.</p>
<p>The most likely problem you may encounter is that the configure script won't <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 standard directories where the compiler will find them, but sometimes that
may not be the case. For example when installing boost on darwin using may not be the case. For example when installing boost on darwin using
darwinports (the package system based on BSD ports) all libraries are 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 installed to <tt class="docutils literal">/opt/local/lib</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 <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"><span class="pre">LDFLAGS</span></tt> and directories. You have to set the enviornment variables <tt class="docutils literal">LDFLAGS</tt> and
<tt class="docutils literal"><span class="pre">CXXFLAGS</span></tt> in order to make the compiler find those libs. In this example <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> you'd set them like this:</p>
<pre class="literal-block"> <pre class="literal-block">
export LDFLAGS=-L/opt/local/lib export LDFLAGS=-L/opt/local/lib
@ -539,7 +563,7 @@ library in this case. For more information about these options, run:</p>
./configure --help ./configure --help
</pre> </pre>
<p>On gentoo the boost libraries that are built with multi-threading support have <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 <p>You know that the boost libraries were found if you see the following output
from the configure script:</p> from the configure script:</p>
<pre class="literal-block"> <pre class="literal-block">
@ -575,10 +599,10 @@ with the following option:</p>
</div> </div>
<div class="section" id="id7"> <div class="section" id="id7">
<h3>Step 3: Building libtorrent</h3> <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> 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 <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 <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> invariant checks), you have to rerun the configure script and rebuild, like this:</p>
<pre class="literal-block"> <pre class="literal-block">
@ -611,7 +635,7 @@ defines you can use to control the build.</p>
</tr> </tr>
</thead> </thead>
<tbody valign="top"> <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, <td>If you define this macro, all asserts,
invariant checks and general debug code will be invariant checks and general debug code will be
removed. Since there is quite a lot of code in 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 compilation units having different views of
structs and class layouts and sizes.</td> structs and class layouts and sizes.</td>
</tr> </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 <td>This macro will enable logging of the session
events, such as tracker announces and incoming events, such as tracker announces and incoming
connections (as well as blocked connections).</td> connections (as well as blocked connections).</td>
</tr> </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 <td>This is defined by default by the Jamfile. It
disables the GeoIP features, and avoids linking disables the GeoIP features, and avoids linking
against LGPL:ed code.</td> against LGPL:ed code.</td>
</tr> </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 <td>If you define this macro, every peer connection
will log its traffic to a log file as well as will log its traffic to a log file as well as
the session log.</td> the session log.</td>
</tr> </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 <td>This will enable extra expensive invariant
checks in the storage, including logging of checks in the storage, including logging of
piece sorting.</td> piece sorting.</td>
</tr> </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 <td>Generates a &quot;upnp.log&quot; file with the UPnP
traffic. This is very useful when debugging traffic. This is very useful when debugging
support for various UPnP routers. support for various UPnP routers.
support for various UPnP routers.</td> support for various UPnP routers.</td>
</tr> </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 <td>This will create a log of all disk activity
which later can parsed and graphed using 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>
<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, <td>This will generate a log with transfer rates,
downloading torrents, seeding torrents, peers, downloading torrents, seeding torrents, peers,
connecting peers and disk buffers in use. The connecting peers and disk buffers in use. The
log can be parsed and graphed with 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>
<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 <td>If building on windows this will make sure the
UTF-8 strings in pathnames are converted into UTF-8 strings in pathnames are converted into
UTF-16 before they are passed to the file UTF-16 before they are passed to the file
operations.</td> operations.</td>
</tr> </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> <td>Disables use of <tt class="docutils literal"><span class="pre">boost::pool&lt;&gt;</span></tt>.</td>
</tr> </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 <td>If this is defined when including the
libtorrent headers, the classes and functions 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 on msvc and default visibility on GCC 4 and
later. Set this in your project if you're later. Set this in your project if you're
linking against libtorrent as a shared library. linking against libtorrent as a shared library.
(This is set by the Jamfile when (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>
<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 <td>If this is defined, the functions and classes
in libtorrent are marked with 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 default visibility on GCC 4 and later. This
should be defined when building libtorrent as should be defined when building libtorrent as
a shared library. (This is set by the Jamfile 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>
<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 <td>If this is defined, the support for trackerless
torrents will be disabled.</td> torrents will be disabled.</td>
</tr> </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 <td>This will enable verbose logging of the DHT
protocol traffic.</td> protocol traffic.</td>
</tr> </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 <td>This will disable any encryption support and
the dependencies of a crypto library. the dependencies of a crypto library.
Encryption support is the peer connection Encryption support is the peer connection
encrypted supported by clients such as encrypted supported by clients such as
uTorrent, Azureus and KTorrent. uTorrent, Azureus and KTorrent.
If this is not defined, either If this is not defined, either
<tt class="docutils literal"><span class="pre">TORRENT_USE_OPENSSL</span></tt> or <tt class="docutils literal">TORRENT_USE_OPENSSL</tt> or
<tt class="docutils literal"><span class="pre">TORRENT_USE_GCRYPT</span></tt> must be defined.</td> <tt class="docutils literal">TORRENT_USE_GCRYPT</tt> must be defined.</td>
</tr> </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 <td>On windows, this will cause the file IO
use wide character API, to properly support use wide character API, to properly support
non-ansi characters.</td> non-ansi characters.</td>
</tr> </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 <td>Defining this will disable the ability to
resolve countries of origin for peer IPs.</td> resolve countries of origin for peer IPs.</td>
</tr> </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 <td>This will disable internal invariant checks in
libtorrent. The invariant checks can sometime libtorrent. The invariant checks can sometime
be quite expensive, they typically don't scale 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 build in debug mode, with asserts enabled, but
make the resulting executable faster.</td> make the resulting executable faster.</td>
</tr> </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 <td>This will enable extra expensive invariant
checks. Useful for finding particular bugs checks. Useful for finding particular bugs
or for running before releases.</td> or for running before releases.</td>
</tr> </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 <td>This will exclude all deprecated functions from
the header files and cpp files.</td> the header files and cpp files.</td>
</tr> </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 <td>Define to either 0 or 1. Enables assert logging
in release builds.</td> in release builds.</td>
</tr> </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> <td>Disables all asserts.</td>
</tr> </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 <td>Uses the libc assert macro rather then the
custom one.</td> custom one.</td>
</tr> </tr>
</tbody> </tbody>
</table> </table>
<p>If you experience that libtorrent uses unreasonable amounts of cpu, it will <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> within the library.</p>
</div> </div>
<div class="section" id="building-openssl-for-windows"> <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"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <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> <title>client_test example program</title>
<link rel="stylesheet" type="text/css" href="../../css/base.css" /> <link rel="stylesheet" type="text/css" href="../../css/base.css" />
<link rel="stylesheet" type="text/css" href="../../css/rst.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. <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 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 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. 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 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 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 libtorrent will then download it from that peer (or from those peers if more
than one).</p> 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" /> <img alt="client_test.png" src="client_test.png" />
<p>The commands available in the client are:</p> <p>The commands available in the client are:</p>
<ul class="simple"> <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> 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> 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">i</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">d</tt> toggle download info. Will show the block list for each torrent,
showing downloaded and requested blocks.</li> 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">p</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">u</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">r</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">f</tt> toggle show file progress. Displays a list of all files and the
download progress for each file.</li> download progress for each file.</li>
</ul> </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 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 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 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"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <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> <title>libtorrent manual</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" /> <meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" /> <link rel="stylesheet" type="text/css" href="../../css/base.css" />
@ -49,7 +49,7 @@
<tr><th class="docinfo-name">Author:</th> <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> <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> <tr><th class="docinfo-name">Version:</th>
<td>0.16.0</td></tr> <td>1.0.0</td></tr>
</tbody> </tbody>
</table> </table>
<div class="contents topic" id="table-of-contents"> <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 <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 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> 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 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> </dd>
</dl> </dl>
</li> </li>
@ -90,13 +90,15 @@ descriptions on how to configure libtorrent for various situations for instance.
<dt>Code</dt> <dt>Code</dt>
<dd><p class="first">Contributing code for new features or bug-fixes is highly welcome. If you're interested <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 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 <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> algorithms, seeding policies, ports to new platforms etc.</p>
</dd> </dd>
</dl> </dl>
</li> </li>
</ol> </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> </div>
<div id="footer"> <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 New features might be better support for integrating with other services, new choking
algorithms, seeding policies, ports to new platforms etc. 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"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <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> <title></title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" /> <meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" /> <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> <p>libtorrent implements a few extensions to the Mainline DHT protocol.</p>
<div class="section" id="get-peers-response"> <div class="section" id="get-peers-response">
<h2>get_peers response</h2> <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 <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"><span class="pre">values</span></tt> as well. This is 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 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 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 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"> <div class="section" id="forward-compatibility">
<h2>forward compatibility</h2> <h2>forward compatibility</h2>
<p>In order to support future DHT messages, any message which is not recognized <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 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 to be properly forwarded by clients that don't understand them instead of
being blocked.</p> being blocked.</p>
@ -85,16 +85,16 @@ as a binary number describing the client version.</p>
</colgroup> </colgroup>
<tbody valign="top"> <tbody valign="top">
<tr><td>uTorrent</td> <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>
<tr><td>libtorrent</td> <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>
<tr><td>MooPolice</td> <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>
<tr><td>GetRight</td> <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> </tr>
</tbody> </tbody>
</table> </table>
@ -102,12 +102,12 @@ as a binary number describing the client version.</p>
<div class="section" id="ipv6-support"> <div class="section" id="ipv6-support">
<h2>IPv6 support</h2> <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><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 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 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 needs 18 bytes. The extension libtorrent applies is to add another key, called
<tt class="docutils literal"><span class="pre">nodes2</span></tt>.</p> <tt class="docutils literal">nodes2</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 <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 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 bytes node-id and then a variable length encoded IP address (6 bytes in IPv4 case
and 18 bytes in IPv6 case).</p> 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"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <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> <title>BitTorrent extension for DHT RSS feeds</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" /> <meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" /> <link rel="stylesheet" type="text/css" href="../../css/base.css" />
@ -49,7 +49,7 @@
<tr><th class="docinfo-name">Author:</th> <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> <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> <tr><th class="docinfo-name">Version:</th>
<td>Draft</td></tr> <td>1.0.0</td></tr>
</tbody> </tbody>
</table> </table>
<div class="contents topic" id="table-of-contents"> <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> the signatures of each individual item.</p>
<p>As with normal DHT announces, the write-token mechanism is used to <p>As with normal DHT announces, the write-token mechanism is used to
prevent IP spoof attacks.</p> 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> Every valid item that is announced, should be stored.</p>
<div class="section" id="terminology"> <div class="section" id="terminology">
<h1>terminology</h1> <h1>terminology</h1>
@ -122,31 +122,31 @@ key = SHA1(name + key)
| sig | | sig |
+---------+ +---------+
</pre> </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> 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 <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. 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> 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"><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 <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"><span class="pre">item</span></tt> or <tt class="docutils literal"><span class="pre">head</span></tt> (whichever 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> is included in the message).</p>
<p>All subscribers MUST verify that the item is announced under the correct DHT key <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 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 as the list-head. If a node fails any of these checks, it must be ignored and the
chain of items considered terminated.</p> chain of items considered terminated.</p>
<p>Each item holds a bencoded dictionary with arbitrary keys, except two mandatory keys: <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 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 are announced to an item, within reasonable restriction such as nesting, size and numeric
range of integers.</p> range of integers.</p>
</div> </div>
<div class="section" id="skip-lists"> <div class="section" id="skip-lists">
<h1>skip lists</h1> <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 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 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> 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"><span class="pre">next</span></tt> field as the remaining <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> size of the list warrants, within reason.</p>
<p>These skip lists allow for parallelized lookups of items and also makes it more efficient <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> 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; 40 O--------------------------&gt;
60 O------------------------------------------------------&gt; 60 O------------------------------------------------------&gt;
</pre> </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>
<div class="section" id="list-head"> <div class="section" id="list-head">
<h1>list-head</h1> <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 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 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 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 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.</p>
<p>The list head's DHT key (which it is announced to) MUST be the SHA1 hash of the name <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> <p>Any node MUST reject any list head which is announced under any other ID.</p>
</div> </div>
<div class="section" id="messages"> <div class="section" id="messages">
<h1>messages</h1> <h1>messages</h1>
<p>These are the messages to deal with linked lists.</p> <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 i.e. the node ID of the node sending the message, to maintain the structure of the DHT
network.</p> 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> <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"><span class="pre">announce_peer</span></tt>, when requesting an item and to write an item respectively.</p> and <tt class="docutils literal">announce_peer</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><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"> <div class="section" id="requesting-items">
<h2>requesting items</h2> <h2>requesting items</h2>
<p>This message can be used to request both a list head and a list item. When requesting <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 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"><span class="pre">n</span></tt> field is not required.</p> <tt class="docutils literal">n</tt> field is not required.</p>
<pre class="literal-block"> <pre class="literal-block">
{ {
&quot;a&quot;: &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;, &quot;y&quot;: &quot;q&quot;,
} }
</pre> </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>). <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"><span class="pre">target</span></tt> is the target node ID the item was written to.</p> <tt class="docutils literal">target</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>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> and it MUST match the name of the feed in the receiving node.</p>
</div> </div>
<div class="section" id="request-item-response"> <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;, &quot;y&quot;: &quot;r&quot;,
} }
</pre> </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> <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"><span class="pre">item</span></tt> field, using the <tt class="docutils literal"><span class="pre">key</span></tt> as 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"><span class="pre">key</span></tt> MUST match the public key of the feed.</p> 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"><span class="pre">item</span></tt> dictionary MAY contain arbitrary keys, and all keys MUST be stored for <p>The <tt class="docutils literal">item</tt> dictionary MAY contain arbitrary keys, and all keys MUST be stored for
items.</p> items.</p>
</div> </div>
<div class="section" id="announcing-items"> <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>
<div class="section" id="rss-feeds"> <div class="section" id="rss-feeds">
<h1>RSS feeds</h1> <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"> <dl class="docutils">
<dt>ih</dt> <dt>ih</dt>
<dd>The torrent's info hash</dd> <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> </dl>
<div class="section" id="example"> <div class="section" id="example">
<h2>example</h2> <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"> <pre class="literal-block">
{ {
&quot;a&quot;: &quot;a&quot;:
@ -374,7 +374,7 @@ the storing node no longer is in the set of the 8 closest nodes.</p>
} }
</pre> </pre>
<p>Strings are printed in hex for printability, but actual encoding is binary.</p> <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> is the signature of, i.e.:</p>
<pre class="literal-block"> <pre class="literal-block">
d9:info-hash20:7ea94c240691311dc0916a2a91eb7c3db2c6f3e43:key64:6bc1de5443d1 d9:info-hash20:7ea94c240691311dc0916a2a91eb7c3db2c6f3e43:key64:6bc1de5443d1

2
docs/dht_sec.html
View File

@ -49,7 +49,7 @@
<tr><th class="docinfo-name">Author:</th> <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> <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> <tr><th class="docinfo-name">Version:</th>
<td>Draft</td></tr> <td>1.0.0</td></tr>
</tbody> </tbody>
</table> </table>
<div class="contents topic" id="table-of-contents"> <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"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <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> <title>BitTorrent extension for arbitrary DHT store</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" /> <meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" /> <link rel="stylesheet" type="text/css" href="../../css/base.css" />
@ -49,7 +49,7 @@
<tr><th class="docinfo-name">Author:</th> <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> <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> <tr><th class="docinfo-name">Version:</th>
<td>Draft</td></tr> <td>1.0.0</td></tr>
</tbody> </tbody>
</table> </table>
<div class="contents topic" id="table-of-contents"> <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> 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, <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 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 <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> than 767 bytes.</p>
</div> </div>
@ -117,6 +119,8 @@ than 767 bytes.</p>
<h1>immutable items</h1> <h1>immutable items</h1>
<p>Immutable items are stored under their SHA-1 hash, and since they cannot be modified, <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> 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"> <div class="section" id="put-message">
<h2>put message</h2> <h2>put message</h2>
<p>Request:</p> <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 <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, 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 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 <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> 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"> <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"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <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> <title>libtorrent Examples</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" /> <meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" /> <link rel="stylesheet" type="text/css" href="../../css/base.css" />
@ -64,9 +64,9 @@
<div class="section" id="examples"> <div class="section" id="examples">
<h1>examples</h1> <h1>examples</h1>
<p>Except for the example programs in this manual, there's also a bigger example <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 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"> <div class="section" id="dump-torrent">
<h2>dump_torrent</h2> <h2>dump_torrent</h2>
<p>This is an example of a program that will take a torrent-file as a parameter and <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"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <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> <title></title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com Ludvig Strigeus, ludde&#64;utorrent.com" /> <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" /> <link rel="stylesheet" type="text/css" href="../../css/base.css" />
@ -76,7 +76,7 @@ support 1 new message:</p>
</tr> </tr>
</thead> </thead>
<tbody valign="top"> <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> <td>20</td>
</tr> </tr>
</tbody> </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 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 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 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> follows (including the message headers used by the bittorrent protocol):</p>
<table border="1" class="docutils"> <table border="1" class="docutils">
<colgroup> <colgroup>
@ -206,7 +206,7 @@ imaginable.</p>
</tr> </tr>
</thead> </thead>
<tbody valign="top"> <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"> <td><table border="1" class="first last docutils">
<colgroup> <colgroup>
<col width="88%" /> <col width="88%" />
@ -217,26 +217,26 @@ imaginable.</p>
</tr> </tr>
</thead> </thead>
<tbody valign="top"> <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> <td>1</td>
</tr> </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> <td>2</td>
</tr> </tr>
</tbody> </tbody>
</table> </table>
</td> </td>
</tr> </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> <td>6881</td>
</tr> </tr>
<tr><td><tt class="docutils literal"><span class="pre">v</span></tt></td> <tr><td><tt class="docutils literal">v</tt></td>
<td>&quot;µTorrent 1.2&quot;</td> <td>&quot;uTorrent 1.2&quot;</td>
</tr> </tr>
</tbody> </tbody>
</table> </table>
<p>and in the encoded form:</p> <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 <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 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 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> to ignore the subsequent handshake messages (or parts of them).</p>
<p>Subsequent handshake messages can be used to enable/disable extensions <p>Subsequent handshake messages can be used to enable/disable extensions
without restarting the connection. If a peer supports changing 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. 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: 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> 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 <p>The extension IDs must be stored for every peer, becuase every peer may have
different IDs for the same extension.</p> different IDs for the same extension.</p>
<p>This specification, deliberately, does not specify any extensions such as <p>This specification, deliberately, does not specify any extensions such as
peer-exchange or metadata exchange. This protocol is merely a transport peer-exchange or metadata exchange. This protocol is merely a transport
for the actual extensions to the bittorrent protocol and the extensions 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> extensions.</p>
</div> </div>
<div class="section" id="rationale"> <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 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 a global registry. The convention is to use a two letter prefix on the
extension message names, the prefix would identify the client first 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 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"><span class="pre">LT</span></tt> prefix.</p> 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 <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. 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 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> lookups each time it sends an extension message.</p>
<p>The reason for having a dictionary instead of having an array (using <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 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 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 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 it possible to map extensions in the handshake to existing extensions with
fixed message IDs.</p> 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"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <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> <title>libtorrent manual</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" /> <meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" /> <link rel="stylesheet" type="text/css" href="../../css/base.css" />
@ -49,7 +49,7 @@
<tr><th class="docinfo-name">Author:</th> <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> <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> <tr><th class="docinfo-name">Version:</th>
<td>0.16.0</td></tr> <td>1.0.0</td></tr>
</tbody> </tbody>
</table> </table>
<div class="contents topic" id="table-of-contents"> <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>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><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 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">no_peer_id=1</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">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>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>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> <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 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 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 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 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> 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%;" /> <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 <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 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 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 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> 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%;" /> <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" /> <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 <p>The root hash is built by hashing all the piece hashes pair-wise, until they all collapse
down to the root.</p> 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>
<div class="section" id="customizable-file-storage"> <div class="section" id="customizable-file-storage">
<h2>customizable file storage</h2> <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> 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 <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 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 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 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 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"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <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> <title></title>
<link rel="stylesheet" type="text/css" href="../../css/base.css" /> <link rel="stylesheet" type="text/css" href="../../css/base.css" />
<link rel="stylesheet" type="text/css" href="../../css/rst.css" /> <link rel="stylesheet" type="text/css" href="../../css/rst.css" />
@ -106,7 +106,7 @@ the library.</p>
<div class="section" id="feedback"> <div class="section" id="feedback">
<h2>Feedback</h2> <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>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>
<div class="section" id="license"> <div class="section" id="license">
<h2>license</h2> <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"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <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> <title></title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" /> <meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" /> <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 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 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 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 <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 is not supported as a stable API. Plugins should be considered spcific to a
specific version of libtorrent. Although, in practice the internals mostly 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"> <div class="section" id="plugin-interface">
<h1>plugin interface</h1> <h1>plugin interface</h1>
<p>The plugin interface consists of three base classes that the plugin may <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>. 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"><span class="pre">&lt;libtorrent/extensions.hpp&gt;</span></tt> header.</p> 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, <p>These plugins are instantiated for each session, torrent and possibly each peer,
respectively.</p> respectively.</p>
<p>For plugins that only need per torrent state, it is enough to only implement <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 <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 torrent has already been started and you want to hook in the extension at
run-time).</p> 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 <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 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 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> will be made on torrent events.</p>
<p>For more elaborate plugins which require session wide state, you would <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> it in to <tt class="docutils literal"><span class="pre">session::add_extension()</span></tt>.</p>
</div> </div>
<div class="section" id="plugin"> <div class="section" id="plugin">
@ -156,7 +156,7 @@ struct plugin
</div> </div>
<div class="section" id="torrent-plugin"> <div class="section" id="torrent-plugin">
<h1>torrent_plugin</h1> <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"> <pre class="literal-block">
struct torrent_plugin struct torrent_plugin
{ {
@ -194,15 +194,15 @@ boost::shared_ptr&lt;peer_plugin&gt; new_connection(peer_connection*);
</pre> </pre>
<p>This function is called each time a new peer is connected to the torrent. You <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 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> function).</p>
<p>If you need an extension to the peer connection (which most plugins do) you <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> 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 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, <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"><span class="pre">weak_ptr</span></tt>.</p> use <tt class="docutils literal">weak_ptr</tt>.</p>
<p>If this function throws an exception, the connection will be closed.</p> <p>If this function throws an exception, the connection will be closed.</p>
</div> </div>
<div class="section" id="on-piece-pass-on-piece-fail"> <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); void on_piece_failed(int index);
</pre> </pre>
<p>These hooks are called when a piece passes the hash check or fails the hash <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 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>
<div class="section" id="tick"> <div class="section" id="tick">
<h2>tick()</h2> <h2>tick()</h2>
@ -232,11 +232,11 @@ bool on_resume();
</pre> </pre>
<p>These hooks are called when the torrent is paused and unpaused respectively. <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 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 will have this hook function called, and the standard handler will also not be
invoked. So, returning true effectively overrides the standard behavior of invoked. So, returning true effectively overrides the standard behavior of
pause or unpause.</p> 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 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 standard handler, you have to keep your own state on whether you want standard
behavior or overridden behavior.</p> behavior or overridden behavior.</p>
@ -264,7 +264,7 @@ virtual void on_add_peer(tcp::endpoint const&amp; ip
</pre> </pre>
<p>This function is called whenever we hear about a peer from any peer source, <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> 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"> <pre class="literal-block">
enum peer_source_flags enum peer_source_flags
{ {
@ -276,14 +276,14 @@ enum peer_source_flags
incoming = 0x20 incoming = 0x20
}; };
</pre> </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"> <pre class="literal-block">
enum flags_t { enum flags_t {
first_time = 1, first_time = 1,
filtered = 2 filtered = 2
}; };
</pre> </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> peer list because of and IP filter, port filter, reserved ports filter.</p>
</div> </div>
</div> </div>
@ -336,18 +336,18 @@ struct disk_buffer_holder
char* buffer(); char* buffer();
}; };
</pre> </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 <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"><span class="pre">release</span></tt> returns the disk 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> 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>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 <p><tt class="docutils literal">buffer()</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> this buffer has been released, <tt class="docutils literal">buffer()</tt> will return 0.</p>
</div> </div>
<div class="section" id="custom-alerts"> <div class="section" id="custom-alerts">
<h1>custom alerts</h1> <h1>custom alerts</h1>
<p>Since plugins are running within internal libtorrent threads, one convenient <p>Since plugins are running within internal libtorrent threads, one convenient
way to communicate with the client is to post custom alerts.</p> 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> base class, looks like this:</p>
<pre class="literal-block"> <pre class="literal-block">
const static int alert_type = <em>&lt;unique alert ID&gt;</em>; 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>; } virtual char const* what() const { return <em>&lt;string literal of the name of this alert&gt;</em>; }
</pre> </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 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> <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"><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><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"><span class="pre">message()</span></tt> virtual function is expected to construct a useful string representation <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 of the alert and the event or data it represents. Something convenient to put in a log file
for instance.</p> 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 <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"><span class="pre">*this</span></tt> is all that's expected.</p> 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 <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> 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> your alert.</p>
<p>For more information, see the alert section in the <a class="reference external" href="manual.html">main manual</a>.</p> <p>For more information, see the alert section in the <a class="reference external" href="manual.html">main manual</a>.</p>
</div> </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"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <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> <title>creating torrents</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" /> <meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" /> <link rel="stylesheet" type="text/css" href="../../css/base.css" />
@ -49,7 +49,7 @@
<tr><th class="docinfo-name">Author:</th> <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> <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> <tr><th class="docinfo-name">Version:</th>
<td>0.16.0</td></tr> <td>1.0.0</td></tr>
</tbody> </tbody>
</table> </table>
<div class="contents topic" id="table-of-contents"> <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="#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="#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="#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> <li><a class="reference internal" href="#file-base-set-file-base" id="id9">file_base() set_file_base()</a></li>
</ul> </ul>
</li> </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 <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> 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 <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>
<div class="section" id="high-level-example"> <div class="section" id="high-level-example">
<h1>high level example</h1> <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); , boost::uint32_t flags = 0);
</pre> </pre>
</blockquote> </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> 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 <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"><span class="pre">p</span></tt> returns true are added, and directories for is encountered. files for which <tt class="docutils literal">p</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> 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"> <pre class="literal-block">
bool Pred(std::string const&amp; p); bool Pred(std::string const&amp; p);
</pre> </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 directory. If no predicate is specified, all files are added, and all directories
are traveresed.</p> are traveresed.</p>
<p>The &quot;..&quot; directory is never traversed.</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> constructor.</p>
</div> </div>
<div class="section" id="set-piece-hashes"> <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> </pre>
</blockquote> </blockquote>
<p>This function will assume that the files added to the torrent file exists at path <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> <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"><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> 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> must have the following signature:</p>
<pre class="literal-block"> <pre class="literal-block">
void Fun(int); void Fun(int);
</pre> </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> file error, the other overloads sets the error code to reflect the error, if any.</p>
</div> </div>
<div class="section" id="file-storage"> <div class="section" id="file-storage">
<h1>file_storage</h1> <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 size. Everything necessary to interpret a regular bittorrent storage
file structure. Its synopsis:</p> file structure. Its synopsis:</p>
<pre class="literal-block"> <pre class="literal-block">
@ -238,12 +238,30 @@ public:
int piece_length() const; int piece_length() const;
int piece_size(int index) const; int piece_size(int index) const;
// index accessors
sha1_hash const&amp; hash(int index) const; sha1_hash const&amp; hash(int index) const;
std::string const&amp; symlink(int index) const; std::string const&amp; symlink(int index) const;
time_t mtime(int index) const; time_t mtime(int index) const;
int file_index(int index) const;
size_type file_base(int index) const; size_type file_base(int index) const;
void set_file_base(int index, size_type off); 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::string const&amp; n);
void set_name(std::wstring 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); void add_file(std::wstring const&amp; p, size_type size, int flags = 0);
</pre> </pre>
</blockquote> </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 file attributes is an extension and may not work in all bittorrent clients.
The possible arreibutes are:</p> The possible arreibutes are:</p>
<pre class="literal-block"> <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> 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. <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 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 <p>The built in functions to traverse a directory to add files will
make sure this requirement is fulfilled.</p> make sure this requirement is fulfilled.</p>
</div> </div>
<div class="section" id="hash-symlink-mtime-file-index"> <div class="section" id="hash-symlink-mtime-file-path-file-size-pad-file-at">
<h2>hash() symlink() mtime() file_index()</h2> <h2>hash() symlink() mtime() file_path() file_size() pad_file_at()</h2>
<blockquote> <blockquote>
<pre class="literal-block"> <pre class="literal-block">
sha1_hash hash(int index) const; sha1_hash hash(int index) const;
std::string const&amp; symlink(int index) const; std::string const&amp; symlink(int index) const;
time_t mtime(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> </pre>
</blockquote> </blockquote>
<p>These functions are used to query the symlink, file hash, <p>These functions are used to query attributes of files at
modification time and the file-index from a file index.</p> a given index.</p>
<p>The file hash is a sha-1 hash of the file, or 0 if none was <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 provided in the torrent file. This can potentially be used to
join a bittorrent network with other file sharing networks.</p> join a bittorrent network with other file sharing networks.</p>
<p>The modification time is the posix time when a file was last <p>The <tt class="docutils literal">mtime()</tt> is the modification time is the posix
modified when the torrent was created, or 0 if it was not provided.</p> time when a file was last modified when the torrent
<p>The file index of a file is simply a 0 based index of the was created, or 0 if it was not included in the torrent file.</p>
file as they are ordered 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>
<div class="section" id="file-base-set-file-base"> <div class="section" id="file-base-set-file-base">
<h2>file_base() set_file_base()</h2> <h2>file_base() set_file_base()</h2>
@ -315,7 +338,7 @@ different file bases, so that they don't overlap.
</div> </div>
<div class="section" id="create-torrent"> <div class="section" id="create-torrent">
<h1>create_torrent</h1> <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"> <pre class="literal-block">
struct create_torrent struct create_torrent
{ {
@ -327,7 +350,7 @@ struct create_torrent
, calculate_file_hashes = 16 , calculate_file_hashes = 16
}; };
create_torrent(file_storage&amp; fs, int piece_size = 0, int pad_size_limit = -1 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); create_torrent(torrent_info const&amp; ti);
entry generate() const; entry generate() const;
@ -363,25 +386,25 @@ enum {
, calculate_file_hashes = 16 , calculate_file_hashes = 16
}; };
create_torrent(file_storage&amp; fs, int piece_size = 0, int pad_size_limit = -1 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); create_torrent(torrent_info const&amp; ti);
</pre> </pre>
</blockquote> </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 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> 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 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 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> 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 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 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> 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> be any combination of the following flags:</p>
<dl class="docutils"> <dl class="docutils">
<dt>optimize</dt> <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. recommended to have a fairly small piece size, say 64 kiB.
When creating merkle torrents, the full hash tree is also generated When creating merkle torrents, the full hash tree is also generated
and should be saved off separately. It is accessed through the 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> <dt>modification_time</dt>
<dd>This will include the file modification time as part of the torrent. <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 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, 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> this flag will have no effect.</dd>
</dl> </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>
<div class="section" id="generate"> <div class="section" id="generate">
<h2>generate()</h2> <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 <p>It may be useful to add custom entries to the torrent file before bencoding it
and saving it to disk.</p> and saving it to disk.</p>
<p>If anything goes wrong during torrent generation, this function will return <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> type of the entry:</p>
<pre class="literal-block"> <pre class="literal-block">
file_storage fs; file_storage fs;
@ -442,7 +468,7 @@ if (e.type() == entry::undefined_t)
} }
</pre> </pre>
<p>For instance, you cannot generate a torrent with 0 files in it. If you don't add <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>
<div class="section" id="set-comment"> <div class="section" id="set-comment">
<h2>set_comment()</h2> <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); void set_comment(char const* str);
</pre> </pre>
</blockquote> </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> The comment in a torrent file is optional.</p>
</div> </div>
<div class="section" id="set-creator"> <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); void set_creator(char const* str);
</pre> </pre>
</blockquote> </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> This is optional.</p>
</div> </div>
<div class="section" id="set-hash"> <div class="section" id="set-hash">
@ -471,7 +497,7 @@ This is optional.</p>
void set_hash(int index, sha1_hash const&amp; h); void set_hash(int index, sha1_hash const&amp; h);
</pre> </pre>
</blockquote> </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 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. 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> 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); void set_file_hash(int index, sha1_hash const&amp; h);
</pre> </pre>
</blockquote> </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 associated with this file (for multi-file torrents) or in the root info dictionary
for single-file torrents.</p> for single-file torrents.</p>
</div> </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 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 a directory containing a directory with the same name as this torrent, and all the
files of the torrent in it.</p> 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>
<div class="section" id="add-node"> <div class="section" id="add-node">
<h2>add_node()</h2> <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 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 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> 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>
<div class="section" id="set-priv-priv"> <div class="section" id="set-priv-priv">
<h2>set_priv() priv()</h2> <h2>set_priv() priv()</h2>
@ -558,7 +586,7 @@ std::vector&lt;sha1_hash&gt; const&amp; merkle_tree() const;
</pre> </pre>
</blockquote> </blockquote>
<p>This function returns the merkle hash tree, if the torrent was created as a merkle <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 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, 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 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"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <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> <title>libtorrent API Documentation</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" /> <meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" /> <link rel="stylesheet" type="text/css" href="../../css/base.css" />
@ -49,7 +49,7 @@
<tr><th class="docinfo-name">Author:</th> <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> <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> <tr><th class="docinfo-name">Version:</th>
<td>0.16.4</td></tr> <td>1.0.0</td></tr>
</tbody> </tbody>
</table> </table>
<div class="contents topic" id="table-of-contents"> <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 <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 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> 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 <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 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 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 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 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> 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. <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 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 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_routing_ips;
bool restrict_search_ips; bool restrict_search_ips;
bool extended_routing_table; bool extended_routing_table;
bool aggressive_lookups;
}; };
</pre> </pre>
<p><tt class="docutils literal">max_peers_reply</tt> is the maximum number of peers the node will send in <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 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 and ignored. libtorrent always tries to open the UDP socket on the same port
as the TCP socket.</p> 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 <p><tt class="docutils literal">is_dht_running()</tt> returns true if the DHT support has been started and false
otherwise.</p> otherwise.</p>
</div> </div>
@ -6321,7 +6333,7 @@ struct peer_disconnected_alert: peer_alert
<div class="section" id="invalid-request-alert"> <div class="section" id="invalid-request-alert">
<h2>invalid_request_alert</h2> <h2>invalid_request_alert</h2>
<p>This is a debug alert that is generated by an incoming invalid piece request. <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> request from the peer.</p>
<pre class="literal-block"> <pre class="literal-block">
struct invalid_request_alert: peer_alert 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[] = static const char const* swedish[] =
{ {
&quot;inget fel&quot;, &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;hash check misslyckades&quot;,
&quot;torrent filen är inte en dictionary&quot;, &quot;torrent filen ar inte en dictionary&quot;,
&quot;'info'-nyckeln saknas eller är korrupt i torrentfilen&quot;, &quot;'info'-nyckeln saknas eller ar korrupt i torrentfilen&quot;,
&quot;'info'-fältet är inte en dictionary&quot;, &quot;'info'-faltet ar inte en dictionary&quot;,
&quot;'piece length' fältet saknas eller är korrupt i torrentfilen&quot;, &quot;'piece length' faltet saknas eller ar korrupt i torrentfilen&quot;,
&quot;torrentfilen saknar namnfältet&quot;, &quot;torrentfilen saknar namnfaltet&quot;,
&quot;ogiltigt namn i torrentfilen (kan vara en attack)&quot;, &quot;ogiltigt namn i torrentfilen (kan vara en attack)&quot;,
// ... more strings here // ... 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"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <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> <title>projects using libtorrent</title>
<link rel="stylesheet" type="text/css" href="../../css/base.css" /> <link rel="stylesheet" type="text/css" href="../../css/base.css" />
<link rel="stylesheet" type="text/css" href="../../css/rst.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 <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> project listed here, let <a class="reference external" href="mailto:arvid&#64;rasterbar.com">me</a> know.</p>
<div class="entry container"> <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><strong>firetorrent</strong></p>
<p><a class="reference external" href="http://www.fireaddons.com/">firetorrent</a> is a single click torrent downloader plugin <p><a class="reference external" href="http://www.fireaddons.com/">firetorrent</a> is a single click torrent downloader plugin
for Firefox and Wyzo.</p> for Firefox and Wyzo.</p>
</div> </div>
<div class="entry container"> <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><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 <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 NAS device powered by Tonido software that allows you to access
your apps, files, music and media from anywhere.</p> your apps, files, music and media from anywhere.</p>
</div> </div>
<div class="entry container"> <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><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. <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 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> browse through multiple torrent trackers searching for particular file.</p>
</div> </div>
<div class="entry container"> <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><strong>qBittorrent</strong></p>
<p><a class="reference external" href="http://www.qbittorrent.org/">qBittorrent</a> is a QT bittorrent <p><a class="reference external" href="http://www.qbittorrent.org/">qBittorrent</a> is a QT bittorrent
client available for linux (likely client available for linux (likely
@ -76,7 +76,7 @@ portable to most other desktops as
well). Written by Christophe Dumez.</p> well). Written by Christophe Dumez.</p>
</div> </div>
<div class="entry container"> <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><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 <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 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> unparalleled searches and download speed to the user</p>
</div> </div>
<div class="entry container"> <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><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 <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 client. It has the ability to automatically resume partial downloads and
background to the system tray.</p> background to the system tray.</p>
</div> </div>
<div class="entry container"> <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><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 <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, an always running PC. Boasting Torrent downloader, DAAP streaming,
Web, E-mail, printer and FTP server etc.</p> Web, E-mail, printer and FTP server etc.</p>
</div> </div>
<div class="entry container"> <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><strong>btg</strong></p>
<p><a class="reference external" href="http://btg.berlios.de//">btg</a> is a unix bittorrent client <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 which is run as a daemon. It has
@ -110,32 +110,32 @@ connects to the daemon. One GUI
(ncurses) and one web interface (ncurses) and one web interface
(accessable through a web browser). (accessable through a web browser).
Written by Michael Wojciechowski Written by Michael Wojciechowski
and Johan Ström.</p> and Johan Strom.</p>
</div> </div>
<div class="entry container"> <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><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 <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> like surfing the web.</p>
<p>This means that anyone will have the ability to reach viewers via the Internet <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> directly on TV, without them having to connect a PC.</p>
</div> </div>
<div class="entry container"> <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><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 <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> interface.</p>
</div> </div>
<div class="entry container"> <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><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 <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 manager. Moreover, FDM is 100% safe, open-source software distributed under
GPL License.</p> GPL License.</p>
</div> </div>
<div class="entry container"> <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><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 <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 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> files without needing to leave your computer on.</p>
</div> </div>
<div class="entry container"> <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><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 <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 let users download a custom-built EXE program with the torrent file
integrated into it.</p> integrated into it.</p>
</div> </div>
<div class="entry container"> <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><strong>Flush</strong></p>
<p><a class="reference external" href="https://sourceforge.net/projects/flush/">Flush</a> is a GTK-based BitTorrent client.</p> <p><a class="reference external" href="https://sourceforge.net/projects/flush/">Flush</a> is a GTK-based BitTorrent client.</p>
</div> </div>
<div class="entry container"> <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><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 <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> content online and enjoy it on your PC and on your Mobile.</p>
</div> </div>
<div class="entry container"> <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><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 <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 and gtkmm for the interface, it has been designed to be a light and full
featured client.</p> featured client.</p>
</div> </div>
<div class="entry container"> <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><strong>electric sheep</strong></p>
<p><a class="reference external" href="http://electricsheep.org">electric sheep</a> is a screensaver <p><a class="reference external" href="http://electricsheep.org">electric sheep</a> is a screensaver
which collectively generates which collectively generates
@ -178,50 +178,50 @@ animations and lets the users
vote which one to live on.</p> vote which one to live on.</p>
</div> </div>
<div class="entry container"> <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><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 <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 video podcasts and video rss). Miro is designed to be easy to use and to give
you an elegant fullscreen viewing experience.</p> you an elegant fullscreen viewing experience.</p>
</div> </div>
<div class="entry container"> <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><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 <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> searching and downloading of torrents directly on your TV.</p>
</div> </div>
<div class="entry container"> <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><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 <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 C++ with the help of the Trolltech Qt 4 library. It's simple to use and
install.</p> install.</p>
</div> </div>
<div class="entry container"> <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><strong>LeechCraft</strong></p>
<p><a class="reference external" href="http://leechcraft.org/">LeechCraft</a> LeechCraft is a free open source cross-platform extensible <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 software, which primary goal is support of file sharing networks and
protocols like HTTP and FTP</p> protocols like HTTP and FTP</p>
</div> </div>
<div class="entry container"> <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><strong>MooPolice</strong></p>
<p><a class="reference external" href="http://www.moopolice.de">MooPolice</a> is a windows bittorrent <p><a class="reference external" href="http://www.moopolice.de">MooPolice</a> is a windows bittorrent
client with a quite unique look.</p> client with a quite unique look.</p>
</div> </div>
<div class="entry container"> <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><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> <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>
<div class="entry container"> <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><strong>BitRocket</strong></p>
<p><a class="reference external" href="http://www.bitrocket.org/">BitRocket</a> is a MacOS X bittorrent client.</p> <p><a class="reference external" href="http://www.bitrocket.org/">BitRocket</a> is a MacOS X bittorrent client.</p>
</div> </div>
<div class="entry container"> <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><strong>BitsCast</strong></p>
<p>RSS reader, podcast subscriber, <p>RSS reader, podcast subscriber,
video feed downloader, bittorrent 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> homepage for more info.</p>
</div> </div>
<div class="entry container"> <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><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> <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>
<div class="entry container"> <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><strong>BitSlug</strong></p>
<p><a class="reference external" href="http://bitslug.sourceforge.net/">BitSlug</a> is a MacOSX cocoa client.</p> <p><a class="reference external" href="http://bitslug.sourceforge.net/">BitSlug</a> is a MacOSX cocoa client.</p>
</div> </div>
<div class="entry container"> <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><strong>Arctic Torrent</strong></p>
<p><a class="reference external" href="http://www.int64.org/arctic.html">Arctic Torrent</a> is a light-weight <p><a class="reference external" href="http://www.int64.org/arctic.html">Arctic Torrent</a> is a light-weight
bittorrent client for windows. 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"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <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> <title>libtorrent python binding</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" /> <meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" /> <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> which is a python module that can be imported in a python program.</p>
<div class="section" id="building-using-setup-py"> <div class="section" id="building-using-setup-py">
<h2>building using setup.py</h2> <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. <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"><span class="pre">bjam</span></tt> and assume that you have boost 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"><span class="pre">$BOOST_PATH</span></tt>. The resulting executable is self-contained, it does 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> not depend any boost or libtorrent dlls.</p>
<p>On other systems, the setup.py is generated by running <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> <p>To build the Python bindings do:</p>
<ol class="arabic"> <ol class="arabic">
<li><p class="first">Run:</p> <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>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 <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> <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> <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"><span class="pre">bjam</span></tt> with the apropriate settings. For the available 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> build variants, see <a class="reference external" href="building.html#step-3-building-libtorrent">libtorrent build options</a>.</p>
<p>For example:</p> <p>For example:</p>
<pre class="literal-block"> <pre class="literal-block">
@ -124,7 +124,7 @@ the <a class="reference external" href="manual.html">main library reference</a>.
<dl class="docutils"> <dl class="docutils">
<dt>asio::tcp::endpoint</dt> <dt>asio::tcp::endpoint</dt>
<dd>The endpoint type is represented as a tuple of a string (as the address) and an int for <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> <dt>libtorrent::time_duration</dt>
<dd>The time duration is represented as a number of seconds in a regular integer.</dd> <dd>The time duration is represented as a number of seconds in a regular integer.</dd>
</dl> </dl>
@ -139,13 +139,13 @@ a list of entries.</p>
</ul> </ul>
<p><tt class="docutils literal"><span class="pre">create_torrent::add_node()</span></tt> takes two arguments, one string and one integer, <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> 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 <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"><span class="pre">session_settings</span></tt> struct. 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"><span class="pre">set_settings</span></tt>, the dictionary does not need to have every settings set, 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> 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> 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> directory.</p>
<p>A very simple example usage of the module would be something like this:</p> <p>A very simple example usage of the module would be something like this:</p>
<pre class="literal-block"> <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"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <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> <title>libtorrent manual</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" /> <meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" /> <link rel="stylesheet" type="text/css" href="../../css/base.css" />
@ -62,7 +62,7 @@
<div class="section" id="running-and-building-tests"> <div class="section" id="running-and-building-tests">
<h1>running and building tests</h1> <h1>running and building tests</h1>
<p>Some of the tests of libtorrent are not self contained. For instance, in <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 <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> describes how to set up your environment to be able to run them.</p>
</div> </div>
@ -90,9 +90,9 @@ lighttpd -V
tool to use to test libtorrent's support for SOCKS4, SOCKS5, HTTPS and tool to use to test libtorrent's support for SOCKS4, SOCKS5, HTTPS and
HTTP proxies.</p> HTTP proxies.</p>
<p>You can download prebuilt binaries for the most common platforms on <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> <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"><span class="pre">PATH</span></tt>. For 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"><span class="pre">/bin</span></tt>.</p> instance <tt class="docutils literal">/bin</tt>.</p>
</div> </div>
<div class="section" id="openssl"> <div class="section" id="openssl">
<h1>OpenSSL</h1> <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 \ tester\ntest&#64;test.com&quot; | openssl req -new -x509 -keyout server.pem \
-out server.pem -days 365 -nodes -out server.pem -days 365 -nodes
</pre> </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> confiuration file.</p>
<p>OpenSSL comes installed with most Linux and BSD distros, including Mac OS X. <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> 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"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <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> <title>libtorrent manual</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" /> <meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" /> <link rel="stylesheet" type="text/css" href="../../css/base.css" />
@ -49,7 +49,7 @@
<tr><th class="docinfo-name">Author:</th> <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> <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> <tr><th class="docinfo-name">Version:</th>
<td>0.16.0</td></tr> <td>1.0.0</td></tr>
</tbody> </tbody>
</table> </table>
<div class="contents topic" id="table-of-contents"> <div class="contents topic" id="table-of-contents">
@ -90,7 +90,7 @@
<div class="section" id="tuning-libtorrent"> <div class="section" id="tuning-libtorrent">
<h1>tuning libtorrent</h1> <h1>tuning libtorrent</h1>
<p>libtorrent expose most constants used in the bittorrent engine for <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 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 that fits a wide range of needs. From low memory embedded devices to
servers seeding thousands of torrents. The default settings in libtorrent 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"> <div class="section" id="reducing-memory-footprint">
<h1>reducing memory footprint</h1> <h1>reducing memory footprint</h1>
<p>These are things you can do to reduce the memory footprint of libtorrent. You get <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> setting preset function.</p>
<p>Keep in mind that lowering memory usage will affect performance, always profile <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> 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> support, you need to patch parts of boost.</p>
<p>Also make sure to optimize for size when compiling.</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. <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 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 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 are different the structures will look different from the libtorrent side and from
the client side and memory corruption will follow.</p> 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 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> 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> <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 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 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 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 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 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 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. <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, 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 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> sets this value to 5 MB.</p>
</div> </div>
<div class="section" id="peers"> <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 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 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 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 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 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 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 of only certain torrents. For instance, you might only be interested in torrents that
are being downloaded.</p> 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> <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"><span class="pre">refresh_torrent_status</span></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 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 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 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 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> 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 <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> gnuplot and python).</p>
<div class="section" id="disk-metrics"> <div class="section" id="disk-metrics">
<h2>disk metrics</h2> <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 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> the disk I/O. The following table is an overview of these files and what they measure.</p>
<table border="1" class="docutils"> <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> </tr>
</thead> </thead>
<tbody valign="top"> <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 <td>This is a log of which operation the disk I/O thread is
engaged in, with timestamps. This tells you what the thread engaged in, with timestamps. This tells you what the thread
is spending its time doing.</td> is spending its time doing.</td>
</tr> </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 <td>This log keeps track of what the buffers allocated from the
disk buffer pool are used for. There are 5 categories. disk buffer pool are used for. There are 5 categories.
receive buffer, send buffer, write cache, read cache and receive buffer, send buffer, write cache, read cache and
temporary hash storage. This is key when optimizing memory temporary hash storage. This is key when optimizing memory
usage.</td> usage.</td>
</tr> </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 <td>This is a low level log of read and write operations, with
timestamps and file offsets. The file offsets are byte timestamps and file offsets. The file offsets are byte
offsets in the torrent (not in any particular file, in the 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"> <div class="section" id="disk-io-thread-log">
<h3>disk_io_thread.log</h3> <h3>disk_io_thread.log</h3>
<p>The structure of this log is simple. For each line, there are two columns, a timestamp and <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 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> 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 <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"><span class="pre">flushing</span></tt> tells you 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> the number of bytes that were flushed from the disk cache.</p>
<p>This is an example excerpt from a log:</p> <p>This is an example excerpt from a log:</p>
<pre class="literal-block"> <pre class="literal-block">
@ -458,8 +458,8 @@ the number of bytes that were flushed from the disk cache.</p>
8255 idle 8255 idle
8431 read 16384 8431 read 16384
</pre> </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 <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"><span class="pre">disk_io.png</span></tt>. 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> 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 <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 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 24910 receive buffer: 3
</pre> </pre>
<p>The time stamp is in milliseconds since start.</p> <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 <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"><span class="pre">disk_buffer.png</span></tt>.</p> 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" /> <img alt="disk_buffer_sample.png" src="disk_buffer_sample.png" />
<p>This is an example graph generated by the parse script.</p> <p>This is an example graph generated by the parse script.</p>
</div> </div>
@ -516,16 +516,16 @@ started, and the second one is where the operation ended.</p>
36766 read_end 367263744 36766 read_end 367263744
</pre> </pre>
<p>The disk access log does not have any good visualization tool yet. There is however a gnuplot <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" /> <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> <p>The density of the disk seeks tells you how hard the drive has to work.</p>
</div> </div>
</div> </div>
<div class="section" id="session-stats"> <div class="section" id="session-stats">
<h2>session stats</h2> <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 <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"><span class="pre">parse_session_stats.py</span></tt> 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"><span class="pre">session_stats_report/index.html</span></tt>.</p> 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> <p>The first line in the log contains all the field names, separated by colon:</p>
<pre class="literal-block"> <pre class="literal-block">
second:upload rate:download rate:downloading torrents:seeding torrents:peers... 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"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <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> <title>libtorrent manual</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" /> <meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" /> <link rel="stylesheet" type="text/css" href="../../css/base.css" />
@ -49,7 +49,7 @@
<tr><th class="docinfo-name">Author:</th> <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> <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> <tr><th class="docinfo-name">Version:</th>
<td>0.16.0</td></tr> <td>1.0.0</td></tr>
</tbody> </tbody>
</table> </table>
<div class="contents topic" id="table-of-contents"> <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"> <pre class="literal-block">
cwnd += gain * (target_delay - delay) cwnd += gain * (target_delay - delay)
</pre> </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>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 <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 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 baseline measurement, to cancel out any fixed delay. By focusing on the
variable delay along a link, it will specifically detect points where variable delay along a link, it will specifically detect points where
there might be congestion, since those points will have buffers.</p> 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. <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 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 be connected via a modem, with the same send buffer restrictions as we assume
@ -284,7 +284,7 @@ with jumbo frames.</p>
</div> </div>
<div class="section" id="clock-drift"> <div class="section" id="clock-drift">
<h2>clock drift</h2> <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 <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 skew which means clocks set to different values (but which may progress at the same
rate).</p> rate).</p>