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

clean up upnp error category by moving it into upnp.cpp, it's not properly encapsulated. added some documentation to torrent_handle. reformatted some documentation comments to honor an 80 column display

This commit is contained in:
Arvid Norberg 2014-02-02 03:05:55 +00:00
parent 0228a2a644
commit 15e2019332
42 changed files with 969 additions and 704 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
bindings/python/src/error_code.cpp
View File

@ -33,6 +33,7 @@ POSSIBILITY OF SUCH DAMAGE.
#include <boost/python.hpp>
#include <libtorrent/error_code.hpp>
#include <libtorrent/lazy_entry.hpp>
#include <libtorrent/upnp.hpp>
using namespace boost::python;
using namespace libtorrent;
@ -61,6 +62,9 @@ void bind_error_code()
def("get_libtorrent_category", &get_libtorrent_category
, return_internal_reference<>());
def("get_upnp_category", &get_upnp_category
, return_internal_reference<>());
def("get_http_category", &get_http_category
, return_internal_reference<>());

4
docs/building.html
View File

@ -778,8 +778,8 @@ the header files and cpp files.</td>
<td>Define to either 0 or 1. Enables assert logging
in release builds.</td>
</tr>
<tr><td><tt class="docutils literal">TORRENT_NO_ASSERTS</tt></td>
<td>Disables all asserts.</td>
<tr><td><tt class="docutils literal">TORRENT_USE_ASSERTS</tt></td>
<td>Define as 0 to disable asserts unconditionally.</td>
</tr>
<tr><td><tt class="docutils literal">TORRENT_USE_SYSTEM_ASSERTS</tt></td>
<td>Uses the libc assert macro rather then the

2
docs/client_test.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.11: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.10: 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" />

2
docs/contributing.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.11: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.10: 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" />

2
docs/dht_extensions.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.11: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.10: 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" />

2
docs/dht_rss.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.11: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.10: http://docutils.sourceforge.net/" />
<title>BitTorrent extension for DHT RSS feeds</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />

2
docs/dht_sec.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.11: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.10: http://docutils.sourceforge.net/" />
<title>BitTorrent DHT security extension</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />

86
docs/dht_store.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.11: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.10: http://docutils.sourceforge.net/" />
<title>BitTorrent extension for arbitrary DHT store</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
@ -68,8 +68,13 @@
</li>
<li><a class="reference internal" href="#signature-verification" id="id10">signature verification</a></li>
<li><a class="reference internal" href="#expiration" id="id11">expiration</a></li>
<li><a class="reference internal" href="#test-vector" id="id12">test vector</a></li>
<li><a class="reference internal" href="#resources" id="id13">resources</a></li>
<li><a class="reference internal" href="#test-vectors" id="id12">test vectors</a><ul>
<li><a class="reference internal" href="#test-1-mutable" id="id13">test 1 (mutable)</a></li>
<li><a class="reference internal" href="#test-2-mutable-with-salt" id="id14">test 2 (mutable with salt)</a></li>
<li><a class="reference internal" href="#test-3-immutable" id="id15">test 3 (immutable)</a></li>
</ul>
</li>
<li><a class="reference internal" href="#resources" id="id16">resources</a></li>
</ul>
</div>
<p>This is a proposal for an extension to the BitTorrent DHT to allow
@ -205,7 +210,7 @@ concatenated with the <tt class="docutils literal">v</tt> key. e.g. something li
<p>If the <tt class="docutils literal">salt</tt> key is present and non-empty, the salt string must be included
in what's signed. Note that if <tt class="docutils literal">salt</tt> is specified and an empty string, it is
as if it was not specified and nothing in addition to the sequence number and
the data is signed.</p>
the data is signed. The salt string may not be longer than 64 bytes.</p>
<p>When a salt is included in what is signed, the key <tt class="docutils literal">salt</tt> with the value of
the key is prepended in its bencoded form. For example, if <tt class="docutils literal">salt</tt> is &quot;foobar&quot;,
the buffer to be signed is:</p>
@ -256,6 +261,11 @@ items, with a single key that readers can verify. This is useful if the
publisher doesn't know ahead of time how many different items are to be
published. It can distribute a single public key for users to authenticate the
published blobs.</p>
<p>Note that the salt is not returned in the response to a <tt class="docutils literal">get</tt> request. This
is intentional. When issuing a <tt class="docutils literal">get</tt> request for an item is expected to
know what the salt is (because it is part of what the target ID that is being
looked up is derived from). There is no need to repeat it back for bystanders
to see.</p>
<p>The <tt class="docutils literal">cas</tt> field is optional. If present it is interpreted as the sha-1 hash of
the sequence number, <tt class="docutils literal">v</tt> field and possibly the <tt class="docutils literal">salt</tt> field, that is
expected to be replaced. The buffer to hash is the same as the one signed when
@ -308,6 +318,10 @@ too big.</td>
<tr><td>206</td>
<td>invalid signature</td>
</tr>
<tr><td>207</td>
<td>salt (i.e. <tt class="docutils literal">salt</tt> field)
too big.</td>
</tr>
<tr><td>301</td>
<td>the CAS hash mismatched,
re-read value and try
@ -347,7 +361,6 @@ item.</p>
&quot;k&quot;: <em>&lt;curve25519 public key (32 bytes string)&gt;</em>,
&quot;nodes&quot;: <em>&lt;IPv4 nodes close to 'target'&gt;</em>,
&quot;nodes6&quot;: <em>&lt;IPv6 nodes close to 'target'&gt;</em>,
&quot;salt&quot;: <em>&lt;optional salt to be appended to &quot;k&quot; when hashing (string)&gt;</em>
&quot;seq&quot;: <em>&lt;monotonically increasing sequence number (integer)&gt;</em>,
&quot;sig&quot;: <em>&lt;curve25519 signature (64 bytes string)&gt;</em>,
&quot;token&quot;: <em>&lt;write-token (string)&gt;</em>,
@ -391,9 +404,15 @@ to keep items alive, they SHOULD be re-announced once an hour.</p>
It would simply repeat the signature for a mutable put without having the
private key.</p>
</div>
<div class="section" id="test-vector">
<h1>test vector</h1>
<p>The buffer being signed:</p>
<div class="section" id="test-vectors">
<h1>test vectors</h1>
<div class="section" id="test-1-mutable">
<h2>test 1 (mutable)</h2>
<p>value:</p>
<pre class="literal-block">
12:Hello World!
</pre>
<p>buffer being signed:</p>
<pre class="literal-block">
3:seqi1e1:v12:Hello World!
</pre>
@ -406,12 +425,61 @@ private key.</p>
e06d3183d14159228433ed599221b80bd0a5ce8352e4bdf0262f76786ef1c74d
b7e7a9fea2c0eb269d61e3b38e450a22e754941ac78479d6c54e1faf6037881d
</pre>
<p>signature:</p>
<p><strong>target ID</strong>:</p>
<pre class="literal-block">
4a533d47ec9c7d95b1ad75f576cffc641853b750
</pre>
<p><strong>signature</strong>:</p>
<pre class="literal-block">
305ac8aeb6c9c151fa120f120ea2cfb923564e11552d06a5d856091e5e853cff
1260d3f39e4999684aa92eb73ffd136e6f4f3ecbfda0ce53a1608ecd7ae21f01
</pre>
</div>
<div class="section" id="test-2-mutable-with-salt">
<h2>test 2 (mutable with salt)</h2>
<p>value:</p>
<pre class="literal-block">
12:Hello World!
</pre>
<p>salt:</p>
<pre class="literal-block">
foobar
</pre>
<p>buffer being signed:</p>
<pre class="literal-block">
4:salt6:foobar3:seqi1e1:v12:Hello World!
</pre>
<p>public key:</p>
<pre class="literal-block">
77ff84905a91936367c01360803104f92432fcd904a43511876df5cdf3e7e548
</pre>
<p>private key:</p>
<pre class="literal-block">
e06d3183d14159228433ed599221b80bd0a5ce8352e4bdf0262f76786ef1c74d
b7e7a9fea2c0eb269d61e3b38e450a22e754941ac78479d6c54e1faf6037881d
</pre>
<p><strong>target ID</strong>:</p>
<pre class="literal-block">
411eba73b6f087ca51a3795d9c8c938d365e32c1
</pre>
<p><strong>signature</strong>:</p>
<pre class="literal-block">
6834284b6b24c3204eb2fea824d82f88883a3d95e8b4a21b8c0ded553d17d17d
df9a8a7104b1258f30bed3787e6cb896fca78c58f8e03b5f18f14951a87d9a08
</pre>
</div>
<div class="section" id="test-3-immutable">
<h2>test 3 (immutable)</h2>
<p>value:</p>
<pre class="literal-block">
12:Hello World!
</pre>
<p><strong>target ID</strong>:</p>
<pre class="literal-block">
e5f96f6f38320f0f33959cb4d3d656452117aadb
</pre>
</div>
</div>
<div class="section" id="resources">
<h1>resources</h1>
<p>Libraries that implement curve25519 DSA:</p>

2
docs/examples.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.11: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.10: 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" />

2
docs/extension_protocol.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.11: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.10: 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" />

2
docs/features.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.11: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.10: 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" />

2
docs/index.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.11: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.10: 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" />

2
docs/manual-ref.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.11: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.10: http://docutils.sourceforge.net/" />
<title>libtorrent API Documentation</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />

2
docs/projects.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.11: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.10: 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" />

7
docs/python_binding.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.11: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.10: http://docutils.sourceforge.net/" />
<title>libtorrent python binding</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
@ -158,7 +158,10 @@ ses.listen_on(6881, 6891)
e = lt.bdecode(open(&quot;test.torrent&quot;, 'rb').read())
info = lt.torrent_info(e)
h = ses.add_torrent(info, &quot;./&quot;, storage_mode=storage_mode_sparse)
params = { save_path: './', \
storage_mode: lt.storage_mode_t.storage_mode_sparse, \
ti: info }
h = ses.add_torrent(params)
while (not h.is_seed()):
s = h.status()

2
docs/reference-Alerts.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.11: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.10: http://docutils.sourceforge.net/" />
<title>Alerts</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />

11
docs/reference-Bencoding.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.11: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.10: http://docutils.sourceforge.net/" />
<title>Bencoding</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
@ -301,6 +301,14 @@ will throw <tt class="docutils literal"><span class="pre">libtorrent::type_error
<p>They will look for an element at the given key in the dictionary, if the
element cannot be found, they will return 0. If an element with the given
key is found, the return a pointer to it.</p>
<a name="to_string()"></a></div>
<div class="section" id="to-string">
<h2>to_string()</h2>
<pre class="literal-block">
std::string <strong>to_string</strong> () const;
</pre>
<p>returns a pretty-printed string representation
of the bencoded structure, with JSON-style syntax</p>
<a name="data_type"></a></div>
<div class="section" id="enum-data-type">
<h2>enum data_type</h2>
@ -721,6 +729,7 @@ it will throw <a class="reference external" href="reference-Error_Codes.html#lib
<pre class="literal-block">
inline std::ostream&amp; <strong>operator&lt;&lt;</strong> (std::ostream&amp; os, const entry&amp; e);
</pre>
<p>prints the bencoded structure to the ostream as a JSON-style structure.</p>
<a name="lazy_bdecode()"></a></div>
<div class="section" id="lazy-bdecode">
<h2>lazy_bdecode()</h2>

672
docs/reference-Core.html
View File

File diff suppressed because it is too large Load Diff

2
docs/reference-Create_Torrents.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.11: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.10: http://docutils.sourceforge.net/" />
<title>Create Torrents</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />

2
docs/reference-Custom_Storage.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.11: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.10: http://docutils.sourceforge.net/" />
<title>Custom Storage</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />

23
docs/reference-Error_Codes.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.11: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.10: http://docutils.sourceforge.net/" />
<title>Error Codes</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
@ -55,10 +55,9 @@
<div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of contents</p>
<ul class="simple">
<li><a class="reference internal" href="#http-error-category" id="id34">http_error_category</a></li>
<li><a class="reference internal" href="#libtorrent-exception" id="id35">libtorrent_exception</a></li>
<li><a class="reference internal" href="#i2p-error-category" id="id36">i2p_error_category</a></li>
<li><a class="reference internal" href="#upnp-error-category" id="id37">upnp_error_category</a></li>
<li><a class="reference internal" href="#http-error-category" id="id33">http_error_category</a></li>
<li><a class="reference internal" href="#libtorrent-exception" id="id34">libtorrent_exception</a></li>
<li><a class="reference internal" href="#i2p-error-category" id="id35">i2p_error_category</a></li>
</ul>
</div>
<a name="http_error_category"></a><div class="section" id="http-error-category">
@ -97,18 +96,6 @@ struct i2p_error_category : boost::system::error_category
virtual std::string <strong>message</strong> (int ev) const BOOST_SYSTEM_NOEXCEPT;
};
</pre>
<a name="upnp_error_category"></a></div>
<div class="section" id="upnp-error-category">
<h1>upnp_error_category</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/upnp.hpp">libtorrent/upnp.hpp</a>&quot;</p>
<pre class="literal-block">
struct upnp_error_category : boost::system::error_category
{
virtual boost::system::error_condition <strong>default_error_condition</strong> (int ev) const BOOST_SYSTEM_NOEXCEPT;
virtual const char* <strong>name</strong> () const BOOST_SYSTEM_NOEXCEPT;
virtual std::string <strong>message</strong> (int ev) const BOOST_SYSTEM_NOEXCEPT;
};
</pre>
<a name="get_libtorrent_category()"></a><div class="section" id="get-libtorrent-category">
<h2>get_libtorrent_category()</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/error_code.hpp">libtorrent/error_code.hpp</a>&quot;</p>
@ -989,7 +976,7 @@ URL. i.e. it doesn't contain &quot;announce.</td>
</tbody>
</table>
<a name="error_code_enum"></a></div>
<div class="section" id="id31">
<div class="section" id="id30">
<h2>enum error_code_enum</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/upnp.hpp">libtorrent/upnp.hpp</a>&quot;</p>
<table border="1" class="docutils">

2
docs/reference-Filter.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.11: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.10: http://docutils.sourceforge.net/" />
<title>Filter</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />

2
docs/reference-Plugins.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.11: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.10: 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" />

2
docs/reference-RSS.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.11: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.10: http://docutils.sourceforge.net/" />
<title>RSS</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />

2
docs/reference-Session.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.11: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.10: http://docutils.sourceforge.net/" />
<title>Session</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />

2
docs/reference-Settings.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.11: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.10: http://docutils.sourceforge.net/" />
<title>Settings</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />

2
docs/reference-Storage.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.11: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.10: http://docutils.sourceforge.net/" />
<title>Storage</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />

2
docs/reference-String.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.11: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.10: http://docutils.sourceforge.net/" />
<title>String</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />

2
docs/reference-Time.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.11: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.10: http://docutils.sourceforge.net/" />
<title>Time</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />

67
docs/reference-Utility.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.11: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.10: http://docutils.sourceforge.net/" />
<title>Utility</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
@ -55,8 +55,8 @@
<div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of contents</p>
<ul class="simple">
<li><a class="reference internal" href="#bitfield" id="id35">bitfield</a></li>
<li><a class="reference internal" href="#sha1-hash" id="id36">sha1_hash</a></li>
<li><a class="reference internal" href="#bitfield" id="id39">bitfield</a></li>
<li><a class="reference internal" href="#sha1-hash" id="id40">sha1_hash</a></li>
</ul>
</div>
<a name="bitfield"></a><div class="section" id="bitfield">
@ -67,12 +67,12 @@ in a heap allocated or borrowed array.</p>
<pre class="literal-block">
struct bitfield
{
<strong>bitfield</strong> (int bits, bool val);
<strong>bitfield</strong> ();
<strong>bitfield</strong> (int bits);
<strong>bitfield</strong> (bitfield const&amp; rhs);
<strong>bitfield</strong> (char const* b, int bits);
<strong>bitfield</strong> (bitfield&amp;&amp; rhs);
<strong>bitfield</strong> (int bits, bool val);
<strong>bitfield</strong> ();
<strong>bitfield</strong> (char const* b, int bits);
void <strong>borrow_bytes</strong> (char* b, int bits);
void <strong>assign</strong> (char const* b, int bits);
bool <strong>get_bit</strong> (int index) const;
@ -90,10 +90,11 @@ struct bitfield
<a name="bitfield()"></a><div class="section" id="id3">
<h2>bitfield()</h2>
<pre class="literal-block">
<strong>bitfield</strong> (int bits, bool val);
<strong>bitfield</strong> ();
<strong>bitfield</strong> (int bits);
<strong>bitfield</strong> (bitfield const&amp; rhs);
<strong>bitfield</strong> (bitfield&amp;&amp; rhs);
<strong>bitfield</strong> (int bits, bool val);
<strong>bitfield</strong> ();
<strong>bitfield</strong> (char const* b, int bits);
</pre>
<p>constructs a new <a class="reference external" href="reference-Utility.html#bitfield">bitfield</a>. The default constructor creates an empty
@ -206,9 +207,9 @@ class sha1_hash
bool <strong>is_all_zeros</strong> () const;
sha1_hash&amp; <strong>operator&lt;&lt;=</strong> (int n);
sha1_hash&amp; <strong>operator&gt;&gt;=</strong> (int n);
bool <strong>operator==</strong> (sha1_hash const&amp; n) const;
bool <strong>operator!=</strong> (sha1_hash const&amp; n) const;
bool <strong>operator&lt;</strong> (sha1_hash const&amp; n) const;
bool <strong>operator==</strong> (sha1_hash const&amp; n) const;
sha1_hash <strong>operator~</strong> ();
sha1_hash <strong>operator^</strong> (sha1_hash const&amp; n) const;
sha1_hash&amp; <strong>operator^=</strong> (sha1_hash const&amp; n);
@ -291,47 +292,61 @@ sha1_hash&amp; <strong>operator&lt;&lt;=</strong> (int n);
sha1_hash&amp; <strong>operator&gt;&gt;=</strong> (int n);
</pre>
<p>shift r <tt class="docutils literal">n</tt> bits.</p>
<a name="operator!=()"></a>
<a name="operator<()"></a>
<a name="operator==()"></a></div>
<div class="section" id="id21">
<h2>operator==()</h2>
<div class="section" id="operator-operator-operator">
<h2>operator!=() operator&lt;() operator==()</h2>
<pre class="literal-block">
bool <strong>operator!=</strong> (sha1_hash const&amp; n) const;
bool <strong>operator&lt;</strong> (sha1_hash const&amp; n) const;
bool <strong>operator==</strong> (sha1_hash const&amp; n) const;
</pre>
<p>standard comparison operators</p>
<a name="operator~()"></a></div>
<div class="section" id="id22">
<div class="section" id="id21">
<h2>operator~()</h2>
<pre class="literal-block">
sha1_hash <strong>operator~</strong> ();
</pre>
<p>negate every bit in the sha1-hash</p>
<a name="operator^=()"></a>
<p>returns a bit-wise negated copy of the sha1-hash</p>
<a name="operator^()"></a></div>
<div class="section" id="operator-operator">
<h2>operator^=() operator^()</h2>
<div class="section" id="id22">
<h2>operator^()</h2>
<pre class="literal-block">
sha1_hash <strong>operator^</strong> (sha1_hash const&amp; n) const;
</pre>
<p>returns the bit-wise XOR of the two sha1-hashes.</p>
<a name="operator^=()"></a></div>
<div class="section" id="id23">
<h2>operator^=()</h2>
<pre class="literal-block">
sha1_hash&amp; <strong>operator^=</strong> (sha1_hash const&amp; n);
</pre>
<p>bit-wise XOR of the two sha1-hash.</p>
<a name="operator&=()"></a>
<p>in-place bit-wise XOR with the passed in <a class="reference external" href="reference-Utility.html#sha1_hash">sha1_hash</a>.</p>
<a name="operator&()"></a></div>
<div class="section" id="id23">
<h2>operator&amp;=() operator&amp;()</h2>
<div class="section" id="id25">
<h2>operator&amp;()</h2>
<pre class="literal-block">
sha1_hash <strong>operator&amp;</strong> (sha1_hash const&amp; n) const;
</pre>
<p>returns the bit-wise AND of the two sha1-hashes.</p>
<a name="operator&=()"></a></div>
<div class="section" id="id26">
<h2>operator&amp;=()</h2>
<pre class="literal-block">
sha1_hash&amp; <strong>operator&amp;=</strong> (sha1_hash const&amp; n);
</pre>
<p>bit-wise AND of the two sha1-hash.</p>
<p>in-place bit-wise AND of the passed in <a class="reference external" href="reference-Utility.html#sha1_hash">sha1_hash</a></p>
<a name="operator|=()"></a></div>
<div class="section" id="id24">
<div class="section" id="id28">
<h2>operator|=()</h2>
<pre class="literal-block">
sha1_hash&amp; <strong>operator|=</strong> (sha1_hash const&amp; n);
</pre>
<p>bit-wise OR of the two sha1-hash.</p>
<p>in-place bit-wise OR of the two sha1-hash.</p>
<a name="operator[]()"></a></div>
<div class="section" id="id25">
<div class="section" id="id29">
<h2>operator[]()</h2>
<pre class="literal-block">
unsigned char&amp; <strong>operator[]</strong> (int i);
@ -384,7 +399,7 @@ to automate the identification of clients. It will not be able to identify peers
standard encodings. Only Azureus style, Shadow's style and Mainline style. This function is
declared in the header <tt class="docutils literal">&lt;libtorrent/identify_client.hpp&gt;</tt>.</p>
<a name="operator<<()"></a></div>
<div class="section" id="id28">
<div class="section" id="id32">
<h2>operator&lt;&lt;()</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/sha1_hash.hpp">libtorrent/sha1_hash.hpp</a>&quot;</p>
<pre class="literal-block">
@ -392,7 +407,7 @@ inline std::ostream&amp; <strong>operator&lt;&lt;</strong> (std::ostream&amp; os
</pre>
<p>print a <a class="reference external" href="reference-Utility.html#sha1_hash">sha1_hash</a> object to an ostream as 40 hexadecimal digits</p>
<a name="operator>>()"></a></div>
<div class="section" id="id31">
<div class="section" id="id35">
<h2>operator&gt;&gt;()</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/sha1_hash.hpp">libtorrent/sha1_hash.hpp</a>&quot;</p>
<pre class="literal-block">

3
docs/reference.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.11: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.10: http://docutils.sourceforge.net/" />
<title>libtorrent reference documentation</title>
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
<link rel="stylesheet" type="text/css" href="../../css/rst.css" />
@ -270,7 +270,6 @@
<div class="line"><a class="reference external" href="reference-Error_Codes.html#http_error_category">http_error_category</a></div>
<div class="line"><a class="reference external" href="reference-Error_Codes.html#libtorrent_exception">libtorrent_exception</a></div>
<div class="line"><a class="reference external" href="reference-Error_Codes.html#i2p_error_category">i2p_error_category</a></div>
<div class="line"><a class="reference external" href="reference-Error_Codes.html#upnp_error_category">upnp_error_category</a></div>
<div class="line"><a class="reference external" href="reference-Error_Codes.html#get_libtorrent_category()">get_libtorrent_category()</a></div>
<div class="line"><a class="reference external" href="reference-Error_Codes.html#get_http_category()">get_http_category()</a></div>
<div class="line"><a class="reference external" href="reference-Error_Codes.html#error_code_enum">error_code_enum</a></div>

24
docs/todo.html
View File

@ -812,7 +812,7 @@ for all peers though</h2><h4>../src/torrent.cpp:6261</h4><pre style="background:
// under a different limit with the auto-manager. Make sure we
// update auto-manage torrents in that case
if (m_auto_managed)
</pre></td></tr><tr style="background: #ccf"><td>relevance&nbsp;1</td><td><a href="javascript:expand(15)">../src/torrent_info.cpp:181</a></td><td>we might save constructing a std::string if this would take a char const* instead</td></tr><tr id="15" style="display: none;" colspan="3"><td colspan="3"><h2>we might save constructing a std::string if this would take a char const* instead</h2><h4>../src/torrent_info.cpp:181</h4><pre style="background: #f6f6f6; border: solid 1px #ddd;"> {
</pre></td></tr><tr style="background: #ccf"><td>relevance&nbsp;1</td><td><a href="javascript:expand(15)">../src/torrent_info.cpp:183</a></td><td>we might save constructing a std::string if this would take a char const* instead</td></tr><tr id="15" style="display: none;" colspan="3"><td colspan="3"><h2>we might save constructing a std::string if this would take a char const* instead</h2><h4>../src/torrent_info.cpp:183</h4><pre style="background: #f6f6f6; border: solid 1px #ddd;"> {
tmp_path += i[0];
tmp_path += i[1];
tmp_path += i[2];
@ -863,9 +863,9 @@ for all peers though</h2><h4>../src/torrent.cpp:6261</h4><pre style="background:
path_element.resize(max_path_len);
}
else
</pre></td></tr><tr style="background: #ccf"><td>relevance&nbsp;1</td><td><a href="javascript:expand(16)">../src/torrent_info.cpp:401</a></td><td>this logic should be a separate step done once the torrent is loaded, and the original filenames should be preserved!</td></tr><tr id="16" style="display: none;" colspan="3"><td colspan="3"><h2>this logic should be a separate step
</pre></td></tr><tr style="background: #ccf"><td>relevance&nbsp;1</td><td><a href="javascript:expand(16)">../src/torrent_info.cpp:403</a></td><td>this logic should be a separate step done once the torrent is loaded, and the original filenames should be preserved!</td></tr><tr id="16" style="display: none;" colspan="3"><td colspan="3"><h2>this logic should be a separate step
done once the torrent is loaded, and the original
filenames should be preserved!</h2><h4>../src/torrent_info.cpp:401</h4><pre style="background: #f6f6f6; border: solid 1px #ddd;">
filenames should be preserved!</h2><h4>../src/torrent_info.cpp:403</h4><pre style="background: #f6f6f6; border: solid 1px #ddd;">
while (*s1 != 0 || *s2 != 0)
{
c1 = to_lower(*s1);
@ -916,8 +916,8 @@ filenames should be preserved!</h2><h4>../src/torrent_info.cpp:401</h4><pre styl
// This is a memory optimization! Instead of having
// each entry keep a string for its filename, make it
</pre></td></tr><tr style="background: #ccf"><td>relevance&nbsp;1</td><td><a href="javascript:expand(17)">../src/torrent_info.cpp:437</a></td><td>once the filename renaming is removed from here this check can be removed as well</td></tr><tr id="17" style="display: none;" colspan="3"><td colspan="3"><h2>once the filename renaming is removed from here
this check can be removed as well</h2><h4>../src/torrent_info.cpp:437</h4><pre style="background: #f6f6f6; border: solid 1px #ddd;"> // increase the counter
</pre></td></tr><tr style="background: #ccf"><td>relevance&nbsp;1</td><td><a href="javascript:expand(17)">../src/torrent_info.cpp:439</a></td><td>once the filename renaming is removed from here this check can be removed as well</td></tr><tr id="17" style="display: none;" colspan="3"><td colspan="3"><h2>once the filename renaming is removed from here
this check can be removed as well</h2><h4>../src/torrent_info.cpp:439</h4><pre style="background: #f6f6f6; border: solid 1px #ddd;"> // increase the counter
int cnt = 0;
if (!files.insert(e.path).second)
{
@ -3003,14 +3003,14 @@ m_sock.bind(endpoint, ec);</h2><h4>../include/libtorrent/proxy_base.hpp:166</h4>
// flags for the source bitmask, each indicating where
// we heard about this tracker
enum tracker_source
</pre></td></tr><tr style="background: #ccc"><td>relevance&nbsp;0</td><td><a href="javascript:expand(59)">../include/libtorrent/upnp.hpp:121</a></td><td>support using the windows API for UPnP operations as well</td></tr><tr id="59" style="display: none;" colspan="3"><td colspan="3"><h2>support using the windows API for UPnP operations as well</h2><h4>../include/libtorrent/upnp.hpp:121</h4><pre style="background: #f6f6f6; border: solid 1px #ddd;"> {
virtual const char* name() const BOOST_SYSTEM_NOEXCEPT;
virtual std::string message(int ev) const BOOST_SYSTEM_NOEXCEPT;
virtual boost::system::error_condition default_error_condition(int ev) const BOOST_SYSTEM_NOEXCEPT
{ return boost::system::error_condition(ev, *this); }
};
</pre></td></tr><tr style="background: #ccc"><td>relevance&nbsp;0</td><td><a href="javascript:expand(59)">../include/libtorrent/upnp.hpp:112</a></td><td>support using the windows API for UPnP operations as well</td></tr><tr id="59" style="display: none;" colspan="3"><td colspan="3"><h2>support using the windows API for UPnP operations as well</h2><h4>../include/libtorrent/upnp.hpp:112</h4><pre style="background: #f6f6f6; border: solid 1px #ddd;"> external_port_must_be_wildcard = 727
};
}
extern TORRENT_EXPORT upnp_error_category upnp_category;
#if BOOST_VERSION &lt; 103500
extern asio::error::error_category upnp_category;
#else
boost::system::error_category&amp; get_upnp_category();
#endif
// int: port-mapping index

5
docs/tuning.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.11: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.10: 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" />
@ -339,8 +339,7 @@ enough to not draining the socket's send buffer before the disk operation comple
<p>The watermark is bound to a max value, to avoid buffer sizes growing out of control.
The default max send buffer size might not be enough to sustain very high upload rates,
and you might have to increase it. It's specified in bytes in
<tt class="docutils literal"><span class="pre">session_settings::send_buffer_watermark</span></tt>. The <tt class="docutils literal">high_performance_seed()</tt> preset
sets this value to 5 MB.</p>
<tt class="docutils literal"><span class="pre">session_settings::send_buffer_watermark</span></tt>.</p>
</div>
<div class="section" id="peers">
<h2>peers</h2>

2
docs/udp_tracker_protocol.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.11: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.10: 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" />

2
docs/utp.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.11: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.10: 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" />

1
include/libtorrent/bitfield.hpp
View File

@ -62,7 +62,6 @@ namespace libtorrent
{ assign(b, bits); }
bitfield(bitfield const& rhs): m_bytes(0), m_size(0), m_own(false)
{ assign(rhs.bytes(), rhs.size()); }
#if __cplusplus > 199711L
bitfield(bitfield&& rhs): m_bytes(rhs.m_bytes), m_size(rhs.m_size), m_own(rhs.m_own)
{ rhs.m_bytes = NULL; }

3
include/libtorrent/entry.hpp
View File

@ -229,6 +229,8 @@ namespace libtorrent
entry* find_key(std::string const& key);
entry const* find_key(std::string const& key) const;
// returns a pretty-printed string representation
// of the bencoded structure, with JSON-style syntax
std::string to_string() const;
protected:
@ -280,6 +282,7 @@ namespace libtorrent
};
#if TORRENT_USE_IOSTREAM
// prints the bencoded structure to the ostream as a JSON-style structure.
inline std::ostream& operator<<(std::ostream& os, const entry& e)
{
os << e.to_string();

13
include/libtorrent/sha1_hash.hpp
View File

@ -189,7 +189,6 @@ namespace libtorrent
{
return std::equal(n.m_number, n.m_number+number_size, m_number);
}
bool operator!=(sha1_hash const& n) const
{
return !std::equal(n.m_number, n.m_number+number_size, m_number);
@ -204,7 +203,7 @@ namespace libtorrent
return false;
}
// negate every bit in the sha1-hash
// returns a bit-wise negated copy of the sha1-hash
sha1_hash operator~()
{
sha1_hash ret;
@ -213,13 +212,15 @@ namespace libtorrent
return ret;
}
// bit-wise XOR of the two sha1-hash.
// returns the bit-wise XOR of the two sha1-hashes.
sha1_hash operator^(sha1_hash const& n) const
{
sha1_hash ret = *this;
ret ^= n;
return ret;
}
// in-place bit-wise XOR with the passed in sha1_hash.
sha1_hash& operator^=(sha1_hash const& n)
{
for (int i = 0; i< number_size; ++i)
@ -227,13 +228,15 @@ namespace libtorrent
return *this;
}
// bit-wise AND of the two sha1-hash.
// returns the bit-wise AND of the two sha1-hashes.
sha1_hash operator&(sha1_hash const& n) const
{
sha1_hash ret = *this;
ret &= n;
return ret;
}
// in-place bit-wise AND of the passed in sha1_hash
sha1_hash& operator&=(sha1_hash const& n)
{
for (int i = 0; i< number_size; ++i)
@ -241,7 +244,7 @@ namespace libtorrent
return *this;
}
// bit-wise OR of the two sha1-hash.
// in-place bit-wise OR of the two sha1-hash.
sha1_hash& operator|=(sha1_hash const& n)
{
for (int i = 0; i< number_size; ++i)

619
include/libtorrent/torrent_handle.hpp
View File

@ -87,13 +87,15 @@ namespace libtorrent
// it from and how far along we are at downloading it.
struct TORRENT_EXPORT block_info
{
// this is the enum used for the block_info::state field.
enum block_state_t
{
// This block has not been downloaded or requested form any peer.
none,
// The block has been requested, but not completely downloaded yet.
requested,
// The block has been downloaded and is currently queued for being written to disk.
// The block has been downloaded and is currently queued for being
// written to disk.
writing,
// The block has been written to disk.
finished
@ -142,9 +144,9 @@ namespace libtorrent
// the state this block is in (see block_state_t)
unsigned state:2;
// the number of peers that is currently requesting this block. Typically this
// is 0 or 1, but at the end of the torrent blocks may be requested by more peers in parallel to
// speed things up.
// the number of peers that is currently requesting this block. Typically
// this is 0 or 1, but at the end of the torrent blocks may be requested
// by more peers in parallel to speed things up.
unsigned num_peers:14;
private:
#if TORRENT_USE_IPV6
@ -153,19 +155,26 @@ namespace libtorrent
#endif
};
// This class holds information about pieces that have outstanding requests
// or outstanding writes
struct TORRENT_EXPORT partial_piece_info
{
// the index of the piece in question. ``blocks_in_piece`` is the
// number of blocks in this particular piece. This number will be the same for most pieces, but
// the index of the piece in question. ``blocks_in_piece`` is the number
// of blocks in this particular piece. This number will be the same for
// most pieces, but
// the last piece may have fewer blocks than the standard pieces.
int piece_index;
// the number of blocks in this piece
int blocks_in_piece;
// the number of blocks in the finished state
// the number of blocks that are in the finished state
int finished;
// the number of blocks in the writing state
// the number of blocks that are in the writing state
int writing;
// the number of blocks in the requested state
// the number of blocks that are in the requested state
int requested;
// this is an array of ``blocks_in_piece`` number of
@ -176,43 +185,50 @@ namespace libtorrent
// get_download_queue() is called, it will be invalidated.
block_info* blocks;
// the speed classes. These may be used by the piece picker to
// coalesce requests of similar download rates
enum state_t { none, slow, medium, fast };
// the download speed class this piece falls into.
// this is used internally to cluster peers of the same
// speed class together when requesting blocks.
//
// set to either ``fast``, ``medium``, ``slow`` or ``none``. It tells which
// download rate category the peers downloading this piece falls into. ``none`` means that no
// peer is currently downloading any part of the piece. Peers prefer picking pieces from
// the same category as themselves. The reason for this is to keep the number of partially
// downloaded pieces down. Pieces set to ``none`` can be converted into any of ``fast``,
// ``medium`` or ``slow`` as soon as a peer want to download from it.
// set to either ``fast``, ``medium``, ``slow`` or ``none``. It tells
// which download rate category the peers downloading this piece falls
// into. ``none`` means that no peer is currently downloading any part of
// the piece. Peers prefer picking pieces from the same category as
// themselves. The reason for this is to keep the number of partially
// downloaded pieces down. Pieces set to ``none`` can be converted into
// any of ``fast``, ``medium`` or ``slow`` as soon as a peer want to
// download from it.
state_t piece_state;
};
// You will usually have to store your torrent handles somewhere, since it's the
// object through which you retrieve information about the torrent and aborts the torrent.
// You will usually have to store your torrent handles somewhere, since it's
// the object through which you retrieve information about the torrent and
// aborts the torrent.
//
// .. warning::
// Any member function that returns a value or fills in a value has to
// be made synchronously. This means it has to wait for the main thread
// to complete the query before it can return. This might potentially be
// expensive if done from within a GUI thread that needs to stay responsive.
// Try to avoid quering for information you don't need, and try to do it
// in as few calls as possible. You can get most of the interesting information
// about a torrent from the torrent_handle::status() call.
// Any member function that returns a value or fills in a value has to be
// made synchronously. This means it has to wait for the main thread to
// complete the query before it can return. This might potentially be
// expensive if done from within a GUI thread that needs to stay
// responsive. Try to avoid quering for information you don't need, and
// try to do it in as few calls as possible. You can get most of the
// interesting information about a torrent from the
// torrent_handle::status() call.
//
// The default constructor will initialize the handle to an invalid state. Which
// means you cannot perform any operation on it, unless you first assign it a
// valid handle. If you try to perform any operation on an uninitialized handle,
// it will throw ``invalid_handle``.
// The default constructor will initialize the handle to an invalid state.
// Which means you cannot perform any operation on it, unless you first
// assign it a valid handle. If you try to perform any operation on an
// uninitialized handle, it will throw ``invalid_handle``.
//
// .. warning:: All operations on a torrent_handle may throw libtorrent_exception
// exception, in case the handle is no longer refering to a torrent. There is
// one exception is_valid() will never throw.
// Since the torrents are processed by a background thread, there is no
// guarantee that a handle will remain valid between two calls.
// .. warning::
// All operations on a torrent_handle may throw libtorrent_exception
// exception, in case the handle is no longer refering to a torrent.
// There is one exception is_valid() will never throw. Since the torrents
// are processed by a background thread, there is no guarantee that a
// handle will remain valid between two calls.
//
struct TORRENT_EXPORT torrent_handle
{
@ -229,122 +245,143 @@ namespace libtorrent
// flags for add_piece().
enum flags_t { overwrite_existing = 1 };
// This function will write ``data`` to the storage as piece ``piece``, as if it had
// been downloaded from a peer. ``data`` is expected to point to a buffer of as many
// bytes as the size of the specified piece. The data in the buffer is copied and
// passed on to the disk IO thread to be written at a later point.
// This function will write ``data`` to the storage as piece ``piece``,
// as if it had been downloaded from a peer. ``data`` is expected to
// point to a buffer of as many bytes as the size of the specified piece.
// The data in the buffer is copied and passed on to the disk IO thread
// to be written at a later point.
//
// By default, data that's already been downloaded is not overwritten by this buffer. If
// you trust this data to be correct (and pass the piece hash check) you may pass the
// overwrite_existing flag. This will instruct libtorrent to overwrite any data that
// may already have been downloaded with this data.
// By default, data that's already been downloaded is not overwritten by
// this buffer. If you trust this data to be correct (and pass the piece
// hash check) you may pass the overwrite_existing flag. This will
// instruct libtorrent to overwrite any data that may already have been
// downloaded with this data.
//
// Since the data is written asynchronously, you may know that is passed or failed the
// hash check by waiting for piece_finished_alert or hash_failed_alert.
// Since the data is written asynchronously, you may know that is passed
// or failed the hash check by waiting for piece_finished_alert or
// hash_failed_alert.
void add_piece(int piece, char const* data, int flags = 0) const;
// This function starts an asynchronous read operation of the specified piece from
// this torrent. You must have completed the download of the specified piece before
// calling this function.
// This function starts an asynchronous read operation of the specified
// piece from this torrent. You must have completed the download of the
// specified piece before calling this function.
//
// When the read operation is completed, it is passed back through an alert,
// read_piece_alert. Since this alert is a reponse to an explicit call, it will
// always be posted, regardless of the alert mask.
// When the read operation is completed, it is passed back through an
// alert, read_piece_alert. Since this alert is a reponse to an explicit
// call, it will always be posted, regardless of the alert mask.
//
// Note that if you read multiple pieces, the read operations are not guaranteed to
// finish in the same order as you initiated them.
// Note that if you read multiple pieces, the read operations are not
// guaranteed to finish in the same order as you initiated them.
void read_piece(int piece) const;
// Returns true if this piece has been completely downloaded, and false otherwise.
// Returns true if this piece has been completely downloaded, and false
// otherwise.
bool have_piece(int piece) const;
void get_full_peer_list(std::vector<peer_list_entry>& v) const;
// takes a reference to a vector that will be cleared and filled
// with one entry for each peer connected to this torrent, given the handle is valid. If the
// torrent_handle is invalid, it will throw libtorrent_exception exception. Each entry in
// the vector contains information about that particular peer. See peer_info.
// takes a reference to a vector that will be cleared and filled with one
// entry for each peer connected to this torrent, given the handle is
// valid. If the torrent_handle is invalid, it will throw
// libtorrent_exception exception. Each entry in the vector contains
// information about that particular peer. See peer_info.
void get_peer_info(std::vector<peer_info>& v) const;
enum status_flags_t
{
// calculates ``distributed_copies``, ``distributed_full_copies`` and ``distributed_fraction``.
// calculates ``distributed_copies``, ``distributed_full_copies`` and
// ``distributed_fraction``.
query_distributed_copies = 1,
// includes partial downloaded blocks in ``total_done`` and ``total_wanted_done``.
// includes partial downloaded blocks in ``total_done`` and
// ``total_wanted_done``.
query_accurate_download_counters = 2,
// includes ``last_seen_complete``.
query_last_seen_complete = 4,
// includes ``pieces``.
query_pieces = 8,
// includes ``verified_pieces`` (only applies to torrents in *seed mode*).
// includes ``verified_pieces`` (only applies to torrents in *seed
// mode*).
query_verified_pieces = 16,
// includes ``torrent_file``, which is all the static information from the .torrent file.
// includes ``torrent_file``, which is all the static information from
// the .torrent file.
query_torrent_file = 32,
// includes ``name``, the name of the torrent. This is either derived from the .torrent
// file, or from the ``&dn=`` magnet link argument or possibly some other source. If the
// name of the torrent is not known, this is an empty string.
// includes ``name``, the name of the torrent. This is either derived
// from the .torrent file, or from the ``&dn=`` magnet link argument
// or possibly some other source. If the name of the torrent is not
// known, this is an empty string.
query_name = 64,
// includes ``save_path``, the path to the directory the files of the torrent are saved to.
// includes ``save_path``, the path to the directory the files of the
// torrent are saved to.
query_save_path = 128,
};
// ``status()`` will return a structure with information about the status of this
// torrent. If the torrent_handle is invalid, it will throw libtorrent_exception exception.
// See torrent_status. The ``flags`` argument filters what information is returned
// in the torrent_status. Some information in there is relatively expensive to calculate, and
// if you're not interested in it (and see performance issues), you can filter them out.
// ``status()`` will return a structure with information about the status
// of this torrent. If the torrent_handle is invalid, it will throw
// libtorrent_exception exception. See torrent_status. The ``flags``
// argument filters what information is returned in the torrent_status.
// Some information in there is relatively expensive to calculate, and if
// you're not interested in it (and see performance issues), you can
// filter them out.
//
// By default everything is included. The flags you can use to decide what to *include* are
// defined in the status_flags_t enum.
// By default everything is included. The flags you can use to decide
// what to *include* are defined in the status_flags_t enum.
torrent_status status(boost::uint32_t flags = 0xffffffff) const;
// ``get_download_queue()`` takes a non-const reference to a vector which it will fill with
// information about pieces that are partially downloaded or not downloaded at all but partially
// requested. See partial_piece_info for the fields in the returned vector.
// ``get_download_queue()`` takes a non-const reference to a vector which
// it will fill with information about pieces that are partially
// downloaded or not downloaded at all but partially requested. See
// partial_piece_info for the fields in the returned vector.
void get_download_queue(std::vector<partial_piece_info>& queue) const;
// flags for set_piece_deadline().
enum deadline_flags { alert_when_available = 1 };
// This function sets or resets the deadline associated with a specific piece
// index (``index``). libtorrent will attempt to download this entire piece before
// the deadline expires. This is not necessarily possible, but pieces with a more
// recent deadline will always be prioritized over pieces with a deadline further
// ahead in time. The deadline (and flags) of a piece can be changed by calling this
// This function sets or resets the deadline associated with a specific
// piece index (``index``). libtorrent will attempt to download this
// entire piece before the deadline expires. This is not necessarily
// possible, but pieces with a more recent deadline will always be
// prioritized over pieces with a deadline further ahead in time. The
// deadline (and flags) of a piece can be changed by calling this
// function again.
//
// The ``flags`` parameter can be used to ask libtorrent to send an alert once the
// piece has been downloaded, by passing alert_when_available. When set, the
// read_piece_alert alert will be delivered, with the piece data, when it's downloaded.
// The ``flags`` parameter can be used to ask libtorrent to send an alert
// once the piece has been downloaded, by passing alert_when_available.
// When set, the read_piece_alert alert will be delivered, with the piece
// data, when it's downloaded.
//
// If the piece is already downloaded when this call is made, nothing happens, unless
// the alert_when_available flag is set, in which case it will do the same thing
// as calling read_piece() for ``index``.
// If the piece is already downloaded when this call is made, nothing
// happens, unless the alert_when_available flag is set, in which case it
// will do the same thing as calling read_piece() for ``index``.
//
// ``deadline`` is the number of milliseconds until this piece should be completed.
//
// ``reset_piece_deadline`` removes the deadline from the piece. If it hasn't already
// been downloaded, it will no longer be considered a priority.
// ``deadline`` is the number of milliseconds until this piece should be
// completed.
//
// ``reset_piece_deadline`` removes the deadline from the piece. If it
// hasn't already been downloaded, it will no longer be considered a
// priority.
void set_piece_deadline(int index, int deadline, int flags = 0) const;
void reset_piece_deadline(int index) const;
// This sets the bandwidth priority of this torrent. The priority of a torrent determines
// how much bandwidth its peers are assigned when distributing upload and download rate quotas.
// A high number gives more bandwidth. The priority must be within the range [0, 255].
// This sets the bandwidth priority of this torrent. The priority of a
// torrent determines how much bandwidth its peers are assigned when
// distributing upload and download rate quotas. A high number gives more
// bandwidth. The priority must be within the range [0, 255].
//
// The default priority is 0, which is the lowest priority.
//
// To query the priority of a torrent, use the ``torrent_handle::status()`` call.
// To query the priority of a torrent, use the
// ``torrent_handle::status()`` call.
//
// Torrents with higher priority will not nececcarily get as much bandwidth as they can
// consume, even if there's is more quota. Other peers will still be weighed in when
// bandwidth is being distributed. With other words, bandwidth is not distributed strictly
// in order of priority, but the priority is used as a weight.
// Torrents with higher priority will not nececcarily get as much
// bandwidth as they can consume, even if there's is more quota. Other
// peers will still be weighed in when bandwidth is being distributed.
// With other words, bandwidth is not distributed strictly in order of
// priority, but the priority is used as a weight.
//
// Peers whose Torrent has a higher priority will take precedence when distributing unchoke slots.
// This is a strict prioritization where every interested peer on a high priority torrent will
// be unchoked before any other, lower priority, torrents have any peers unchoked.
// Peers whose Torrent has a higher priority will take precedence when
// distributing unchoke slots. This is a strict prioritization where
// every interested peer on a high priority torrent will be unchoked
// before any other, lower priority, torrents have any peers unchoked.
void set_priority(int prio) const;
#ifndef TORRENT_NO_DEPRECATE
@ -361,60 +398,65 @@ namespace libtorrent
piece_granularity = 1
};
// This function fills in the supplied vector with the the number of bytes downloaded
// of each file in this torrent. The progress values are ordered the same as the files
// in the torrent_info. This operation is not very cheap. Its complexity is *O(n + mj)*.
// Where *n* is the number of files, *m* is the number of downloading pieces and *j*
// is the number of blocks in a piece.
// This function fills in the supplied vector with the the number of
// bytes downloaded of each file in this torrent. The progress values are
// ordered the same as the files in the torrent_info. This operation is
// not very cheap. Its complexity is *O(n + mj)*. Where *n* is the number
// of files, *m* is the number of downloading pieces and *j* is the
// number of blocks in a piece.
//
// The ``flags`` parameter can be used to specify the granularity of the file progress. If
// left at the default value of 0, the progress will be as accurate as possible, but also
// more expensive to calculate. If ``torrent_handle::piece_granularity`` is specified,
// the progress will be specified in piece granularity. i.e. only pieces that have been
// fully downloaded and passed the hash check count. When specifying piece granularity,
// the operation is a lot cheaper, since libtorrent already keeps track of this internally
// and no calculation is required.
// The ``flags`` parameter can be used to specify the granularity of the
// file progress. If left at the default value of 0, the progress will be
// as accurate as possible, but also more expensive to calculate. If
// ``torrent_handle::piece_granularity`` is specified, the progress will
// be specified in piece granularity. i.e. only pieces that have been
// fully downloaded and passed the hash check count. When specifying
// piece granularity, the operation is a lot cheaper, since libtorrent
// already keeps track of this internally and no calculation is required.
void file_progress(std::vector<size_type>& progress, int flags = 0) const;
// If the torrent is in an error state (i.e. ``torrent_status::error`` is non-empty), this
// will clear the error and start the torrent again.
// If the torrent is in an error state (i.e. ``torrent_status::error`` is
// non-empty), this will clear the error and start the torrent again.
void clear_error() const;
// ``trackers()`` will return the list of trackers for this torrent. The
// announce entry contains both a string ``url`` which specify the announce url
// for the tracker as well as an int ``tier``, which is specifies the order in
// which this tracker is tried. If you want libtorrent to use another list of
// trackers for this torrent, you can use ``replace_trackers()`` which takes
// a list of the same form as the one returned from ``trackers()`` and will
// replace it. If you want an immediate effect, you have to call
// force_reannounce(). See announce_entry.
// announce entry contains both a string ``url`` which specify the
// announce url for the tracker as well as an int ``tier``, which is
// specifies the order in which this tracker is tried. If you want
// libtorrent to use another list of trackers for this torrent, you can
// use ``replace_trackers()`` which takes a list of the same form as the
// one returned from ``trackers()`` and will replace it. If you want an
// immediate effect, you have to call force_reannounce(). See
// announce_entry.
//
// ``add_tracker()`` will look if the specified tracker is already in the set.
// If it is, it doesn't do anything. If it's not in the current set of trackers,
// it will insert it in the tier specified in the announce_entry.
// ``add_tracker()`` will look if the specified tracker is already in the
// set. If it is, it doesn't do anything. If it's not in the current set
// of trackers, it will insert it in the tier specified in the
// announce_entry.
//
// The updated set of trackers will be saved in the resume data, and when a torrent
// is started with resume data, the trackers from the resume data will replace the
// original ones.
// The updated set of trackers will be saved in the resume data, and when
// a torrent is started with resume data, the trackers from the resume
// data will replace the original ones.
std::vector<announce_entry> trackers() const;
void replace_trackers(std::vector<announce_entry> const&) const;
void add_tracker(announce_entry const&) const;
// ``add_url_seed()`` adds another url to the torrent's list of url seeds. If the
// given url already exists in that list, the call has no effect. The torrent
// will connect to the server and try to download pieces from it, unless it's
// paused, queued, checking or seeding. ``remove_url_seed()`` removes the given
// url if it exists already. ``url_seeds()`` return a set of the url seeds
// currently in this torrent. Note that urls that fails may be removed
// automatically from the list.
// ``add_url_seed()`` adds another url to the torrent's list of url
// seeds. If the given url already exists in that list, the call has no
// effect. The torrent will connect to the server and try to download
// pieces from it, unless it's paused, queued, checking or seeding.
// ``remove_url_seed()`` removes the given url if it exists already.
// ``url_seeds()`` return a set of the url seeds currently in this
// torrent. Note that urls that fails may be removed automatically from
// the list.
//
// See http-seeding_ for more information.
void add_url_seed(std::string const& url) const;
void remove_url_seed(std::string const& url) const;
std::set<std::string> url_seeds() const;
// These functions are identical as the ``*_url_seed()`` variants, but they
// operate on `BEP 17`_ web seeds instead of `BEP 19`_.
// These functions are identical as the ``*_url_seed()`` variants, but
// they operate on `BEP 17`_ web seeds instead of `BEP 19`_.
//
// See http-seeding_ for more information.
void add_http_seed(std::string const& url) const;
@ -429,144 +471,178 @@ namespace libtorrent
void add_extension(boost::function<boost::shared_ptr<torrent_plugin>(torrent*, void*)> const& ext
, void* userdata = 0);
// ``set_metadata`` expects the *info* section of metadata. i.e. The buffer passed in will be
// hashed and verified against the info-hash. If it fails, a ``metadata_failed_alert`` will be
// generated. If it passes, a ``metadata_received_alert`` is generated. The function returns
// true if the metadata is successfully set on the torrent, and false otherwise. If the torrent
// already has metadata, this function will not affect the torrent, and false will be returned.
// ``set_metadata`` expects the *info* section of metadata. i.e. The
// buffer passed in will be hashed and verified against the info-hash. If
// it fails, a ``metadata_failed_alert`` will be generated. If it passes,
// a ``metadata_received_alert`` is generated. The function returns true
// if the metadata is successfully set on the torrent, and false
// otherwise. If the torrent already has metadata, this function will not
// affect the torrent, and false will be returned.
bool set_metadata(char const* metadata, int size) const;
// Returns true if this handle refers to a valid torrent and false if it hasn't been initialized
// or if the torrent it refers to has been aborted. Note that a handle may become invalid after
// it has been added to the session. Usually this is because the storage for the torrent is
// somehow invalid or if the filenames are not allowed (and hence cannot be opened/created) on
// your filesystem. If such an error occurs, a file_error_alert is generated and all handles
// that refers to that torrent will become invalid.
// Returns true if this handle refers to a valid torrent and false if it
// hasn't been initialized or if the torrent it refers to has been
// aborted. Note that a handle may become invalid after it has been added
// to the session. Usually this is because the storage for the torrent is
// somehow invalid or if the filenames are not allowed (and hence cannot
// be opened/created) on your filesystem. If such an error occurs, a
// file_error_alert is generated and all handles that refers to that
// torrent will become invalid.
bool is_valid() const;
// flags for torrent_session::pause()
enum pause_flags_t { graceful_pause = 1 };
// ``pause()``, and ``resume()`` will disconnect all peers and reconnect all peers respectively.
// When a torrent is paused, it will however remember all share ratios to all peers and remember
// all potential (not connected) peers. Torrents may be paused automatically if there is a file
// error (e.g. disk full) or something similar. See file_error_alert.
// ``pause()``, and ``resume()`` will disconnect all peers and reconnect
// all peers respectively. When a torrent is paused, it will however
// remember all share ratios to all peers and remember all potential (not
// connected) peers. Torrents may be paused automatically if there is a
// file error (e.g. disk full) or something similar. See
// file_error_alert.
//
// To know if a torrent is paused or not, call ``torrent_handle::status()`` and inspect
// ``torrent_status::paused``.
// To know if a torrent is paused or not, call
// ``torrent_handle::status()`` and inspect ``torrent_status::paused``.
//
// The ``flags`` argument to pause can be set to ``torrent_handle::graceful_pause`` which will
// delay the disconnect of peers that we're still downloading outstanding requests from. The torrent
// will not accept any more requests and will disconnect all idle peers. As soon as a peer is
// done transferring the blocks that were requested from it, it is disconnected. This is a graceful
// shut down of the torrent in the sense that no downloaded bytes are wasted.
// The ``flags`` argument to pause can be set to
// ``torrent_handle::graceful_pause`` which will delay the disconnect of
// peers that we're still downloading outstanding requests from. The
// torrent will not accept any more requests and will disconnect all idle
// peers. As soon as a peer is done transferring the blocks that were
// requested from it, it is disconnected. This is a graceful shut down of
// the torrent in the sense that no downloaded bytes are wasted.
//
// torrents that are auto-managed may be automatically resumed again. It does not make sense to
// pause an auto-managed torrent without making it not automanaged first. Torrents are auto-managed
// by default when added to the session. For more information, see queuing_.
// torrents that are auto-managed may be automatically resumed again. It
// does not make sense to pause an auto-managed torrent without making it
// not automanaged first. Torrents are auto-managed by default when added
// to the session. For more information, see queuing_.
void pause(int flags = 0) const;
void resume() const;
// Explicitly sets the upload mode of the torrent. In upload mode, the torrent will not
// request any pieces. If the torrent is auto managed, it will automatically be taken out
// of upload mode periodically (see ``session_settings::optimistic_disk_retry``). Torrents
// are automatically put in upload mode whenever they encounter a disk write error.
// Explicitly sets the upload mode of the torrent. In upload mode, the
// torrent will not request any pieces. If the torrent is auto managed,
// it will automatically be taken out of upload mode periodically (see
// ``session_settings::optimistic_disk_retry``). Torrents are
// automatically put in upload mode whenever they encounter a disk write
// error.
//
// ``m`` should be true to enter upload mode, and false to leave it.
//
// To test if a torrent is in upload mode, call ``torrent_handle::status()`` and inspect
// To test if a torrent is in upload mode, call
// ``torrent_handle::status()`` and inspect
// ``torrent_status::upload_mode``.
void set_upload_mode(bool b) const;
// Enable or disable share mode for this torrent. When in share mode, the torrent will
// not necessarily be downloaded, especially not the whole of it. Only parts that are likely
// to be distributed to more than 2 other peers are downloaded, and only if the previous
// prediction was correct.
// Enable or disable share mode for this torrent. When in share mode, the
// torrent will not necessarily be downloaded, especially not the whole
// of it. Only parts that are likely to be distributed to more than 2
// other peers are downloaded, and only if the previous prediction was
// correct.
void set_share_mode(bool b) const;
// Instructs libtorrent to flush all the disk caches for this torrent and close all
// file handles. This is done asynchronously and you will be notified that it's complete
// through cache_flushed_alert.
// Instructs libtorrent to flush all the disk caches for this torrent and
// close all file handles. This is done asynchronously and you will be
// notified that it's complete through cache_flushed_alert.
//
// Note that by the time you get the alert, libtorrent may have cached more data for the
// torrent, but you are guaranteed that whatever cached data libtorrent had by the time
// you called ``torrent_handle::flush_cache()`` has been written to disk.
// Note that by the time you get the alert, libtorrent may have cached
// more data for the torrent, but you are guaranteed that whatever cached
// data libtorrent had by the time you called
// ``torrent_handle::flush_cache()`` has been written to disk.
void flush_cache() const;
// Set to true to apply the session global IP filter to this torrent (which is the
// default). Set to false to make this torrent ignore the IP filter.
// Set to true to apply the session global IP filter to this torrent
// (which is the default). Set to false to make this torrent ignore the
// IP filter.
void apply_ip_filter(bool b) const;
// ``force_recheck`` puts the torrent back in a state where it assumes to have no resume data.
// All peers will be disconnected and the torrent will stop announcing to the tracker. The torrent
// will be added to the checking queue, and will be checked (all the files will be read and
// compared to the piece hashes). Once the check is complete, the torrent will start connecting
// to peers again, as normal.
// ``force_recheck`` puts the torrent back in a state where it assumes to
// have no resume data. All peers will be disconnected and the torrent
// will stop announcing to the tracker. The torrent will be added to the
// checking queue, and will be checked (all the files will be read and
// compared to the piece hashes). Once the check is complete, the torrent
// will start connecting to peers again, as normal.
void force_recheck() const;
// flags used in the save_resume_data call to control additional
// actions or fields to save.
enum save_resume_flags_t
{
// the disk cache will be flushed before creating the resume data. This avoids a problem with
// file timestamps in the resume data in case the cache hasn't been flushed yet.
// the disk cache will be flushed before creating the resume data.
// This avoids a problem with file timestamps in the resume data in
// case the cache hasn't been flushed yet.
flush_disk_cache = 1,
// the resume data will contain the metadata
// from the torrent file as well. This is default for any torrent that's added without a torrent
// file (such as a magnet link or a URL).
// the resume data will contain the metadata from the torrent file as
// well. This is default for any torrent that's added without a
// torrent file (such as a magnet link or a URL).
save_info_dict = 2
};
// ``save_resume_data()`` generates fast-resume data and returns it as an entry. This entry
// is suitable for being bencoded. For more information about how fast-resume works, see fast-resume_.
// ``save_resume_data()`` generates fast-resume data and returns it as an
// entry. This entry is suitable for being bencoded. For more information
// about how fast-resume works, see fast-resume_.
//
// The ``flags`` argument is a bitmask of flags ORed together. see save_resume_flags_t
// The ``flags`` argument is a bitmask of flags ORed together. see
// save_resume_flags_t
//
// This operation is asynchronous, ``save_resume_data`` will return immediately. The resume data
// is delivered when it's done through an save_resume_data_alert.
// This operation is asynchronous, ``save_resume_data`` will return
// immediately. The resume data is delivered when it's done through an
// save_resume_data_alert.
//
// The fast resume data will be empty in the following cases:
//
// 1. The torrent handle is invalid.
// 2. The torrent is checking (or is queued for checking) its storage, it will obviously
// not be ready to write resume data.
// 3. The torrent hasn't received valid metadata and was started without metadata
// (see libtorrent's metadata-from-peers_ extension)
// 2. The torrent is checking (or is queued for checking) its storage, it
// will obviously not be ready to write resume data.
// 3. The torrent hasn't received valid metadata and was started without
// metadata (see libtorrent's metadata-from-peers_ extension)
//
// Note that by the time you receive the fast resume data, it may already be invalid if the torrent
// is still downloading! The recommended practice is to first pause the session, then generate the
// fast resume data, and then close it down. Make sure to not remove_torrent() before you receive
// the save_resume_data_alert though. There's no need to pause when saving intermittent resume data.
// Note that by the time you receive the fast resume data, it may already
// be invalid if the torrent is still downloading! The recommended
// practice is to first pause the session, then generate the fast resume
// data, and then close it down. Make sure to not remove_torrent() before
// you receive the save_resume_data_alert though. There's no need to
// pause when saving intermittent resume data.
//
//.. warning:: If you pause every torrent individually instead of pausing the session, every torrent
// will have its paused state saved in the resume data!
//.. warning::
// If you pause every torrent individually instead of pausing the
// session, every torrent will have its paused state saved in the
// resume data!
//
//.. warning:: The resume data contains the modification timestamps for all files. If one file has
// been modified when the torrent is added again, the will be rechecked. When shutting down, make
// sure to flush the disk cache before saving the resume data. This will make sure that the file
// timestamps are up to date and won't be modified after saving the resume data. The recommended way
// to do this is to pause the torrent, which will flush the cache and disconnect all peers.
//.. warning::
// The resume data contains the modification timestamps for all files.
// If one file has been modified when the torrent is added again, the
// will be rechecked. When shutting down, make sure to flush the disk
// cache before saving the resume data. This will make sure that the
// file timestamps are up to date and won't be modified after saving
// the resume data. The recommended way to do this is to pause the
// torrent, which will flush the cache and disconnect all peers.
//
//.. note:: It is typically a good idea to save resume data whenever a torrent is completed or paused. In those
// cases you don't need to pause the torrent or the session, since the torrent will do no more writing
// to its files. If you save resume data for torrents when they are paused, you can accelerate the
// shutdown process by not saving resume data again for paused torrents. Completed torrents should
// have their resume data saved when they complete and on exit, since their statistics might be updated.
//.. note::
// It is typically a good idea to save resume data whenever a torrent
// is completed or paused. In those cases you don't need to pause the
// torrent or the session, since the torrent will do no more writing to
// its files. If you save resume data for torrents when they are
// paused, you can accelerate the shutdown process by not saving resume
// data again for paused torrents. Completed torrents should have their
// resume data saved when they complete and on exit, since their
// statistics might be updated.
//
// In full allocation mode the reume data is never invalidated by subsequent
// writes to the files, since pieces won't move around. This means that you don't need to
// pause before writing resume data in full or sparse mode. If you don't, however, any data written to
// disk after you saved resume data and before the session closed is lost.
// In full allocation mode the reume data is never invalidated by
// subsequent writes to the files, since pieces won't move around. This
// means that you don't need to pause before writing resume data in full
// or sparse mode. If you don't, however, any data written to disk after
// you saved resume data and before the session closed is lost.
//
// It also means that if the resume data is out dated, libtorrent will not re-check the files, but assume
// that it is fairly recent. The assumption is that it's better to loose a little bit than to re-check
// It also means that if the resume data is out dated, libtorrent will
// not re-check the files, but assume that it is fairly recent. The
// assumption is that it's better to loose a little bit than to re-check
// the entire file.
//
// It is still a good idea to save resume data periodically during download as well as when
// closing down.
// It is still a good idea to save resume data periodically during
// download as well as when closing down.
//
// Example code to pause and save resume data for all torrents and wait for the alerts::
// Example code to pause and save resume data for all torrents and wait
// for the alerts::
//
// extern int outstanding_resume_data; // global counter of outstanding resume data
// std::vector<torrent_handle> handles = ses.get_torrents();
@ -617,78 +693,91 @@ namespace libtorrent
// --outstanding_resume_data;
// }
//
//.. note:: Note how ``outstanding_resume_data`` is a global counter in this example.
// This is deliberate, otherwise there is a race condition for torrents that
// was just asked to save their resume data, they posted the alert, but it has
// not been received yet. Those torrents would report that they don't need to
// save resume data again, and skipped by the initial loop, and thwart the counter
// otherwise.
//.. note::
// Note how ``outstanding_resume_data`` is a global counter in this
// example. This is deliberate, otherwise there is a race condition for
// torrents that was just asked to save their resume data, they posted
// the alert, but it has not been received yet. Those torrents would
// report that they don't need to save resume data again, and skipped by
// the initial loop, and thwart the counter otherwise.
void save_resume_data(int flags = 0) const;
// This function returns true if any whole chunk has been downloaded since the
// torrent was first loaded or since the last time the resume data was saved. When
// saving resume data periodically, it makes sense to skip any torrent which hasn't
// downloaded anything since the last time.
// This function returns true if any whole chunk has been downloaded
// since the torrent was first loaded or since the last time the resume
// data was saved. When saving resume data periodically, it makes sense
// to skip any torrent which hasn't downloaded anything since the last
// time.
//
//.. note:: A torrent's resume data is considered saved as soon as the alert
// is posted. It is important to make sure this alert is received and handled
// in order for this function to be meaningful.
//.. note::
// A torrent's resume data is considered saved as soon as the alert is
// posted. It is important to make sure this alert is received and
// handled in order for this function to be meaningful.
bool need_save_resume_data() const;
// changes whether the torrent is auto managed or not. For more info,
// see queuing_.
void auto_managed(bool m) const;
// Every torrent that is added is assigned a queue position exactly one greater than
// the greatest queue position of all existing torrents. Torrents that are being
// seeded have -1 as their queue position, since they're no longer in line to be downloaded.
// Every torrent that is added is assigned a queue position exactly one
// greater than the greatest queue position of all existing torrents.
// Torrents that are being seeded have -1 as their queue position, since
// they're no longer in line to be downloaded.
//
// When a torrent is removed or turns into a seed, all torrents with greater queue positions
// have their positions decreased to fill in the space in the sequence.
// When a torrent is removed or turns into a seed, all torrents with
// greater queue positions have their positions decreased to fill in the
// space in the sequence.
//
// ``queue_position()`` returns the torrent's position in the download queue. The torrents
// with the smallest numbers are the ones that are being downloaded. The smaller number,
// the closer the torrent is to the front of the line to be started.
// ``queue_position()`` returns the torrent's position in the download
// queue. The torrents with the smallest numbers are the ones that are
// being downloaded. The smaller number, the closer the torrent is to the
// front of the line to be started.
//
// The queue position is also available in the torrent_status.
//
// The ``queue_position_*()`` functions adjust the torrents position in the queue. Up means
// closer to the front and down means closer to the back of the queue. Top and bottom refers
// to the front and the back of the queue respectively.
// The ``queue_position_*()`` functions adjust the torrents position in
// the queue. Up means closer to the front and down means closer to the
// back of the queue. Top and bottom refers to the front and the back of
// the queue respectively.
int queue_position() const;
void queue_position_up() const;
void queue_position_down() const;
void queue_position_top() const;
void queue_position_bottom() const;
// Sets or gets the flag that derermines if countries should be resolved for the peers of this
// torrent. It defaults to false. If it is set to true, the peer_info structure for the peers
// in this torrent will have their ``country`` member set. See peer_info for more information
// on how to interpret this field.
// Sets or gets the flag that derermines if countries should be resolved
// for the peers of this torrent. It defaults to false. If it is set to
// true, the peer_info structure for the peers in this torrent will have
// their ``country`` member set. See peer_info for more information on
// how to interpret this field.
void resolve_countries(bool r);
bool resolve_countries() const;
// For SSL torrents, use this to specify a path to a .pem file to use as this client's certificate.
// The certificate must be signed by the certificate in the .torrent file to be valid.
// For SSL torrents, use this to specify a path to a .pem file to use as
// this client's certificate. The certificate must be signed by the
// certificate in the .torrent file to be valid.
//
// ``cert`` is a path to the (signed) certificate in .pem format corresponding to this torrent.
// ``cert`` is a path to the (signed) certificate in .pem format
// corresponding to this torrent.
//
// ``private_key`` is a path to the private key for the specified certificate. This must be in .pem
// format.
// ``private_key`` is a path to the private key for the specified
// certificate. This must be in .pem format.
//
// ``dh_params`` is a path to the Diffie-Hellman parameter file, which needs to be in .pem format.
// You can generate this file using the openssl command like this:
// ``openssl dhparam -outform PEM -out dhparams.pem 512``.
// ``dh_params`` is a path to the Diffie-Hellman parameter file, which
// needs to be in .pem format. You can generate this file using the
// openssl command like this: ``openssl dhparam -outform PEM -out
// dhparams.pem 512``.
//
// ``passphrase`` may be specified if the private key is encrypted and requires a passphrase to
// be decrypted.
// ``passphrase`` may be specified if the private key is encrypted and
// requires a passphrase to be decrypted.
//
// Note that when a torrent first starts up, and it needs a certificate, it will suspend connecting
// to any peers until it has one. It's typically desirable to resume the torrent after setting the
// ssl certificate.
// Note that when a torrent first starts up, and it needs a certificate,
// it will suspend connecting to any peers until it has one. It's
// typically desirable to resume the torrent after setting the ssl
// certificate.
//
// If you receive a torrent_need_cert_alert, you need to call this to provide a valid cert. If you
// don't have a cert you won't be allowed to connect to any peers.
// If you receive a torrent_need_cert_alert, you need to call this to
// provide a valid cert. If you don't have a cert you won't be allowed to
// connect to any peers.
void set_ssl_certificate(std::string const& certificate
, std::string const& private_key
, std::string const& dh_params

15
include/libtorrent/upnp.hpp
View File

@ -93,20 +93,7 @@ namespace libtorrent
};
}
#if BOOST_VERSION < 103500
extern asio::error::error_category upnp_category;
#else
struct TORRENT_EXPORT upnp_error_category : boost::system::error_category
{
virtual const char* name() const BOOST_SYSTEM_NOEXCEPT;
virtual std::string message(int ev) const BOOST_SYSTEM_NOEXCEPT;
virtual boost::system::error_condition default_error_condition(int ev) const BOOST_SYSTEM_NOEXCEPT
{ return boost::system::error_condition(ev, *this); }
};
extern TORRENT_EXPORT upnp_error_category upnp_category;
#endif
boost::system::error_category& get_upnp_category();
// int: port-mapping index
// address: external address as queried from router

62
src/upnp.cpp
View File

@ -58,7 +58,7 @@ POSSIBILITY OF SUCH DAMAGE.
#endif
#include <cstdlib>
using namespace libtorrent;
namespace libtorrent {
static error_code ec;
@ -795,7 +795,7 @@ struct parse_state
}
};
TORRENT_EXPORT void find_control_url(int type, char const* string, parse_state& state)
TORRENT_EXTRA_EXPORT void find_control_url(int type, char const* string, parse_state& state)
{
if (type == xml_start_tag)
{
@ -1098,36 +1098,48 @@ namespace
#if BOOST_VERSION >= 103500
const char* upnp_error_category::name() const BOOST_SYSTEM_NOEXCEPT
struct upnp_error_category : boost::system::error_category
{
return "UPnP error";
}
std::string upnp_error_category::message(int ev) const BOOST_SYSTEM_NOEXCEPT
{
int num_errors = sizeof(error_codes) / sizeof(error_codes[0]);
error_code_t* end = error_codes + num_errors;
error_code_t tmp = {ev, 0};
error_code_t* e = std::lower_bound(error_codes, end, tmp
, boost::bind(&error_code_t::code, _1) < boost::bind(&error_code_t::code, _2));
if (e != end && e->code == ev)
virtual const char* name() const BOOST_SYSTEM_NOEXCEPT
{
return e->msg;
return "UPnP error";
}
return "unknown UPnP error";
}
namespace libtorrent
virtual std::string message(int ev) const BOOST_SYSTEM_NOEXCEPT
{
int num_errors = sizeof(error_codes) / sizeof(error_codes[0]);
error_code_t* end = error_codes + num_errors;
error_code_t tmp = {ev, 0};
error_code_t* e = std::lower_bound(error_codes, end, tmp
, boost::bind(&error_code_t::code, _1) < boost::bind(&error_code_t::code, _2));
if (e != end && e->code == ev)
{
return e->msg;
}
char msg[200];
snprintf(msg, sizeof(msg), "unknown UPnP error (%d)", ev);
return msg;
}
virtual boost::system::error_condition default_error_condition(
int ev) const BOOST_SYSTEM_NOEXCEPT
{
return boost::system::error_condition(ev, *this);
}
};
boost::system::error_category& get_upnp_category()
{
TORRENT_EXPORT upnp_error_category upnp_category;
static upnp_error_category cat;
return cat;
}
#else
namespace libtorrent
boost::system::error_category& get_upnp_category()
{
TORRENT_EXPORT ::asio::error::error_category upnp_category(21);
static ::asio::error::error_category cat(21);
return cat;
}
#endif
@ -1386,7 +1398,7 @@ void upnp::return_error(int mapping, int code, mutex::scoped_lock& l)
error_string += e->msg;
}
l.unlock();
m_callback(mapping, address(), 0, error_code(code, upnp_category));
m_callback(mapping, address(), 0, error_code(code, get_upnp_category()));
l.lock();
}
@ -1441,7 +1453,7 @@ void upnp::on_upnp_unmap_response(error_code const& e
l.unlock();
m_callback(mapping, address(), 0, p.status_code() != 200
? error_code(p.status_code(), get_http_category())
: error_code(s.error_code, upnp_category));
: error_code(s.error_code, get_upnp_category()));
l.lock();
d.mapping[mapping].protocol = none;
@ -1525,3 +1537,5 @@ void upnp::close()
}
}
}

6
test/test_xml.cpp
View File

@ -235,6 +235,8 @@ char upnp_xml2[] =
using namespace libtorrent;
namespace libtorrent {
struct parse_state
{
parse_state(): in_service(false), service_type("") {}
@ -255,7 +257,9 @@ struct parse_state
std::string url_base;
};
TORRENT_EXPORT void find_control_url(int type, char const* string, parse_state& state);
TORRENT_EXTRA_EXPORT void find_control_url(int type\
, char const* string, parse_state& state);
}
void parser_callback(std::string& out, int token, char const* s, char const* val)
{