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

reference documentation cleanup

This commit is contained in:
Arvid Norberg 2014-04-28 04:46:33 +00:00
parent d7b8dbdc8f
commit 903ac3b268
19 changed files with 733 additions and 628 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
docs/gen_reference_doc.py
View File

@ -146,12 +146,19 @@ def highlight_signature(s):
# make the name of the function bold # make the name of the function bold
name2[-1] = '**' + name2[-1] + '** ' name2[-1] = '**' + name2[-1] + '** '
name2[0] = name2[0].replace('*', '\\*')
# if there is a return value, make sure we preserve pointer types
if len(name2) > 1:
name2[0] = name2[0].replace('*', '\\*')
name[0] = ' '.join(name2) name[0] = ' '.join(name2)
# we have to escape asterisks, since this is rendered into # we have to escape asterisks, since this is rendered into
# a parsed literal in rst # a parsed literal in rst
name[1] = name[1].replace('*', '\\*') name[1] = name[1].replace('*', '\\*')
# comments in signatures are italic
name[1] = name[1].replace('/\\*', '*/\\*')
name[1] = name[1].replace('\\*/', '\\*/*')
return '('.join(name) return '('.join(name)
def html_sanitize(s): def html_sanitize(s):
@ -756,25 +763,28 @@ def linkify_symbols(string):
in_literal = True in_literal = True
words = l.split(' ') words = l.split(' ')
if len(words) == 1:
ret.append(l)
continue
for i in range(len(words)): for i in range(len(words)):
# it's important to preserve leading # it's important to preserve leading
# tabs, since that's relevant for # tabs, since that's relevant for
# rst markup # rst markup
leading_tabs = 0
while leading_tabs < len(words[i]) and words[i][leading_tabs] == '\t': leading = ''
leading_tabs += 1 w = words[i]
if len(w) == 0: continue
while len(w) > 0 and \
w[0] in ['\t', ' ', '(', '[', '{']:
leading += w[0]
w = w[1:]
# preserve commas and dots at the end # preserve commas and dots at the end
w = words[i].strip() w = w.strip()
trailing = '' trailing = ''
if len(w) == 0: continue if len(w) == 0: continue
while len(w) > 1 and (w[-1] == '.' or w[-1] == ',' or (w[-1] == ')' and w[-2:] != '()')): while len(w) > 1 and w[-1] in ['.', ',', ')'] and w[-2:] != '()':
trailing = w[-1] + trailing trailing = w[-1] + trailing
w = w[:-1] w = w[:-1]
@ -789,7 +799,7 @@ def linkify_symbols(string):
if w in symbols: if w in symbols:
link_name = link_name.replace('-', ' ') link_name = link_name.replace('-', ' ')
# print ' found %s -> %s' % (w, link_name) # print ' found %s -> %s' % (w, link_name)
words[i] = (leading_tabs * '\t') + print_link(link_name, symbols[w]) + trailing words[i] = leading + print_link(link_name, symbols[w]) + trailing
ret.append(' '.join(words)) ret.append(' '.join(words))
return '\n'.join(ret) return '\n'.join(ret)

28
docs/manual-ref.html
View File

@ -55,17 +55,17 @@
<div class="contents topic" id="table-of-contents"> <div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of contents</p> <p class="topic-title first">Table of contents</p>
<ul class="simple"> <ul class="simple">
<li><a class="reference internal" href="#overview" id="id52">overview</a></li> <li><a class="reference internal" href="#overview" id="id55">overview</a></li>
<li><a class="reference internal" href="#things-to-keep-in-mind" id="id53">things to keep in mind</a></li> <li><a class="reference internal" href="#things-to-keep-in-mind" id="id56">things to keep in mind</a></li>
<li><a class="reference internal" href="#network-primitives" id="id54">network primitives</a></li> <li><a class="reference internal" href="#network-primitives" id="id57">network primitives</a></li>
<li><a class="reference internal" href="#exceptions" id="id55">exceptions</a></li> <li><a class="reference internal" href="#exceptions" id="id58">exceptions</a></li>
<li><a class="reference internal" href="#magnet-links" id="id56">magnet links</a></li> <li><a class="reference internal" href="#magnet-links" id="id59">magnet links</a></li>
<li><a class="reference internal" href="#queuing" id="id57">queuing</a></li> <li><a class="reference internal" href="#queuing" id="id60">queuing</a></li>
<li><a class="reference internal" href="#fast-resume" id="id58">fast resume</a></li> <li><a class="reference internal" href="#fast-resume" id="id61">fast resume</a></li>
<li><a class="reference internal" href="#storage-allocation" id="id59">storage allocation</a></li> <li><a class="reference internal" href="#storage-allocation" id="id62">storage allocation</a></li>
<li><a class="reference internal" href="#extensions" id="id60">extensions</a></li> <li><a class="reference internal" href="#extensions" id="id63">extensions</a></li>
<li><a class="reference internal" href="#piece-picker" id="id61">piece picker</a></li> <li><a class="reference internal" href="#piece-picker" id="id64">piece picker</a></li>
<li><a class="reference internal" href="#ssl-torrents" id="id62">SSL torrents</a></li> <li><a class="reference internal" href="#ssl-torrents" id="id65">SSL torrents</a></li>
</ul> </ul>
</div> </div>
<div class="section" id="overview"> <div class="section" id="overview">
@ -93,7 +93,7 @@ and <a class="reference external" href="reference-Session.html#start_natpmp()">s
<li>handle updates to torrents, (see <a class="reference external" href="reference-Alerts.html#state_update_alert">state_update_alert</a>).</li> <li>handle updates to torrents, (see <a class="reference external" href="reference-Alerts.html#state_update_alert">state_update_alert</a>).</li>
<li>handle other alerts, (see <a class="reference external" href="reference-Alerts.html#alert">alert</a>).</li> <li>handle other alerts, (see <a class="reference external" href="reference-Alerts.html#alert">alert</a>).</li>
<li>query the <a class="reference external" href="reference-Session.html#session">session</a> for information (see <a class="reference external" href="reference-Session.html#status()">session::status()</a>).</li> <li>query the <a class="reference external" href="reference-Session.html#session">session</a> for information (see <a class="reference external" href="reference-Session.html#status()">session::status()</a>).</li>
<li>add and remove torrents from the <a class="reference external" href="reference-Session.html#session">session</a> (remove_torrent())</li> <li>add and remove torrents from the <a class="reference external" href="reference-Session.html#session">session</a> (<a class="reference external" href="reference-Session.html#remove_torrent()">remove_torrent()</a>)</li>
</ul> </ul>
</blockquote> </blockquote>
</li> </li>
@ -815,7 +815,7 @@ into the normal tit-for-tat mode of bittorrent, and will result in a long
ramp-up time. The heuristic to mitigate this problem is to, for the first few ramp-up time. The heuristic to mitigate this problem is to, for the first few
pieces, pick random pieces rather than rare pieces. The threshold for when to pieces, pick random pieces rather than rare pieces. The threshold for when to
leave this initial picker mode is determined by leave this initial picker mode is determined by
session_settings::initial_picker_threshold.</p> <a class="reference external" href="reference-Settings.html#initial_picker_threshold">session_settings::initial_picker_threshold</a>.</p>
</div> </div>
<div class="section" id="reverse-order"> <div class="section" id="reverse-order">
<h2>reverse order</h2> <h2>reverse order</h2>
@ -841,7 +841,7 @@ number of partial pieces is minimized (and hence the turn-around time for
downloading a block until it can be uploaded to others is minimized). It also downloading a block until it can be uploaded to others is minimized). It also
puts less stress on the disk cache, since fewer partial pieces need to be kept puts less stress on the disk cache, since fewer partial pieces need to be kept
in the cache. Whether or not to enable this is controlled by in the cache. Whether or not to enable this is controlled by
session_settings::prioritize_partial_pieces.</p> <a class="reference external" href="reference-Settings.html#prioritize_partial_pieces">session_settings::prioritize_partial_pieces</a>.</p>
<p>The main benefit of not prioritizing partial pieces is that the rarest first <p>The main benefit of not prioritizing partial pieces is that the rarest first
algorithm gets to have more influence on which pieces are picked. The picker is algorithm gets to have more influence on which pieces are picked. The picker is
more likely to truly pick the rarest piece, and hence improving the performance more likely to truly pick the rarest piece, and hence improving the performance

8
docs/reference-Alerts.html
View File

@ -793,7 +793,7 @@ code indicating an error.</p>
<pre class="literal-block"> <pre class="literal-block">
struct scrape_failed_alert: tracker_alert struct scrape_failed_alert: tracker_alert
{ {
**scrape_failed_alert** (torrent_handle const&amp; h <strong>scrape_failed_alert</strong> (torrent_handle const&amp; h
, std::string const&amp; u , std::string const&amp; u
, std::string const&amp; m); , std::string const&amp; m);
virtual std::string <strong>message</strong> () const; virtual std::string <strong>message</strong> () const;
@ -2364,7 +2364,7 @@ specifically the overload for looking up immutable items in the DHT.</p>
struct dht_immutable_item_alert: alert struct dht_immutable_item_alert: alert
{ {
virtual bool <strong>discardable</strong> () const; virtual bool <strong>discardable</strong> () const;
**dht_immutable_item_alert** (sha1_hash const&amp; t, entry const&amp; i); <strong>dht_immutable_item_alert</strong> (sha1_hash const&amp; t, entry const&amp; i);
virtual std::string <strong>message</strong> () const; virtual std::string <strong>message</strong> () const;
| alert::dht_notification; | alert::dht_notification;
@ -2390,7 +2390,7 @@ specifically the overload for looking up mutable items in the DHT.</p>
<pre class="literal-block"> <pre class="literal-block">
struct dht_mutable_item_alert: alert struct dht_mutable_item_alert: alert
{ {
**dht_mutable_item_alert** (boost::array&lt;char, 32&gt; k <strong>dht_mutable_item_alert</strong> (boost::array&lt;char, 32&gt; k
, boost::array&lt;char, 64&gt; sig , boost::array&lt;char, 64&gt; sig
, boost::uint64_t sequence , boost::uint64_t sequence
, std::string const&amp; s , std::string const&amp; s
@ -2471,7 +2471,7 @@ salt and sequence number the item was stored under.</dd>
<pre class="literal-block"> <pre class="literal-block">
struct i2p_alert : alert struct i2p_alert : alert
{ {
**i2p_alert** (error_code const&amp; ec); <strong>i2p_alert</strong> (error_code const&amp; ec);
virtual std::string <strong>message</strong> () const; virtual std::string <strong>message</strong> () const;
const static int static_category = alert::error_notification; const static int static_category = alert::error_notification;

50
docs/reference-Bencoding.html
View File

@ -55,11 +55,11 @@
<div class="contents topic" id="table-of-contents"> <div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of contents</p> <p class="topic-title first">Table of contents</p>
<ul class="simple"> <ul class="simple">
<li><a class="reference internal" href="#invalid-encoding" id="id53">invalid_encoding</a></li> <li><a class="reference internal" href="#invalid-encoding" id="id54">invalid_encoding</a></li>
<li><a class="reference internal" href="#type-error" id="id54">type_error</a></li> <li><a class="reference internal" href="#type-error" id="id55">type_error</a></li>
<li><a class="reference internal" href="#entry" id="id55">entry</a></li> <li><a class="reference internal" href="#entry" id="id56">entry</a></li>
<li><a class="reference internal" href="#pascal-string" id="id56">pascal_string</a></li> <li><a class="reference internal" href="#pascal-string" id="id57">pascal_string</a></li>
<li><a class="reference internal" href="#lazy-entry" id="id57">lazy_entry</a></li> <li><a class="reference internal" href="#lazy-entry" id="id58">lazy_entry</a></li>
</ul> </ul>
</div> </div>
<p>Bencoding is a common representation in bittorrent used for <p>Bencoding is a common representation in bittorrent used for
@ -115,7 +115,7 @@ of the <a class="reference external" href="reference-Bencoding.html#entry">entry
<pre class="literal-block"> <pre class="literal-block">
struct type_error: std::runtime_error struct type_error: std::runtime_error
{ {
**type_error** (const char* error); <strong>type_error</strong> (const char* error);
}; };
</pre> </pre>
<a name="entry"></a></div> <a name="entry"></a></div>
@ -129,11 +129,11 @@ or a string.</p>
class entry class entry
{ {
data_type <strong>type</strong> () const; data_type <strong>type</strong> () const;
**entry** (list_type const&amp;); <strong>entry</strong> (list_type const&amp;);
**entry** (integer_type const&amp;); <strong>entry</strong> (integer_type const&amp;);
**entry** (dictionary_type const&amp;); <strong>entry</strong> (dictionary_type const&amp;);
**entry** (string_type const&amp;); <strong>entry</strong> (string_type const&amp;);
**entry** (data_type t); <strong>entry</strong> (data_type t);
void <strong>operator=</strong> (string_type const&amp;); void <strong>operator=</strong> (string_type const&amp;);
void <strong>operator=</strong> (entry const&amp;); void <strong>operator=</strong> (entry const&amp;);
void <strong>operator=</strong> (integer_type const&amp;); void <strong>operator=</strong> (integer_type const&amp;);
@ -181,10 +181,10 @@ data_type <strong>type</strong> () const;
<div class="section" id="id16"> <div class="section" id="id16">
<h2>entry()</h2> <h2>entry()</h2>
<pre class="literal-block"> <pre class="literal-block">
**entry** (list_type const&amp;); <strong>entry</strong> (list_type const&amp;);
**entry** (integer_type const&amp;); <strong>entry</strong> (integer_type const&amp;);
**entry** (dictionary_type const&amp;); <strong>entry</strong> (dictionary_type const&amp;);
**entry** (string_type const&amp;); <strong>entry</strong> (string_type const&amp;);
</pre> </pre>
<p>constructors directly from a specific type. <p>constructors directly from a specific type.
The content of the argument is copied into the The content of the argument is copied into the
@ -193,7 +193,7 @@ newly constructed <a class="reference external" href="reference-Bencoding.html#e
<div class="section" id="id18"> <div class="section" id="id18">
<h2>entry()</h2> <h2>entry()</h2>
<pre class="literal-block"> <pre class="literal-block">
**entry** (data_type t); <strong>entry</strong> (data_type t);
</pre> </pre>
<p>construct an empty <a class="reference external" href="reference-Bencoding.html#entry">entry</a> of the specified type. <p>construct an empty <a class="reference external" href="reference-Bencoding.html#entry">entry</a> of the specified type.
see <a class="reference external" href="reference-Bencoding.html#data_type">data_type</a> enum.</p> see <a class="reference external" href="reference-Bencoding.html#data_type">data_type</a> enum.</p>
@ -209,7 +209,7 @@ void <strong>operator=</strong> (dictionary_type const&amp;);
void <strong>operator=</strong> (list_type const&amp;); void <strong>operator=</strong> (list_type const&amp;);
</pre> </pre>
<p>copies the structure of the right hand side into this <p>copies the structure of the right hand side into this
entry.</p> <a class="reference external" href="reference-Bencoding.html#entry">entry</a>.</p>
<a name="string()"></a> <a name="string()"></a>
<a name="dict()"></a> <a name="dict()"></a>
<a name="integer()"></a> <a name="integer()"></a>
@ -273,7 +273,7 @@ void <strong>swap</strong> (entry&amp; e);
</pre> </pre>
<p>swaps the content of <em>this</em> with <tt class="docutils literal">e</tt>.</p> <p>swaps the content of <em>this</em> with <tt class="docutils literal">e</tt>.</p>
<a name="operator[]()"></a></div> <a name="operator[]()"></a></div>
<div class="section" id="id23"> <div class="section" id="id24">
<h2>operator[]()</h2> <h2>operator[]()</h2>
<pre class="literal-block"> <pre class="literal-block">
entry&amp; <strong>operator[]</strong> (std::string const&amp; key); entry&amp; <strong>operator[]</strong> (std::string const&amp; key);
@ -372,22 +372,22 @@ would require copying the string.</p>
<pre class="literal-block"> <pre class="literal-block">
struct pascal_string struct pascal_string
{ {
**pascal_string** (char const* p, int l); <strong>pascal_string</strong> (char const* p, int l);
bool <strong>operator&lt;</strong> (pascal_string const&amp; rhs) const; bool <strong>operator&lt;</strong> (pascal_string const&amp; rhs) const;
int len; int len;
char const* ptr; char const* ptr;
}; };
</pre> </pre>
<a name="pascal_string()"></a><div class="section" id="id30"> <a name="pascal_string()"></a><div class="section" id="id31">
<h2>pascal_string()</h2> <h2>pascal_string()</h2>
<pre class="literal-block"> <pre class="literal-block">
**pascal_string** (char const* p, int l); <strong>pascal_string</strong> (char const* p, int l);
</pre> </pre>
<p>construct a string pointing to the characters at <tt class="docutils literal">p</tt> <p>construct a string pointing to the characters at <tt class="docutils literal">p</tt>
of length <tt class="docutils literal">l</tt> characters. No NULL termination is required.</p> of length <tt class="docutils literal">l</tt> characters. No NULL termination is required.</p>
<a name="operator<()"></a></div> <a name="operator<()"></a></div>
<div class="section" id="id31"> <div class="section" id="id32">
<h2>operator&lt;()</h2> <h2>operator&lt;()</h2>
<pre class="literal-block"> <pre class="literal-block">
bool <strong>operator&lt;</strong> (pascal_string const&amp; rhs) const; bool <strong>operator&lt;</strong> (pascal_string const&amp; rhs) const;
@ -460,7 +460,7 @@ struct lazy_entry
}; };
}; };
</pre> </pre>
<a name="type()"></a><div class="section" id="id35"> <a name="type()"></a><div class="section" id="id36">
<h2>type()</h2> <h2>type()</h2>
<pre class="literal-block"> <pre class="literal-block">
entry_type_t <strong>type</strong> () const; entry_type_t <strong>type</strong> () const;
@ -636,7 +636,7 @@ std::pair&lt;char const*, int&gt; <strong>data_section</strong> () const;
<p>returns pointers into the source buffer where <p>returns pointers into the source buffer where
this <a class="reference external" href="reference-Bencoding.html#entry">entry</a> has its bencoded data</p> this <a class="reference external" href="reference-Bencoding.html#entry">entry</a> has its bencoded data</p>
<a name="swap()"></a></div> <a name="swap()"></a></div>
<div class="section" id="id43"> <div class="section" id="id44">
<h2>swap()</h2> <h2>swap()</h2>
<pre class="literal-block"> <pre class="literal-block">
void <strong>swap</strong> (lazy_entry&amp; e); void <strong>swap</strong> (lazy_entry&amp; e);
@ -724,7 +724,7 @@ entry e = bdecode(buf, buf + data_size);
<p>If <tt class="docutils literal">bdecode()</tt> encounters invalid encoded data in the range given to it <p>If <tt class="docutils literal">bdecode()</tt> encounters invalid encoded data in the range given to it
it will throw <a class="reference external" href="reference-Error_Codes.html#libtorrent_exception">libtorrent_exception</a>.</p> it will throw <a class="reference external" href="reference-Error_Codes.html#libtorrent_exception">libtorrent_exception</a>.</p>
<a name="operator<<()"></a></div> <a name="operator<<()"></a></div>
<div class="section" id="id50"> <div class="section" id="id51">
<h2>operator&lt;&lt;()</h2> <h2>operator&lt;&lt;()</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/entry.hpp">libtorrent/entry.hpp</a>&quot;</p> <p>Declared in &quot;<a class="reference external" href="../include/libtorrent/entry.hpp">libtorrent/entry.hpp</a>&quot;</p>
<pre class="literal-block"> <pre class="literal-block">

112
docs/reference-Core.html
View File

@ -55,15 +55,15 @@
<div class="contents topic" id="table-of-contents"> <div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of contents</p> <p class="topic-title first">Table of contents</p>
<ul class="simple"> <ul class="simple">
<li><a class="reference internal" href="#disk-buffer-holder" id="id167">disk_buffer_holder</a></li> <li><a class="reference internal" href="#disk-buffer-holder" id="id175">disk_buffer_holder</a></li>
<li><a class="reference internal" href="#peer-info" id="id168">peer_info</a></li> <li><a class="reference internal" href="#peer-info" id="id176">peer_info</a></li>
<li><a class="reference internal" href="#peer-request" id="id169">peer_request</a></li> <li><a class="reference internal" href="#peer-request" id="id177">peer_request</a></li>
<li><a class="reference internal" href="#block-info" id="id170">block_info</a></li> <li><a class="reference internal" href="#block-info" id="id178">block_info</a></li>
<li><a class="reference internal" href="#partial-piece-info" id="id171">partial_piece_info</a></li> <li><a class="reference internal" href="#partial-piece-info" id="id179">partial_piece_info</a></li>
<li><a class="reference internal" href="#torrent-handle" id="id172">torrent_handle</a></li> <li><a class="reference internal" href="#torrent-handle" id="id180">torrent_handle</a></li>
<li><a class="reference internal" href="#torrent-status" id="id173">torrent_status</a></li> <li><a class="reference internal" href="#torrent-status" id="id181">torrent_status</a></li>
<li><a class="reference internal" href="#announce-entry" id="id174">announce_entry</a></li> <li><a class="reference internal" href="#announce-entry" id="id182">announce_entry</a></li>
<li><a class="reference internal" href="#torrent-info" id="id175">torrent_info</a></li> <li><a class="reference internal" href="#torrent-info" id="id183">torrent_info</a></li>
</ul> </ul>
</div> </div>
<a name="disk_buffer_holder"></a><div class="section" id="disk-buffer-holder"> <a name="disk_buffer_holder"></a><div class="section" id="disk-buffer-holder">
@ -78,8 +78,8 @@ this buffer has been released, <tt class="docutils literal">buffer()</tt> will r
<pre class="literal-block"> <pre class="literal-block">
struct disk_buffer_holder struct disk_buffer_holder
{ {
**disk_buffer_holder** (disk_buffer_pool&amp; disk_pool, char* buf); <strong>disk_buffer_holder</strong> (disk_buffer_pool&amp; disk_pool, char* buf);
**~disk_buffer_holder** (); <strong>~disk_buffer_holder</strong> ();
char* <strong>release</strong> (); char* <strong>release</strong> ();
char* <strong>get</strong> () const; char* <strong>get</strong> () const;
void <strong>reset</strong> (char* buf = 0); void <strong>reset</strong> (char* buf = 0);
@ -89,7 +89,7 @@ struct disk_buffer_holder
<a name="disk_buffer_holder()"></a><div class="section" id="id2"> <a name="disk_buffer_holder()"></a><div class="section" id="id2">
<h2>disk_buffer_holder()</h2> <h2>disk_buffer_holder()</h2>
<pre class="literal-block"> <pre class="literal-block">
**disk_buffer_holder** (disk_buffer_pool&amp; disk_pool, char* buf); <strong>disk_buffer_holder</strong> (disk_buffer_pool&amp; disk_pool, char* buf);
</pre> </pre>
<p>construct a buffer holder that will free the held buffer <p>construct a buffer holder that will free the held buffer
using a disk buffer pool directly (there's only one using a disk buffer pool directly (there's only one
@ -98,7 +98,7 @@ disk_buffer_pool per <a class="reference external" href="reference-Session.html#
<div class="section" id="id4"> <div class="section" id="id4">
<h2>~disk_buffer_holder()</h2> <h2>~disk_buffer_holder()</h2>
<pre class="literal-block"> <pre class="literal-block">
**~disk_buffer_holder** (); <strong>~disk_buffer_holder</strong> ();
</pre> </pre>
<p>frees any unreleased disk buffer held by this object</p> <p>frees any unreleased disk buffer held by this object</p>
<a name="release()"></a></div> <a name="release()"></a></div>
@ -1011,7 +1011,7 @@ handle will remain valid between two calls.</p>
<pre class="literal-block"> <pre class="literal-block">
struct torrent_handle struct torrent_handle
{ {
**torrent_handle** (); <strong>torrent_handle</strong> ();
void <strong>add_piece</strong> (int piece, char const* data, int flags = 0) const; void <strong>add_piece</strong> (int piece, char const* data, int flags = 0) const;
void <strong>read_piece</strong> (int piece) const; void <strong>read_piece</strong> (int piece) const;
bool <strong>have_piece</strong> (int piece) const; bool <strong>have_piece</strong> (int piece) const;
@ -1136,7 +1136,7 @@ struct torrent_handle
<a name="torrent_handle()"></a><div class="section" id="id26"> <a name="torrent_handle()"></a><div class="section" id="id26">
<h2>torrent_handle()</h2> <h2>torrent_handle()</h2>
<pre class="literal-block"> <pre class="literal-block">
**torrent_handle** (); <strong>torrent_handle</strong> ();
</pre> </pre>
<p>constructs a torrent handle that does not refer to a torrent. <p>constructs a torrent handle that does not refer to a torrent.
i.e. <a class="reference external" href="reference-Core.html#is_valid()">is_valid()</a> will return false.</p> i.e. <a class="reference external" href="reference-Core.html#is_valid()">is_valid()</a> will return false.</p>
@ -1158,7 +1158,7 @@ instruct libtorrent to overwrite any data that may already have been
downloaded with this data.</p> downloaded with this data.</p>
<p>Since the data is written asynchronously, you may know that is passed <p>Since the data is written asynchronously, you may know that is passed
or failed the hash check by waiting for <a class="reference external" href="reference-Alerts.html#piece_finished_alert">piece_finished_alert</a> or or failed the hash check by waiting for <a class="reference external" href="reference-Alerts.html#piece_finished_alert">piece_finished_alert</a> or
hash_failed_alert.</p> <a class="reference external" href="reference-Alerts.html#hash_failed_alert">hash_failed_alert</a>.</p>
<a name="read_piece()"></a></div> <a name="read_piece()"></a></div>
<div class="section" id="read-piece"> <div class="section" id="read-piece">
<h2>read_piece()</h2> <h2>read_piece()</h2>
@ -1312,11 +1312,11 @@ libtorrent to use another list of trackers for this torrent, you can
use <tt class="docutils literal">replace_trackers()</tt> which takes a list of the same form as the use <tt class="docutils literal">replace_trackers()</tt> which takes a list of the same form as the
one returned from <tt class="docutils literal">trackers()</tt> and will replace it. If you want an one returned from <tt class="docutils literal">trackers()</tt> and will replace it. If you want an
immediate effect, you have to call <a class="reference external" href="reference-Core.html#force_reannounce()">force_reannounce()</a>. See immediate effect, you have to call <a class="reference external" href="reference-Core.html#force_reannounce()">force_reannounce()</a>. See
announce_entry.</p> <a class="reference external" href="reference-Core.html#announce_entry">announce_entry</a>.</p>
<p><tt class="docutils literal">add_tracker()</tt> will look if the specified tracker is already in the <p><tt class="docutils literal">add_tracker()</tt> 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 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 of trackers, it will insert it in the tier specified in the
announce_entry.</p> <a class="reference external" href="reference-Core.html#announce_entry">announce_entry</a>.</p>
<p>The updated set of trackers will be saved in the resume data, and when <p>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 a torrent is started with resume data, the trackers from the resume
data will replace the original ones.</p> data will replace the original ones.</p>
@ -1405,7 +1405,7 @@ all peers respectively. When a torrent is paused, it will however
remember all share ratios to all peers and remember all potential (not remember all share ratios to all peers and remember all potential (not
connected) peers. Torrents may be paused automatically if there is a connected) peers. Torrents may be paused automatically if there is a
file error (e.g. disk full) or something similar. See file error (e.g. disk full) or something similar. See
file_error_alert.</p> <a class="reference external" href="reference-Alerts.html#file_error_alert">file_error_alert</a>.</p>
<p>To know if a torrent is paused or not, call <p>To know if a torrent is paused or not, call
<tt class="docutils literal"><span class="pre">torrent_handle::status()</span></tt> and inspect <tt class="docutils literal"><span class="pre">torrent_status::paused</span></tt>.</p> <tt class="docutils literal"><span class="pre">torrent_handle::status()</span></tt> and inspect <tt class="docutils literal"><span class="pre">torrent_status::paused</span></tt>.</p>
<p>The <tt class="docutils literal">flags</tt> argument to pause can be set to <p>The <tt class="docutils literal">flags</tt> argument to pause can be set to
@ -1490,10 +1490,10 @@ void <strong>save_resume_data</strong> (int flags = 0) const;
<a class="reference external" href="reference-Bencoding.html#entry">entry</a>. This <a class="reference external" href="reference-Bencoding.html#entry">entry</a> is suitable for being bencoded. For more information <a class="reference external" href="reference-Bencoding.html#entry">entry</a>. This <a class="reference external" href="reference-Bencoding.html#entry">entry</a> is suitable for being bencoded. For more information
about how fast-resume works, see <a class="reference external" href="manual-ref.html#fast-resume">fast resume</a>.</p> about how fast-resume works, see <a class="reference external" href="manual-ref.html#fast-resume">fast resume</a>.</p>
<p>The <tt class="docutils literal">flags</tt> argument is a bitmask of flags ORed together. see <p>The <tt class="docutils literal">flags</tt> argument is a bitmask of flags ORed together. see
save_resume_flags_t</p> <a class="reference external" href="reference-Core.html#save_resume_flags_t">save_resume_flags_t</a></p>
<p>This operation is asynchronous, <tt class="docutils literal">save_resume_data</tt> will return <p>This operation is asynchronous, <tt class="docutils literal">save_resume_data</tt> will return
immediately. The resume data is delivered when it's done through an immediately. The resume data is delivered when it's done through an
save_resume_data_alert.</p> <a class="reference external" href="reference-Alerts.html#save_resume_data_alert">save_resume_data_alert</a>.</p>
<p>The fast resume data will be empty in the following cases:</p> <p>The fast resume data will be empty in the following cases:</p>
<blockquote> <blockquote>
<ol class="arabic simple"> <ol class="arabic simple">
@ -1916,7 +1916,7 @@ void <strong>set_max_uploads</strong> (int max_uploads) const;
at the same time on this torrent. If you set this to -1, there will be at the same time on this torrent. If you set this to -1, there will be
no limit. This defaults to infinite. The primary setting controlling no limit. This defaults to infinite. The primary setting controlling
this is the global unchoke slots limit, set by unchoke_slots_limit in this is the global unchoke slots limit, set by unchoke_slots_limit in
session_settings.</p> <a class="reference external" href="reference-Settings.html#session_settings">session_settings</a>.</p>
<p><tt class="docutils literal">max_uploads()</tt> returns the current settings.</p> <p><tt class="docutils literal">max_uploads()</tt> returns the current settings.</p>
<a name="max_connections()"></a> <a name="max_connections()"></a>
<a name="set_max_connections()"></a></div> <a name="set_max_connections()"></a></div>
@ -2231,7 +2231,7 @@ torrent file (such as a magnet link or a URL).</td>
<h1>torrent_status</h1> <h1>torrent_status</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/torrent_handle.hpp">libtorrent/torrent_handle.hpp</a>&quot;</p> <p>Declared in &quot;<a class="reference external" href="../include/libtorrent/torrent_handle.hpp">libtorrent/torrent_handle.hpp</a>&quot;</p>
<p>holds a snapshot of the status of a torrent, as queried by <p>holds a snapshot of the status of a torrent, as queried by
torrent_handle::status().</p> <a class="reference external" href="reference-Core.html#status()">torrent_handle::status()</a>.</p>
<pre class="literal-block"> <pre class="literal-block">
struct torrent_status struct torrent_status
{ {
@ -2326,7 +2326,7 @@ struct torrent_status
sha1_hash info_hash; sha1_hash info_hash;
}; };
</pre> </pre>
<a name="operator==()"></a><div class="section" id="id102"> <a name="operator==()"></a><div class="section" id="id110">
<h2>operator==()</h2> <h2>operator==()</h2>
<pre class="literal-block"> <pre class="literal-block">
bool <strong>operator==</strong> (torrent_status const&amp; st) const; bool <strong>operator==</strong> (torrent_status const&amp; st) const;
@ -2334,7 +2334,7 @@ bool <strong>operator==</strong> (torrent_status const&amp; st) const;
<p>compres if the torrent status objects come from the same torrent. i.e. <p>compres if the torrent status objects come from the same torrent. i.e.
only the <a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a> field is compared.</p> only the <a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a> field is compared.</p>
<a name="state_t"></a></div> <a name="state_t"></a></div>
<div class="section" id="id104"> <div class="section" id="id112">
<h2>enum state_t</h2> <h2>enum state_t</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/torrent_handle.hpp">libtorrent/torrent_handle.hpp</a>&quot;</p> <p>Declared in &quot;<a class="reference external" href="../include/libtorrent/torrent_handle.hpp">libtorrent/torrent_handle.hpp</a>&quot;</p>
<table border="1" class="docutils"> <table border="1" class="docutils">
@ -2822,9 +2822,9 @@ relates to a specific torrent.</p>
<pre class="literal-block"> <pre class="literal-block">
struct announce_entry struct announce_entry
{ {
**announce_entry** (std::string const&amp; u); <strong>announce_entry</strong> (std::string const&amp; u);
**~announce_entry** (); <strong>~announce_entry</strong> ();
**announce_entry** (); <strong>announce_entry</strong> ();
int <strong>next_announce_in</strong> () const; int <strong>next_announce_in</strong> () const;
int <strong>min_announce_in</strong> () const; int <strong>min_announce_in</strong> () const;
void <strong>reset</strong> (); void <strong>reset</strong> ();
@ -2865,9 +2865,9 @@ struct announce_entry
<a name="~announce_entry()"></a><div class="section" id="announce-entry-announce-entry"> <a name="~announce_entry()"></a><div class="section" id="announce-entry-announce-entry">
<h2>announce_entry() ~announce_entry()</h2> <h2>announce_entry() ~announce_entry()</h2>
<pre class="literal-block"> <pre class="literal-block">
**announce_entry** (std::string const&amp; u); <strong>announce_entry</strong> (std::string const&amp; u);
**~announce_entry** (); <strong>~announce_entry</strong> ();
**announce_entry** (); <strong>announce_entry</strong> ();
</pre> </pre>
<p>constructs a tracker announce <a class="reference external" href="reference-Bencoding.html#entry">entry</a> with <tt class="docutils literal">u</tt> as the URL.</p> <p>constructs a tracker announce <a class="reference external" href="reference-Bencoding.html#entry">entry</a> with <tt class="docutils literal">u</tt> as the URL.</p>
<a name="min_announce_in()"></a> <a name="min_announce_in()"></a>
@ -2884,7 +2884,7 @@ allowed to force another tracker update with this tracker.</p>
<p>If the last time this tracker was contacted failed, <tt class="docutils literal">last_error</tt> is the error <p>If the last time this tracker was contacted failed, <tt class="docutils literal">last_error</tt> is the error
code describing what error occurred.</p> code describing what error occurred.</p>
<a name="reset()"></a></div> <a name="reset()"></a></div>
<div class="section" id="id125"> <div class="section" id="id133">
<h2>reset()</h2> <h2>reset()</h2>
<pre class="literal-block"> <pre class="literal-block">
void <strong>reset</strong> (); void <strong>reset</strong> ();
@ -3047,15 +3047,15 @@ announces.</dd>
<pre class="literal-block"> <pre class="literal-block">
class torrent_info : public intrusive_ptr_base&lt;torrent_info&gt; class torrent_info : public intrusive_ptr_base&lt;torrent_info&gt;
{ {
**torrent_info** (std::string const&amp; filename, int flags = 0); <strong>torrent_info</strong> (std::string const&amp; filename, int flags = 0);
**torrent_info** (char const* buffer, int size, error_code&amp; ec, int flags = 0); <strong>torrent_info</strong> (char const* buffer, int size, error_code&amp; ec, int flags = 0);
**torrent_info** (sha1_hash const&amp; info_hash, int flags = 0); <strong>torrent_info</strong> (sha1_hash const&amp; info_hash, int flags = 0);
**torrent_info** (lazy_entry const&amp; torrent_file, int flags = 0); <strong>torrent_info</strong> (lazy_entry const&amp; torrent_file, int flags = 0);
**torrent_info** (char const* buffer, int size, int flags = 0); <strong>torrent_info</strong> (char const* buffer, int size, int flags = 0);
**torrent_info** (lazy_entry const&amp; torrent_file, error_code&amp; ec, int flags = 0); <strong>torrent_info</strong> (lazy_entry const&amp; torrent_file, error_code&amp; ec, int flags = 0);
**torrent_info** (torrent_info const&amp; t, int flags = 0); <strong>torrent_info</strong> (torrent_info const&amp; t, int flags = 0);
**torrent_info** (std::string const&amp; filename, error_code&amp; ec, int flags = 0); <strong>torrent_info</strong> (std::string const&amp; filename, error_code&amp; ec, int flags = 0);
**~torrent_info** (); <strong>~torrent_info</strong> ();
file_storage const&amp; <strong>files</strong> () const; file_storage const&amp; <strong>files</strong> () const;
file_storage const&amp; <strong>orig_files</strong> () const; file_storage const&amp; <strong>orig_files</strong> () const;
void <strong>rename_file</strong> (int index, std::string const&amp; new_filename); void <strong>rename_file</strong> (int index, std::string const&amp; new_filename);
@ -3100,17 +3100,17 @@ class torrent_info : public intrusive_ptr_base&lt;torrent_info&gt;
bool <strong>is_merkle_torrent</strong> () const; bool <strong>is_merkle_torrent</strong> () const;
}; };
</pre> </pre>
<a name="torrent_info()"></a><div class="section" id="id129"> <a name="torrent_info()"></a><div class="section" id="id137">
<h2>torrent_info()</h2> <h2>torrent_info()</h2>
<pre class="literal-block"> <pre class="literal-block">
**torrent_info** (std::string const&amp; filename, int flags = 0); <strong>torrent_info</strong> (std::string const&amp; filename, int flags = 0);
**torrent_info** (char const* buffer, int size, error_code&amp; ec, int flags = 0); <strong>torrent_info</strong> (char const* buffer, int size, error_code&amp; ec, int flags = 0);
**torrent_info** (sha1_hash const&amp; info_hash, int flags = 0); <strong>torrent_info</strong> (sha1_hash const&amp; info_hash, int flags = 0);
**torrent_info** (lazy_entry const&amp; torrent_file, int flags = 0); <strong>torrent_info</strong> (lazy_entry const&amp; torrent_file, int flags = 0);
**torrent_info** (char const* buffer, int size, int flags = 0); <strong>torrent_info</strong> (char const* buffer, int size, int flags = 0);
**torrent_info** (lazy_entry const&amp; torrent_file, error_code&amp; ec, int flags = 0); <strong>torrent_info</strong> (lazy_entry const&amp; torrent_file, error_code&amp; ec, int flags = 0);
**torrent_info** (torrent_info const&amp; t, int flags = 0); <strong>torrent_info</strong> (torrent_info const&amp; t, int flags = 0);
**torrent_info** (std::string const&amp; filename, error_code&amp; ec, int flags = 0); <strong>torrent_info</strong> (std::string const&amp; filename, error_code&amp; ec, int flags = 0);
</pre> </pre>
<p>The constructor that takes an info-hash will initialize the info-hash to the given value, <p>The constructor that takes an info-hash will initialize the info-hash to the given value,
but leave all other fields empty. This is used internally when downloading torrents without but leave all other fields empty. This is used internally when downloading torrents without
@ -3132,10 +3132,10 @@ always throw if an error occurs. These overloads are not available when building
exception support.</p> exception support.</p>
<p>The <tt class="docutils literal">flags</tt> argument is currently unused.</p> <p>The <tt class="docutils literal">flags</tt> argument is currently unused.</p>
<a name="~torrent_info()"></a></div> <a name="~torrent_info()"></a></div>
<div class="section" id="id137"> <div class="section" id="id145">
<h2>~torrent_info()</h2> <h2>~torrent_info()</h2>
<pre class="literal-block"> <pre class="literal-block">
**~torrent_info** (); <strong>~torrent_info</strong> ();
</pre> </pre>
<p>frees all storage associated with this <a class="reference external" href="reference-Core.html#torrent_info">torrent_info</a> object</p> <p>frees all storage associated with this <a class="reference external" href="reference-Core.html#torrent_info">torrent_info</a> object</p>
<a name="orig_files()"></a> <a name="orig_files()"></a>
@ -3157,7 +3157,7 @@ names. Filename may be chaged using <tt class="docutils literal"><span class="pr
<p>For more information on the <a class="reference external" href="reference-Storage.html#file_storage">file_storage</a> object, see the separate document on how <p>For more information on the <a class="reference external" href="reference-Storage.html#file_storage">file_storage</a> object, see the separate document on how
to create torrents.</p> to create torrents.</p>
<a name="rename_file()"></a></div> <a name="rename_file()"></a></div>
<div class="section" id="id143"> <div class="section" id="id151">
<h2>rename_file()</h2> <h2>rename_file()</h2>
<pre class="literal-block"> <pre class="literal-block">
void <strong>rename_file</strong> (int index, std::string const&amp; new_filename); void <strong>rename_file</strong> (int index, std::string const&amp; new_filename);
@ -3242,7 +3242,7 @@ the piece index as argument and gives you the exact size of that piece. It will
be the same as <tt class="docutils literal">piece_length()</tt> except in the case of the last piece, which may be the same as <tt class="docutils literal">piece_length()</tt> except in the case of the last piece, which may
be smaller.</p> be smaller.</p>
<a name="info_hash()"></a></div> <a name="info_hash()"></a></div>
<div class="section" id="id150"> <div class="section" id="id158">
<h2>info_hash()</h2> <h2>info_hash()</h2>
<pre class="literal-block"> <pre class="literal-block">
const sha1_hash&amp; <strong>info_hash</strong> () const; const sha1_hash&amp; <strong>info_hash</strong> () const;
@ -3289,7 +3289,7 @@ std::string <strong>ssl_cert</strong> () const;
torrent. Otherwise returns an empty string. The certificate is torrent. Otherwise returns an empty string. The certificate is
the the public certificate in x509 format.</p> the the public certificate in x509 format.</p>
<a name="is_valid()"></a></div> <a name="is_valid()"></a></div>
<div class="section" id="id153"> <div class="section" id="id161">
<h2>is_valid()</h2> <h2>is_valid()</h2>
<pre class="literal-block"> <pre class="literal-block">
bool <strong>is_valid</strong> () const; bool <strong>is_valid</strong> () const;
@ -3402,7 +3402,7 @@ lazy_entry const* <strong>info</strong> (char const* key) const;
It can be used to access extension values put in the .torrent file. If the specified It can be used to access extension values put in the .torrent file. If the specified
key cannot be found, it returns NULL.</p> key cannot be found, it returns NULL.</p>
<a name="swap()"></a></div> <a name="swap()"></a></div>
<div class="section" id="id158"> <div class="section" id="id166">
<h2>swap()</h2> <h2>swap()</h2>
<pre class="literal-block"> <pre class="literal-block">
void <strong>swap</strong> (torrent_info&amp; ti); void <strong>swap</strong> (torrent_info&amp; ti);

8
docs/reference-Create_Torrents.html
View File

@ -103,8 +103,8 @@ the torrent. The <a class="reference external" href="reference-Bencoding.html#en
<pre class="literal-block"> <pre class="literal-block">
struct create_torrent struct create_torrent
{ {
**create_torrent** (torrent_info const&amp; ti); <strong>create_torrent</strong> (torrent_info const&amp; ti);
**create_torrent** (file_storage&amp; fs, int piece_size = 0 <strong>create_torrent</strong> (file_storage&amp; fs, int piece_size = 0
, int pad_file_limit = -1, int flags = optimize, int alignment = 0x4000); , int pad_file_limit = -1, int flags = optimize, int alignment = 0x4000);
entry <strong>generate</strong> () const; entry <strong>generate</strong> () const;
file_storage const&amp; <strong>files</strong> () const; file_storage const&amp; <strong>files</strong> () const;
@ -137,8 +137,8 @@ struct create_torrent
<a name="create_torrent()"></a><div class="section" id="id5"> <a name="create_torrent()"></a><div class="section" id="id5">
<h2>create_torrent()</h2> <h2>create_torrent()</h2>
<pre class="literal-block"> <pre class="literal-block">
**create_torrent** (torrent_info const&amp; ti); <strong>create_torrent</strong> (torrent_info const&amp; ti);
**create_torrent** (file_storage&amp; fs, int piece_size = 0 <strong>create_torrent</strong> (file_storage&amp; fs, int piece_size = 0
, int pad_file_limit = -1, int flags = optimize, int alignment = 0x4000); , int pad_file_limit = -1, int flags = optimize, int alignment = 0x4000);
</pre> </pre>
<p>The <tt class="docutils literal">piece_size</tt> is the size of each piece in bytes. It must <p>The <tt class="docutils literal">piece_size</tt> is the size of each piece in bytes. It must

160
docs/reference-Custom_Storage.html
View File

@ -55,14 +55,24 @@
<div class="contents topic" id="table-of-contents"> <div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of contents</p> <p class="topic-title first">Table of contents</p>
<ul class="simple"> <ul class="simple">
<li><a class="reference internal" href="#file-pool" id="id18">file_pool</a></li> <li><a class="reference internal" href="#file-pool" id="id22">file_pool</a></li>
<li><a class="reference internal" href="#storage-interface" id="id19">storage_interface</a></li> <li><a class="reference internal" href="#storage-interface" id="id23">storage_interface</a></li>
<li><a class="reference internal" href="#default-storage" id="id20">default_storage</a></li> <li><a class="reference internal" href="#default-storage" id="id24">default_storage</a></li>
</ul> </ul>
</div> </div>
<p>This is an example storage implementation that stores all pieces in a <tt class="docutils literal"><span class="pre">std::map</span></tt>, <p>libtorrent provides a customization point for storage of data. By default,
i.e. in RAM. It's not necessarily very useful in practice, but illustrates the (<tt class="docutils literal">default_storage</tt>) downloaded files are saved to disk according with the
basics of implementing a custom storage.</p> general conventions of bittorrent clients, mimicing the original file layout
when the torrent was created. The libtorrent user may define a custom
storage to store piece data in a different way.</p>
<p>A custom storage implementation must derive from and implement the
<a class="reference external" href="reference-Custom_Storage.html#storage_interface">storage_interface</a>. You must also provide a function that constructs the
custom storage object and provide this function to the <a class="reference external" href="reference-Session.html#add_torrent()">add_torrent()</a> call
via <a class="reference external" href="reference-Session.html#add_torrent_params">add_torrent_params</a>. Either passed in to the constructor or by setting
the <a class="reference external" href="reference-Session.html#storage">add_torrent_params::storage</a> field.</p>
<p>This is an example storage implementation that stores all pieces in a
<tt class="docutils literal"><span class="pre">std::map</span></tt>, i.e. in RAM. It's not necessarily very useful in practice, but
illustrates the basics of implementing a custom storage.</p>
<pre class="literal-block"> <pre class="literal-block">
struct temp_storage : storage_interface struct temp_storage : storage_interface
{ {
@ -139,8 +149,8 @@ may be windows where more file handles are open.</p>
<pre class="literal-block"> <pre class="literal-block">
struct file_pool : boost::noncopyable struct file_pool : boost::noncopyable
{ {
**~file_pool** (); <strong>~file_pool</strong> ();
**file_pool** (int size = 40); <strong>file_pool</strong> (int size = 40);
boost::intrusive_ptr&lt;file&gt; <strong>open_file</strong> (void* st, std::string const&amp; p boost::intrusive_ptr&lt;file&gt; <strong>open_file</strong> (void* st, std::string const&amp; p
, int file_index, file_storage const&amp; fs, int m, error_code&amp; ec); , int file_index, file_storage const&amp; fs, int m, error_code&amp; ec);
void <strong>release</strong> (void* st); void <strong>release</strong> (void* st);
@ -153,8 +163,8 @@ struct file_pool : boost::noncopyable
<a name="file_pool()"></a><div class="section" id="file-pool-file-pool"> <a name="file_pool()"></a><div class="section" id="file-pool-file-pool">
<h2>~file_pool() file_pool()</h2> <h2>~file_pool() file_pool()</h2>
<pre class="literal-block"> <pre class="literal-block">
**~file_pool** (); <strong>~file_pool</strong> ();
**file_pool** (int size = 40); <strong>file_pool</strong> (int size = 40);
</pre> </pre>
<p><tt class="docutils literal">size</tt> specifies the number of allowed files handles <p><tt class="docutils literal">size</tt> specifies the number of allowed files handles
to hold open at any given time.</p> to hold open at any given time.</p>
@ -200,23 +210,24 @@ by the <a class="reference external" href="reference-Custom_Storage.html#file_po
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/storage.hpp">libtorrent/storage.hpp</a>&quot;</p> <p>Declared in &quot;<a class="reference external" href="../include/libtorrent/storage.hpp">libtorrent/storage.hpp</a>&quot;</p>
<p>The storage interface is a pure virtual class that can be implemented to <p>The storage interface is a pure virtual class that can be implemented to
customize how and where data for a torrent is stored. The default storage customize how and where data for a torrent is stored. The default storage
implementation uses regular files in the filesystem, mapping the files in the implementation uses regular files in the filesystem, mapping the files in
torrent in the way one would assume a torrent is saved to disk. Implementing the torrent in the way one would assume a torrent is saved to disk.
your own storage interface makes it possible to store all data in RAM, or in Implementing your own storage interface makes it possible to store all
some optimized order on disk (the order the pieces are received for instance), data in RAM, or in some optimized order on disk (the order the pieces are
or saving multifile torrents in a single file in order to be able to take received for instance), or saving multifile torrents in a single file in
advantage of optimized disk-I/O.</p> order to be able to take advantage of optimized disk-I/O.</p>
<p>It is also possible to write a thin class that uses the default storage but <p>It is also possible to write a thin class that uses the default storage
modifies some particular behavior, for instance encrypting the data before but modifies some particular behavior, for instance encrypting the data
it's written to disk, and decrypting it when it's read again.</p> before it's written to disk, and decrypting it when it's read again.</p>
<p>The storage interface is based on slots, each slot is 'piece_size' number <p>The storage interface is based on slots, each slot is 'piece_size' number
of bytes. All access is done by writing and reading whole or partial of bytes. All access is done by writing and reading whole or partial
slots. One slot is one piece in the torrent, but the data in the slot slots. One slot is one piece in the torrent, but the data in the slot
does not necessarily correspond to the piece with the same index (in does not necessarily correspond to the piece with the same index (in
compact allocation mode it won't).</p> compact allocation mode it won't).</p>
<p>libtorrent comes with two built-in storage implementations; <tt class="docutils literal">default_storage</tt> <p>libtorrent comes with two built-in storage implementations;
and <tt class="docutils literal">disabled_storage</tt>. Their constructor functions are called <a class="reference external" href="reference-Storage.html#default_storage_constructor()">default_storage_constructor()</a> <tt class="docutils literal">default_storage</tt> and <tt class="docutils literal">disabled_storage</tt>. Their constructor functions
and <tt class="docutils literal">disabled_storage_constructor</tt> respectively. The disabled storage does are called <a class="reference external" href="reference-Storage.html#default_storage_constructor()">default_storage_constructor()</a> and
<tt class="docutils literal">disabled_storage_constructor</tt> respectively. The disabled storage does
just what it sounds like. It throws away data that's written, and it just what it sounds like. It throws away data that's written, and it
reads garbage. It's useful mostly for benchmarking and profiling purpose.</p> reads garbage. It's useful mostly for benchmarking and profiling purpose.</p>
<pre class="literal-block"> <pre class="literal-block">
@ -254,9 +265,10 @@ struct storage_interface
<pre class="literal-block"> <pre class="literal-block">
virtual bool <strong>initialize</strong> (bool allocate_files) = 0; virtual bool <strong>initialize</strong> (bool allocate_files) = 0;
</pre> </pre>
<p>This function is called when the storage is to be initialized. The default storage <p>This function is called when the storage is to be initialized. The
will create directories and empty files at this point. If <tt class="docutils literal">allocate_files</tt> is true, default storage will create directories and empty files at this point.
it will also <tt class="docutils literal">ftruncate</tt> all files to their target size.</p> If <tt class="docutils literal">allocate_files</tt> is true, it will also <tt class="docutils literal">ftruncate</tt> all files to
their target size.</p>
<p>Returning <tt class="docutils literal">true</tt> indicates an error occurred.</p> <p>Returning <tt class="docutils literal">true</tt> indicates an error occurred.</p>
<a name="has_any_file()"></a></div> <a name="has_any_file()"></a></div>
<div class="section" id="has-any-file"> <div class="section" id="has-any-file">
@ -264,9 +276,10 @@ it will also <tt class="docutils literal">ftruncate</tt> all files to their targ
<pre class="literal-block"> <pre class="literal-block">
virtual bool <strong>has_any_file</strong> () = 0; virtual bool <strong>has_any_file</strong> () = 0;
</pre> </pre>
<p>This function is called when first checking (or re-checking) the storage for a torrent. <p>This function is called when first checking (or re-checking) the
It should return true if any of the files that is used in this storage exists on disk. storage for a torrent. It should return true if any of the files that
If so, the storage will be checked for existing pieces before starting the download.</p> is used in this storage exists on disk. If so, the storage will be
checked for existing pieces before starting the download.</p>
<a name="set_file_priority()"></a></div> <a name="set_file_priority()"></a></div>
<div class="section" id="set-file-priority"> <div class="section" id="set-file-priority">
<h2>set_file_priority()</h2> <h2>set_file_priority()</h2>
@ -282,35 +295,37 @@ virtual void <strong>set_file_priority</strong> (std::vector&lt;boost::uint8_t&g
virtual int <strong>writev</strong> (<a class="reference external" href="file::iovec_t">file::iovec_t</a> const* bufs, int slot, int offset, int num_bufs, int flags = <a class="reference external" href="file::random_access">file::random_access</a>); virtual int <strong>writev</strong> (<a class="reference external" href="file::iovec_t">file::iovec_t</a> const* bufs, int slot, int offset, int num_bufs, int flags = <a class="reference external" href="file::random_access">file::random_access</a>);
virtual int <strong>readv</strong> (<a class="reference external" href="file::iovec_t">file::iovec_t</a> const* bufs, int slot, int offset, int num_bufs, int flags = <a class="reference external" href="file::random_access">file::random_access</a>); virtual int <strong>readv</strong> (<a class="reference external" href="file::iovec_t">file::iovec_t</a> const* bufs, int slot, int offset, int num_bufs, int flags = <a class="reference external" href="file::random_access">file::random_access</a>);
</pre> </pre>
<p>These functions should read or write the data in or to the given <tt class="docutils literal">slot</tt> at the given <tt class="docutils literal">offset</tt>. <p>These functions should read or write the data in or to the given
It should read or write <tt class="docutils literal">num_bufs</tt> buffers sequentially, where the size of each buffer <tt class="docutils literal">slot</tt> at the given <tt class="docutils literal">offset</tt>. It should read or write <tt class="docutils literal">num_bufs</tt>
is specified in the buffer array <tt class="docutils literal">bufs</tt>. The <a class="reference external" href="file::iovec_t">file::iovec_t</a> type has the following members:</p> buffers sequentially, where the size of each buffer is specified in
the buffer array <tt class="docutils literal">bufs</tt>. The <a class="reference external" href="file::iovec_t">file::iovec_t</a> type has the following
members:</p>
<pre class="literal-block"> <pre class="literal-block">
struct iovec_t struct iovec_t { void* iov_base; size_t iov_len; };
{
void* iov_base;
size_t iov_len;
};
</pre> </pre>
<p>The return value is the number of bytes actually read or written, or -1 on failure. If <p>The return value is the number of bytes actually read or written, or
it returns -1, the error code is expected to be set to</p> -1 on failure. If it returns -1, the error code is expected to be set
<p>Every buffer in <tt class="docutils literal">bufs</tt> can be assumed to be page aligned and be of a page aligned size, to</p>
except for the last buffer of the torrent. The allocated buffer can be assumed to fit a <p>Every buffer in <tt class="docutils literal">bufs</tt> can be assumed to be page aligned and be of a
fully page aligned number of bytes though. This is useful when reading and writing the page aligned size, except for the last buffer of the torrent. The
last piece of a file in unbuffered mode.</p> allocated buffer can be assumed to fit a fully page aligned number of
<p>The <tt class="docutils literal">offset</tt> is aligned to 16 kiB boundries <em>most of the time</em>, but there are rare bytes though. This is useful when reading and writing the last piece
exceptions when it's not. Specifically if the read cache is disabled/or full and a of a file in unbuffered mode.</p>
client requests unaligned data, or the file itself is not aligned in the torrent. <p>The <tt class="docutils literal">offset</tt> is aligned to 16 kiB boundries <em>most of the time</em>, but
Most clients request aligned data.</p> there are rare exceptions when it's not. Specifically if the read
cache is disabled/or full and a client requests unaligned data, or the
file itself is not aligned in the torrent. Most clients request
aligned data.</p>
<a name="hint_read()"></a></div> <a name="hint_read()"></a></div>
<div class="section" id="hint-read"> <div class="section" id="hint-read">
<h2>hint_read()</h2> <h2>hint_read()</h2>
<pre class="literal-block"> <pre class="literal-block">
virtual void <strong>hint_read</strong> (int, int, int); virtual void <strong>hint_read</strong> (int, int, int);
</pre> </pre>
<p>This function is called when a read job is queued. It gives the storage wrapper an <p>This function is called when a read job is queued. It gives the
opportunity to hint the operating system about this coming read. For instance, the storage wrapper an opportunity to hint the operating system about this
storage may call <tt class="docutils literal">posix_fadvise(POSIX_FADV_WILLNEED)</tt> or <tt class="docutils literal">fcntl(F_RDADVISE)</tt>.</p> coming read. For instance, the storage may call
<tt class="docutils literal">posix_fadvise(POSIX_FADV_WILLNEED)</tt> or <tt class="docutils literal">fcntl(F_RDADVISE)</tt>.</p>
<a name="read()"></a></div> <a name="read()"></a></div>
<div class="section" id="read"> <div class="section" id="read">
<h2>read()</h2> <h2>read()</h2>
@ -339,20 +354,21 @@ byte at offset <tt class="docutils literal">offset</tt> in slot <tt class="docut
<pre class="literal-block"> <pre class="literal-block">
virtual int <strong>sparse_end</strong> (int start) const; virtual int <strong>sparse_end</strong> (int start) const;
</pre> </pre>
<p>This function is optional. It is supposed to return the first piece, starting at <p>This function is optional. It is supposed to return the first piece,
<tt class="docutils literal">start</tt> that is fully contained within a data-region on disk (i.e. non-sparse starting at <tt class="docutils literal">start</tt> that is fully contained within a data-region on
region). The purpose of this is to skip parts of files that can be known to contain disk (i.e. non-sparse region). The purpose of this is to skip parts of
zeros when checking files.</p> files that can be known to contain zeros when checking files.</p>
<a name="move_storage()"></a></div> <a name="move_storage()"></a></div>
<div class="section" id="move-storage"> <div class="section" id="move-storage">
<h2>move_storage()</h2> <h2>move_storage()</h2>
<pre class="literal-block"> <pre class="literal-block">
virtual int <strong>move_storage</strong> (std::string const&amp; save_path, int flags) = 0; virtual int <strong>move_storage</strong> (std::string const&amp; save_path, int flags) = 0;
</pre> </pre>
<p>This function should move all the files belonging to the storage to the new save_path. <p>This function should move all the files belonging to the storage to
The default storage moves the single file or the directory of the torrent.</p> the new save_path. The default storage moves the single file or the
<p>Before moving the files, any open file handles may have to be closed, like directory of the torrent.</p>
<tt class="docutils literal">release_files()</tt>.</p> <p>Before moving the files, any open file handles may have to be closed,
like <tt class="docutils literal">release_files()</tt>.</p>
<p>returns one of: <p>returns one of:
| no_error = 0 | no_error = 0
| need_full_check = -1 | need_full_check = -1
@ -396,9 +412,10 @@ efficient than reading and writing the data.</p>
<pre class="literal-block"> <pre class="literal-block">
virtual bool <strong>swap_slots</strong> (int slot1, int slot2) = 0; virtual bool <strong>swap_slots</strong> (int slot1, int slot2) = 0;
</pre> </pre>
<p>This function should swap the data in <tt class="docutils literal">slot1</tt> and <tt class="docutils literal">slot2</tt>. The default <p>This function should swap the data in <tt class="docutils literal">slot1</tt> and <tt class="docutils literal">slot2</tt>. The
storage uses a scratch buffer to read the data into, then moving the other default storage uses a scratch buffer to read the data into, then
slot and finally writing back the temporary slot's data</p> moving the other slot and finally writing back the temporary slot's
data</p>
<p>This is only used in compact mode.</p> <p>This is only used in compact mode.</p>
<p>Returning <tt class="docutils literal">true</tt> indicates an error occurred.</p> <p>Returning <tt class="docutils literal">true</tt> indicates an error occurred.</p>
<a name="swap_slots3()"></a></div> <a name="swap_slots3()"></a></div>
@ -408,8 +425,8 @@ slot and finally writing back the temporary slot's data</p>
virtual bool <strong>swap_slots3</strong> (int slot1, int slot2, int slot3) = 0; virtual bool <strong>swap_slots3</strong> (int slot1, int slot2, int slot3) = 0;
</pre> </pre>
<p>This function should do a 3-way swap, or shift of the slots. <tt class="docutils literal">slot1</tt> <p>This function should do a 3-way swap, or shift of the slots. <tt class="docutils literal">slot1</tt>
should move to <tt class="docutils literal">slot2</tt>, which should be moved to <tt class="docutils literal">slot3</tt> which in turn should move to <tt class="docutils literal">slot2</tt>, which should be moved to <tt class="docutils literal">slot3</tt> which in
should be moved to <tt class="docutils literal">slot1</tt>.</p> turn should be moved to <tt class="docutils literal">slot1</tt>.</p>
<p>This is only used in compact mode.</p> <p>This is only used in compact mode.</p>
<p>Returning <tt class="docutils literal">true</tt> indicates an error occurred.</p> <p>Returning <tt class="docutils literal">true</tt> indicates an error occurred.</p>
<a name="release_files()"></a></div> <a name="release_files()"></a></div>
@ -436,10 +453,11 @@ virtual bool <strong>rename_file</strong> (int index, std::string const&amp; new
<pre class="literal-block"> <pre class="literal-block">
virtual bool <strong>delete_files</strong> () = 0; virtual bool <strong>delete_files</strong> () = 0;
</pre> </pre>
<p>This function should delete all files and directories belonging to this storage.</p> <p>This function should delete all files and directories belonging to
this storage.</p>
<p>Returning <tt class="docutils literal">true</tt> indicates an error occurred.</p> <p>Returning <tt class="docutils literal">true</tt> indicates an error occurred.</p>
<p>The <tt class="docutils literal">disk_buffer_pool</tt> is used to allocate and free disk buffers. It has the <p>The <tt class="docutils literal">disk_buffer_pool</tt> is used to allocate and free disk buffers. It
following members:</p> has the following members:</p>
<pre class="literal-block"> <pre class="literal-block">
struct disk_buffer_pool : boost::noncopyable struct disk_buffer_pool : boost::noncopyable
{ {
@ -500,13 +518,13 @@ to the storage</p>
<div class="section" id="default-storage"> <div class="section" id="default-storage">
<h1>default_storage</h1> <h1>default_storage</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/storage.hpp">libtorrent/storage.hpp</a>&quot;</p> <p>Declared in &quot;<a class="reference external" href="../include/libtorrent/storage.hpp">libtorrent/storage.hpp</a>&quot;</p>
<p>The default implementation of <a class="reference external" href="reference-Custom_Storage.html#storage_interface">storage_interface</a>. Behaves as a normal bittorrent client. <p>The default implementation of <a class="reference external" href="reference-Custom_Storage.html#storage_interface">storage_interface</a>. Behaves as a normal
It is possible to derive from this class in order to override some of its behavior, when bittorrent client. It is possible to derive from this class in order to
implementing a custom storage.</p> override some of its behavior, when implementing a custom storage.</p>
<pre class="literal-block"> <pre class="literal-block">
class default_storage : public storage_interface, boost::noncopyable class default_storage : public storage_interface, boost::noncopyable
{ {
**default_storage** (file_storage const&amp; fs, file_storage const* mapped <strong>default_storage</strong> (file_storage const&amp; fs, file_storage const* mapped
, std::string const&amp; path, file_pool&amp; fp , std::string const&amp; path, file_pool&amp; fp
, std::vector&lt;boost::uint8_t&gt; const&amp; file_prio); , std::vector&lt;boost::uint8_t&gt; const&amp; file_prio);
bool <strong>move_slot</strong> (int src_slot, int dst_slot); bool <strong>move_slot</strong> (int src_slot, int dst_slot);
@ -531,10 +549,10 @@ class default_storage : public storage_interface, boost::noncopyable
file_storage const&amp; <strong>files</strong> () const; file_storage const&amp; <strong>files</strong> () const;
}; };
</pre> </pre>
<a name="default_storage()"></a><div class="section" id="id11"> <a name="default_storage()"></a><div class="section" id="id15">
<h2>default_storage()</h2> <h2>default_storage()</h2>
<pre class="literal-block"> <pre class="literal-block">
**default_storage** (file_storage const&amp; fs, file_storage const* mapped <strong>default_storage</strong> (file_storage const&amp; fs, file_storage const* mapped
, std::string const&amp; path, file_pool&amp; fp , std::string const&amp; path, file_pool&amp; fp
, std::vector&lt;boost::uint8_t&gt; const&amp; file_prio); , std::vector&lt;boost::uint8_t&gt; const&amp; file_prio);
</pre> </pre>

10
docs/reference-Error_Codes.html
View File

@ -55,7 +55,7 @@
<div class="contents topic" id="table-of-contents"> <div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of contents</p> <p class="topic-title first">Table of contents</p>
<ul class="simple"> <ul class="simple">
<li><a class="reference internal" href="#libtorrent-exception" id="id37">libtorrent_exception</a></li> <li><a class="reference internal" href="#libtorrent-exception" id="id38">libtorrent_exception</a></li>
</ul> </ul>
</div> </div>
<a name="libtorrent_exception"></a><div class="section" id="libtorrent-exception"> <a name="libtorrent_exception"></a><div class="section" id="libtorrent-exception">
@ -66,7 +66,7 @@ struct libtorrent_exception: std::exception
{ {
error_code <strong>error</strong> () const; error_code <strong>error</strong> () const;
virtual <strong>~libtorrent_exception</strong> () throw(); virtual <strong>~libtorrent_exception</strong> () throw();
**libtorrent_exception** (error_code const&amp; s); <strong>libtorrent_exception</strong> (error_code const&amp; s);
virtual const char* <strong>what</strong> () const throw(); virtual const char* <strong>what</strong> () const throw();
}; };
</pre> </pre>
@ -216,7 +216,7 @@ matched the info-hash, but failed to be parsed</td>
<tr><td>duplicate_torrent</td> <tr><td>duplicate_torrent</td>
<td>19</td> <td>19</td>
<td>There's already a torrent with that info-hash added to the <td>There's already a torrent with that info-hash added to the
session</td> <a class="reference external" href="reference-Session.html#session">session</a></td>
</tr> </tr>
<tr><td>invalid_torrent_handle</td> <tr><td>invalid_torrent_handle</td>
<td>20</td> <td>20</td>
@ -918,7 +918,7 @@ URL. i.e. it doesn't contain &quot;announce.</td>
</tbody> </tbody>
</table> </table>
<a name="error_code_enum"></a></div> <a name="error_code_enum"></a></div>
<div class="section" id="id31"> <div class="section" id="id32">
<h2>enum error_code_enum</h2> <h2>enum error_code_enum</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/lazy_entry.hpp">libtorrent/lazy_entry.hpp</a>&quot;</p> <p>Declared in &quot;<a class="reference external" href="../include/libtorrent/lazy_entry.hpp">libtorrent/lazy_entry.hpp</a>&quot;</p>
<table border="1" class="docutils"> <table border="1" class="docutils">
@ -1036,7 +1036,7 @@ URL. i.e. it doesn't contain &quot;announce.</td>
</tbody> </tbody>
</table> </table>
<a name="error_code_enum"></a></div> <a name="error_code_enum"></a></div>
<div class="section" id="id34"> <div class="section" id="id35">
<h2>enum error_code_enum</h2> <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> <p>Declared in &quot;<a class="reference external" href="../include/libtorrent/upnp.hpp">libtorrent/upnp.hpp</a>&quot;</p>
<table border="1" class="docutils"> <table border="1" class="docutils">

80
docs/reference-Plugins.html
View File

@ -240,15 +240,15 @@ ability to change or override the default libtorrent behavior.</p>
struct torrent_plugin struct torrent_plugin
{ {
virtual boost::shared_ptr&lt;peer_plugin&gt; <strong>new_connection</strong> (peer_connection*); virtual boost::shared_ptr&lt;peer_plugin&gt; <strong>new_connection</strong> (peer_connection*);
virtual void <strong>on_piece_pass</strong> (int /*index*/); virtual void <strong>on_piece_pass</strong> (int <em>/*index*/</em>);
virtual void <strong>on_piece_failed</strong> (int /*index*/); virtual void <strong>on_piece_failed</strong> (int <em>/*index*/</em>);
virtual void <strong>tick</strong> (); virtual void <strong>tick</strong> ();
virtual bool <strong>on_resume</strong> (); virtual bool <strong>on_resume</strong> ();
virtual bool <strong>on_pause</strong> (); virtual bool <strong>on_pause</strong> ();
virtual void <strong>on_files_checked</strong> (); virtual void <strong>on_files_checked</strong> ();
virtual void <strong>on_state</strong> (int /*s*/); virtual void <strong>on_state</strong> (int <em>/*s*/</em>);
virtual void <strong>on_add_peer</strong> (<a class="reference external" href="tcp::endpoint">tcp::endpoint</a> const&amp;, virtual void <strong>on_add_peer</strong> (<a class="reference external" href="tcp::endpoint">tcp::endpoint</a> const&amp;,
int /*src*/, int /*flags*/); int <em>/*src*/</em>, int <em>/*flags*/</em>);
}; };
</pre> </pre>
<a name="new_connection()"></a><div class="section" id="new-connection"> <a name="new_connection()"></a><div class="section" id="new-connection">
@ -273,8 +273,8 @@ use <tt class="docutils literal">weak_ptr</tt>.</p>
<div class="section" id="on-piece-failed-on-piece-pass"> <div class="section" id="on-piece-failed-on-piece-pass">
<h3>on_piece_failed() on_piece_pass()</h3> <h3>on_piece_failed() on_piece_pass()</h3>
<pre class="literal-block"> <pre class="literal-block">
virtual void <strong>on_piece_pass</strong> (int /*index*/); virtual void <strong>on_piece_pass</strong> (int <em>/*index*/</em>);
virtual void <strong>on_piece_failed</strong> (int /*index*/); virtual void <strong>on_piece_failed</strong> (int <em>/*index*/</em>);
</pre> </pre>
<p>These hooks are called when a piece passes the hash check or fails the hash <p>These hooks are called when a piece passes the hash check or fails the hash
check, respectively. The <tt class="docutils literal">index</tt> is the piece index that was downloaded. check, respectively. The <tt class="docutils literal">index</tt> is the piece index that was downloaded.
@ -320,7 +320,7 @@ can start downloading.</p>
<div class="section" id="on-state"> <div class="section" id="on-state">
<h3>on_state()</h3> <h3>on_state()</h3>
<pre class="literal-block"> <pre class="literal-block">
virtual void <strong>on_state</strong> (int /*s*/); virtual void <strong>on_state</strong> (int <em>/*s*/</em>);
</pre> </pre>
<p>called when the torrent changes state <p>called when the torrent changes state
the state is one of <a class="reference external" href="reference-Core.html#state_t">torrent_status::state_t</a> the state is one of <a class="reference external" href="reference-Core.html#state_t">torrent_status::state_t</a>
@ -330,7 +330,7 @@ enum members</p>
<h3>on_add_peer()</h3> <h3>on_add_peer()</h3>
<pre class="literal-block"> <pre class="literal-block">
virtual void <strong>on_add_peer</strong> (<a class="reference external" href="tcp::endpoint">tcp::endpoint</a> const&amp;, virtual void <strong>on_add_peer</strong> (<a class="reference external" href="tcp::endpoint">tcp::endpoint</a> const&amp;,
int /*src*/, int /*flags*/); int <em>/*src*/</em>, int <em>/*flags*/</em>);
</pre> </pre>
<p>called every time a new peer is added to the peer list. <p>called every time a new peer is added to the peer list.
This is before the peer is connected to. For <tt class="docutils literal">flags</tt>, see This is before the peer is connected to. For <tt class="docutils literal">flags</tt>, see
@ -354,33 +354,33 @@ struct peer_plugin
{ {
virtual char const* <strong>type</strong> () const; virtual char const* <strong>type</strong> () const;
virtual void <strong>add_handshake</strong> (entry&amp;); virtual void <strong>add_handshake</strong> (entry&amp;);
virtual void <strong>on_disconnect</strong> (error_code const&amp; /*ec*/); virtual void <strong>on_disconnect</strong> (error_code const&amp; <em>/*ec*/</em>);
virtual void <strong>on_connected</strong> (); virtual void <strong>on_connected</strong> ();
virtual bool <strong>on_handshake</strong> (char const* /*reserved_bits*/); virtual bool <strong>on_handshake</strong> (char const* <em>/*reserved_bits*/</em>);
virtual bool <strong>on_extension_handshake</strong> (lazy_entry const&amp;); virtual bool <strong>on_extension_handshake</strong> (lazy_entry const&amp;);
virtual bool <strong>on_have</strong> (int /*index*/); virtual bool <strong>on_have</strong> (int <em>/*index*/</em>);
virtual bool <strong>on_bitfield</strong> (bitfield const&amp; /*bitfield*/); virtual bool <strong>on_bitfield</strong> (bitfield const&amp; <em>/*bitfield*/</em>);
virtual bool <strong>on_have_all</strong> (); virtual bool <strong>on_have_all</strong> ();
virtual bool <strong>on_reject</strong> (peer_request const&amp;); virtual bool <strong>on_reject</strong> (peer_request const&amp;);
virtual bool <strong>on_request</strong> (peer_request const&amp;); virtual bool <strong>on_request</strong> (peer_request const&amp;);
virtual bool <strong>on_unchoke</strong> (); virtual bool <strong>on_unchoke</strong> ();
virtual bool <strong>on_interested</strong> (); virtual bool <strong>on_interested</strong> ();
virtual bool <strong>on_allowed_fast</strong> (int /*index*/); virtual bool <strong>on_allowed_fast</strong> (int <em>/*index*/</em>);
virtual bool <strong>on_have_none</strong> (); virtual bool <strong>on_have_none</strong> ();
virtual bool <strong>on_choke</strong> (); virtual bool <strong>on_choke</strong> ();
virtual bool <strong>on_not_interested</strong> (); virtual bool <strong>on_not_interested</strong> ();
virtual bool <strong>on_piece</strong> (peer_request const&amp; /*piece*/ virtual bool <strong>on_piece</strong> (peer_request const&amp; <em>/*piece*/</em>
, disk_buffer_holder&amp; /*data*/); , disk_buffer_holder&amp; <em>/*data*/</em>);
virtual bool <strong>on_suggest</strong> (int /*index*/); virtual bool <strong>on_suggest</strong> (int <em>/*index*/</em>);
virtual bool <strong>on_cancel</strong> (peer_request const&amp;); virtual bool <strong>on_cancel</strong> (peer_request const&amp;);
virtual bool <strong>on_dont_have</strong> (int /*index*/); virtual bool <strong>on_dont_have</strong> (int <em>/*index*/</em>);
virtual bool <strong>can_disconnect</strong> (error_code const&amp; /*ec*/); virtual bool <strong>can_disconnect</strong> (error_code const&amp; <em>/*ec*/</em>);
virtual bool <strong>on_extended</strong> (int /*length*/, int /*msg*/, virtual bool <strong>on_extended</strong> (int <em>/*length*/</em>, int <em>/*msg*/</em>,
buffer::const_interval /*body*/); buffer::const_interval <em>/*body*/</em>);
virtual bool <strong>on_unknown_message</strong> (int /*length*/, int /*msg*/, virtual bool <strong>on_unknown_message</strong> (int <em>/*length*/</em>, int <em>/*msg*/</em>,
buffer::const_interval /*body*/); buffer::const_interval <em>/*body*/</em>);
virtual void <strong>on_piece_pass</strong> (int /*index*/); virtual void <strong>on_piece_pass</strong> (int <em>/*index*/</em>);
virtual void <strong>on_piece_failed</strong> (int /*index*/); virtual void <strong>on_piece_failed</strong> (int <em>/*index*/</em>);
virtual void <strong>tick</strong> (); virtual void <strong>tick</strong> ();
virtual bool <strong>write_request</strong> (peer_request const&amp;); virtual bool <strong>write_request</strong> (peer_request const&amp;);
}; };
@ -404,7 +404,7 @@ this is not called for web seeds</p>
<div class="section" id="on-disconnect"> <div class="section" id="on-disconnect">
<h3>on_disconnect()</h3> <h3>on_disconnect()</h3>
<pre class="literal-block"> <pre class="literal-block">
virtual void <strong>on_disconnect</strong> (error_code const&amp; /*ec*/); virtual void <strong>on_disconnect</strong> (error_code const&amp; <em>/*ec*/</em>);
</pre> </pre>
<p>called when the peer is being disconnected.</p> <p>called when the peer is being disconnected.</p>
<a name="on_connected()"></a></div> <a name="on_connected()"></a></div>
@ -421,7 +421,7 @@ called.</p>
<div class="section" id="on-handshake"> <div class="section" id="on-handshake">
<h3>on_handshake()</h3> <h3>on_handshake()</h3>
<pre class="literal-block"> <pre class="literal-block">
virtual bool <strong>on_handshake</strong> (char const* /*reserved_bits*/); virtual bool <strong>on_handshake</strong> (char const* <em>/*reserved_bits*/</em>);
</pre> </pre>
<p>this is called when the initial BT handshake is received. Returning false <p>this is called when the initial BT handshake is received. Returning false
means that the other end doesn't support this extension and will remove means that the other end doesn't support this extension and will remove
@ -456,22 +456,22 @@ this is not called for web seeds</p>
<div class="section" id="on-bitfield-on-have-none-on-suggest-on-unchoke-on-cancel-on-have-on-choke-on-piece-on-request-on-reject-on-not-interested-on-interested-on-allowed-fast-on-have-all-on-dont-have"> <div class="section" id="on-bitfield-on-have-none-on-suggest-on-unchoke-on-cancel-on-have-on-choke-on-piece-on-request-on-reject-on-not-interested-on-interested-on-allowed-fast-on-have-all-on-dont-have">
<h3>on_bitfield() on_have_none() on_suggest() on_unchoke() on_cancel() on_have() on_choke() on_piece() on_request() on_reject() on_not_interested() on_interested() on_allowed_fast() on_have_all() on_dont_have()</h3> <h3>on_bitfield() on_have_none() on_suggest() on_unchoke() on_cancel() on_have() on_choke() on_piece() on_request() on_reject() on_not_interested() on_interested() on_allowed_fast() on_have_all() on_dont_have()</h3>
<pre class="literal-block"> <pre class="literal-block">
virtual bool <strong>on_have</strong> (int /*index*/); virtual bool <strong>on_have</strong> (int <em>/*index*/</em>);
virtual bool <strong>on_bitfield</strong> (bitfield const&amp; /*bitfield*/); virtual bool <strong>on_bitfield</strong> (bitfield const&amp; <em>/*bitfield*/</em>);
virtual bool <strong>on_have_all</strong> (); virtual bool <strong>on_have_all</strong> ();
virtual bool <strong>on_reject</strong> (peer_request const&amp;); virtual bool <strong>on_reject</strong> (peer_request const&amp;);
virtual bool <strong>on_request</strong> (peer_request const&amp;); virtual bool <strong>on_request</strong> (peer_request const&amp;);
virtual bool <strong>on_unchoke</strong> (); virtual bool <strong>on_unchoke</strong> ();
virtual bool <strong>on_interested</strong> (); virtual bool <strong>on_interested</strong> ();
virtual bool <strong>on_allowed_fast</strong> (int /*index*/); virtual bool <strong>on_allowed_fast</strong> (int <em>/*index*/</em>);
virtual bool <strong>on_have_none</strong> (); virtual bool <strong>on_have_none</strong> ();
virtual bool <strong>on_choke</strong> (); virtual bool <strong>on_choke</strong> ();
virtual bool <strong>on_not_interested</strong> (); virtual bool <strong>on_not_interested</strong> ();
virtual bool <strong>on_piece</strong> (peer_request const&amp; /*piece*/ virtual bool <strong>on_piece</strong> (peer_request const&amp; <em>/*piece*/</em>
, disk_buffer_holder&amp; /*data*/); , disk_buffer_holder&amp; <em>/*data*/</em>);
virtual bool <strong>on_suggest</strong> (int /*index*/); virtual bool <strong>on_suggest</strong> (int <em>/*index*/</em>);
virtual bool <strong>on_cancel</strong> (peer_request const&amp;); virtual bool <strong>on_cancel</strong> (peer_request const&amp;);
virtual bool <strong>on_dont_have</strong> (int /*index*/); virtual bool <strong>on_dont_have</strong> (int <em>/*index*/</em>);
</pre> </pre>
<p>returning true from any of the message handlers <p>returning true from any of the message handlers
indicates that the <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> has handeled the message. indicates that the <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> has handeled the message.
@ -482,7 +482,7 @@ handler.</p>
<div class="section" id="can-disconnect"> <div class="section" id="can-disconnect">
<h3>can_disconnect()</h3> <h3>can_disconnect()</h3>
<pre class="literal-block"> <pre class="literal-block">
virtual bool <strong>can_disconnect</strong> (error_code const&amp; /*ec*/); virtual bool <strong>can_disconnect</strong> (error_code const&amp; <em>/*ec*/</em>);
</pre> </pre>
<p>called when libtorrent think this peer should be disconnected. <p>called when libtorrent think this peer should be disconnected.
if the <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> returns false, the peer will not be disconnected.</p> if the <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> returns false, the peer will not be disconnected.</p>
@ -490,8 +490,8 @@ if the <a class="reference external" href="reference-Plugins.html#plugin">plugin
<div class="section" id="on-extended"> <div class="section" id="on-extended">
<h3>on_extended()</h3> <h3>on_extended()</h3>
<pre class="literal-block"> <pre class="literal-block">
virtual bool <strong>on_extended</strong> (int /*length*/, int /*msg*/, virtual bool <strong>on_extended</strong> (int <em>/*length*/</em>, int <em>/*msg*/</em>,
buffer::const_interval /*body*/); buffer::const_interval <em>/*body*/</em>);
</pre> </pre>
<p>called when an extended message is received. If returning true, <p>called when an extended message is received. If returning true,
the message is not processed by any other <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> and if false the message is not processed by any other <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> and if false
@ -502,8 +502,8 @@ this is not called for web seeds</p>
<div class="section" id="on-unknown-message"> <div class="section" id="on-unknown-message">
<h3>on_unknown_message()</h3> <h3>on_unknown_message()</h3>
<pre class="literal-block"> <pre class="literal-block">
virtual bool <strong>on_unknown_message</strong> (int /*length*/, int /*msg*/, virtual bool <strong>on_unknown_message</strong> (int <em>/*length*/</em>, int <em>/*msg*/</em>,
buffer::const_interval /*body*/); buffer::const_interval <em>/*body*/</em>);
</pre> </pre>
<p>this is not called for web seeds</p> <p>this is not called for web seeds</p>
<a name="on_piece_failed()"></a> <a name="on_piece_failed()"></a>
@ -511,8 +511,8 @@ virtual bool <strong>on_unknown_message</strong> (int /*length*/, int /*msg*/,
<div class="section" id="id53"> <div class="section" id="id53">
<h3>on_piece_failed() on_piece_pass()</h3> <h3>on_piece_failed() on_piece_pass()</h3>
<pre class="literal-block"> <pre class="literal-block">
virtual void <strong>on_piece_pass</strong> (int /*index*/); virtual void <strong>on_piece_pass</strong> (int <em>/*index*/</em>);
virtual void <strong>on_piece_failed</strong> (int /*index*/); virtual void <strong>on_piece_failed</strong> (int <em>/*index*/</em>);
</pre> </pre>
<p>called when a piece that this peer participated in either <p>called when a piece that this peer participated in either
fails or passes the hash_check</p> fails or passes the hash_check</p>

10
docs/reference-RSS.html
View File

@ -69,8 +69,8 @@ a feed of torrents.</p>
<pre class="literal-block"> <pre class="literal-block">
struct feed_item struct feed_item
{ {
**feed_item** (); <strong>feed_item</strong> ();
**~feed_item** (); <strong>~feed_item</strong> ();
std::string url; std::string url;
std::string uuid; std::string uuid;
@ -119,7 +119,7 @@ after adding the feed</p>
<pre class="literal-block"> <pre class="literal-block">
struct feed_settings struct feed_settings
{ {
**feed_settings** (); <strong>feed_settings</strong> ();
std::string url; std::string url;
bool auto_download; bool auto_download;
@ -173,7 +173,7 @@ calling <a class="reference external" href="reference-RSS.html#get_feed_status()
<pre class="literal-block"> <pre class="literal-block">
struct feed_status struct feed_status
{ {
**feed_status** (); <strong>feed_status</strong> ();
std::string url; std::string url;
std::string title; std::string title;
@ -240,7 +240,7 @@ default ttl, or the ttl specified by the feed.</dd>
<pre class="literal-block"> <pre class="literal-block">
struct feed_handle struct feed_handle
{ {
**feed_handle** (); <strong>feed_handle</strong> ();
void <strong>update_feed</strong> (); void <strong>update_feed</strong> ();
feed_status <strong>get_feed_status</strong> () const; feed_status <strong>get_feed_status</strong> () const;
void <strong>set_settings</strong> (feed_settings const&amp; s); void <strong>set_settings</strong> (feed_settings const&amp; s);

325
docs/reference-Session.html
View File

@ -55,39 +55,42 @@
<div class="contents topic" id="table-of-contents"> <div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of contents</p> <p class="topic-title first">Table of contents</p>
<ul class="simple"> <ul class="simple">
<li><a class="reference internal" href="#add-torrent-params" id="id168">add_torrent_params</a></li> <li><a class="reference internal" href="#add-torrent-params" id="id172">add_torrent_params</a></li>
<li><a class="reference internal" href="#cache-status" id="id169">cache_status</a></li> <li><a class="reference internal" href="#cache-status" id="id173">cache_status</a></li>
<li><a class="reference internal" href="#session-proxy" id="id170">session_proxy</a></li> <li><a class="reference internal" href="#session-proxy" id="id174">session_proxy</a></li>
<li><a class="reference internal" href="#id36" id="id171">session</a></li> <li><a class="reference internal" href="#id36" id="id175">session</a></li>
<li><a class="reference internal" href="#dht-lookup" id="id172">dht_lookup</a></li> <li><a class="reference internal" href="#dht-lookup" id="id176">dht_lookup</a></li>
<li><a class="reference internal" href="#dht-routing-bucket" id="id173">dht_routing_bucket</a></li> <li><a class="reference internal" href="#dht-routing-bucket" id="id177">dht_routing_bucket</a></li>
<li><a class="reference internal" href="#utp-status" id="id174">utp_status</a></li> <li><a class="reference internal" href="#utp-status" id="id178">utp_status</a></li>
<li><a class="reference internal" href="#session-status" id="id175">session_status</a></li> <li><a class="reference internal" href="#session-status" id="id179">session_status</a></li>
</ul> </ul>
</div> </div>
<a name="add_torrent_params"></a><div class="section" id="add-torrent-params"> <a name="add_torrent_params"></a><div class="section" id="add-torrent-params">
<h1>add_torrent_params</h1> <h1>add_torrent_params</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/add_torrent_params.hpp">libtorrent/add_torrent_params.hpp</a>&quot;</p> <p>Declared in &quot;<a class="reference external" href="../include/libtorrent/add_torrent_params.hpp">libtorrent/add_torrent_params.hpp</a>&quot;</p>
<p>The <a class="reference external" href="reference-Session.html#add_torrent_params">add_torrent_params</a> is a parameter pack for adding torrents to a <a class="reference external" href="reference-Session.html#session">session</a>. <p>The <a class="reference external" href="reference-Session.html#add_torrent_params">add_torrent_params</a> is a parameter pack for adding torrents to a
The key fields when adding a torrent are:</p> <a class="reference external" href="reference-Session.html#session">session</a>. The key fields when adding a torrent are:</p>
<ul class="simple"> <ul class="simple">
<li>ti - when you have a .torrent file</li> <li>ti - when you have a .torrent file</li>
<li>url - when you have a magnet link or http URL to the .torrent file</li> <li>url - when you have a magnet link or http URL to the .torrent file</li>
<li>info_hash - when all you have is an info-hash (this is similar to a magnet link)</li> <li>info_hash - when all you have is an info-hash (this is similar to a
magnet link)</li>
</ul> </ul>
<p>one of those fields need to be set. Another mandatory field is <tt class="docutils literal">save_path</tt>. <p>one of those fields need to be set. Another mandatory field is
The <a class="reference external" href="reference-Session.html#add_torrent_params">add_torrent_params</a> object is passed into one of the <tt class="docutils literal"><span class="pre">session::add_torrent()</span></tt> <tt class="docutils literal">save_path</tt>. The <a class="reference external" href="reference-Session.html#add_torrent_params">add_torrent_params</a> object is passed into one of the
overloads or <tt class="docutils literal"><span class="pre">session::async_add_torrent()</span></tt>.</p> <tt class="docutils literal"><span class="pre">session::add_torrent()</span></tt> overloads or <tt class="docutils literal"><span class="pre">session::async_add_torrent()</span></tt>.</p>
<p>If you only specify the info-hash, the torrent file will be downloaded from peers, <p>If you only specify the info-hash, the torrent file will be downloaded
which requires them to support the metadata extension. For the metadata extension from peers, which requires them to support the metadata extension. For
to work, libtorrent must be built with extensions enabled (<tt class="docutils literal">TORRENT_DISABLE_EXTENSIONS</tt> must not be the metadata extension to work, libtorrent must be built with extensions
defined). It also takes an optional <tt class="docutils literal">name</tt> argument. This may be left empty in case no enabled (<tt class="docutils literal">TORRENT_DISABLE_EXTENSIONS</tt> must not be defined). It also
name should be assigned to the torrent. In case it's not, the name is used for takes an optional <tt class="docutils literal">name</tt> argument. This may be left empty in case no
the torrent as long as it doesn't have metadata. See <tt class="docutils literal"><span class="pre">torrent_handle::name</span></tt>.</p> name should be assigned to the torrent. In case it's not, the name is
used for the torrent as long as it doesn't have metadata. See
<tt class="docutils literal"><span class="pre">torrent_handle::name</span></tt>.</p>
<pre class="literal-block"> <pre class="literal-block">
struct add_torrent_params struct add_torrent_params
{ {
**add_torrent_params** (storage_constructor_type sc = default_storage_constructor); <strong>add_torrent_params</strong> (storage_constructor_type sc = default_storage_constructor);
enum flags_t enum flags_t
{ {
@ -132,20 +135,20 @@ struct add_torrent_params
<a name="add_torrent_params()"></a><div class="section" id="id5"> <a name="add_torrent_params()"></a><div class="section" id="id5">
<h2>add_torrent_params()</h2> <h2>add_torrent_params()</h2>
<pre class="literal-block"> <pre class="literal-block">
**add_torrent_params** (storage_constructor_type sc = default_storage_constructor); <strong>add_torrent_params</strong> (storage_constructor_type sc = default_storage_constructor);
</pre> </pre>
<p>The constructor can be used to initialize the storage constructor, which determines <p>The constructor can be used to initialize the storage constructor,
the storage mechanism for the downloaded or seeding data for the torrent. For more which determines the storage mechanism for the downloaded or seeding
information, see the <tt class="docutils literal">storage</tt> field.</p> data for the torrent. For more information, see the <tt class="docutils literal">storage</tt> field.</p>
<a name="flags_t"></a></div> <a name="flags_t"></a></div>
<div class="section" id="enum-flags-t"> <div class="section" id="enum-flags-t">
<h2>enum flags_t</h2> <h2>enum flags_t</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/add_torrent_params.hpp">libtorrent/add_torrent_params.hpp</a>&quot;</p> <p>Declared in &quot;<a class="reference external" href="../include/libtorrent/add_torrent_params.hpp">libtorrent/add_torrent_params.hpp</a>&quot;</p>
<table border="1" class="docutils"> <table border="1" class="docutils">
<colgroup> <colgroup>
<col width="21%" /> <col width="27%" />
<col width="5%" /> <col width="7%" />
<col width="74%" /> <col width="66%" />
</colgroup> </colgroup>
<thead valign="bottom"> <thead valign="bottom">
<tr><th class="head">name</th> <tr><th class="head">name</th>
@ -156,84 +159,99 @@ information, see the <tt class="docutils literal">storage</tt> field.</p>
<tbody valign="top"> <tbody valign="top">
<tr><td>flag_seed_mode</td> <tr><td>flag_seed_mode</td>
<td>1</td> <td>1</td>
<td><p class="first">If <tt class="docutils literal">flag_seed_mode</tt> is set, libtorrent will assume that all files are present <td><p class="first">If <tt class="docutils literal">flag_seed_mode</tt> is set, libtorrent will assume that all files
for this torrent and that they all match the hashes in the torrent file. Each time are present for this torrent and that they all match the hashes in
a peer requests to download a block, the piece is verified against the hash, unless the torrent file. Each time a peer requests to download a block,
it has been verified already. If a hash fails, the torrent will automatically leave the piece is verified against the hash, unless it has been verified
the seed mode and recheck all the files. The use case for this mode is if a torrent already. If a hash fails, the torrent will automatically leave the
is created and seeded, or if the user already know that the files are complete, this seed mode and recheck all the files. The use case for this mode is
is a way to avoid the initial file checks, and significantly reduce the startup time.</p> if a torrent is created and seeded, or if the user already know
<p>Setting <tt class="docutils literal">flag_seed_mode</tt> on a torrent without metadata (a .torrent file) is a no-op that the files are complete, this is a way to avoid the initial
and will be ignored.</p> file checks, and significantly reduce the startup time.</p>
<p class="last">If resume data is passed in with this torrent, the seed mode saved in there will <p>Setting <tt class="docutils literal">flag_seed_mode</tt> on a torrent without metadata (a
override the seed mode you set here.</p> .torrent file) is a no-op and will be ignored.</p>
<p class="last">If resume data is passed in with this torrent, the seed mode saved
in there will override the seed mode you set here.</p>
</td> </td>
</tr> </tr>
<tr><td>flag_override_resume_data</td> <tr><td>flag_override_resume_data</td>
<td>2</td> <td>2</td>
<td><p class="first">If <tt class="docutils literal">flag_override_resume_data</tt> is set, the <tt class="docutils literal">paused</tt> and <tt class="docutils literal">auto_managed</tt> <td><p class="first">If <tt class="docutils literal">flag_override_resume_data</tt> is set, the <tt class="docutils literal">paused</tt> and
state of the torrent are not loaded from the resume data, but the states requested <tt class="docutils literal">auto_managed</tt> state of the torrent are not loaded from the
by the flags in <tt class="docutils literal">add_torrent_params</tt> will override them.</p> resume data, but the states requested by the flags in
<p class="last">If you pass in resume data, the paused state of the torrent when the resume data <tt class="docutils literal">add_torrent_params</tt> will override them.</p>
was saved will override the paused state you pass in here. You can override this <p class="last">If you pass in resume data, the paused state of the torrent when
by setting <tt class="docutils literal">flag_override_resume_data</tt>.</p> the resume data was saved will override the paused state you pass
in here. You can override this by setting
<tt class="docutils literal">flag_override_resume_data</tt>.</p>
</td> </td>
</tr> </tr>
<tr><td>flag_upload_mode</td> <tr><td>flag_upload_mode</td>
<td>4</td> <td>4</td>
<td><p class="first">If <tt class="docutils literal">flag_upload_mode</tt> is set, the torrent will be initialized in upload-mode, <td><p class="first">If <tt class="docutils literal">flag_upload_mode</tt> is set, the torrent will be initialized in
which means it will not make any piece requests. This state is typically entered upload-mode, which means it will not make any piece requests. This
on disk I/O errors, and if the torrent is also auto managed, it will be taken out state is typically entered on disk I/O errors, and if the torrent
of this state periodically. This mode can be used to avoid race conditions when is also auto managed, it will be taken out of this state
adjusting priorities of pieces before allowing the torrent to start downloading.</p> periodically. This mode can be used to avoid race conditions when
<p class="last">If the torrent is auto-managed (<tt class="docutils literal">flag_auto_managed</tt>), the torrent will eventually adjusting priorities of pieces before allowing the torrent to start
be taken out of upload-mode, regardless of how it got there. If it's important to downloading.</p>
manually control when the torrent leaves upload mode, don't make it auto managed.</p> <p class="last">If the torrent is auto-managed (<tt class="docutils literal">flag_auto_managed</tt>), the torrent
will eventually be taken out of upload-mode, regardless of how it
got there. If it's important to manually control when the torrent
leaves upload mode, don't make it auto managed.</p>
</td> </td>
</tr> </tr>
<tr><td>flag_share_mode</td> <tr><td>flag_share_mode</td>
<td>8</td> <td>8</td>
<td><p class="first">determines if the torrent should be added in <em>share mode</em> or not. <td><p class="first">determines if the torrent should be added in <em>share mode</em> or not.
Share mode indicates that we are not interested in downloading the torrent, but Share mode indicates that we are not interested in downloading the
merley want to improve our share ratio (i.e. increase it). A torrent started in torrent, but merley want to improve our share ratio (i.e. increase
share mode will do its best to never download more than it uploads to the swarm. it). A torrent started in share mode will do its best to never
If the swarm does not have enough demand for upload capacity, the torrent will download more than it uploads to the swarm. If the swarm does not
not download anything. This mode is intended to be safe to add any number of torrents have enough demand for upload capacity, the torrent will not
to, without manual screening, without the risk of downloading more than is uploaded.</p> download anything. This mode is intended to be safe to add any
<p>A torrent in share mode sets the priority to all pieces to 0, except for the pieces number of torrents to, without manual screening, without the risk
that are downloaded, when pieces are decided to be downloaded. This affects the progress of downloading more than is uploaded.</p>
bar, which might be set to &quot;100% finished&quot; most of the time. Do not change file or piece <p>A torrent in share mode sets the priority to all pieces to 0,
except for the pieces that are downloaded, when pieces are decided
to be downloaded. This affects the progress bar, which might be set
to &quot;100% finished&quot; most of the time. Do not change file or piece
priorities for torrents in share mode, it will make it not work.</p> priorities for torrents in share mode, it will make it not work.</p>
<p class="last">The share mode has one setting, the share ratio target, see <tt class="docutils literal"><span class="pre">session_settings::share_mode_target</span></tt> <p class="last">The share mode has one setting, the share ratio target, see
for more info.</p> <tt class="docutils literal"><span class="pre">session_settings::share_mode_target</span></tt> for more info.</p>
</td> </td>
</tr> </tr>
<tr><td>flag_apply_ip_filter</td> <tr><td>flag_apply_ip_filter</td>
<td>16</td> <td>16</td>
<td>determines if the IP filter should apply to this torrent or not. By <td>determines if the IP filter should apply to this torrent or not. By
default all torrents are subject to filtering by the IP filter (i.e. this flag is set by default all torrents are subject to filtering by the IP filter
default). This is useful if certain torrents needs to be excempt for some reason, being (i.e. this flag is set by default). This is useful if certain
an auto-update torrent for instance.</td> torrents needs to be excempt for some reason, being an auto-update
torrent for instance.</td>
</tr> </tr>
<tr><td>flag_paused</td> <tr><td>flag_paused</td>
<td>32</td> <td>32</td>
<td>specifies whether or not the torrent is to be started in a paused <td>specifies whether or not the torrent is to be started in a paused
state. I.e. it won't connect to the tracker or any of the peers until it's state. I.e. it won't connect to the tracker or any of the peers
resumed. This is typically a good way of avoiding race conditions when setting until it's resumed. This is typically a good way of avoiding race
configuration options on torrents before starting them.</td> conditions when setting configuration options on torrents before
starting them.</td>
</tr> </tr>
<tr><td>flag_auto_managed</td> <tr><td>flag_auto_managed</td>
<td>64</td> <td>64</td>
<td><p class="first">If the torrent is auto-managed (<tt class="docutils literal">flag_auto_managed</tt>), the torrent may be resumed <td><p class="first">If the torrent is auto-managed (<tt class="docutils literal">flag_auto_managed</tt>), the torrent
at any point, regardless of how it paused. If it's important to manually control may be resumed at any point, regardless of how it paused. If it's
when the torrent is paused and resumed, don't make it auto managed.</p> important to manually control when the torrent is paused and
<p>If <tt class="docutils literal">flag_auto_managed</tt> is set, the torrent will be queued, started and seeded resumed, don't make it auto managed.</p>
automatically by libtorrent. When this is set, the torrent should also be started <p>If <tt class="docutils literal">flag_auto_managed</tt> is set, the torrent will be queued,
as paused. The default queue order is the order the torrents were added. They started and seeded automatically by libtorrent. When this is set,
are all downloaded in that order. For more details, see <a class="reference external" href="manual-ref.html#queuing">queuing</a>.</p> the torrent should also be started as paused. The default queue
<p class="last">If you pass in resume data, the auto_managed state of the torrent when the resume data order is the order the torrents were added. They are all downloaded
was saved will override the auto_managed state you pass in here. You can override this in that order. For more details, see <a class="reference external" href="manual-ref.html#queuing">queuing</a>.</p>
by setting <tt class="docutils literal">override_resume_data</tt>.</p> <p class="last">If you pass in resume data, the auto_managed state of the torrent
when the resume data was saved will override the auto_managed state
you pass in here. You can override this by setting
<tt class="docutils literal">override_resume_data</tt>.</p>
</td> </td>
</tr> </tr>
<tr><td>flag_duplicate_is_error</td> <tr><td>flag_duplicate_is_error</td>
@ -243,7 +261,8 @@ by setting <tt class="docutils literal">override_resume_data</tt>.</p>
<tr><td>flag_merge_resume_trackers</td> <tr><td>flag_merge_resume_trackers</td>
<td>256</td> <td>256</td>
<td>defaults to off and specifies whether tracker URLs loaded from <td>defaults to off and specifies whether tracker URLs loaded from
resume data should be added to the trackers in the torrent or replace the trackers.</td> resume data should be added to the trackers in the torrent or
replace the trackers.</td>
</tr> </tr>
<tr><td>flag_update_subscribe</td> <tr><td>flag_update_subscribe</td>
<td>512</td> <td>512</td>
@ -252,16 +271,16 @@ updates when calling <a class="reference external" href="reference-Session.html#
</tr> </tr>
<tr><td>flag_super_seeding</td> <tr><td>flag_super_seeding</td>
<td>1024</td> <td>1024</td>
<td>sets the torrent into super seeding mode. If the torrent <td>sets the torrent into super seeding mode. If the torrent is not a
is not a seed, this flag has no effect. It has the same effect as calling seed, this flag has no effect. It has the same effect as calling
<tt class="docutils literal"><span class="pre">torrent_handle::super_seeding(true)</span></tt> on the torrent handle immediately <tt class="docutils literal"><span class="pre">torrent_handle::super_seeding(true)</span></tt> on the torrent handle
after adding it.</td> immediately after adding it.</td>
</tr> </tr>
<tr><td>flag_sequential_download</td> <tr><td>flag_sequential_download</td>
<td>2048</td> <td>2048</td>
<td>sets the sequential download state for the torrent. <td>sets the sequential download state for the torrent. It has the same
It has the same effect as calling <tt class="docutils literal"><span class="pre">torrent_handle::sequential_download(true)</span></tt> effect as calling <tt class="docutils literal"><span class="pre">torrent_handle::sequential_download(true)</span></tt> on
on the torrent handle immediately after adding it.</td> the torrent handle immediately after adding it.</td>
</tr> </tr>
</tbody> </tbody>
</table> </table>
@ -272,13 +291,13 @@ is used for forward binary compatibility.</dd>
</dl> </dl>
<a name="ti"></a><dl class="docutils"> <a name="ti"></a><dl class="docutils">
<dt>ti</dt> <dt>ti</dt>
<dd><a class="reference external" href="reference-Core.html#torrent_info">torrent_info</a> object with the torrent to add. Unless the url or info_hash <dd><a class="reference external" href="reference-Core.html#torrent_info">torrent_info</a> object with the torrent to add. Unless the url or
is set, this is required to be initiazlied.</dd> info_hash is set, this is required to be initiazlied.</dd>
</dl> </dl>
<a name="trackers"></a><dl class="docutils"> <a name="trackers"></a><dl class="docutils">
<dt>trackers</dt> <dt>trackers</dt>
<dd>If the torrent doesn't have a tracker, but relies on the DHT to find peers, the <dd>If the torrent doesn't have a tracker, but relies on the DHT to find
<tt class="docutils literal">trackers</tt> can specify tracker URLs for the torrent.</dd> peers, the <tt class="docutils literal">trackers</tt> can specify tracker URLs for the torrent.</dd>
</dl> </dl>
<a name="url_seeds"></a><dl class="docutils"> <a name="url_seeds"></a><dl class="docutils">
<dt>url_seeds</dt> <dt>url_seeds</dt>
@ -288,62 +307,71 @@ is set, this is required to be initiazlied.</dd>
<a name="name"></a> <a name="name"></a>
<a name="save_path"></a><dl class="docutils"> <a name="save_path"></a><dl class="docutils">
<dt>dht_nodes name save_path</dt> <dt>dht_nodes name save_path</dt>
<dd>a list of hostname and port pairs, representing DHT nodes to be <dd>a list of hostname and port pairs, representing DHT nodes to be added
added to the <a class="reference external" href="reference-Session.html#session">session</a> (if DHT is enabled). The hostname may be an IP address.</dd> to the <a class="reference external" href="reference-Session.html#session">session</a> (if DHT is enabled). The hostname may be an IP address.</dd>
</dl> </dl>
<a name="resume_data"></a><dl class="docutils"> <a name="resume_data"></a><dl class="docutils">
<dt>resume_data</dt> <dt>resume_data</dt>
<dd>The optional parameter, <tt class="docutils literal">resume_data</tt> can be given if up to date fast-resume data <dd>The optional parameter, <tt class="docutils literal">resume_data</tt> can be given if up to date
is available. The fast-resume data can be acquired from a running torrent by calling fast-resume data is available. The fast-resume data can be acquired
<a class="reference external" href="reference-Core.html#save_resume_data()">save_resume_data()</a> on <a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a>. See <a class="reference external" href="manual-ref.html#fast-resume">fast resume</a>. The <tt class="docutils literal">vector</tt> that is from a running torrent by calling <a class="reference external" href="reference-Core.html#save_resume_data()">save_resume_data()</a> on
passed in will be swapped into the running torrent instance with <tt class="docutils literal"><span class="pre">std::vector::swap()</span></tt>.</dd> <a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a>. See <a class="reference external" href="manual-ref.html#fast-resume">fast resume</a>. The <tt class="docutils literal">vector</tt> that is passed in
will be swapped into the running torrent instance with
<tt class="docutils literal"><span class="pre">std::vector::swap()</span></tt>.</dd>
</dl> </dl>
<a name="storage_mode"></a><dl class="docutils"> <a name="storage_mode"></a><dl class="docutils">
<dt>storage_mode</dt> <dt>storage_mode</dt>
<dd>One of the values from <a class="reference external" href="reference-Storage.html#storage_mode_t">storage_mode_t</a>. For more information, see <a class="reference external" href="manual-ref.html#storage-allocation">storage allocation</a>.</dd> <dd>One of the values from <a class="reference external" href="reference-Storage.html#storage_mode_t">storage_mode_t</a>. For more information, see
<a class="reference external" href="manual-ref.html#storage-allocation">storage allocation</a>.</dd>
</dl> </dl>
<a name="storage"></a><dl class="docutils"> <a name="storage"></a><dl class="docutils">
<dt>storage</dt> <dt>storage</dt>
<dd>can be used to customize how the data is stored. The default <dd>can be used to customize how the data is stored. The default storage
storage will simply write the data to the files it belongs to, but it could be will simply write the data to the files it belongs to, but it could be
overridden to save everything to a single file at a specific location or encrypt the overridden to save everything to a single file at a specific location
content on disk for instance. For more information about the <a class="reference external" href="reference-Custom_Storage.html#storage_interface">storage_interface</a> or encrypt the content on disk for instance. For more information
that needs to be implemented for a custom storage, see <a class="reference external" href="reference-Custom_Storage.html#storage_interface">storage_interface</a>.</dd> about the <a class="reference external" href="reference-Custom_Storage.html#storage_interface">storage_interface</a> that needs to be implemented for a custom
storage, see <a class="reference external" href="reference-Custom_Storage.html#storage_interface">storage_interface</a>.</dd>
</dl> </dl>
<a name="userdata"></a><dl class="docutils"> <a name="userdata"></a><dl class="docutils">
<dt>userdata</dt> <dt>userdata</dt>
<dd>The <tt class="docutils literal">userdata</tt> parameter is optional and will be passed on to the extension <dd>The <tt class="docutils literal">userdata</tt> parameter is optional and will be passed on to the
constructor functions, if any (see <a class="reference internal" href="#add-extension">add_extension()</a>).</dd> extension constructor functions, if any (see <a class="reference internal" href="#add-extension">add_extension()</a>).</dd>
</dl> </dl>
<a name="file_priorities"></a><dl class="docutils"> <a name="file_priorities"></a><dl class="docutils">
<dt>file_priorities</dt> <dt>file_priorities</dt>
<dd>can be set to control the initial file priorities when adding <dd>can be set to control the initial file priorities when adding a
a torrent. The semantics are the same as for <tt class="docutils literal"><span class="pre">torrent_handle::prioritize_files()</span></tt>.</dd> torrent. The semantics are the same as for
<tt class="docutils literal"><span class="pre">torrent_handle::prioritize_files()</span></tt>.</dd>
</dl> </dl>
<a name="trackerid"></a><dl class="docutils"> <a name="trackerid"></a><dl class="docutils">
<dt>trackerid</dt> <dt>trackerid</dt>
<dd>the default tracker id to be used when announcing to trackers. By default <dd>the default tracker id to be used when announcing to trackers. By
this is empty, and no tracker ID is used, since this is an optional argument. If default this is empty, and no tracker ID is used, since this is an
a tracker returns a tracker ID, that ID is used instead of this.</dd> optional argument. If a tracker returns a tracker ID, that ID is used
instead of this.</dd>
</dl> </dl>
<a name="url"></a><dl class="docutils"> <a name="url"></a><dl class="docutils">
<dt>url</dt> <dt>url</dt>
<dd><p class="first">If you specify a <tt class="docutils literal">url</tt>, the torrent will be set in <tt class="docutils literal">downloading_metadata</tt> state <dd><p class="first">If you specify a <tt class="docutils literal">url</tt>, the torrent will be set in
until the .torrent file has been downloaded. If there's any error while downloading, <tt class="docutils literal">downloading_metadata</tt> state until the .torrent file has been
the torrent will be stopped and the torrent error state (<tt class="docutils literal"><span class="pre">torrent_status::error</span></tt>) downloaded. If there's any error while downloading, the torrent will
will indicate what went wrong. The <tt class="docutils literal">url</tt> may refer to a magnet link or a regular be stopped and the torrent error state (<tt class="docutils literal"><span class="pre">torrent_status::error</span></tt>)
http URL.</p> will indicate what went wrong. The <tt class="docutils literal">url</tt> may refer to a magnet link
<p>If it refers to an HTTP URL, the info-hash for the added torrent will not be the or a regular http URL.</p>
true info-hash of the .torrent. Instead a placeholder, unique, info-hash is used <p>If it refers to an HTTP URL, the info-hash for the added torrent will
which is later updated once the .torrent file has been downloaded.</p> not be the true info-hash of the .torrent. Instead a placeholder,
unique, info-hash is used which is later updated once the .torrent
file has been downloaded.</p>
<p class="last">Once the info-hash change happens, a <a class="reference external" href="reference-Alerts.html#torrent_update_alert">torrent_update_alert</a> is posted.</p> <p class="last">Once the info-hash change happens, a <a class="reference external" href="reference-Alerts.html#torrent_update_alert">torrent_update_alert</a> is posted.</p>
</dd> </dd>
</dl> </dl>
<a name="uuid"></a><dl class="docutils"> <a name="uuid"></a><dl class="docutils">
<dt>uuid</dt> <dt>uuid</dt>
<dd>if <tt class="docutils literal">uuid</tt> is specified, it is used to find duplicates. If another torrent is already <dd>if <tt class="docutils literal">uuid</tt> is specified, it is used to find duplicates. If another
running with the same UUID as the one being added, it will be considered a duplicate. This torrent is already running with the same UUID as the one being added,
is mainly useful for RSS feed items which has UUIDs specified.</dd> it will be considered a duplicate. This is mainly useful for RSS feed
items which has UUIDs specified.</dd>
</dl> </dl>
<a name="source_feed_url"></a><dl class="docutils"> <a name="source_feed_url"></a><dl class="docutils">
<dt>source_feed_url</dt> <dt>source_feed_url</dt>
@ -352,7 +380,8 @@ if it comes from an RSS feed.</dd>
</dl> </dl>
<a name="flags"></a><dl class="docutils"> <a name="flags"></a><dl class="docutils">
<dt>flags</dt> <dt>flags</dt>
<dd>flags controlling aspects of this torrent and how it's added. See <a class="reference external" href="reference-Core.html#flags_t">flags_t</a> for details.</dd> <dd>flags controlling aspects of this torrent and how it's added. See
<a class="reference external" href="reference-Core.html#flags_t">flags_t</a> for details.</dd>
</dl> </dl>
<a name="info_hash"></a><dl class="docutils"> <a name="info_hash"></a><dl class="docutils">
<dt>info_hash</dt> <dt>info_hash</dt>
@ -365,14 +394,14 @@ is the only known property of the torrent. i.e. you don't have a
<a name="upload_limit"></a> <a name="upload_limit"></a>
<a name="download_limit"></a><dl class="docutils"> <a name="download_limit"></a><dl class="docutils">
<dt>max_uploads max_connections upload_limit download_limit</dt> <dt>max_uploads max_connections upload_limit download_limit</dt>
<dd><p class="first"><tt class="docutils literal">max_uploads</tt>, <tt class="docutils literal">max_connections</tt>, <tt class="docutils literal">upload_limit</tt>, <tt class="docutils literal">download_limit</tt> correspond <dd><p class="first"><tt class="docutils literal">max_uploads</tt>, <tt class="docutils literal">max_connections</tt>, <tt class="docutils literal">upload_limit</tt>,
to the <tt class="docutils literal">set_max_uploads()</tt>, <tt class="docutils literal">set_max_connections()</tt>, <tt class="docutils literal">set_upload_limit()</tt> and <tt class="docutils literal">download_limit</tt> correspond to the <tt class="docutils literal">set_max_uploads()</tt>,
<tt class="docutils literal">set_download_limit()</tt> functions on <a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a>. These values let you initialize <tt class="docutils literal">set_max_connections()</tt>, <tt class="docutils literal">set_upload_limit()</tt> and
these settings when the torrent is added, instead of calling these functions immediately <tt class="docutils literal">set_download_limit()</tt> functions on <a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a>. These values let
following adding it.</p> you initialize these settings when the torrent is added, instead of
<p class="last">-1 means unlimited on these settings calling these functions immediately following adding it.</p>
just like their counterpart functions <p class="last">-1 means unlimited on these settings just like their counterpart
on <a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a></p> functions on <a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a></p>
</dd> </dd>
</dl> </dl>
<a name="cache_status"></a></div> <a name="cache_status"></a></div>
@ -385,7 +414,7 @@ relevant for the disk io thread and disk cache.</p>
<pre class="literal-block"> <pre class="literal-block">
struct cache_status struct cache_status
{ {
**cache_status** (); <strong>cache_status</strong> ();
size_type blocks_written; size_type blocks_written;
size_type writes; size_type writes;
@ -415,7 +444,7 @@ struct cache_status
<a name="cache_status()"></a><div class="section" id="id23"> <a name="cache_status()"></a><div class="section" id="id23">
<h2>cache_status()</h2> <h2>cache_status()</h2>
<pre class="literal-block"> <pre class="literal-block">
**cache_status** (); <strong>cache_status</strong> ();
</pre> </pre>
<p>initializes all counters to 0</p> <p>initializes all counters to 0</p>
<a name="blocks_written"></a><dl class="docutils"> <a name="blocks_written"></a><dl class="docutils">
@ -531,13 +560,13 @@ is done shutting down.</p>
<pre class="literal-block"> <pre class="literal-block">
class session_proxy class session_proxy
{ {
**session_proxy** (); <strong>session_proxy</strong> ();
}; };
</pre> </pre>
<a name="session_proxy()"></a><div class="section" id="id34"> <a name="session_proxy()"></a><div class="section" id="id34">
<h2>session_proxy()</h2> <h2>session_proxy()</h2>
<pre class="literal-block"> <pre class="literal-block">
**session_proxy** (); <strong>session_proxy</strong> ();
</pre> </pre>
<p>default constructor, does not refer to any <a class="reference external" href="reference-Session.html#session">session</a> <p>default constructor, does not refer to any <a class="reference external" href="reference-Session.html#session">session</a>
implementation object.</p> implementation object.</p>
@ -554,18 +583,18 @@ torrents to participate in.</p>
<pre class="literal-block"> <pre class="literal-block">
class session: public boost::noncopyable class session: public boost::noncopyable
{ {
**session** (fingerprint const&amp; print = fingerprint(&quot;LT&quot; <strong>session</strong> (fingerprint const&amp; print = fingerprint(&quot;LT&quot;
, LIBTORRENT_VERSION_MAJOR, LIBTORRENT_VERSION_MINOR, 0, 0) , LIBTORRENT_VERSION_MAJOR, LIBTORRENT_VERSION_MINOR, 0, 0)
, int flags = start_default_features | add_default_plugins , int flags = start_default_features | add_default_plugins
, boost::uint32_t alert_mask = alert::error_notification , boost::uint32_t alert_mask = alert::error_notification
TORRENT_LOGPATH_ARG_DEFAULT); TORRENT_LOGPATH_ARG_DEFAULT);
**session** (fingerprint const&amp; print <strong>session</strong> (fingerprint const&amp; print
, std::pair&lt;int, int&gt; listen_port_range , std::pair&lt;int, int&gt; listen_port_range
, char const* listen_interface = &quot;0.0.0.0&quot; , char const* listen_interface = &quot;0.0.0.0&quot;
, int flags = start_default_features | add_default_plugins , int flags = start_default_features | add_default_plugins
, int alert_mask = alert::error_notification , int alert_mask = alert::error_notification
TORRENT_LOGPATH_ARG_DEFAULT); TORRENT_LOGPATH_ARG_DEFAULT);
**~session** (); <strong>~session</strong> ();
void <strong>load_state</strong> (lazy_entry const&amp; e); void <strong>load_state</strong> (lazy_entry const&amp; e);
void <strong>save_state</strong> (entry&amp; e, boost::uint32_t flags = 0xffffffff) const; void <strong>save_state</strong> (entry&amp; e, boost::uint32_t flags = 0xffffffff) const;
void <strong>refresh_torrent_status</strong> (std::vector&lt;torrent_status&gt;* ret void <strong>refresh_torrent_status</strong> (std::vector&lt;torrent_status&gt;* ret
@ -684,12 +713,12 @@ class session: public boost::noncopyable
<a name="session()"></a><div class="section" id="id40"> <a name="session()"></a><div class="section" id="id40">
<h2>session()</h2> <h2>session()</h2>
<pre class="literal-block"> <pre class="literal-block">
**session** (fingerprint const&amp; print = fingerprint(&quot;LT&quot; <strong>session</strong> (fingerprint const&amp; print = fingerprint(&quot;LT&quot;
, LIBTORRENT_VERSION_MAJOR, LIBTORRENT_VERSION_MINOR, 0, 0) , LIBTORRENT_VERSION_MAJOR, LIBTORRENT_VERSION_MINOR, 0, 0)
, int flags = start_default_features | add_default_plugins , int flags = start_default_features | add_default_plugins
, boost::uint32_t alert_mask = alert::error_notification , boost::uint32_t alert_mask = alert::error_notification
TORRENT_LOGPATH_ARG_DEFAULT); TORRENT_LOGPATH_ARG_DEFAULT);
**session** (fingerprint const&amp; print <strong>session</strong> (fingerprint const&amp; print
, std::pair&lt;int, int&gt; listen_port_range , std::pair&lt;int, int&gt; listen_port_range
, char const* listen_interface = &quot;0.0.0.0&quot; , char const* listen_interface = &quot;0.0.0.0&quot;
, int flags = start_default_features | add_default_plugins , int flags = start_default_features | add_default_plugins
@ -711,12 +740,12 @@ nat-pmp) and default plugins (ut_metadata, ut_pex and smart_ban). The
default is to start those things. If you do not want them to start, default is to start those things. If you do not want them to start,
pass 0 as the flags parameter.</p> pass 0 as the flags parameter.</p>
<p>The <tt class="docutils literal">alert_mask</tt> is the same mask that you would send to <p>The <tt class="docutils literal">alert_mask</tt> is the same mask that you would send to
set_alert_mask().</p> <a class="reference external" href="reference-Session.html#set_alert_mask()">set_alert_mask()</a>.</p>
<a name="~session()"></a></div> <a name="~session()"></a></div>
<div class="section" id="id42"> <div class="section" id="id43">
<h2>~session()</h2> <h2>~session()</h2>
<pre class="literal-block"> <pre class="literal-block">
**~session** (); <strong>~session</strong> ();
</pre> </pre>
<p>The destructor of <a class="reference external" href="reference-Session.html#session">session</a> will notify all trackers that our torrents <p>The destructor of <a class="reference external" href="reference-Session.html#session">session</a> will notify all trackers that our torrents
have been shut down. If some trackers are down, they will time out. have been shut down. If some trackers are down, they will time out.
@ -998,7 +1027,7 @@ void <strong>dht_get_item</strong> (sha1_hash const&amp; target);
<p>query the DHT for an immutable item at the <tt class="docutils literal">target</tt> hash. <p>query the DHT for an immutable item at the <tt class="docutils literal">target</tt> hash.
the result is posted as a <a class="reference external" href="reference-Alerts.html#dht_immutable_item_alert">dht_immutable_item_alert</a>.</p> the result is posted as a <a class="reference external" href="reference-Alerts.html#dht_immutable_item_alert">dht_immutable_item_alert</a>.</p>
<a name="dht_get_item()"></a></div> <a name="dht_get_item()"></a></div>
<div class="section" id="id97"> <div class="section" id="id98">
<h2>dht_get_item()</h2> <h2>dht_get_item()</h2>
<pre class="literal-block"> <pre class="literal-block">
void <strong>dht_get_item</strong> (boost::array&lt;char, 32&gt; key void <strong>dht_get_item</strong> (boost::array&lt;char, 32&gt; key
@ -1020,7 +1049,7 @@ the returned hash is the key that is to be used to look the item
up agan. It's just the sha-1 hash of the bencoded form of the up agan. It's just the sha-1 hash of the bencoded form of the
structure.</p> structure.</p>
<a name="dht_put_item()"></a></div> <a name="dht_put_item()"></a></div>
<div class="section" id="id99"> <div class="section" id="id100">
<h2>dht_put_item()</h2> <h2>dht_put_item()</h2>
<pre class="literal-block"> <pre class="literal-block">
void <strong>dht_put_item</strong> (boost::array&lt;char, 32&gt; key void <strong>dht_put_item</strong> (boost::array&lt;char, 32&gt; key
@ -1210,7 +1239,7 @@ should be the ip-address of the interface you want the listener socket
bound to. <tt class="docutils literal">listen_on()</tt> returns the error code of the operation in bound to. <tt class="docutils literal">listen_on()</tt> returns the error code of the operation in
<tt class="docutils literal">ec</tt>. If this indicates success, the <a class="reference external" href="reference-Session.html#session">session</a> is listening on a port <tt class="docutils literal">ec</tt>. If this indicates success, the <a class="reference external" href="reference-Session.html#session">session</a> is listening on a port
within the specified range. If it fails, it will also generate an within the specified range. If it fails, it will also generate an
appropriate <a class="reference external" href="reference-Alerts.html#alert">alert</a> (listen_failed_alert).</p> appropriate <a class="reference external" href="reference-Alerts.html#alert">alert</a> (<a class="reference external" href="reference-Alerts.html#listen_failed_alert">listen_failed_alert</a>).</p>
<p>If all ports in the specified range fails to be opened for listening, <p>If all ports in the specified range fails to be opened for listening,
libtorrent will try to use port 0 (which tells the operating system to libtorrent will try to use port 0 (which tells the operating system to
pick a port that's free). If that still fails you may see a pick a port that's free). If that still fails you may see a
@ -1288,13 +1317,13 @@ void <strong>set_proxy</strong> (proxy_settings const&amp; s);
proxy_settings <strong>proxy</strong> () const; proxy_settings <strong>proxy</strong> () const;
</pre> </pre>
<p>These functions sets and queries the proxy settings to be used for the <p>These functions sets and queries the proxy settings to be used for the
session.</p> <a class="reference external" href="reference-Session.html#session">session</a>.</p>
<p>For more information on what settings are available for proxies, see <p>For more information on what settings are available for proxies, see
<a class="reference external" href="reference-Settings.html#proxy_settings">proxy_settings</a>. If the <a class="reference external" href="reference-Session.html#session">session</a> is not in anonymous mode, proxies that <a class="reference external" href="reference-Settings.html#proxy_settings">proxy_settings</a>. If the <a class="reference external" href="reference-Session.html#session">session</a> is not in anonymous mode, proxies that
aren't working or fail, will automatically be disabled and packets aren't working or fail, will automatically be disabled and packets
will flow without using any proxy. If you want to enforce using a will flow without using any proxy. If you want to enforce using a
proxy, even when the proxy doesn't work, enable anonymous_mode in proxy, even when the proxy doesn't work, enable anonymous_mode in
session_settings.</p> <a class="reference external" href="reference-Settings.html#session_settings">session_settings</a>.</p>
<a name="i2p_proxy()"></a> <a name="i2p_proxy()"></a>
<a name="set_i2p_proxy()"></a></div> <a name="set_i2p_proxy()"></a></div>
<div class="section" id="i2p-proxy-set-i2p-proxy"> <div class="section" id="i2p-proxy-set-i2p-proxy">

34
docs/reference-Settings.html
View File

@ -55,10 +55,10 @@
<div class="contents topic" id="table-of-contents"> <div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of contents</p> <p class="topic-title first">Table of contents</p>
<ul class="simple"> <ul class="simple">
<li><a class="reference internal" href="#proxy-settings" id="id37">proxy_settings</a></li> <li><a class="reference internal" href="#proxy-settings" id="id38">proxy_settings</a></li>
<li><a class="reference internal" href="#session-settings" id="id38">session_settings</a></li> <li><a class="reference internal" href="#session-settings" id="id39">session_settings</a></li>
<li><a class="reference internal" href="#dht-settings" id="id39">dht_settings</a></li> <li><a class="reference internal" href="#dht-settings" id="id40">dht_settings</a></li>
<li><a class="reference internal" href="#pe-settings" id="id40">pe_settings</a></li> <li><a class="reference internal" href="#pe-settings" id="id41">pe_settings</a></li>
</ul> </ul>
</div> </div>
<a name="proxy_settings"></a><div class="section" id="proxy-settings"> <a name="proxy_settings"></a><div class="section" id="proxy-settings">
@ -69,7 +69,7 @@ direct certain traffic to a proxy.</p>
<pre class="literal-block"> <pre class="literal-block">
struct proxy_settings struct proxy_settings
{ {
**proxy_settings** (); <strong>proxy_settings</strong> ();
std::string hostname; std::string hostname;
std::string username; std::string username;
@ -83,7 +83,7 @@ struct proxy_settings
<a name="proxy_settings()"></a><div class="section" id="id2"> <a name="proxy_settings()"></a><div class="section" id="id2">
<h2>proxy_settings()</h2> <h2>proxy_settings()</h2>
<pre class="literal-block"> <pre class="literal-block">
**proxy_settings** (); <strong>proxy_settings</strong> ();
</pre> </pre>
<p>defaults constructs proxy settings, initializing it to the default <p>defaults constructs proxy settings, initializing it to the default
settings.</p> settings.</p>
@ -131,9 +131,9 @@ session::get_settings() to get the current settings.</p>
<pre class="literal-block"> <pre class="literal-block">
struct session_settings struct session_settings
{ {
**session_settings** (std::string const&amp; user_agent = &quot;libtorrent/&quot; <strong>session_settings</strong> (std::string const&amp; user_agent = &quot;libtorrent/&quot;
LIBTORRENT_VERSION); LIBTORRENT_VERSION);
**~session_settings** (); <strong>~session_settings</strong> ();
enum io_buffer_mode_t enum io_buffer_mode_t
{ {
@ -336,9 +336,9 @@ struct session_settings
<a name="session_settings()"></a><div class="section" id="session-settings-session-settings"> <a name="session_settings()"></a><div class="section" id="session-settings-session-settings">
<h2>~session_settings() session_settings()</h2> <h2>~session_settings() session_settings()</h2>
<pre class="literal-block"> <pre class="literal-block">
**session_settings** (std::string const&amp; user_agent = &quot;libtorrent/&quot; <strong>session_settings</strong> (std::string const&amp; user_agent = &quot;libtorrent/&quot;
LIBTORRENT_VERSION); LIBTORRENT_VERSION);
**~session_settings** (); <strong>~session_settings</strong> ();
</pre> </pre>
<p>initializes the <a class="reference external" href="reference-Settings.html#session_settings">session_settings</a> to the default settings.</p> <p>initializes the <a class="reference external" href="reference-Settings.html#session_settings">session_settings</a> to the default settings.</p>
<a name="io_buffer_mode_t"></a></div> <a name="io_buffer_mode_t"></a></div>
@ -1179,7 +1179,7 @@ until libtorrent will take it out of the upload mode, to test if the
error condition has been fixed.</p> error condition has been fixed.</p>
<p>libtorrent will only do this automatically for auto managed torrents.</p> <p>libtorrent will only do this automatically for auto managed torrents.</p>
<p class="last">You can explicitly take a torrent out of upload only mode using <p class="last">You can explicitly take a torrent out of upload only mode using
set_upload_mode().</p> <a class="reference external" href="reference-Core.html#set_upload_mode()">set_upload_mode()</a>.</p>
</dd> </dd>
</dl> </dl>
<a name="disable_hash_checks"></a><dl class="docutils"> <a name="disable_hash_checks"></a><dl class="docutils">
@ -1744,7 +1744,7 @@ socket on the same port as the TCP socket.</p>
<pre class="literal-block"> <pre class="literal-block">
struct dht_settings struct dht_settings
{ {
**dht_settings** (); <strong>dht_settings</strong> ();
int max_peers_reply; int max_peers_reply;
int search_branching; int search_branching;
@ -1761,10 +1761,10 @@ struct dht_settings
bool ignore_dark_internet; bool ignore_dark_internet;
}; };
</pre> </pre>
<a name="dht_settings()"></a><div class="section" id="id25"> <a name="dht_settings()"></a><div class="section" id="id26">
<h2>dht_settings()</h2> <h2>dht_settings()</h2>
<pre class="literal-block"> <pre class="literal-block">
**dht_settings** (); <strong>dht_settings</strong> ();
</pre> </pre>
<p>initialized <a class="reference external" href="reference-Settings.html#dht_settings">dht_settings</a> to the default values</p> <p>initialized <a class="reference external" href="reference-Settings.html#dht_settings">dht_settings</a> to the default values</p>
<a name="max_peers_reply"></a><dl class="docutils"> <a name="max_peers_reply"></a><dl class="docutils">
@ -1859,7 +1859,7 @@ to peer protocol encryption.</p>
<pre class="literal-block"> <pre class="literal-block">
struct pe_settings struct pe_settings
{ {
**pe_settings** (); <strong>pe_settings</strong> ();
enum enc_policy enum enc_policy
{ {
@ -1881,10 +1881,10 @@ struct pe_settings
bool prefer_rc4; bool prefer_rc4;
}; };
</pre> </pre>
<a name="pe_settings()"></a><div class="section" id="id29"> <a name="pe_settings()"></a><div class="section" id="id30">
<h2>pe_settings()</h2> <h2>pe_settings()</h2>
<pre class="literal-block"> <pre class="literal-block">
**pe_settings** (); <strong>pe_settings</strong> ();
</pre> </pre>
<p>initializes the encryption settings with the default vaues</p> <p>initializes the encryption settings with the default vaues</p>
<a name="enc_policy"></a></div> <a name="enc_policy"></a></div>

6
docs/reference-Time.html
View File

@ -55,8 +55,8 @@
<div class="contents topic" id="table-of-contents"> <div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of contents</p> <p class="topic-title first">Table of contents</p>
<ul class="simple"> <ul class="simple">
<li><a class="reference internal" href="#time-duration" id="id17">time_duration</a></li> <li><a class="reference internal" href="#time-duration" id="id18">time_duration</a></li>
<li><a class="reference internal" href="#ptime" id="id18">ptime</a></li> <li><a class="reference internal" href="#ptime" id="id19">ptime</a></li>
</ul> </ul>
</div> </div>
<p>This section contains fundamental time types used internally by <p>This section contains fundamental time types used internally by
@ -68,7 +68,7 @@ in time.</p>
and they can only be constructed via one of the construction functions and they can only be constructed via one of the construction functions
that take a well defined time unit (seconds, minutes, etc.). They can that take a well defined time unit (seconds, minutes, etc.). They can
only be turned into well defined time units by the accessor functions only be turned into well defined time units by the accessor functions
(total_microseconds(), etc.).</p> (<a class="reference external" href="reference-Time.html#total_microseconds()">total_microseconds()</a>, etc.).</p>
<div class="note"> <div class="note">
<p class="first admonition-title">Note</p> <p class="first admonition-title">Note</p>
<p class="last">In a future version of libtorrent, these types will be replaced <p class="last">In a future version of libtorrent, these types will be replaced

28
docs/reference-Utility.html
View File

@ -67,12 +67,12 @@ in a heap allocated or borrowed array.</p>
<pre class="literal-block"> <pre class="literal-block">
struct bitfield struct bitfield
{ {
**bitfield** (int bits); <strong>bitfield</strong> (int bits);
**bitfield** (bitfield const&amp; rhs); <strong>bitfield</strong> (bitfield const&amp; rhs);
**bitfield** (bitfield&amp;&amp; rhs); <strong>bitfield</strong> (bitfield&amp;&amp; rhs);
**bitfield** (int bits, bool val); <strong>bitfield</strong> (int bits, bool val);
**bitfield** (); <strong>bitfield</strong> ();
**bitfield** (char const* b, int bits); <strong>bitfield</strong> (char const* b, int bits);
void <strong>borrow_bytes</strong> (char* b, int bits); void <strong>borrow_bytes</strong> (char* b, int bits);
void <strong>assign</strong> (char const* b, int bits); void <strong>assign</strong> (char const* b, int bits);
bool <strong>get_bit</strong> (int index) const; bool <strong>get_bit</strong> (int index) const;
@ -90,12 +90,12 @@ struct bitfield
<a name="bitfield()"></a><div class="section" id="id3"> <a name="bitfield()"></a><div class="section" id="id3">
<h2>bitfield()</h2> <h2>bitfield()</h2>
<pre class="literal-block"> <pre class="literal-block">
**bitfield** (int bits); <strong>bitfield</strong> (int bits);
**bitfield** (bitfield const&amp; rhs); <strong>bitfield</strong> (bitfield const&amp; rhs);
**bitfield** (bitfield&amp;&amp; rhs); <strong>bitfield</strong> (bitfield&amp;&amp; rhs);
**bitfield** (int bits, bool val); <strong>bitfield</strong> (int bits, bool val);
**bitfield** (); <strong>bitfield</strong> ();
**bitfield** (char const* b, int bits); <strong>bitfield</strong> (char const* b, int bits);
</pre> </pre>
<p>constructs a new <a class="reference external" href="reference-Utility.html#bitfield">bitfield</a>. The default constructor creates an empty <p>constructs a new <a class="reference external" href="reference-Utility.html#bitfield">bitfield</a>. The default constructor creates an empty
<a class="reference external" href="reference-Utility.html#bitfield">bitfield</a>. <tt class="docutils literal">bits</tt> is the size of the <a class="reference external" href="reference-Utility.html#bitfield">bitfield</a> (specified in bits). <a class="reference external" href="reference-Utility.html#bitfield">bitfield</a>. <tt class="docutils literal">bits</tt> is the size of the <a class="reference external" href="reference-Utility.html#bitfield">bitfield</a> (specified in bits).
@ -196,7 +196,7 @@ peer IDs, node IDs etc.</p>
<pre class="literal-block"> <pre class="literal-block">
class sha1_hash class sha1_hash
{ {
**sha1_hash** (); <strong>sha1_hash</strong> ();
static sha1_hash <strong>max</strong> (); static sha1_hash <strong>max</strong> ();
static sha1_hash <strong>min</strong> (); static sha1_hash <strong>min</strong> ();
explicit <strong>sha1_hash</strong> (char const* s); explicit <strong>sha1_hash</strong> (char const* s);
@ -230,7 +230,7 @@ class sha1_hash
<a name="sha1_hash()"></a><div class="section" id="id18"> <a name="sha1_hash()"></a><div class="section" id="id18">
<h2>sha1_hash()</h2> <h2>sha1_hash()</h2>
<pre class="literal-block"> <pre class="literal-block">
**sha1_hash** (); <strong>sha1_hash</strong> ();
</pre> </pre>
<p>constructs an all-sero sha1-hash</p> <p>constructs an all-sero sha1-hash</p>
<a name="max()"></a></div> <a name="max()"></a></div>

277
include/libtorrent/add_torrent_params.hpp
View File

@ -51,29 +51,32 @@ namespace libtorrent
class torrent; class torrent;
struct torrent_plugin; struct torrent_plugin;
// The add_torrent_params is a parameter pack for adding torrents to a session. // The add_torrent_params is a parameter pack for adding torrents to a
// The key fields when adding a torrent are: // session. The key fields when adding a torrent are:
// //
// * ti - when you have a .torrent file // * ti - when you have a .torrent file
// * url - when you have a magnet link or http URL to the .torrent file // * url - when you have a magnet link or http URL to the .torrent file
// * info_hash - when all you have is an info-hash (this is similar to a magnet link) // * info_hash - when all you have is an info-hash (this is similar to a
// magnet link)
// //
// one of those fields need to be set. Another mandatory field is ``save_path``. // one of those fields need to be set. Another mandatory field is
// The add_torrent_params object is passed into one of the ``session::add_torrent()`` // ``save_path``. The add_torrent_params object is passed into one of the
// overloads or ``session::async_add_torrent()``. // ``session::add_torrent()`` overloads or ``session::async_add_torrent()``.
// //
// If you only specify the info-hash, the torrent file will be downloaded from peers, // If you only specify the info-hash, the torrent file will be downloaded
// which requires them to support the metadata extension. For the metadata extension // from peers, which requires them to support the metadata extension. For
// to work, libtorrent must be built with extensions enabled (``TORRENT_DISABLE_EXTENSIONS`` must not be // the metadata extension to work, libtorrent must be built with extensions
// defined). It also takes an optional ``name`` argument. This may be left empty in case no // enabled (``TORRENT_DISABLE_EXTENSIONS`` must not be defined). It also
// name should be assigned to the torrent. In case it's not, the name is used for // takes an optional ``name`` argument. This may be left empty in case no
// the torrent as long as it doesn't have metadata. See ``torrent_handle::name``. // name should be assigned to the torrent. In case it's not, the name is
// used for the torrent as long as it doesn't have metadata. See
// ``torrent_handle::name``.
// //
struct TORRENT_EXPORT add_torrent_params struct TORRENT_EXPORT add_torrent_params
{ {
// The constructor can be used to initialize the storage constructor, which determines // The constructor can be used to initialize the storage constructor,
// the storage mechanism for the downloaded or seeding data for the torrent. For more // which determines the storage mechanism for the downloaded or seeding
// information, see the ``storage`` field. // data for the torrent. For more information, see the ``storage`` field.
add_torrent_params(storage_constructor_type sc = default_storage_constructor) add_torrent_params(storage_constructor_type sc = default_storage_constructor)
: version(LIBTORRENT_VERSION_NUM) : version(LIBTORRENT_VERSION_NUM)
#ifndef TORRENT_NO_DEPRECATE #ifndef TORRENT_NO_DEPRECATE
@ -127,102 +130,118 @@ namespace libtorrent
// values for the ``flags`` field // values for the ``flags`` field
enum flags_t enum flags_t
{ {
// If ``flag_seed_mode`` is set, libtorrent will assume that all files are present // If ``flag_seed_mode`` is set, libtorrent will assume that all files
// for this torrent and that they all match the hashes in the torrent file. Each time // are present for this torrent and that they all match the hashes in
// a peer requests to download a block, the piece is verified against the hash, unless // the torrent file. Each time a peer requests to download a block,
// it has been verified already. If a hash fails, the torrent will automatically leave // the piece is verified against the hash, unless it has been verified
// the seed mode and recheck all the files. The use case for this mode is if a torrent // already. If a hash fails, the torrent will automatically leave the
// is created and seeded, or if the user already know that the files are complete, this // seed mode and recheck all the files. The use case for this mode is
// is a way to avoid the initial file checks, and significantly reduce the startup time. // if a torrent is created and seeded, or if the user already know
// that the files are complete, this is a way to avoid the initial
// file checks, and significantly reduce the startup time.
// //
// Setting ``flag_seed_mode`` on a torrent without metadata (a .torrent file) is a no-op // Setting ``flag_seed_mode`` on a torrent without metadata (a
// and will be ignored. // .torrent file) is a no-op and will be ignored.
// //
// If resume data is passed in with this torrent, the seed mode saved in there will // If resume data is passed in with this torrent, the seed mode saved
// override the seed mode you set here. // in there will override the seed mode you set here.
flag_seed_mode = 0x001, flag_seed_mode = 0x001,
// If ``flag_override_resume_data`` is set, the ``paused`` and ``auto_managed`` // If ``flag_override_resume_data`` is set, the ``paused`` and
// state of the torrent are not loaded from the resume data, but the states requested // ``auto_managed`` state of the torrent are not loaded from the
// by the flags in ``add_torrent_params`` will override them. // resume data, but the states requested by the flags in
// ``add_torrent_params`` will override them.
// //
// If you pass in resume data, the paused state of the torrent when the resume data // If you pass in resume data, the paused state of the torrent when
// was saved will override the paused state you pass in here. You can override this // the resume data was saved will override the paused state you pass
// by setting ``flag_override_resume_data``. // in here. You can override this by setting
// ``flag_override_resume_data``.
flag_override_resume_data = 0x002, flag_override_resume_data = 0x002,
// If ``flag_upload_mode`` is set, the torrent will be initialized in upload-mode, // If ``flag_upload_mode`` is set, the torrent will be initialized in
// which means it will not make any piece requests. This state is typically entered // upload-mode, which means it will not make any piece requests. This
// on disk I/O errors, and if the torrent is also auto managed, it will be taken out // state is typically entered on disk I/O errors, and if the torrent
// of this state periodically. This mode can be used to avoid race conditions when // is also auto managed, it will be taken out of this state
// adjusting priorities of pieces before allowing the torrent to start downloading. // periodically. This mode can be used to avoid race conditions when
// adjusting priorities of pieces before allowing the torrent to start
// downloading.
// //
// If the torrent is auto-managed (``flag_auto_managed``), the torrent will eventually // If the torrent is auto-managed (``flag_auto_managed``), the torrent
// be taken out of upload-mode, regardless of how it got there. If it's important to // will eventually be taken out of upload-mode, regardless of how it
// manually control when the torrent leaves upload mode, don't make it auto managed. // got there. If it's important to manually control when the torrent
// leaves upload mode, don't make it auto managed.
flag_upload_mode = 0x004, flag_upload_mode = 0x004,
// determines if the torrent should be added in *share mode* or not. // determines if the torrent should be added in *share mode* or not.
// Share mode indicates that we are not interested in downloading the torrent, but // Share mode indicates that we are not interested in downloading the
// merley want to improve our share ratio (i.e. increase it). A torrent started in // torrent, but merley want to improve our share ratio (i.e. increase
// share mode will do its best to never download more than it uploads to the swarm. // it). A torrent started in share mode will do its best to never
// If the swarm does not have enough demand for upload capacity, the torrent will // download more than it uploads to the swarm. If the swarm does not
// not download anything. This mode is intended to be safe to add any number of torrents // have enough demand for upload capacity, the torrent will not
// to, without manual screening, without the risk of downloading more than is uploaded. // download anything. This mode is intended to be safe to add any
// number of torrents to, without manual screening, without the risk
// of downloading more than is uploaded.
// //
// A torrent in share mode sets the priority to all pieces to 0, except for the pieces // A torrent in share mode sets the priority to all pieces to 0,
// that are downloaded, when pieces are decided to be downloaded. This affects the progress // except for the pieces that are downloaded, when pieces are decided
// bar, which might be set to "100% finished" most of the time. Do not change file or piece // to be downloaded. This affects the progress bar, which might be set
// to "100% finished" most of the time. Do not change file or piece
// priorities for torrents in share mode, it will make it not work. // priorities for torrents in share mode, it will make it not work.
// //
// The share mode has one setting, the share ratio target, see ``session_settings::share_mode_target`` // The share mode has one setting, the share ratio target, see
// for more info. // ``session_settings::share_mode_target`` for more info.
flag_share_mode = 0x008, flag_share_mode = 0x008,
// determines if the IP filter should apply to this torrent or not. By // determines if the IP filter should apply to this torrent or not. By
// default all torrents are subject to filtering by the IP filter (i.e. this flag is set by // default all torrents are subject to filtering by the IP filter
// default). This is useful if certain torrents needs to be excempt for some reason, being // (i.e. this flag is set by default). This is useful if certain
// an auto-update torrent for instance. // torrents needs to be excempt for some reason, being an auto-update
// torrent for instance.
flag_apply_ip_filter = 0x010, flag_apply_ip_filter = 0x010,
// specifies whether or not the torrent is to be started in a paused // specifies whether or not the torrent is to be started in a paused
// state. I.e. it won't connect to the tracker or any of the peers until it's // state. I.e. it won't connect to the tracker or any of the peers
// resumed. This is typically a good way of avoiding race conditions when setting // until it's resumed. This is typically a good way of avoiding race
// configuration options on torrents before starting them. // conditions when setting configuration options on torrents before
// starting them.
flag_paused = 0x020, flag_paused = 0x020,
// If the torrent is auto-managed (``flag_auto_managed``), the torrent may be resumed // If the torrent is auto-managed (``flag_auto_managed``), the torrent
// at any point, regardless of how it paused. If it's important to manually control // may be resumed at any point, regardless of how it paused. If it's
// when the torrent is paused and resumed, don't make it auto managed. // important to manually control when the torrent is paused and
// resumed, don't make it auto managed.
// //
// If ``flag_auto_managed`` is set, the torrent will be queued, started and seeded // If ``flag_auto_managed`` is set, the torrent will be queued,
// automatically by libtorrent. When this is set, the torrent should also be started // started and seeded automatically by libtorrent. When this is set,
// as paused. The default queue order is the order the torrents were added. They // the torrent should also be started as paused. The default queue
// are all downloaded in that order. For more details, see queuing_. // order is the order the torrents were added. They are all downloaded
// in that order. For more details, see queuing_.
// //
// If you pass in resume data, the auto_managed state of the torrent when the resume data // If you pass in resume data, the auto_managed state of the torrent
// was saved will override the auto_managed state you pass in here. You can override this // when the resume data was saved will override the auto_managed state
// by setting ``override_resume_data``. // you pass in here. You can override this by setting
// ``override_resume_data``.
flag_auto_managed = 0x040, flag_auto_managed = 0x040,
flag_duplicate_is_error = 0x080, flag_duplicate_is_error = 0x080,
// defaults to off and specifies whether tracker URLs loaded from // defaults to off and specifies whether tracker URLs loaded from
// resume data should be added to the trackers in the torrent or replace the trackers. // resume data should be added to the trackers in the torrent or
// replace the trackers.
flag_merge_resume_trackers = 0x100, flag_merge_resume_trackers = 0x100,
// on by default and means that this torrent will be part of state // on by default and means that this torrent will be part of state
// updates when calling post_torrent_updates(). // updates when calling post_torrent_updates().
flag_update_subscribe = 0x200, flag_update_subscribe = 0x200,
// sets the torrent into super seeding mode. If the torrent // sets the torrent into super seeding mode. If the torrent is not a
// is not a seed, this flag has no effect. It has the same effect as calling // seed, this flag has no effect. It has the same effect as calling
// ``torrent_handle::super_seeding(true)`` on the torrent handle immediately // ``torrent_handle::super_seeding(true)`` on the torrent handle
// after adding it. // immediately after adding it.
flag_super_seeding = 0x400, flag_super_seeding = 0x400,
// sets the sequential download state for the torrent. // sets the sequential download state for the torrent. It has the same
// It has the same effect as calling ``torrent_handle::sequential_download(true)`` // effect as calling ``torrent_handle::sequential_download(true)`` on
// on the torrent handle immediately after adding it. // the torrent handle immediately after adding it.
flag_sequential_download = 0x800, flag_sequential_download = 0x800,
// internal // internal
@ -236,87 +255,97 @@ namespace libtorrent
// is used for forward binary compatibility. // is used for forward binary compatibility.
int version; int version;
// torrent_info object with the torrent to add. Unless the url or info_hash // torrent_info object with the torrent to add. Unless the url or
// is set, this is required to be initiazlied. // info_hash is set, this is required to be initiazlied.
boost::intrusive_ptr<torrent_info> ti; boost::intrusive_ptr<torrent_info> ti;
#ifndef TORRENT_NO_DEPRECATE #ifndef TORRENT_NO_DEPRECATE
char const* tracker_url; char const* tracker_url;
#endif #endif
// If the torrent doesn't have a tracker, but relies on the DHT to find peers, the // If the torrent doesn't have a tracker, but relies on the DHT to find
// ``trackers`` can specify tracker URLs for the torrent. // peers, the ``trackers`` can specify tracker URLs for the torrent.
std::vector<std::string> trackers; std::vector<std::string> trackers;
// url seeds to be added to the torrent (`BEP 17`_). // url seeds to be added to the torrent (`BEP 17`_).
std::vector<std::string> url_seeds; std::vector<std::string> url_seeds;
// a list of hostname and port pairs, representing DHT nodes to be // a list of hostname and port pairs, representing DHT nodes to be added
// added to the session (if DHT is enabled). The hostname may be an IP address. // to the session (if DHT is enabled). The hostname may be an IP address.
std::vector<std::pair<std::string, int> > dht_nodes; std::vector<std::pair<std::string, int> > dht_nodes;
std::string name; std::string name;
std::string save_path; std::string save_path;
// The optional parameter, ``resume_data`` can be given if up to date fast-resume data // The optional parameter, ``resume_data`` can be given if up to date
// is available. The fast-resume data can be acquired from a running torrent by calling // fast-resume data is available. The fast-resume data can be acquired
// save_resume_data() on torrent_handle. See fast-resume_. The ``vector`` that is // from a running torrent by calling save_resume_data() on
// passed in will be swapped into the running torrent instance with ``std::vector::swap()``. // torrent_handle. See fast-resume_. The ``vector`` that is passed in
// will be swapped into the running torrent instance with
// ``std::vector::swap()``.
std::vector<char> resume_data; std::vector<char> resume_data;
// One of the values from storage_mode_t. For more information, see storage-allocation_. // One of the values from storage_mode_t. For more information, see
// storage-allocation_.
storage_mode_t storage_mode; storage_mode_t storage_mode;
// can be used to customize how the data is stored. The default // can be used to customize how the data is stored. The default storage
// storage will simply write the data to the files it belongs to, but it could be // will simply write the data to the files it belongs to, but it could be
// overridden to save everything to a single file at a specific location or encrypt the // overridden to save everything to a single file at a specific location
// content on disk for instance. For more information about the storage_interface // or encrypt the content on disk for instance. For more information
// that needs to be implemented for a custom storage, see storage_interface. // about the storage_interface that needs to be implemented for a custom
// storage, see storage_interface.
storage_constructor_type storage; storage_constructor_type storage;
// The ``userdata`` parameter is optional and will be passed on to the extension // The ``userdata`` parameter is optional and will be passed on to the
// constructor functions, if any (see `add_extension()`_). // extension constructor functions, if any (see `add_extension()`_).
void* userdata; void* userdata;
// can be set to control the initial file priorities when adding // can be set to control the initial file priorities when adding a
// a torrent. The semantics are the same as for ``torrent_handle::prioritize_files()``. // torrent. The semantics are the same as for
// ``torrent_handle::prioritize_files()``.
std::vector<boost::uint8_t> file_priorities; std::vector<boost::uint8_t> file_priorities;
// torrent extension construction functions can be added to this // torrent extension construction functions can be added to this vector
// vector to have them be added immediately when the torrent is // to have them be added immediately when the torrent is constructed.
// constructed. This may be desired over the torrent_handle::add_extension() // This may be desired over the torrent_handle::add_extension() in order
// in order to avoid race conditions. For instance it may be important // to avoid race conditions. For instance it may be important to have the
// to have the plugin catch events that happen very early on after // plugin catch events that happen very early on after the torrent is
// the torrent is created. // created.
std::vector<boost::function<boost::shared_ptr<torrent_plugin>(torrent*, void*)> > std::vector<boost::function<boost::shared_ptr<torrent_plugin>(torrent*, void*)> >
extensions; extensions;
// the default tracker id to be used when announcing to trackers. By default // the default tracker id to be used when announcing to trackers. By
// this is empty, and no tracker ID is used, since this is an optional argument. If // default this is empty, and no tracker ID is used, since this is an
// a tracker returns a tracker ID, that ID is used instead of this. // optional argument. If a tracker returns a tracker ID, that ID is used
// instead of this.
std::string trackerid; std::string trackerid;
// If you specify a ``url``, the torrent will be set in ``downloading_metadata`` state // If you specify a ``url``, the torrent will be set in
// until the .torrent file has been downloaded. If there's any error while downloading, // ``downloading_metadata`` state until the .torrent file has been
// the torrent will be stopped and the torrent error state (``torrent_status::error``) // downloaded. If there's any error while downloading, the torrent will
// will indicate what went wrong. The ``url`` may refer to a magnet link or a regular // be stopped and the torrent error state (``torrent_status::error``)
// http URL. // will indicate what went wrong. The ``url`` may refer to a magnet link
// or a regular http URL.
// //
// If it refers to an HTTP URL, the info-hash for the added torrent will not be the // If it refers to an HTTP URL, the info-hash for the added torrent will
// true info-hash of the .torrent. Instead a placeholder, unique, info-hash is used // not be the true info-hash of the .torrent. Instead a placeholder,
// which is later updated once the .torrent file has been downloaded. // unique, info-hash is used which is later updated once the .torrent
// file has been downloaded.
// //
// Once the info-hash change happens, a torrent_update_alert is posted. // Once the info-hash change happens, a torrent_update_alert is posted.
std::string url; std::string url;
// if ``uuid`` is specified, it is used to find duplicates. If another torrent is already // if ``uuid`` is specified, it is used to find duplicates. If another
// running with the same UUID as the one being added, it will be considered a duplicate. This // torrent is already running with the same UUID as the one being added,
// is mainly useful for RSS feed items which has UUIDs specified. // it will be considered a duplicate. This is mainly useful for RSS feed
// items which has UUIDs specified.
std::string uuid; std::string uuid;
// should point to the URL of the RSS feed this torrent comes from, // should point to the URL of the RSS feed this torrent comes from,
// if it comes from an RSS feed. // if it comes from an RSS feed.
std::string source_feed_url; std::string source_feed_url;
// flags controlling aspects of this torrent and how it's added. See flags_t for details. // flags controlling aspects of this torrent and how it's added. See
// flags_t for details.
boost::uint64_t flags; boost::uint64_t flags;
// set this to the info hash of the torrent to add in case the info-hash // set this to the info hash of the torrent to add in case the info-hash
@ -324,15 +353,15 @@ namespace libtorrent
// .torrent file nor a magnet link. // .torrent file nor a magnet link.
sha1_hash info_hash; sha1_hash info_hash;
// ``max_uploads``, ``max_connections``, ``upload_limit``, ``download_limit`` correspond // ``max_uploads``, ``max_connections``, ``upload_limit``,
// to the ``set_max_uploads()``, ``set_max_connections()``, ``set_upload_limit()`` and // ``download_limit`` correspond to the ``set_max_uploads()``,
// ``set_download_limit()`` functions on torrent_handle. These values let you initialize // ``set_max_connections()``, ``set_upload_limit()`` and
// these settings when the torrent is added, instead of calling these functions immediately // ``set_download_limit()`` functions on torrent_handle. These values let
// following adding it. // you initialize these settings when the torrent is added, instead of
// calling these functions immediately following adding it.
// //
// -1 means unlimited on these settings // -1 means unlimited on these settings just like their counterpart
// just like their counterpart functions // functions on torrent_handle
// on torrent_handle
int max_uploads; int max_uploads;
int max_connections; int max_connections;
int upload_limit; int upload_limit;

26
include/libtorrent/alert.hpp
View File

@ -49,24 +49,22 @@ POSSIBILITY OF SUCH DAMAGE.
// OVERVIEW // OVERVIEW
// //
// The pop_alert() function on session is the interface for retrieving // The pop_alerts() function on session is the main interface for retrieving
// alerts, warnings, messages and errors from libtorrent. If no alerts have // alerts (warnings, messages and errors from libtorrent). If no alerts have
// been posted by libtorrent pop_alert() will return a default initialized // been posted by libtorrent pop_alert() will return an empty list.
// ``std::auto_ptr`` object. If there is an alert in libtorrent's queue, the alert
// from the front of the queue is popped and returned.
// You can then use the alert object and query
// //
// By default, only errors are reported. set_alert_mask() can be // By default, only errors are reported. set_alert_mask() can be used to
// used to specify which kinds of events should be reported. The alert mask // specify which kinds of events should be reported. The alert mask is
// is comprised by bits from the category_t enum. // comprised by bits from the category_t enum.
// //
// Every alert belongs to one or more category. There is a small cost involved in posting alerts. Only // Every alert belongs to one or more category. There is a small cost involved
// alerts that belong to an enabled category are posted. Setting the alert bitmask to 0 will disable // in posting alerts. Only alerts that belong to an enabled category are
// all alerts (except those that are non-discardable). // posted. Setting the alert bitmask to 0 will disable all alerts (except those
// that are non-discardable).
// //
// There are other alert base classes that some alerts derive from, all the // There are other alert base classes that some alerts derive from, all the
// alerts that are generated for a specific torrent are derived from torrent_alert, // alerts that are generated for a specific torrent are derived from
// and tracker events derive from tracker_alert. // torrent_alert, and tracker events derive from tracker_alert.
// //
#ifdef _MSC_VER #ifdef _MSC_VER

2
include/libtorrent/bitfield.hpp
View File

@ -48,7 +48,7 @@ namespace libtorrent
{ {
// constructs a new bitfield. The default constructor creates an empty // constructs a new bitfield. The default constructor creates an empty
// bitfield. ``bits`` is the size of the bitfield (specified in bits). // bitfield. ``bits`` is the size of the bitfield (specified in bits).
// `` val`` is the value to initialize the bits to. If not specified // ``val`` is the value to initialize the bits to. If not specified
// all bits are initialized to 0. // all bits are initialized to 0.
// //
// The constructor taking a pointer ``b`` and ``bits`` copies a bitfield // The constructor taking a pointer ``b`` and ``bits`` copies a bitfield

15
include/libtorrent/identify_client.hpp
View File

@ -50,17 +50,18 @@ POSSIBILITY OF SUCH DAMAGE.
namespace libtorrent namespace libtorrent
{ {
// This function is declared in the header ``<libtorrent/identify_client.hpp>``. It can can be used // This function can can be used to extract a string describing a client
// to extract a string describing a client version from its peer-id. It will recognize most clients // version from its peer-id. It will recognize most clients that have this
// that have this kind of identification in the peer-id. // kind of identification in the peer-id.
TORRENT_EXPORT std::string identify_client(const peer_id& p); TORRENT_EXPORT std::string identify_client(const peer_id& p);
// Returns an optional fingerprint if any can be identified from the peer id. This can be used // Returns an optional fingerprint if any can be identified from the peer
// to automate the identification of clients. It will not be able to identify peers with non- // id. This can be used to automate the identification of clients. It will
// standard encodings. Only Azureus style, Shadow's style and Mainline style. This function is // not be able to identify peers with non- standard encodings. Only Azureus
// declared in the header ``<libtorrent/identify_client.hpp>``. // style, Shadow's style and Mainline style.
TORRENT_EXPORT boost::optional<fingerprint> client_fingerprint(peer_id const& p); TORRENT_EXPORT boost::optional<fingerprint> client_fingerprint(peer_id const& p);
} }
#endif // TORRENT_IDENTIFY_CLIENT_HPP_INCLUDED #endif // TORRENT_IDENTIFY_CLIENT_HPP_INCLUDED

150
include/libtorrent/storage.hpp
View File

@ -66,9 +66,21 @@ POSSIBILITY OF SUCH DAMAGE.
// OVERVIEW // OVERVIEW
// //
// This is an example storage implementation that stores all pieces in a ``std::map``, // libtorrent provides a customization point for storage of data. By default,
// i.e. in RAM. It's not necessarily very useful in practice, but illustrates the // (``default_storage``) downloaded files are saved to disk according with the
// basics of implementing a custom storage. // general conventions of bittorrent clients, mimicing the original file layout
// when the torrent was created. The libtorrent user may define a custom
// storage to store piece data in a different way.
//
// A custom storage implementation must derive from and implement the
// storage_interface. You must also provide a function that constructs the
// custom storage object and provide this function to the add_torrent() call
// via add_torrent_params. Either passed in to the constructor or by setting
// the add_torrent_params::storage field.
//
// This is an example storage implementation that stores all pieces in a
// ``std::map``, i.e. in RAM. It's not necessarily very useful in practice, but
// illustrates the basics of implementing a custom storage.
// //
//:: //::
// //
@ -166,16 +178,16 @@ namespace libtorrent
// The storage interface is a pure virtual class that can be implemented to // The storage interface is a pure virtual class that can be implemented to
// customize how and where data for a torrent is stored. The default storage // customize how and where data for a torrent is stored. The default storage
// implementation uses regular files in the filesystem, mapping the files in the // implementation uses regular files in the filesystem, mapping the files in
// torrent in the way one would assume a torrent is saved to disk. Implementing // the torrent in the way one would assume a torrent is saved to disk.
// your own storage interface makes it possible to store all data in RAM, or in // Implementing your own storage interface makes it possible to store all
// some optimized order on disk (the order the pieces are received for instance), // data in RAM, or in some optimized order on disk (the order the pieces are
// or saving multifile torrents in a single file in order to be able to take // received for instance), or saving multifile torrents in a single file in
// advantage of optimized disk-I/O. // order to be able to take advantage of optimized disk-I/O.
// //
// It is also possible to write a thin class that uses the default storage but // It is also possible to write a thin class that uses the default storage
// modifies some particular behavior, for instance encrypting the data before // but modifies some particular behavior, for instance encrypting the data
// it's written to disk, and decrypting it when it's read again. // before it's written to disk, and decrypting it when it's read again.
// //
// The storage interface is based on slots, each slot is 'piece_size' number // The storage interface is based on slots, each slot is 'piece_size' number
// of bytes. All access is done by writing and reading whole or partial // of bytes. All access is done by writing and reading whole or partial
@ -183,9 +195,10 @@ namespace libtorrent
// does not necessarily correspond to the piece with the same index (in // does not necessarily correspond to the piece with the same index (in
// compact allocation mode it won't). // compact allocation mode it won't).
// //
// libtorrent comes with two built-in storage implementations; ``default_storage`` // libtorrent comes with two built-in storage implementations;
// and ``disabled_storage``. Their constructor functions are called default_storage_constructor() // ``default_storage`` and ``disabled_storage``. Their constructor functions
// and ``disabled_storage_constructor`` respectively. The disabled storage does // are called default_storage_constructor() and
// ``disabled_storage_constructor`` respectively. The disabled storage does
// just what it sounds like. It throws away data that's written, and it // just what it sounds like. It throws away data that's written, and it
// reads garbage. It's useful mostly for benchmarking and profiling purpose. // reads garbage. It's useful mostly for benchmarking and profiling purpose.
// //
@ -195,50 +208,54 @@ namespace libtorrent
storage_interface(): m_disk_pool(0), m_settings(0) {} storage_interface(): m_disk_pool(0), m_settings(0) {}
// This function is called when the storage is to be initialized. The default storage // This function is called when the storage is to be initialized. The
// will create directories and empty files at this point. If ``allocate_files`` is true, // default storage will create directories and empty files at this point.
// it will also ``ftruncate`` all files to their target size. // If ``allocate_files`` is true, it will also ``ftruncate`` all files to
// their target size.
// //
// Returning ``true`` indicates an error occurred. // Returning ``true`` indicates an error occurred.
virtual bool initialize(bool allocate_files) = 0; virtual bool initialize(bool allocate_files) = 0;
// This function is called when first checking (or re-checking) the storage for a torrent. // This function is called when first checking (or re-checking) the
// It should return true if any of the files that is used in this storage exists on disk. // storage for a torrent. It should return true if any of the files that
// If so, the storage will be checked for existing pieces before starting the download. // is used in this storage exists on disk. If so, the storage will be
// checked for existing pieces before starting the download.
virtual bool has_any_file() = 0; virtual bool has_any_file() = 0;
// change the priorities of files. // change the priorities of files.
virtual void set_file_priority(std::vector<boost::uint8_t> const& prio) = 0; virtual void set_file_priority(std::vector<boost::uint8_t> const& prio) = 0;
// These functions should read or write the data in or to the given ``slot`` at the given ``offset``. // These functions should read or write the data in or to the given
// It should read or write ``num_bufs`` buffers sequentially, where the size of each buffer // ``slot`` at the given ``offset``. It should read or write ``num_bufs``
// is specified in the buffer array ``bufs``. The file::iovec_t type has the following members:: // buffers sequentially, where the size of each buffer is specified in
// the buffer array ``bufs``. The file::iovec_t type has the following
// members::
// //
// struct iovec_t // struct iovec_t { void* iov_base; size_t iov_len; };
// {
// void* iov_base;
// size_t iov_len;
// };
// //
// The return value is the number of bytes actually read or written, or -1 on failure. If // The return value is the number of bytes actually read or written, or
// it returns -1, the error code is expected to be set to // -1 on failure. If it returns -1, the error code is expected to be set
// to
// //
// Every buffer in ``bufs`` can be assumed to be page aligned and be of a page aligned size, // Every buffer in ``bufs`` can be assumed to be page aligned and be of a
// except for the last buffer of the torrent. The allocated buffer can be assumed to fit a // page aligned size, except for the last buffer of the torrent. The
// fully page aligned number of bytes though. This is useful when reading and writing the // allocated buffer can be assumed to fit a fully page aligned number of
// last piece of a file in unbuffered mode. // bytes though. This is useful when reading and writing the last piece
// of a file in unbuffered mode.
// //
// The ``offset`` is aligned to 16 kiB boundries *most of the time*, but there are rare // The ``offset`` is aligned to 16 kiB boundries *most of the time*, but
// exceptions when it's not. Specifically if the read cache is disabled/or full and a // there are rare exceptions when it's not. Specifically if the read
// client requests unaligned data, or the file itself is not aligned in the torrent. // cache is disabled/or full and a client requests unaligned data, or the
// Most clients request aligned data. // file itself is not aligned in the torrent. Most clients request
// aligned data.
virtual int readv(file::iovec_t const* bufs, int slot, int offset, int num_bufs, int flags = file::random_access); virtual int readv(file::iovec_t const* bufs, int slot, int offset, int num_bufs, int flags = file::random_access);
virtual int writev(file::iovec_t const* bufs, int slot, int offset, int num_bufs, int flags = file::random_access); virtual int writev(file::iovec_t const* bufs, int slot, int offset, int num_bufs, int flags = file::random_access);
// This function is called when a read job is queued. It gives the storage wrapper an // This function is called when a read job is queued. It gives the
// opportunity to hint the operating system about this coming read. For instance, the // storage wrapper an opportunity to hint the operating system about this
// storage may call ``posix_fadvise(POSIX_FADV_WILLNEED)`` or ``fcntl(F_RDADVISE)``. // coming read. For instance, the storage may call
// ``posix_fadvise(POSIX_FADV_WILLNEED)`` or ``fcntl(F_RDADVISE)``.
virtual void hint_read(int, int, int) {} virtual void hint_read(int, int, int) {}
// negative return value indicates an error // negative return value indicates an error
@ -251,17 +268,18 @@ namespace libtorrent
// byte at offset ``offset`` in slot ``slot``. // byte at offset ``offset`` in slot ``slot``.
virtual size_type physical_offset(int slot, int offset) = 0; virtual size_type physical_offset(int slot, int offset) = 0;
// This function is optional. It is supposed to return the first piece, starting at // This function is optional. It is supposed to return the first piece,
// ``start`` that is fully contained within a data-region on disk (i.e. non-sparse // starting at ``start`` that is fully contained within a data-region on
// region). The purpose of this is to skip parts of files that can be known to contain // disk (i.e. non-sparse region). The purpose of this is to skip parts of
// zeros when checking files. // files that can be known to contain zeros when checking files.
virtual int sparse_end(int start) const { return start; } virtual int sparse_end(int start) const { return start; }
// This function should move all the files belonging to the storage to the new save_path. // This function should move all the files belonging to the storage to
// The default storage moves the single file or the directory of the torrent. // the new save_path. The default storage moves the single file or the
// directory of the torrent.
// //
// Before moving the files, any open file handles may have to be closed, like // Before moving the files, any open file handles may have to be closed,
// ``release_files()``. // like ``release_files()``.
// //
// returns one of: // returns one of:
// | no_error = 0 // | no_error = 0
@ -295,9 +313,10 @@ namespace libtorrent
// Returning ``true`` indicates an error occurred. // Returning ``true`` indicates an error occurred.
virtual bool move_slot(int src_slot, int dst_slot) = 0; virtual bool move_slot(int src_slot, int dst_slot) = 0;
// This function should swap the data in ``slot1`` and ``slot2``. The default // This function should swap the data in ``slot1`` and ``slot2``. The
// storage uses a scratch buffer to read the data into, then moving the other // default storage uses a scratch buffer to read the data into, then
// slot and finally writing back the temporary slot's data // moving the other slot and finally writing back the temporary slot's
// data
// //
// This is only used in compact mode. // This is only used in compact mode.
// //
@ -305,8 +324,8 @@ namespace libtorrent
virtual bool swap_slots(int slot1, int slot2) = 0; virtual bool swap_slots(int slot1, int slot2) = 0;
// This function should do a 3-way swap, or shift of the slots. ``slot1`` // This function should do a 3-way swap, or shift of the slots. ``slot1``
// should move to ``slot2``, which should be moved to ``slot3`` which in turn // should move to ``slot2``, which should be moved to ``slot3`` which in
// should be moved to ``slot1``. // turn should be moved to ``slot1``.
// //
// This is only used in compact mode. // This is only used in compact mode.
// //
@ -324,12 +343,13 @@ namespace libtorrent
// ``true`` should be returned. // ``true`` should be returned.
virtual bool rename_file(int index, std::string const& new_filename) = 0; virtual bool rename_file(int index, std::string const& new_filename) = 0;
// This function should delete all files and directories belonging to this storage. // This function should delete all files and directories belonging to
// this storage.
// //
// Returning ``true`` indicates an error occurred. // Returning ``true`` indicates an error occurred.
// //
// The ``disk_buffer_pool`` is used to allocate and free disk buffers. It has the // The ``disk_buffer_pool`` is used to allocate and free disk buffers. It
// following members:: // has the following members::
// //
// struct disk_buffer_pool : boost::noncopyable // struct disk_buffer_pool : boost::noncopyable
// { // {
@ -347,13 +367,13 @@ namespace libtorrent
#ifndef TORRENT_NO_DEPRECATE #ifndef TORRENT_NO_DEPRECATE
// This function is called each time a file is completely downloaded. The // This function is called each time a file is completely downloaded. The
// storage implementation can perform last operations on a file. The file will // storage implementation can perform last operations on a file. The file
// not be opened for writing after this. // will not be opened for writing after this.
// //
// ``index`` is the index of the file that completed. // ``index`` is the index of the file that completed.
// //
// On windows the default storage implementation clears the sparse file flag // On windows the default storage implementation clears the sparse file
// on the specified file. // flag on the specified file.
virtual void finalize_file(int) {} virtual void finalize_file(int) {}
#endif #endif
@ -389,9 +409,9 @@ namespace libtorrent
session_settings* m_settings; session_settings* m_settings;
}; };
// The default implementation of storage_interface. Behaves as a normal bittorrent client. // The default implementation of storage_interface. Behaves as a normal
// It is possible to derive from this class in order to override some of its behavior, when // bittorrent client. It is possible to derive from this class in order to
// implementing a custom storage. // override some of its behavior, when implementing a custom storage.
class TORRENT_EXPORT default_storage : public storage_interface, boost::noncopyable class TORRENT_EXPORT default_storage : public storage_interface, boost::noncopyable
{ {
public: public: