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

regenerated documentation. added makefile for docs, added rst template file

This commit is contained in:
Arvid Norberg 2008-10-17 03:23:30 +00:00
parent 18017c3f72
commit 81bf8763f6
13 changed files with 1338 additions and 861 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

141
docs/building.html
View File

@ -3,54 +3,76 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title>libtorrent manual</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
<link rel="stylesheet" type="text/css" href="../../css/rst.css" />
<link rel="stylesheet" href="style.css" type="text/css" />
<style type="text/css">
/* Hides from IE-mac \*/
* html pre { height: 1%; }
/* End hide from IE-mac */
</style>
</head>
<body>
<div class="document" id="libtorrent-manual">
<div id="container">
<div id="headerNav">
<ul>
<li class="first"><a href="/">Home</a></li>
<li><a href="../../products.html">Products</a></li>
<li><a href="../../contact.html">Contact</a></li>
</ul>
</div>
<div id="header">
<h1><span>Rasterbar Software</span></h1>
<h2><span>Software developement and consulting</span></h2>
<span>
</span>
</div>
<div id="main">
<h1 class="title">libtorrent manual</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>Arvid Norberg, <a class="last reference" 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>
</tbody>
</table>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first"><a name="table-of-contents">Table of contents</a></p>
<p class="topic-title first">Table of contents</p>
<ul class="simple">
<li><a class="reference" href="#downloading-and-building" id="id9" name="id9">downloading and building</a><ul>
<li><a class="reference" href="#building-from-svn" id="id10" name="id10">building from svn</a></li>
<li><a class="reference" href="#building-with-bbv2" id="id11" name="id11">building with BBv2</a></li>
<li><a class="reference" href="#building-with-autotools" id="id12" name="id12">building with autotools</a></li>
<li><a class="reference" href="#building-with-other-build-systems" id="id13" name="id13">building with other build systems</a></li>
<li><a class="reference" href="#build-configurations" id="id14" name="id14">build configurations</a></li>
<li><a class="reference" href="#building-openssl-for-windows" id="id15" name="id15">building openssl for windows</a></li>
<li><a class="reference internal" href="#downloading-and-building" id="id9">downloading and building</a><ul>
<li><a class="reference internal" href="#building-from-svn" id="id10">building from svn</a></li>
<li><a class="reference internal" href="#building-with-bbv2" id="id11">building with BBv2</a></li>
<li><a class="reference internal" href="#building-with-autotools" id="id12">building with autotools</a></li>
<li><a class="reference internal" href="#building-with-other-build-systems" id="id13">building with other build systems</a></li>
<li><a class="reference internal" href="#build-configurations" id="id14">build configurations</a></li>
<li><a class="reference internal" href="#building-openssl-for-windows" id="id15">building openssl for windows</a></li>
</ul>
</li>
</ul>
</div>
<div class="section">
<h1><a id="downloading-and-building" name="downloading-and-building">downloading and building</a></h1>
<div class="section" id="downloading-and-building">
<h1>downloading and building</h1>
<p>To acquire the latest version of libtorrent, you'll have to grab it from SVN.
You'll find instructions on how to do this <a class="reference" 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
(BBv2) and autotools (for unix-like systems). If you still can't build after
following these instructions, you can usually get help in the <tt class="docutils literal"><span class="pre">#libtorrent</span></tt>
IRC channel on <tt class="docutils literal"><span class="pre">irc.freenode.net</span></tt>.</p>
<p>Community contributed build tutorials can be found on the <a class="reference" href="http://code.rasterbar.com/libtorrent/wiki/Building">wiki</a>.</p>
<div class="section">
<h2><a id="building-from-svn" name="building-from-svn">building from svn</a></h2>
<p>Community contributed build tutorials can be found on the <a class="reference external" href="http://code.rasterbar.com/libtorrent/wiki/Building">wiki</a>.</p>
<div class="section" id="building-from-svn">
<h2>building from svn</h2>
<p>To build libtorrent from svn you need to check out the libtorrent sources from
sourceforge and also check out the asio sources from its sourceforge cvs.
If you downloaded a release tarball, you can skip this section.</p>
<p>To prepare the directory structure for building, follow these steps:</p>
<ul class="simple">
<li>Check out libtorrent (<a class="reference" href="http://sourceforge.net/svn/?group_id=79942">instructions</a>).</li>
<li>Check out asio (<a class="reference" href="http://sourceforge.net/cvs/?group_id=122478">instructions</a>).</li>
<li>Check out libtorrent (<a class="reference external" href="http://sourceforge.net/svn/?group_id=79942">instructions</a>).</li>
<li>Check out asio (<a class="reference external" href="http://sourceforge.net/cvs/?group_id=122478">instructions</a>).</li>
<li>Copy the <tt class="docutils literal"><span class="pre">asio/include/asio/</span></tt> directory into the <tt class="docutils literal"><span class="pre">libtorrent/include/libtorrent/</span></tt>
directory. Alternatively you can make a symbolic link.</li>
<li>Copy <tt class="docutils literal"><span class="pre">asio/include/asio.hpp</span></tt> into <tt class="docutils literal"><span class="pre">libtorrent/include/libtorrent</span></tt>.</li>
@ -58,11 +80,11 @@ directory. Alternatively you can make a symbolic link.</li>
<p>Now the libtorrent directory is ready for building. Follow the steps in one
of the following sections depending on which build system you prefer to use.</p>
</div>
<div class="section">
<h2><a id="building-with-bbv2" name="building-with-bbv2">building with BBv2</a></h2>
<div class="section" id="building-with-bbv2">
<h2>building with BBv2</h2>
<p>The primary reason to use boost-build is that it will automatically build the
dependent boost libraries with the correct compiler settings, in order to
ensure that the build targets are link compatible (see <a class="reference" href="http://boost.org/more/separate_compilation.html">boost guidelines</a>
ensure that the build targets are link compatible (see <a class="reference external" href="http://boost.org/more/separate_compilation.html">boost guidelines</a>
for some details on this issue).</p>
<p>Since BBv2 will build the boost libraries for you, you need the full boost
source package. Having boost installed via some package system is usually not
@ -70,17 +92,17 @@ enough (and even if it is enough, the necessary environment variables are
usually not set by the package installer).</p>
<p>If you want to build against an installed copy of boost, you can skip directly
to step 3 (assuming you also have boost build installed).</p>
<div class="section">
<h3><a id="step-1-download-boost" name="step-1-download-boost">Step 1: Download boost</a></h3>
<p>You'll find boost <a class="reference" href="http://sourceforge.net/project/showfiles.php?group_id=7586&amp;package_id=8041&amp;release_id=619445">here</a>.</p>
<div class="section" id="step-1-download-boost">
<h3>Step 1: Download boost</h3>
<p>You'll find boost <a class="reference external" href="http://sourceforge.net/project/showfiles.php?group_id=7586&amp;package_id=8041&amp;release_id=619445">here</a>.</p>
<p>Extract the archive to some directory where you want it. For the sake of this
guide, let's assume you extract the package to <tt class="docutils literal"><span class="pre">c:\boost_1_34_0</span></tt> (I'm using
a windows path in this example since if you're on linux/unix you're more likely
to use the autotools). You'll need at least version 1.34 of the boost library
in order to build libtorrent.</p>
</div>
<div class="section">
<h3><a id="step-2-setup-bbv2" name="step-2-setup-bbv2">Step 2: Setup BBv2</a></h3>
<div class="section" id="step-2-setup-bbv2">
<h3>Step 2: Setup BBv2</h3>
<p>First you need to build <tt class="docutils literal"><span class="pre">bjam</span></tt>. You do this by opening a terminal (In
windows, run <tt class="docutils literal"><span class="pre">cmd</span></tt>). Change directory to
<tt class="docutils literal"><span class="pre">c:\boost_1_34_0\tools\jam\src</span></tt>. Then run the script called
@ -130,10 +152,10 @@ using darwin : 3.3 : g++-3.3 ;
using darwin : 4.0 : g++-4.0 ;
</pre>
<p>Note that the spaces around the semi-colons and colons are important!</p>
<p>Also see the <a class="reference" href="http://www.boost.org/doc/html/bbv2/installation.html">official installation instructions</a>.</p>
<p>Also see the <a class="reference external" href="http://www.boost.org/doc/html/bbv2/installation.html">official installation instructions</a>.</p>
</div>
<div class="section">
<h3><a id="step-3-building-libtorrent" name="step-3-building-libtorrent">Step 3: Building libtorrent</a></h3>
<div class="section" id="step-3-building-libtorrent">
<h3>Step 3: Building libtorrent</h3>
<p>When building libtorrent, the <tt class="docutils literal"><span class="pre">Jamfile</span></tt> expects the environment variable
<tt class="docutils literal"><span class="pre">BOOST_ROOT</span></tt> to be set to the boost installation directory. It uses this to
find the boost libraries it depends on, so they can be built and their headers
@ -195,7 +217,7 @@ Also, make sure the paths are correct in the different environments. In cygwin,
<tt class="docutils literal"><span class="pre">/cygdrive/c/boost_1_34_0</span></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>
<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.
For more build configuration flags see <a class="reference" 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>
<table border="1" class="docutils">
<colgroup>
@ -270,10 +292,10 @@ with the libtorrent package.</li>
<tr><td><tt class="docutils literal"><span class="pre">geoip</span></tt></td>
<td><ul class="first last simple">
<li><tt class="docutils literal"><span class="pre">off</span></tt> - geo ip lookups disabled</li>
<li><tt class="docutils literal"><span class="pre">static</span></tt> - <a class="reference" href="http://www.maxmind.com/app/api">MaxMind</a> geo ip lookup code linked
<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
in statically. Note that this code is under
LGPL license.</li>
<li><tt class="docutils literal"><span class="pre">shared</span></tt> - The <a class="reference" href="http://www.maxmind.com/app/api">MaxMind</a> geo ip lookup library
<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
is expected to be installed on the system and
it will be used.</li>
</ul>
@ -395,12 +417,12 @@ the name of the feature, just the value.</p>
<p>When building the example client on windows, you need to build with
<tt class="docutils literal"><span class="pre">link=static</span></tt> otherwise you may get unresolved external symbols for some
boost.program-options symbols.</p>
<p>For more information, see the <a class="reference" href="http://www.boost.org/tools/build/v2/index.html">Boost build v2 documentation</a>, or more
specifically <a class="reference" href="http://www.boost.org/doc/html/bbv2/reference.html#bbv2.advanced.builtins.features">the section on builtin features</a>.</p>
<p>For more information, see the <a class="reference external" href="http://www.boost.org/tools/build/v2/index.html">Boost build v2 documentation</a>, or more
specifically <a class="reference external" href="http://www.boost.org/doc/html/bbv2/reference.html#bbv2.advanced.builtins.features">the section on builtin features</a>.</p>
</div>
</div>
<div class="section">
<h2><a id="building-with-autotools" name="building-with-autotools">building with autotools</a></h2>
<div class="section" id="building-with-autotools">
<h2>building with autotools</h2>
<p>First of all, you need to install <tt class="docutils literal"><span class="pre">automake</span></tt> and <tt class="docutils literal"><span class="pre">autoconf</span></tt>. Many
unix/linux systems comes with these preinstalled.</p>
<p>The prerequisites for building libtorrent are boost.thread, boost.date_time
@ -411,11 +433,11 @@ boost.integer, boost.iterator, boost.tuple, boost.array, boost.function,
boost.smart_ptr, boost.preprocessor, boost.static_assert.</p>
<p>If you want to build the <tt class="docutils literal"><span class="pre">client_test</span></tt> example, you'll also need boost.regex
and boost.program_options.</p>
<div class="section">
<h3><a id="step-1-generating-the-build-system" name="step-1-generating-the-build-system">Step 1: Generating the build system</a></h3>
<div class="section" id="step-1-generating-the-build-system">
<h3>Step 1: Generating the build system</h3>
<p>No build system is present if libtorrent is checked out from CVS - it
needs to be generated first. If you're building from a released tarball,
you may skip directly to <a class="reference" href="#step-2-running-configure">Step 2: Running configure</a>.</p>
you may skip directly to <a class="reference internal" href="#step-2-running-configure">Step 2: Running configure</a>.</p>
<p>Execute the following commands, in the given order, to generate
the build system:</p>
<pre class="literal-block">
@ -427,8 +449,8 @@ autoconf
</pre>
<p>On darwin/OSX you have to run <tt class="docutils literal"><span class="pre">glibtoolize</span></tt> instead of <tt class="docutils literal"><span class="pre">libtoolize</span></tt>.</p>
</div>
<div class="section">
<h3><a id="step-2-running-configure" name="step-2-running-configure">Step 2: Running configure</a></h3>
<div class="section" id="step-2-running-configure">
<h3>Step 2: Running configure</h3>
<p>In your shell, change directory to the libtorrent directory and run
<tt class="docutils literal"><span class="pre">./configure</span></tt>. This will look for libraries and C++ features that libtorrent
is dependent on. If something is missing or can't be found it will print an
@ -476,8 +498,8 @@ checking for main in -lboost_thread... yes
directory contains spaces. Make sure you either rename the directories with
spaces in their names to remove the spaces or move the libtorrent directory.</p>
</div>
<div class="section">
<h3><a id="creating-a-debug-build" name="creating-a-debug-build">Creating a debug build</a></h3>
<div class="section" id="creating-a-debug-build">
<h3>Creating a debug build</h3>
<p>To tell configure to build a debug version (with debug info, asserts
and invariant checks enabled), you have to run the configure script
with the following option:</p>
@ -485,8 +507,8 @@ with the following option:</p>
./configure --enable-debug=yes
</pre>
</div>
<div class="section">
<h3><a id="creating-a-release-build" name="creating-a-release-build">Creating a release build</a></h3>
<div class="section" id="creating-a-release-build">
<h3>Creating a release build</h3>
<p>To tell the configure to build a release version (without debug info,
asserts and invariant checks), you have to run the configure script
with the following option:</p>
@ -495,8 +517,8 @@ with the following option:</p>
</pre>
<p>The above option make use of -DNDEBUG, which is used throughout libtorrent.</p>
</div>
<div class="section">
<h3><a id="id8" name="id8">Step 3: Building libtorrent</a></h3>
<div class="section" id="id8">
<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
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
@ -510,8 +532,8 @@ make
</pre>
</div>
</div>
<div class="section">
<h2><a id="building-with-other-build-systems" name="building-with-other-build-systems">building with other build systems</a></h2>
<div class="section" id="building-with-other-build-systems">
<h2>building with other build systems</h2>
<p>If you're making your own project file, note that there are two versions of
the file abstraction. There's one <tt class="docutils literal"><span class="pre">file_win.cpp</span></tt> which relies on windows
file API that supports files larger than 2 Gigabytes. This does not work in
@ -524,10 +546,10 @@ filenames, so if your target is Windows 2000 and up, you may want to use
<p>If you're building in MS Visual Studio, you may have to set the compiler
options &quot;force conformance in for loop scope&quot;, &quot;treat wchar_t as built-in
type&quot; and &quot;Enable Run-Time Type Info&quot; to Yes. For a detailed description
on how to build libtorrent with VS, see <a class="reference" href="http://code.rasterbar.com/libtorrent/wiki/Building">the wiki</a>.</p>
on how to build libtorrent with VS, see <a class="reference external" href="http://code.rasterbar.com/libtorrent/wiki/Building">the wiki</a>.</p>
</div>
<div class="section">
<h2><a id="build-configurations" name="build-configurations">build configurations</a></h2>
<div class="section" id="build-configurations">
<h2>build configurations</h2>
<p>By default libtorrent is built In debug mode, and will have pretty expensive
invariant checks and asserts built into it. If you want to disable such checks
(you want to do that in a release build) you can see the table below for which
@ -677,8 +699,8 @@ the header files and cpp files.</td>
definitely help to define <tt class="docutils literal"><span class="pre">NDEBUG</span></tt>, since it will remove the invariant checks
within the library.</p>
</div>
<div class="section">
<h2><a id="building-openssl-for-windows" name="building-openssl-for-windows">building openssl for windows</a></h2>
<div class="section" id="building-openssl-for-windows">
<h2>building openssl for windows</h2>
<p>To build openssl for windows with Visual Studio 7.1 (2003) execute the following commands
in a command shell:</p>
<pre class="literal-block">
@ -694,6 +716,17 @@ copy out32\ssleay32.lib &quot;C:\Program Files\Microsoft Visual Studio .NET 2003
be picked up by libtorrent.</p>
</div>
</div>
</div>
<div id="footer">
<span>Copyright &copy; 2005 Rasterbar Software.</span>
</div>
</div>
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
_uacct = "UA-1599045-1";
urchinTracker();
</script>
</div>
</body>
</html>

33
docs/client_test.html
View File

@ -5,10 +5,32 @@
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title>client_test example program</title>
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
<link rel="stylesheet" type="text/css" href="../../css/rst.css" />
<link rel="stylesheet" href="style.css" type="text/css" />
<style type="text/css">
/* Hides from IE-mac \*/
* html pre { height: 1%; }
/* End hide from IE-mac */
</style>
</head>
<body>
<div class="document" id="client-test-example-program">
<div id="container">
<div id="headerNav">
<ul>
<li class="first"><a href="/">Home</a></li>
<li><a href="../../products.html">Products</a></li>
<li><a href="../../contact.html">Contact</a></li>
</ul>
</div>
<div id="header">
<h1><span>Rasterbar Software</span></h1>
<h2><span>Software developement and consulting</span></h2>
<span>
</span>
</div>
<div id="main">
<h1 class="title">client_test example program</h1>
<p>Client test is a, more or less, complete bittorrent client. It lacks most
@ -50,6 +72,17 @@ instead of dowloading parts of pieces. It may make it easier to determine
which peer that sent the corrupt data if a piece fails the hash test.</p>
<img alt="unicode_support.png" src="unicode_support.png" />
<p>There's unicode support on linux, MacOS X and Windows.</p>
</div>
<div id="footer">
<span>Copyright &copy; 2005 Rasterbar Software.</span>
</div>
</div>
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
_uacct = "UA-1599045-1";
urchinTracker();
</script>
</div>
</body>
</html>

47
docs/dht_extensions.html
View File

@ -6,24 +6,46 @@
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title></title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
<link rel="stylesheet" type="text/css" href="../../css/rst.css" />
<link rel="stylesheet" href="style.css" type="text/css" />
<style type="text/css">
/* Hides from IE-mac \*/
* html pre { height: 1%; }
/* End hide from IE-mac */
</style>
</head>
<body>
<div class="document">
<div id="container">
<div id="headerNav">
<ul>
<li class="first"><a href="/">Home</a></li>
<li><a href="../../products.html">Products</a></li>
<li><a href="../../contact.html">Contact</a></li>
</ul>
</div>
<div id="header">
<h1><span>Rasterbar Software</span></h1>
<h2><span>Software developement and consulting</span></h2>
<span>
</span>
</div>
<div id="main">
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>Arvid Norberg, <a class="last reference" 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>
</tbody>
</table>
<div class="section">
<h1><a id="mainline-dht-extensions" name="mainline-dht-extensions">Mainline DHT extensions</a></h1>
<div class="section" id="mainline-dht-extensions">
<h1>Mainline DHT extensions</h1>
<p>libtorrent implements a few extensions to the Mainline DHT protocol.</p>
<div class="section">
<h2><a id="client-identification" name="client-identification">client identification</a></h2>
<div class="section" id="client-identification">
<h2>client identification</h2>
<p>In each DHT packet, an extra key is inserted named &quot;v&quot;. This is a string
describing the client and version used. This can help alot when debugging
and finding errors in client implementations. The string is encoded as four
@ -51,8 +73,8 @@ as a binary number describing the client version.</p>
</tbody>
</table>
</div>
<div class="section">
<h2><a id="ipv6-support" name="ipv6-support">IPv6 support</a></h2>
<div class="section" id="ipv6-support">
<h2>IPv6 support</h2>
<p>The DHT messages that don't support IPv6 are the <tt class="docutils literal"><span class="pre">nodes</span></tt> replies.
They encode all the contacts as 6 bytes packed together in sequence in a
string. The problem is that IPv6 endpoints cannot be encoded as 6 bytes, but
@ -66,6 +88,17 @@ and 18 bytes in IPv6 case).</p>
only IPv4 nodes present.</p>
</div>
</div>
</div>
<div id="footer">
<span>Copyright &copy; 2005 Rasterbar Software.</span>
</div>
</div>
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
_uacct = "UA-1599045-1";
urchinTracker();
</script>
</div>
</body>
</html>

65
docs/examples.html
View File

@ -3,41 +3,63 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title>libtorrent Examples</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
<link rel="stylesheet" type="text/css" href="../../css/rst.css" />
<link rel="stylesheet" href="style.css" type="text/css" />
<style type="text/css">
/* Hides from IE-mac \*/
* html pre { height: 1%; }
/* End hide from IE-mac */
</style>
</head>
<body>
<div class="document" id="libtorrent-examples">
<div id="container">
<div id="headerNav">
<ul>
<li class="first"><a href="/">Home</a></li>
<li><a href="../../products.html">Products</a></li>
<li><a href="../../contact.html">Contact</a></li>
</ul>
</div>
<div id="header">
<h1><span>Rasterbar Software</span></h1>
<h2><span>Software developement and consulting</span></h2>
<span>
</span>
</div>
<div id="main">
<h1 class="title">libtorrent Examples</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>Arvid Norberg, <a class="last reference" 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>
</tbody>
</table>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first"><a name="table-of-contents">Table of contents</a></p>
<p class="topic-title first">Table of contents</p>
<ul class="simple">
<li><a class="reference" href="#examples" id="id2" name="id2">examples</a><ul>
<li><a class="reference" href="#dump-torrent" id="id3" name="id3">dump_torrent</a></li>
<li><a class="reference" href="#simple-client" id="id4" name="id4">simple client</a></li>
<li><a class="reference" href="#make-torrent" id="id5" name="id5">make_torrent</a></li>
<li><a class="reference internal" href="#examples" id="id2">examples</a><ul>
<li><a class="reference internal" href="#dump-torrent" id="id3">dump_torrent</a></li>
<li><a class="reference internal" href="#simple-client" id="id4">simple client</a></li>
<li><a class="reference internal" href="#make-torrent" id="id5">make_torrent</a></li>
</ul>
</li>
</ul>
</div>
<div class="section">
<h1><a id="examples" name="examples">examples</a></h1>
<div class="section" id="examples">
<h1>examples</h1>
<p>Except for the example programs in this manual, there's also a bigger example
of a (little bit) more complete client, <tt class="docutils literal"><span class="pre">client_test</span></tt>. There are separate
instructions for how to use it <a class="reference" 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>
<div class="section">
<h2><a id="dump-torrent" name="dump-torrent">dump_torrent</a></h2>
<div class="section" id="dump-torrent">
<h2>dump_torrent</h2>
<p>This is an example of a program that will take a torrent-file as a parameter and
print information about it to std out:</p>
<pre class="literal-block">
@ -140,8 +162,8 @@ int main(int argc, char* argv[])
}
</pre>
</div>
<div class="section">
<h2><a id="simple-client" name="simple-client">simple client</a></h2>
<div class="section" id="simple-client">
<h2>simple client</h2>
<p>This is a simple client. It doesn't have much output to keep it simple:</p>
<pre class="literal-block">
int main(int argc, char* argv[])
@ -185,8 +207,8 @@ if (argc != 2)
}
</pre>
</div>
<div class="section">
<h2><a id="make-torrent" name="make-torrent">make_torrent</a></h2>
<div class="section" id="make-torrent">
<h2>make_torrent</h2>
<p>Shows how to create a torrent from a directory tree:</p>
<pre class="literal-block">
#include &lt;iostream&gt;
@ -277,6 +299,17 @@ int main(int argc, char* argv[])
</pre>
</div>
</div>
</div>
<div id="footer">
<span>Copyright &copy; 2005 Rasterbar Software.</span>
</div>
</div>
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
_uacct = "UA-1599045-1";
urchinTracker();
</script>
</div>
</body>
</html>

49
docs/extension_protocol.html
View File

@ -6,22 +6,44 @@
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title></title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com Ludvig Strigeus, ludde&#64;utorrent.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
<link rel="stylesheet" type="text/css" href="../../css/rst.css" />
<link rel="stylesheet" href="style.css" type="text/css" />
<style type="text/css">
/* Hides from IE-mac \*/
* html pre { height: 1%; }
/* End hide from IE-mac */
</style>
</head>
<body>
<div class="document">
<div id="container">
<div id="headerNav">
<ul>
<li class="first"><a href="/">Home</a></li>
<li><a href="../../products.html">Products</a></li>
<li><a href="../../contact.html">Contact</a></li>
</ul>
</div>
<div id="header">
<h1><span>Rasterbar Software</span></h1>
<h2><span>Software developement and consulting</span></h2>
<span>
</span>
</div>
<div id="main">
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>Arvid Norberg, <a class="reference" href="mailto:arvid&#64;rasterbar.com">arvid&#64;rasterbar.com</a>
Ludvig Strigeus, <a class="last reference" href="mailto:ludde&#64;utorrent.com">ludde&#64;utorrent.com</a></td></tr>
<td>Arvid Norberg, <a class="reference external" href="mailto:arvid&#64;rasterbar.com">arvid&#64;rasterbar.com</a>
Ludvig Strigeus, <a class="last reference external" href="mailto:ludde&#64;utorrent.com">ludde&#64;utorrent.com</a></td></tr>
</tbody>
</table>
<div class="section">
<h1><a id="extension-protocol-for-bittorrent" name="extension-protocol-for-bittorrent">extension protocol for bittorrent</a></h1>
<div class="section" id="extension-protocol-for-bittorrent">
<h1>extension protocol for bittorrent</h1>
<p>The intention of this protocol is to provide a simple and thin transport
for extensions to the bittorrent protocol. Supporting this protocol makes
it easy to add new extensions without interfering with the standard
@ -81,8 +103,8 @@ message as specified by the handshake.</td>
</tr>
</tbody>
</table>
<div class="section">
<h2><a id="handshake-message" name="handshake-message">handshake message</a></h2>
<div class="section" id="handshake-message">
<h2>handshake message</h2>
<p>The payload of the handshake message is a bencoded dictionary. All items
in the dictionary are optional. Any unknown names should be ignored
by the client. All parts of the dictionary are case sensitive.
@ -233,8 +255,8 @@ 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
extensions.</p>
</div>
<div class="section">
<h2><a id="rationale" name="rationale">rationale</a></h2>
<div class="section" id="rationale">
<h2>rationale</h2>
<p>The reason why the extension messages' IDs would be defined in the handshake
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
@ -265,6 +287,17 @@ protocol more readable for a human, but the BT protocol wasn't designed to
be a human readable protocol, so why bother.</p>
</div>
</div>
</div>
<div id="footer">
<span>Copyright &copy; 2005 Rasterbar Software.</span>
</div>
</div>
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
_uacct = "UA-1599045-1";
urchinTracker();
</script>
</div>
</body>
</html>

79
docs/features.html
View File

@ -6,30 +6,52 @@
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title>libtorrent manual</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
<link rel="stylesheet" type="text/css" href="../../css/rst.css" />
<link rel="stylesheet" href="style.css" type="text/css" />
<style type="text/css">
/* Hides from IE-mac \*/
* html pre { height: 1%; }
/* End hide from IE-mac */
</style>
</head>
<body>
<div class="document" id="libtorrent-manual">
<div id="container">
<div id="headerNav">
<ul>
<li class="first"><a href="/">Home</a></li>
<li><a href="../../products.html">Products</a></li>
<li><a href="../../contact.html">Contact</a></li>
</ul>
</div>
<div id="header">
<h1><span>Rasterbar Software</span></h1>
<h2><span>Software developement and consulting</span></h2>
<span>
</span>
</div>
<div id="main">
<h1 class="title">libtorrent manual</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>Arvid Norberg, <a class="last reference" 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>
</tbody>
</table>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first"><a name="table-of-contents">Table of contents</a></p>
<p class="topic-title first">Table of contents</p>
<ul class="simple">
<li><a class="reference" href="#introduction" id="id6" name="id6">introduction</a></li>
<li><a class="reference" href="#features" id="id7" name="id7">features</a></li>
<li><a class="reference" href="#portability" id="id8" name="id8">portability</a></li>
<li><a class="reference" href="#license" id="id9" name="id9">license</a></li>
<li><a class="reference internal" href="#introduction" id="id4">introduction</a></li>
<li><a class="reference internal" href="#features" id="id5">features</a></li>
<li><a class="reference internal" href="#portability" id="id6">portability</a></li>
<li><a class="reference internal" href="#license" id="id7">license</a></li>
</ul>
</div>
<div class="section">
<h1><a id="introduction" name="introduction">introduction</a></h1>
<div class="section" id="introduction">
<h1>introduction</h1>
<p>libtorrent is a C++ library that aims to be a good alternative to all the
other bittorrent implementations around. It is a
library and not a full featured client, although it comes with a working
@ -41,33 +63,33 @@ example client.</p>
<li>to be very easy to use</li>
</ul>
</div>
<div class="section">
<h1><a id="features" name="features">features</a></h1>
<div class="section" id="features">
<h1>features</h1>
<p>libtorrent is still being developed, however it is stable. It is an ongoing
project (including this documentation). The current state includes the
following features:</p>
<ul class="simple">
<li>trackerless torrents (using the Mainline kademlia DHT protocol) with
some <a class="reference" href="dht_extensions.html">DHT extensions</a>.</li>
some <a class="reference external" href="dht_extensions.html">DHT extensions</a>.</li>
<li>support for IPv6</li>
<li>NAT-PMP and UPnP support (automatic port mapping on routers that supports it)</li>
<li>piece-wise, unordered, incremental file allocation</li>
<li>uses separate threads for checking files and for main downloader, with a
fool-proof thread-safe library interface. (i.e. There's no way for the
user to cause a deadlock). (see <a class="reference" href="manual.html#threads">threads</a>)</li>
user to cause a deadlock). (see <a class="reference external" href="manual.html#threads">threads</a>)</li>
<li>adjusts the length of the request queue depending on download rate.</li>
<li>multitracker extension support (as <a class="reference" href="http://home.elp.rr.com/tur/multitracker-spec.txt">specified by John Hoffman</a>)</li>
<li>multitracker extension support (as <a class="reference external" href="http://home.elp.rr.com/tur/multitracker-spec.txt">specified by John Hoffman</a>)</li>
<li>supports files &gt; 2 gigabytes.</li>
<li>serves multiple torrents on a single port and in a single thread</li>
<li>fast resume support, a way to get rid of the costly piece check at the
start of a resumed torrent. Saves the storage state, piece_picker state
as well as all local peers in a separate fast-resume file.</li>
<li><a class="reference" href="manual.html#http-seeding">HTTP seeding</a>, as <a class="reference" href="http://www.getright.com/seedtorrent.html">specified by Michael Burford of GetRight</a>.</li>
<li><a class="reference external" href="manual.html#http-seeding">HTTP seeding</a>, as <a class="reference external" href="http://www.getright.com/seedtorrent.html">specified by Michael Burford of GetRight</a>.</li>
<li>piece picking on block-level (as opposed to piece-level).
This means it can download parts of the same piece from different peers.
It will also prefer to download whole pieces from single peers if the
download speed is high enough from that particular peer.</li>
<li>supports the <a class="reference" href="extension_protocol.html">udp-tracker protocol</a> by Olaf van der Spek.</li>
<li>supports the <a class="reference external" href="udp_tracker_protocol.html">udp-tracker protocol</a> by Olaf van der Spek.</li>
<li>queues torrents for file check, instead of checking all of them in parallel.</li>
<li>supports http proxies and basic proxy authentication</li>
<li>gzipped tracker-responses</li>
@ -76,7 +98,7 @@ unchoked peers</li>
<li>implements fair trade. User settable trade-ratio, must at least be 1:1,
but one can choose to trade 1 for 2 or any other ratio that isn't unfair
to the other party.</li>
<li>supports an <a class="reference" href="udp_tracker_protocol.html">extension protocol</a>. See <a class="reference" href="manual.html#extensions">extensions</a>.</li>
<li>supports an <a class="reference external" href="extension_protocol.html">extension protocol</a>. See <a class="reference external" href="manual.html#extensions">extensions</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>possibility to limit the number of connections.</li>
<li>delays have messages if there's no other outgoing traffic to the peer, and
@ -91,11 +113,11 @@ want to download.</li>
being connected</li>
</ul>
</div>
<div class="section">
<h1><a id="portability" name="portability">portability</a></h1>
<div class="section" id="portability">
<h1>portability</h1>
<p>libtorrent is portable at least among Windows, MacOS X and other UNIX-systems.
It uses Boost.Thread, Boost.Filesystem, Boost.Date_time and various other
boost libraries as well as <a class="reference" href="http://www.zlib.org">zlib</a> (shipped) and <a class="reference" href="http://asio.sf.net">asio</a> (shipped). At least version
boost libraries as well as <a class="reference external" href="http://www.zlib.org">zlib</a> (shipped) and <a class="reference external" href="http://asio.sf.net">asio</a> (shipped). At least version
1.33.1 of boost is required.</p>
<p>Since libtorrent uses asio, it will take full advantage of high performance
network APIs on the most popular platforms. I/O completion ports on windows,
@ -114,15 +136,26 @@ epoll on linux and kqueue on MacOS X and BSD.</p>
<li>msvc6</li>
</ul>
</div>
<div class="section">
<h1><a id="license" name="license">license</a></h1>
<p>libtorrent is released under the <a class="reference" href="http://www.opensource.org/licenses/bsd-license.php">BSD-license</a>.</p>
<div class="section" id="license">
<h1>license</h1>
<p>libtorrent is released under the <a class="reference external" href="http://www.opensource.org/licenses/bsd-license.php">BSD-license</a>.</p>
<p>This means that you can use the library in your project without having to
release its source code. The only requirement is that you give credit
to the author of the library by including the libtorrent license in your
software or documentation.</p>
<p><a class="reference" href="projects.html">Here's</a> a list of some projects that uses libtorrent.</p>
<p><a class="reference external" href="projects.html">Here's</a> a list of some projects that uses libtorrent.</p>
</div>
</div>
<div id="footer">
<span>Copyright &copy; 2005 Rasterbar Software.</span>
</div>
</div>
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
_uacct = "UA-1599045-1";
urchinTracker();
</script>
</div>
</body>
</html>

33
docs/index.html
View File

@ -5,10 +5,32 @@
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title></title>
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
<link rel="stylesheet" type="text/css" href="../../css/rst.css" />
<link rel="stylesheet" href="style.css" type="text/css" />
<style type="text/css">
/* Hides from IE-mac \*/
* html pre { height: 1%; }
/* End hide from IE-mac */
</style>
</head>
<body>
<div class="document">
<div id="container">
<div id="headerNav">
<ul>
<li class="first"><a href="/">Home</a></li>
<li><a href="../../products.html">Products</a></li>
<li><a href="../../contact.html">Contact</a></li>
</ul>
</div>
<div id="header">
<h1><span>Rasterbar Software</span></h1>
<h2><span>Software developement and consulting</span></h2>
<span>
</span>
</div>
<div id="main">
<div id="librarySidebar"><ul class="simple">
@ -85,6 +107,17 @@ library and not a full featured client, although it comes with a working
<p><a class="reference external" href="http://sourceforge.net"><img alt="sf_logo" src="http://sourceforge.net/sflogo.php?group_id=7994" /></a></p>
</div></div>
</div>
</div>
<div id="footer">
<span>Copyright &copy; 2005 Rasterbar Software.</span>
</div>
</div>
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
_uacct = "UA-1599045-1";
urchinTracker();
</script>
</div>
</body>
</html>

112
docs/libtorrent_plugins.html
View File

@ -3,41 +3,64 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title></title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
<link rel="stylesheet" type="text/css" href="../../css/rst.css" />
<link rel="stylesheet" href="style.css" type="text/css" />
<style type="text/css">
/* Hides from IE-mac \*/
* html pre { height: 1%; }
/* End hide from IE-mac */
</style>
</head>
<body>
<div class="document">
<div id="container">
<div id="headerNav">
<ul>
<li class="first"><a href="/">Home</a></li>
<li><a href="../../products.html">Products</a></li>
<li><a href="../../contact.html">Contact</a></li>
</ul>
</div>
<div id="header">
<h1><span>Rasterbar Software</span></h1>
<h2><span>Software developement and consulting</span></h2>
<span>
</span>
</div>
<div id="main">
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>Arvid Norberg, <a class="last reference" 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>
</tbody>
</table>
<div class="section">
<h1><a id="libtorrent-plugins" name="libtorrent-plugins">libtorrent plugins</a></h1>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
<div class="section" id="libtorrent-plugins">
<h1>libtorrent plugins</h1>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference" href="#libtorrent-plugins" id="id1" name="id1">libtorrent plugins</a><ul>
<li><a class="reference" href="#a-word-of-caution" id="id2" name="id2">a word of caution</a></li>
<li><a class="reference internal" href="#libtorrent-plugins" id="id1">libtorrent plugins</a><ul>
<li><a class="reference internal" href="#a-word-of-caution" id="id2">a word of caution</a></li>
</ul>
</li>
<li><a class="reference" href="#plugin-interface" id="id3" name="id3">plugin interface</a></li>
<li><a class="reference" href="#torrent-plugin" id="id4" name="id4">torrent_plugin</a><ul>
<li><a class="reference" href="#new-connection" id="id5" name="id5">new_connection()</a></li>
<li><a class="reference" href="#on-piece-pass-on-piece-fail" id="id6" name="id6">on_piece_pass() on_piece_fail()</a></li>
<li><a class="reference" href="#tick" id="id7" name="id7">tick()</a></li>
<li><a class="reference" href="#on-pause-on-resume" id="id8" name="id8">on_pause() on_resume()</a></li>
<li><a class="reference" href="#on-files-checked" id="id9" name="id9">on_files_checked()</a></li>
<li><a class="reference internal" href="#plugin-interface" id="id3">plugin interface</a></li>
<li><a class="reference internal" href="#torrent-plugin" id="id4">torrent_plugin</a><ul>
<li><a class="reference internal" href="#new-connection" id="id5">new_connection()</a></li>
<li><a class="reference internal" href="#on-piece-pass-on-piece-fail" id="id6">on_piece_pass() on_piece_fail()</a></li>
<li><a class="reference internal" href="#tick" id="id7">tick()</a></li>
<li><a class="reference internal" href="#on-pause-on-resume" id="id8">on_pause() on_resume()</a></li>
<li><a class="reference internal" href="#on-files-checked" id="id9">on_files_checked()</a></li>
</ul>
</li>
<li><a class="reference" href="#peer-plugin" id="id10" name="id10">peer_plugin</a></li>
<li><a class="reference" href="#disk-buffer-holder" id="id11" name="id11">disk_buffer_holder</a></li>
<li><a class="reference internal" href="#peer-plugin" id="id10">peer_plugin</a></li>
<li><a class="reference internal" href="#disk-buffer-holder" id="id11">disk_buffer_holder</a></li>
</ul>
</div>
<p>libtorrent has a plugin interface for implementing extensions to the protocol.
@ -47,13 +70,13 @@ to fit a particular (closed) network.</p>
<p>In short, the plugin interface makes it possible to:</p>
<ul class="simple">
<li>register extension messages (sent in the extension handshake), see
<a class="reference" href="extension_protocol.html">extensions</a>.</li>
<a class="reference external" href="extension_protocol.html">extensions</a>.</li>
<li>add data and parse data from the extension handshake.</li>
<li>send extension messages and standard bittorrent messages.</li>
<li>override or block the handling of standard bittorrent messages.</li>
</ul>
<div class="section">
<h2><a id="a-word-of-caution" name="a-word-of-caution">a word of caution</a></h2>
<div class="section" id="a-word-of-caution">
<h2>a word of caution</h2>
<p>Writing your own plugin is a very easy way to introduce serious bugs such as
dead locks and race conditions. Since a plugin has access to internal
structures it is also quite easy to sabotage libtorrent's operation.</p>
@ -64,12 +87,12 @@ thread, you cannot use any of the member functions on the internal structures
in libtorrent, since those require the mutex to be locked. Futhermore, you would
also need to have a mutex on your own shared data within the plugin, to make
sure it is not accessed at the same time from the libtorrent thread (through a
callback). See <a class="reference" 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, use an internal queue, and do the actual sending in <tt class="docutils literal"><span class="pre">tick()</span></tt>.</p>
</div>
</div>
<div class="section">
<h1><a id="plugin-interface" name="plugin-interface">plugin interface</a></h1>
<div class="section" id="plugin-interface">
<h1>plugin interface</h1>
<p>The plugin interface consists of two base classes that the plugin may
implement. These are called <tt class="docutils literal"><span class="pre">torrent_plugin</span></tt> and <tt class="docutils literal"><span class="pre">peer_plugin</span></tt>. They are
both found in the <tt class="docutils literal"><span class="pre">&lt;libtorrent/extensions.hpp&gt;</span></tt> header.</p>
@ -92,8 +115,8 @@ 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
will be made on torrent events.</p>
</div>
<div class="section">
<h1><a id="torrent-plugin" name="torrent-plugin">torrent_plugin</a></h1>
<div class="section" id="torrent-plugin">
<h1>torrent_plugin</h1>
<p>The synopsis for <tt class="docutils literal"><span class="pre">torrent_plugin</span></tt> follows:</p>
<pre class="literal-block">
struct torrent_plugin
@ -115,8 +138,8 @@ struct torrent_plugin
<p>This is the base class for a torrent_plugin. Your derived class is (if added
as an extension) instantiated for each torrent in the session. The callback
hook functions are defined as follows.</p>
<div class="section">
<h2><a id="new-connection" name="new-connection">new_connection()</a></h2>
<div class="section" id="new-connection">
<h2>new_connection()</h2>
<pre class="literal-block">
boost::shared_ptr&lt;peer_plugin&gt; new_connection(peer_connection*);
</pre>
@ -133,8 +156,8 @@ held by the torrent object. So, it is generally a good idea to not keep a
use <tt class="docutils literal"><span class="pre">weak_ptr</span></tt>.</p>
<p>If this function throws an exception, the connection will be closed.</p>
</div>
<div class="section">
<h2><a id="on-piece-pass-on-piece-fail" name="on-piece-pass-on-piece-fail">on_piece_pass() on_piece_fail()</a></h2>
<div class="section" id="on-piece-pass-on-piece-fail">
<h2>on_piece_pass() on_piece_fail()</h2>
<pre class="literal-block">
void on_piece_pass(int index);
void on_piece_failed(int index);
@ -144,16 +167,16 @@ check, respectively. The <tt class="docutils literal"><span class="pre">index</s
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>
</div>
<div class="section">
<h2><a id="tick" name="tick">tick()</a></h2>
<div class="section" id="tick">
<h2>tick()</h2>
<pre class="literal-block">
void tick();
</pre>
<p>This hook is called approximately once per second. It is a way of making it
easy for plugins to do timed events, for sending messages or whatever.</p>
</div>
<div class="section">
<h2><a id="on-pause-on-resume" name="on-pause-on-resume">on_pause() on_resume()</a></h2>
<div class="section" id="on-pause-on-resume">
<h2>on_pause() on_resume()</h2>
<pre class="literal-block">
bool on_pause();
bool on_resume();
@ -169,8 +192,8 @@ handler it will recurse back into your handler, so in order to invoke the
standard handler, you have to keep your own state on whether you want standard
behavior or overridden behavior.</p>
</div>
<div class="section">
<h2><a id="on-files-checked" name="on-files-checked">on_files_checked()</a></h2>
<div class="section" id="on-files-checked">
<h2>on_files_checked()</h2>
<pre class="literal-block">
void on_files_checked();
</pre>
@ -180,8 +203,8 @@ checked. If there are no files to check, this function is called immediately.</p
can start downloading.</p>
</div>
</div>
<div class="section">
<h1><a id="peer-plugin" name="peer-plugin">peer_plugin</a></h1>
<div class="section" id="peer-plugin">
<h1>peer_plugin</h1>
<pre class="literal-block">
struct peer_plugin
{
@ -218,8 +241,8 @@ struct peer_plugin
};
</pre>
</div>
<div class="section">
<h1><a id="disk-buffer-holder" name="disk-buffer-holder">disk_buffer_holder</a></h1>
<div class="section" id="disk-buffer-holder">
<h1>disk_buffer_holder</h1>
<pre class="literal-block">
struct disk_buffer_holder
{
@ -236,6 +259,17 @@ buffer and transferres ownership and responsibility to free it to the caller.</p
<p><tt class="docutils literal"><span class="pre">buffer()</span></tt> returns the pointer without transferring responsibility. If
this buffer has been released, <tt class="docutils literal"><span class="pre">buffer()</span></tt> will return 0.</p>
</div>
</div>
<div id="footer">
<span>Copyright &copy; 2005 Rasterbar Software.</span>
</div>
</div>
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
_uacct = "UA-1599045-1";
urchinTracker();
</script>
</div>
</body>
</html>

30
docs/makefile Normal file
View File

@ -0,0 +1,30 @@
WEB_PATH = ~/Documents/rasterbar/web/products/libtorrent
DOCUTILS = ~/docutils
TARGETS = index.html \
udp_tracker_protocol.html \
projects.html \
client_test.html \
manual.html \
building.html \
features.html \
examples.html \
extension_protocol.html \
dht_extensions.html \
libtorrent_plugins.html
all: $(TARGETS)
%.pdf:%.tex
texexec --pdf $?
%.tex:%.rst
$(DOCUTILS)/tools/rst2context.py $? $@
%.html:%.rst
python $(DOCUTILS)/tools/rst2html.py --template=template.txt --stylesheet-path=style.css --link-stylesheet --no-toc-backlinks $? > $@
cp $@ $(WEB_PATH)/$@
clean:
rm -f $(TARGETS) round_trip_distribution.log

1423
docs/manual.html
View File

File diff suppressed because it is too large Load Diff

33
docs/projects.html
View File

@ -5,10 +5,32 @@
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title>projects using libtorrent</title>
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
<link rel="stylesheet" type="text/css" href="../../css/rst.css" />
<link rel="stylesheet" href="style.css" type="text/css" />
<style type="text/css">
/* Hides from IE-mac \*/
* html pre { height: 1%; }
/* End hide from IE-mac */
</style>
</head>
<body>
<div class="document" id="projects-using-libtorrent">
<div id="container">
<div id="headerNav">
<ul>
<li class="first"><a href="/">Home</a></li>
<li><a href="../../products.html">Products</a></li>
<li><a href="../../contact.html">Contact</a></li>
</ul>
</div>
<div id="header">
<h1><span>Rasterbar Software</span></h1>
<h2><span>Software developement and consulting</span></h2>
<span>
</span>
</div>
<div id="main">
<h1 class="title">projects using libtorrent</h1>
<p>These are some of the public projects that uses libtorrent. If you want your
@ -199,6 +221,17 @@ among other things, bittorrent.</p>
</tr>
</tbody>
</table>
</div>
<div id="footer">
<span>Copyright &copy; 2005 Rasterbar Software.</span>
</div>
</div>
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
_uacct = "UA-1599045-1";
urchinTracker();
</script>
</div>
</body>
</html>

41
docs/template.txt Normal file
View File

@ -0,0 +1,41 @@
%(head_prefix)s
%(head)s
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
<link rel="stylesheet" type="text/css" href="../../css/rst.css" />
%(stylesheet)s
<style type="text/css">
/* Hides from IE-mac \*/
* html pre { height: 1%%; }
/* End hide from IE-mac */
</style>
%(body_prefix)s
<div id="container">
<div id="headerNav">
<ul>
<li class="first"><a href="/">Home</a></li>
<li><a href="../../products.html">Products</a></li>
<li><a href="../../contact.html">Contact</a></li>
</ul>
</div>
<div id="header">
<h1><span>Rasterbar Software</span></h1>
<h2><span>Software developement and consulting</span></h2>
<span>
</span>
</div>
<div id="main">
%(body_pre_docinfo)s
%(docinfo)s
%(body)s
</div>
<div id="footer">
<span>Copyright &copy; 2005 Rasterbar Software.</span>
</div>
</div>
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
_uacct = "UA-1599045-1";
urchinTracker();
</script>
%(body_suffix)s

113
docs/udp_tracker_protocol.html
View File

@ -6,52 +6,74 @@
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title>Bittorrent udp-tracker protocol extension</title>
<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/rst.css" />
<link rel="stylesheet" href="style.css" type="text/css" />
<style type="text/css">
/* Hides from IE-mac \*/
* html pre { height: 1%; }
/* End hide from IE-mac */
</style>
</head>
<body>
<div class="document" id="bittorrent-udp-tracker-protocol-extension">
<div id="container">
<div id="headerNav">
<ul>
<li class="first"><a href="/">Home</a></li>
<li><a href="../../products.html">Products</a></li>
<li><a href="../../contact.html">Contact</a></li>
</ul>
</div>
<div id="header">
<h1><span>Rasterbar Software</span></h1>
<h2><span>Software developement and consulting</span></h2>
<span>
</span>
</div>
<div id="main">
<h1 class="title">Bittorrent udp-tracker protocol extension</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>Arvid Norberg, <a class="last reference" 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>
</tbody>
</table>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first"><a name="table-of-contents">Table of contents</a></p>
<p class="topic-title first">Table of contents</p>
<ul class="simple">
<li><a class="reference" href="#introduction" id="id2" name="id2">introduction</a></li>
<li><a class="reference" href="#connecting" id="id3" name="id3">connecting</a></li>
<li><a class="reference" href="#announcing" id="id4" name="id4">announcing</a></li>
<li><a class="reference" href="#scraping" id="id5" name="id5">scraping</a></li>
<li><a class="reference" href="#errors" id="id6" name="id6">errors</a></li>
<li><a class="reference" href="#actions" id="id7" name="id7">actions</a></li>
<li><a class="reference" href="#extensions" id="id8" name="id8">extensions</a><ul>
<li><a class="reference" href="#authentication" id="id9" name="id9">authentication</a></li>
<li><a class="reference internal" href="#introduction" id="id2">introduction</a></li>
<li><a class="reference internal" href="#connecting" id="id3">connecting</a></li>
<li><a class="reference internal" href="#announcing" id="id4">announcing</a></li>
<li><a class="reference internal" href="#scraping" id="id5">scraping</a></li>
<li><a class="reference internal" href="#errors" id="id6">errors</a></li>
<li><a class="reference internal" href="#actions" id="id7">actions</a></li>
<li><a class="reference internal" href="#extensions" id="id8">extensions</a><ul>
<li><a class="reference internal" href="#authentication" id="id9">authentication</a></li>
</ul>
</li>
<li><a class="reference" href="#credits" id="id10" name="id10">credits</a></li>
<li><a class="reference internal" href="#credits" id="id10">credits</a></li>
</ul>
</div>
<div class="section">
<h1><a id="introduction" name="introduction">introduction</a></h1>
<div class="section" id="introduction">
<h1>introduction</h1>
<p>A tracker with the protocol &quot;udp://&quot; in its URI
is supposed to be contacted using this protocol.</p>
<p>This protocol is supported by
<a class="reference" href="http://xbtt.sourceforge.net">xbt-tracker</a>.</p>
<a class="reference external" href="http://xbtt.sourceforge.net">xbt-tracker</a>.</p>
<p>For additional information and descritptions of
the terminology used in this document, see
the <a class="reference" href="http://wiki.theory.org/index.php/BitTorrentSpecification">protocol specification</a></p>
the <a class="reference external" href="http://wiki.theory.org/index.php/BitTorrentSpecification">protocol specification</a></p>
<p>All values are sent in network byte order (big endian). The sizes
are specified with ANSI-C standard types.</p>
<p>If no response to a request is received within 15 seconds, resend
the request. If no reply has been received after 60 seconds, stop
retrying.</p>
</div>
<div class="section">
<h1><a id="connecting" name="connecting">connecting</a></h1>
<div class="section" id="connecting">
<h1>connecting</h1>
<p>Client sends packet:</p>
<table border="1" class="docutils">
<colgroup>
@ -100,7 +122,7 @@ identify the protocol.</td>
<td>action</td>
<td>Describes the type of packet, in this
case it should be 0, for connect.
If 3 (for error) see <a class="reference" href="#errors">errors</a>.</td>
If 3 (for error) see <a class="reference internal" href="#errors">errors</a>.</td>
</tr>
<tr><td>int32_t</td>
<td>transaction_id</td>
@ -120,8 +142,8 @@ anymore.</td>
</tbody>
</table>
</div>
<div class="section">
<h1><a id="announcing" name="announcing">announcing</a></h1>
<div class="section" id="announcing">
<h1>announcing</h1>
<p>Client sends packet:</p>
<table border="1" class="docutils">
<colgroup>
@ -144,7 +166,7 @@ establishing the connection.</td>
<tr><td>int32_t</td>
<td>action</td>
<td>Action. in this case, 1 for announce.
See <a class="reference" href="#actions">actions</a>.</td>
See <a class="reference internal" href="#actions">actions</a>.</td>
</tr>
<tr><td>int32_t</td>
<td>transaction_id</td>
@ -209,7 +231,7 @@ in the reply. Use -1 for default.</td>
</tr>
<tr><td>uint16_t</td>
<td>extensions</td>
<td>See <a class="reference" href="#extensions">extensions</a></td>
<td>See <a class="reference internal" href="#extensions">extensions</a></td>
</tr>
</tbody>
</table>
@ -231,8 +253,8 @@ in the reply. Use -1 for default.</td>
<td>action</td>
<td>The action this is a reply to. Should
in this case be 1 for announce.
If 3 (for error) see <a class="reference" href="#errors">errors</a>.
See <a class="reference" href="#actions">actions</a>.</td>
If 3 (for error) see <a class="reference internal" href="#errors">errors</a>.
See <a class="reference internal" href="#actions">actions</a>.</td>
</tr>
<tr><td>int32_t</td>
<td>transaction_id</td>
@ -282,8 +304,8 @@ seeding.</td>
</tbody>
</table>
</div>
<div class="section">
<h1><a id="scraping" name="scraping">scraping</a></h1>
<div class="section" id="scraping">
<h1>scraping</h1>
<p>Client sends packet:</p>
<table border="1" class="docutils">
<colgroup>
@ -306,7 +328,7 @@ establishing of the connection.</td>
<tr><td>int32_t</td>
<td>action</td>
<td>The action, in this case, 2 for
scrape. See <a class="reference" href="#actions">actions</a>.</td>
scrape. See <a class="reference internal" href="#actions">actions</a>.</td>
</tr>
<tr><td>int32_t</td>
<td>transaction_id</td>
@ -353,7 +375,7 @@ the MTU.</p>
<td>action</td>
<td>The action, should in this case be
2 for scrape.
If 3 (for error) see <a class="reference" href="#errors">errors</a>.</td>
If 3 (for error) see <a class="reference internal" href="#errors">errors</a>.</td>
</tr>
<tr><td>int32_t</td>
<td>transaction_id</td>
@ -393,8 +415,8 @@ leechers.</td>
</tbody>
</table>
</div>
<div class="section">
<h1><a id="errors" name="errors">errors</a></h1>
<div class="section" id="errors">
<h1>errors</h1>
<p>In case of a tracker error,</p>
<p>server replies packet:</p>
<table border="1" class="docutils">
@ -413,7 +435,7 @@ leechers.</td>
<tr><td>int32_t</td>
<td>action</td>
<td>The action, in this case 3, for error.
See <a class="reference" href="#actions">actions</a>.</td>
See <a class="reference internal" href="#actions">actions</a>.</td>
</tr>
<tr><td>int32_t</td>
<td>transaction_id</td>
@ -428,8 +450,8 @@ describing the error.</td>
</tbody>
</table>
</div>
<div class="section">
<h1><a id="actions" name="actions">actions</a></h1>
<div class="section" id="actions">
<h1>actions</h1>
<p>The action fields has the following encoding:</p>
<blockquote>
<ul class="simple">
@ -440,17 +462,17 @@ describing the error.</td>
</ul>
</blockquote>
</div>
<div class="section">
<h1><a id="extensions" name="extensions">extensions</a></h1>
<div class="section" id="extensions">
<h1>extensions</h1>
<p>The extensions field is a bitmask. The following
bits are assigned:</p>
<blockquote>
<ul class="simple">
<li>1 = <a class="reference" href="#authentication">authentication</a>.</li>
<li>1 = <a class="reference internal" href="#authentication">authentication</a>.</li>
</ul>
</blockquote>
<div class="section">
<h2><a id="authentication" name="authentication">authentication</a></h2>
<div class="section" id="authentication">
<h2>authentication</h2>
<p>The packet will have an authentication part
appended to it. It has the following format:</p>
<table border="1" class="docutils">
@ -489,10 +511,21 @@ from the 20 bytes hash calculated.</td>
</table>
</div>
</div>
<div class="section">
<h1><a id="credits" name="credits">credits</a></h1>
<div class="section" id="credits">
<h1>credits</h1>
<p>Protocol designed by Olaf van der Spek</p>
</div>
</div>
<div id="footer">
<span>Copyright &copy; 2005 Rasterbar Software.</span>
</div>
</div>
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
_uacct = "UA-1599045-1";
urchinTracker();
</script>
</div>
</body>
</html>