premiere
/
premiere-libtorrent
2
2
Fork 1
Code Issues Pull Requests Releases Wiki 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
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)
# we have to escape asterisks, since this is rendered into
# a parsed literal in rst
name[1] = name[1].replace('*', '\\*')
# comments in signatures are italic
name[1] = name[1].replace('/\\*', '*/\\*')
name[1] = name[1].replace('\\*/', '\\*/*')
return '('.join(name)
def html_sanitize(s):
@ -756,25 +763,28 @@ def linkify_symbols(string):
in_literal = True
words = l.split(' ')
if len(words) == 1:
ret.append(l)
continue
for i in range(len(words)):
# it's important to preserve leading
# tabs, since that's relevant for
# rst markup
leading_tabs = 0
while leading_tabs < len(words[i]) and words[i][leading_tabs] == '\t':
leading_tabs += 1
leading = ''
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
w = words[i].strip()
w = w.strip()
trailing = ''
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
w = w[:-1]
@ -789,7 +799,7 @@ def linkify_symbols(string):
if w in symbols:
link_name = link_name.replace('-', ' ')
# 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))
return '\n'.join(ret)

28
docs/manual-ref.html
View File

@ -55,17 +55,17 @@
<div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of contents</p>
<ul class="simple">
<li><a class="reference internal" href="#overview" id="id52">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="#network-primitives" id="id54">network primitives</a></li>
<li><a class="reference internal" href="#exceptions" id="id55">exceptions</a></li>
<li><a class="reference internal" href="#magnet-links" id="id56">magnet links</a></li>
<li><a class="reference internal" href="#queuing" id="id57">queuing</a></li>
<li><a class="reference internal" href="#fast-resume" id="id58">fast resume</a></li>
<li><a class="reference internal" href="#storage-allocation" id="id59">storage allocation</a></li>
<li><a class="reference internal" href="#extensions" id="id60">extensions</a></li>
<li><a class="reference internal" href="#piece-picker" id="id61">piece picker</a></li>
<li><a class="reference internal" href="#ssl-torrents" id="id62">SSL torrents</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="id56">things to keep in mind</a></li>
<li><a class="reference internal" href="#network-primitives" id="id57">network primitives</a></li>
<li><a class="reference internal" href="#exceptions" id="id58">exceptions</a></li>
<li><a class="reference internal" href="#magnet-links" id="id59">magnet links</a></li>
<li><a class="reference internal" href="#queuing" id="id60">queuing</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="id62">storage allocation</a></li>
<li><a class="reference internal" href="#extensions" id="id63">extensions</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="id65">SSL torrents</a></li>
</ul>
</div>
<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 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>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>
</blockquote>
</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
pieces, pick random pieces rather than rare pieces. The threshold for when to
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 class="section" id="reverse-order">
<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
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
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
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

8
docs/reference-Alerts.html
View File

@ -793,7 +793,7 @@ code indicating an error.</p>
<pre class="literal-block">
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; m);
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
{
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;
| alert::dht_notification;
@ -2390,7 +2390,7 @@ specifically the overload for looking up mutable items in the DHT.</p>
<pre class="literal-block">
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::uint64_t sequence
, std::string const&amp; s
@ -2471,7 +2471,7 @@ salt and sequence number the item was stored under.</dd>
<pre class="literal-block">
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;
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">
<p class="topic-title first">Table of contents</p>
<ul class="simple">
<li><a class="reference internal" href="#invalid-encoding" id="id53">invalid_encoding</a></li>
<li><a class="reference internal" href="#type-error" id="id54">type_error</a></li>
<li><a class="reference internal" href="#entry" id="id55">entry</a></li>
<li><a class="reference internal" href="#pascal-string" id="id56">pascal_string</a></li>
<li><a class="reference internal" href="#lazy-entry" id="id57">lazy_entry</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="id55">type_error</a></li>
<li><a class="reference internal" href="#entry" id="id56">entry</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="id58">lazy_entry</a></li>
</ul>
</div>
<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">
struct type_error: std::runtime_error
{
**type_error** (const char* error);
<strong>type_error</strong> (const char* error);
};
</pre>
<a name="entry"></a></div>
@ -129,11 +129,11 @@ or a string.</p>
class entry
{
data_type <strong>type</strong> () const;
**entry** (list_type const&amp;);
**entry** (integer_type const&amp;);
**entry** (dictionary_type const&amp;);
**entry** (string_type const&amp;);
**entry** (data_type t);
<strong>entry</strong> (list_type const&amp;);
<strong>entry</strong> (integer_type const&amp;);
<strong>entry</strong> (dictionary_type const&amp;);
<strong>entry</strong> (string_type const&amp;);
<strong>entry</strong> (data_type t);
void <strong>operator=</strong> (string_type const&amp;);
void <strong>operator=</strong> (entry 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">
<h2>entry()</h2>
<pre class="literal-block">
**entry** (list_type const&amp;);
**entry** (integer_type const&amp;);
**entry** (dictionary_type const&amp;);
**entry** (string_type const&amp;);
<strong>entry</strong> (list_type const&amp;);
<strong>entry</strong> (integer_type const&amp;);
<strong>entry</strong> (dictionary_type const&amp;);
<strong>entry</strong> (string_type const&amp;);
</pre>
<p>constructors directly from a specific type.
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">
<h2>entry()</h2>
<pre class="literal-block">
**entry** (data_type t);
<strong>entry</strong> (data_type t);
</pre>
<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>
@ -209,7 +209,7 @@ void <strong>operator=</strong> (dictionary_type const&amp;);
void <strong>operator=</strong> (list_type const&amp;);
</pre>
<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="dict()"></a>
<a name="integer()"></a>
@ -273,7 +273,7 @@ void <strong>swap</strong> (entry&amp; e);
</pre>
<p>swaps the content of <em>this</em> with <tt class="docutils literal">e</tt>.</p>
<a name="operator[]()"></a></div>
<div class="section" id="id23">
<div class="section" id="id24">
<h2>operator[]()</h2>
<pre class="literal-block">
entry&amp; <strong>operator[]</strong> (std::string const&amp; key);
@ -372,22 +372,22 @@ would require copying the string.</p>
<pre class="literal-block">
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;
int len;
char const* ptr;
};
</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>
<pre class="literal-block">
**pascal_string** (char const* p, int l);
<strong>pascal_string</strong> (char const* p, int l);
</pre>
<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>
<a name="operator<()"></a></div>
<div class="section" id="id31">
<div class="section" id="id32">
<h2>operator&lt;()</h2>
<pre class="literal-block">
bool <strong>operator&lt;</strong> (pascal_string const&amp; rhs) const;
@ -460,7 +460,7 @@ struct lazy_entry
};
};
</pre>
<a name="type()"></a><div class="section" id="id35">
<a name="type()"></a><div class="section" id="id36">
<h2>type()</h2>
<pre class="literal-block">
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
this <a class="reference external" href="reference-Bencoding.html#entry">entry</a> has its bencoded data</p>
<a name="swap()"></a></div>
<div class="section" id="id43">
<div class="section" id="id44">
<h2>swap()</h2>
<pre class="literal-block">
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
it will throw <a class="reference external" href="reference-Error_Codes.html#libtorrent_exception">libtorrent_exception</a>.</p>
<a name="operator<<()"></a></div>
<div class="section" id="id50">
<div class="section" id="id51">
<h2>operator&lt;&lt;()</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/entry.hpp">libtorrent/entry.hpp</a>&quot;</p>
<pre class="literal-block">

112
docs/reference-Core.html
View File

@ -55,15 +55,15 @@
<div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of contents</p>
<ul class="simple">
<li><a class="reference internal" href="#disk-buffer-holder" id="id167">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-request" id="id169">peer_request</a></li>
<li><a class="reference internal" href="#block-info" id="id170">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="#torrent-handle" id="id172">torrent_handle</a></li>
<li><a class="reference internal" href="#torrent-status" id="id173">torrent_status</a></li>
<li><a class="reference internal" href="#announce-entry" id="id174">announce_entry</a></li>
<li><a class="reference internal" href="#torrent-info" id="id175">torrent_info</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="id176">peer_info</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="id178">block_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="id180">torrent_handle</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="id182">announce_entry</a></li>
<li><a class="reference internal" href="#torrent-info" id="id183">torrent_info</a></li>
</ul>
</div>
<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">
struct disk_buffer_holder
{
**disk_buffer_holder** (disk_buffer_pool&amp; disk_pool, char* buf);
**~disk_buffer_holder** ();
<strong>disk_buffer_holder</strong> (disk_buffer_pool&amp; disk_pool, char* buf);
<strong>~disk_buffer_holder</strong> ();
char* <strong>release</strong> ();
char* <strong>get</strong> () const;
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">
<h2>disk_buffer_holder()</h2>
<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>
<p>construct a buffer holder that will free the held buffer
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">
<h2>~disk_buffer_holder()</h2>
<pre class="literal-block">
**~disk_buffer_holder** ();
<strong>~disk_buffer_holder</strong> ();
</pre>
<p>frees any unreleased disk buffer held by this object</p>
<a name="release()"></a></div>
@ -1011,7 +1011,7 @@ handle will remain valid between two calls.</p>
<pre class="literal-block">
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>read_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">
<h2>torrent_handle()</h2>
<pre class="literal-block">
**torrent_handle** ();
<strong>torrent_handle</strong> ();
</pre>
<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>
@ -1158,7 +1158,7 @@ instruct libtorrent to overwrite any data that may already have been
downloaded with this data.</p>
<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
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>
<div class="section" id="read-piece">
<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
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
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
set. If it is, it doesn't do anything. If it's not in the current set
of trackers, it will insert it in the tier specified in the
announce_entry.</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
a torrent is started with resume data, the trackers from the resume
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
connected) peers. Torrents may be paused automatically if there is a
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
<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
@ -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
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
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
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>
<blockquote>
<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
no limit. This defaults to infinite. The primary setting controlling
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>
<a name="max_connections()"></a>
<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>
<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
torrent_handle::status().</p>
<a class="reference external" href="reference-Core.html#status()">torrent_handle::status()</a>.</p>
<pre class="literal-block">
struct torrent_status
{
@ -2326,7 +2326,7 @@ struct torrent_status
sha1_hash info_hash;
};
</pre>
<a name="operator==()"></a><div class="section" id="id102">
<a name="operator==()"></a><div class="section" id="id110">
<h2>operator==()</h2>
<pre class="literal-block">
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.
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>
<div class="section" id="id104">
<div class="section" id="id112">
<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>
<table border="1" class="docutils">
@ -2822,9 +2822,9 @@ relates to a specific torrent.</p>
<pre class="literal-block">
struct announce_entry
{
**announce_entry** (std::string const&amp; u);
**~announce_entry** ();
**announce_entry** ();
<strong>announce_entry</strong> (std::string const&amp; u);
<strong>~announce_entry</strong> ();
<strong>announce_entry</strong> ();
int <strong>next_announce_in</strong> () const;
int <strong>min_announce_in</strong> () const;
void <strong>reset</strong> ();
@ -2865,9 +2865,9 @@ struct announce_entry
<a name="~announce_entry()"></a><div class="section" id="announce-entry-announce-entry">
<h2>announce_entry() ~announce_entry()</h2>
<pre class="literal-block">
**announce_entry** (std::string const&amp; u);
**~announce_entry** ();
**announce_entry** ();
<strong>announce_entry</strong> (std::string const&amp; u);
<strong>~announce_entry</strong> ();
<strong>announce_entry</strong> ();
</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>
<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
code describing what error occurred.</p>
<a name="reset()"></a></div>
<div class="section" id="id125">
<div class="section" id="id133">
<h2>reset()</h2>
<pre class="literal-block">
void <strong>reset</strong> ();
@ -3047,15 +3047,15 @@ announces.</dd>
<pre class="literal-block">
class torrent_info : public intrusive_ptr_base&lt;torrent_info&gt;
{
**torrent_info** (std::string const&amp; filename, int flags = 0);
**torrent_info** (char const* buffer, int size, error_code&amp; ec, int flags = 0);
**torrent_info** (sha1_hash const&amp; info_hash, int flags = 0);
**torrent_info** (lazy_entry const&amp; torrent_file, int flags = 0);
**torrent_info** (char const* buffer, int size, int flags = 0);
**torrent_info** (lazy_entry const&amp; torrent_file, error_code&amp; ec, int flags = 0);
**torrent_info** (torrent_info const&amp; t, int flags = 0);
**torrent_info** (std::string const&amp; filename, error_code&amp; ec, int flags = 0);
**~torrent_info** ();
<strong>torrent_info</strong> (std::string const&amp; filename, int flags = 0);
<strong>torrent_info</strong> (char const* buffer, int size, error_code&amp; ec, int flags = 0);
<strong>torrent_info</strong> (sha1_hash const&amp; info_hash, int flags = 0);
<strong>torrent_info</strong> (lazy_entry const&amp; torrent_file, int flags = 0);
<strong>torrent_info</strong> (char const* buffer, int size, int flags = 0);
<strong>torrent_info</strong> (lazy_entry const&amp; torrent_file, error_code&amp; ec, int flags = 0);
<strong>torrent_info</strong> (torrent_info const&amp; t, int flags = 0);
<strong>torrent_info</strong> (std::string const&amp; filename, error_code&amp; ec, int flags = 0);
<strong>~torrent_info</strong> ();
file_storage const&amp; <strong>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);
@ -3100,17 +3100,17 @@ class torrent_info : public intrusive_ptr_base&lt;torrent_info&gt;
bool <strong>is_merkle_torrent</strong> () const;
};
</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>
<pre class="literal-block">
**torrent_info** (std::string const&amp; filename, int flags = 0);
**torrent_info** (char const* buffer, int size, error_code&amp; ec, int flags = 0);
**torrent_info** (sha1_hash const&amp; info_hash, int flags = 0);
**torrent_info** (lazy_entry const&amp; torrent_file, int flags = 0);
**torrent_info** (char const* buffer, int size, int flags = 0);
**torrent_info** (lazy_entry const&amp; torrent_file, error_code&amp; ec, int flags = 0);
**torrent_info** (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, int flags = 0);
<strong>torrent_info</strong> (char const* buffer, int size, error_code&amp; ec, int flags = 0);
<strong>torrent_info</strong> (sha1_hash const&amp; info_hash, int flags = 0);
<strong>torrent_info</strong> (lazy_entry const&amp; torrent_file, int flags = 0);
<strong>torrent_info</strong> (char const* buffer, int size, int flags = 0);
<strong>torrent_info</strong> (lazy_entry const&amp; torrent_file, error_code&amp; ec, int flags = 0);
<strong>torrent_info</strong> (torrent_info const&amp; t, int flags = 0);
<strong>torrent_info</strong> (std::string const&amp; filename, error_code&amp; ec, int flags = 0);
</pre>
<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
@ -3132,10 +3132,10 @@ always throw if an error occurs. These overloads are not available when building
exception support.</p>
<p>The <tt class="docutils literal">flags</tt> argument is currently unused.</p>
<a name="~torrent_info()"></a></div>
<div class="section" id="id137">
<div class="section" id="id145">
<h2>~torrent_info()</h2>
<pre class="literal-block">
**~torrent_info** ();
<strong>~torrent_info</strong> ();
</pre>
<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>
@ -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
to create torrents.</p>
<a name="rename_file()"></a></div>
<div class="section" id="id143">
<div class="section" id="id151">
<h2>rename_file()</h2>
<pre class="literal-block">
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 smaller.</p>
<a name="info_hash()"></a></div>
<div class="section" id="id150">
<div class="section" id="id158">
<h2>info_hash()</h2>
<pre class="literal-block">
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
the the public certificate in x509 format.</p>
<a name="is_valid()"></a></div>
<div class="section" id="id153">
<div class="section" id="id161">
<h2>is_valid()</h2>
<pre class="literal-block">
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
key cannot be found, it returns NULL.</p>
<a name="swap()"></a></div>
<div class="section" id="id158">
<div class="section" id="id166">
<h2>swap()</h2>
<pre class="literal-block">
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">
struct create_torrent
{
**create_torrent** (torrent_info const&amp; ti);
**create_torrent** (file_storage&amp; fs, int piece_size = 0
<strong>create_torrent</strong> (torrent_info const&amp; ti);
<strong>create_torrent</strong> (file_storage&amp; fs, int piece_size = 0
, int pad_file_limit = -1, int flags = optimize, int alignment = 0x4000);
entry <strong>generate</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">
<h2>create_torrent()</h2>
<pre class="literal-block">
**create_torrent** (torrent_info const&amp; ti);
**create_torrent** (file_storage&amp; fs, int piece_size = 0
<strong>create_torrent</strong> (torrent_info const&amp; ti);
<strong>create_torrent</strong> (file_storage&amp; fs, int piece_size = 0
, int pad_file_limit = -1, int flags = optimize, int alignment = 0x4000);
</pre>
<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">
<p class="topic-title first">Table of contents</p>
<ul class="simple">
<li><a class="reference internal" href="#file-pool" id="id18">file_pool</a></li>
<li><a class="reference internal" href="#storage-interface" id="id19">storage_interface</a></li>
<li><a class="reference internal" href="#default-storage" id="id20">default_storage</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="id23">storage_interface</a></li>
<li><a class="reference internal" href="#default-storage" id="id24">default_storage</a></li>
</ul>
</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>,
i.e. in RAM. It's not necessarily very useful in practice, but illustrates the
basics of implementing a custom storage.</p>
<p>libtorrent provides a customization point for storage of data. By default,
(<tt class="docutils literal">default_storage</tt>) downloaded files are saved to disk according with the
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">
struct temp_storage : storage_interface
{
@ -139,8 +149,8 @@ may be windows where more file handles are open.</p>
<pre class="literal-block">
struct file_pool : boost::noncopyable
{
**~file_pool** ();
**file_pool** (int size = 40);
<strong>~file_pool</strong> ();
<strong>file_pool</strong> (int size = 40);
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);
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">
<h2>~file_pool() file_pool()</h2>
<pre class="literal-block">
**~file_pool** ();
**file_pool** (int size = 40);
<strong>~file_pool</strong> ();
<strong>file_pool</strong> (int size = 40);
</pre>
<p><tt class="docutils literal">size</tt> specifies the number of allowed files handles
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>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
implementation uses regular files in the filesystem, mapping the files in the
torrent in the way one would assume a torrent is saved to disk. Implementing
your own storage interface makes it possible to store all data in RAM, or in
some optimized order on disk (the order the pieces are received for instance),
or saving multifile torrents in a single file in 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
modifies some particular behavior, for instance encrypting the data before
it's written to disk, and decrypting it when it's read again.</p>
implementation uses regular files in the filesystem, mapping the files in
the torrent in the way one would assume a torrent is saved to disk.
Implementing your own storage interface makes it possible to store all
data in RAM, or in some optimized order on disk (the order the pieces are
received for instance), or saving multifile torrents in a single file in
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 modifies some particular behavior, for instance encrypting the data
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
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
does not necessarily correspond to the piece with the same index (in
compact allocation mode it won't).</p>
<p>libtorrent comes with two built-in storage implementations; <tt class="docutils literal">default_storage</tt>
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>
and <tt class="docutils literal">disabled_storage_constructor</tt> respectively. The disabled storage does
<p>libtorrent comes with two built-in storage implementations;
<tt class="docutils literal">default_storage</tt> 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> 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
reads garbage. It's useful mostly for benchmarking and profiling purpose.</p>
<pre class="literal-block">
@ -254,9 +265,10 @@ struct storage_interface
<pre class="literal-block">
virtual bool <strong>initialize</strong> (bool allocate_files) = 0;
</pre>
<p>This function is called when the storage is to be initialized. The default storage
will create directories and empty files at this point. 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>This function is called when the storage is to be initialized. The
default storage will create directories and empty files at this point.
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>
<a name="has_any_file()"></a></div>
<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">
virtual bool <strong>has_any_file</strong> () = 0;
</pre>
<p>This function is called when first checking (or re-checking) the storage for a torrent.
It should return true if any of the files that is used in this storage exists on disk.
If so, the storage will be checked for existing pieces before starting the download.</p>
<p>This function is called when first checking (or re-checking) the
storage for a torrent. It should return true if any of the files that
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>
<div class="section" id="set-file-priority">
<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>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>
<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>.
It should read or write <tt class="docutils literal">num_bufs</tt> 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>
<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>. It should read or write <tt class="docutils literal">num_bufs</tt>
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">
struct iovec_t
{
void* iov_base;
size_t iov_len;
};
struct iovec_t { void* iov_base; size_t iov_len; };
</pre>
<p>The return value is the number of bytes actually read or written, or -1 on failure. If
it returns -1, the error code is expected to be set to</p>
<p>Every buffer in <tt class="docutils literal">bufs</tt> can be assumed to be page aligned and be of a page aligned size,
except for the last buffer of the torrent. The allocated buffer can be assumed to fit a
fully page aligned number of bytes though. This is useful when reading and writing the
last piece of a file in unbuffered mode.</p>
<p>The <tt class="docutils literal">offset</tt> is aligned to 16 kiB boundries <em>most of the time</em>, but 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>
<p>The return value is the number of bytes actually read or written, or
-1 on failure. If it returns -1, the error code is expected to be set
to</p>
<p>Every buffer in <tt class="docutils literal">bufs</tt> can be assumed to be page aligned and be of a
page aligned size, except for the last buffer of the torrent. The
allocated buffer can be assumed to fit a fully page aligned number of
bytes though. This is useful when reading and writing the last piece
of a file in unbuffered mode.</p>
<p>The <tt class="docutils literal">offset</tt> is aligned to 16 kiB boundries <em>most of the time</em>, but
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>
<div class="section" id="hint-read">
<h2>hint_read()</h2>
<pre class="literal-block">
virtual void <strong>hint_read</strong> (int, int, int);
</pre>
<p>This function is called when a read job is queued. It gives the storage wrapper an
opportunity to hint the operating system about this 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>
<p>This function is called when a read job is queued. It gives the
storage wrapper an opportunity to hint the operating system about this
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>
<div class="section" id="read">
<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">
virtual int <strong>sparse_end</strong> (int start) const;
</pre>
<p>This function is optional. It is supposed to return the first piece, starting at
<tt class="docutils literal">start</tt> that is fully contained within a data-region on disk (i.e. non-sparse
region). The purpose of this is to skip parts of files that can be known to contain
zeros when checking files.</p>
<p>This function is optional. It is supposed to return the first piece,
starting at <tt class="docutils literal">start</tt> that is fully contained within a data-region on
disk (i.e. non-sparse region). The purpose of this is to skip parts of
files that can be known to contain zeros when checking files.</p>
<a name="move_storage()"></a></div>
<div class="section" id="move-storage">
<h2>move_storage()</h2>
<pre class="literal-block">
virtual int <strong>move_storage</strong> (std::string const&amp; save_path, int flags) = 0;
</pre>
<p>This function should move all the files belonging to the storage to the new save_path.
The default storage moves the single file or the directory of the torrent.</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>This function should move all the files belonging to the storage to
the new save_path. The default storage moves the single file or the
directory of the torrent.</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:
| no_error = 0
| need_full_check = -1
@ -396,9 +412,10 @@ efficient than reading and writing the data.</p>
<pre class="literal-block">
virtual bool <strong>swap_slots</strong> (int slot1, int slot2) = 0;
</pre>
<p>This function should swap the data in <tt class="docutils literal">slot1</tt> and <tt class="docutils literal">slot2</tt>. The default
storage uses a scratch buffer to read the data into, then moving the other
slot and finally writing back the temporary slot's data</p>
<p>This function should swap the data in <tt class="docutils literal">slot1</tt> and <tt class="docutils literal">slot2</tt>. The
default storage uses a scratch buffer to read the data into, then
moving the other slot and finally writing back the temporary slot's
data</p>
<p>This is only used in compact mode.</p>
<p>Returning <tt class="docutils literal">true</tt> indicates an error occurred.</p>
<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;
</pre>
<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 be moved to <tt class="docutils literal">slot1</tt>.</p>
should move to <tt class="docutils literal">slot2</tt>, which should be moved to <tt class="docutils literal">slot3</tt> which in
turn should be moved to <tt class="docutils literal">slot1</tt>.</p>
<p>This is only used in compact mode.</p>
<p>Returning <tt class="docutils literal">true</tt> indicates an error occurred.</p>
<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">
virtual bool <strong>delete_files</strong> () = 0;
</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>The <tt class="docutils literal">disk_buffer_pool</tt> is used to allocate and free disk buffers. It has the
following members:</p>
<p>The <tt class="docutils literal">disk_buffer_pool</tt> is used to allocate and free disk buffers. It
has the following members:</p>
<pre class="literal-block">
struct disk_buffer_pool : boost::noncopyable
{
@ -500,13 +518,13 @@ to the storage</p>
<div class="section" id="default-storage">
<h1>default_storage</h1>
<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.
It is possible to derive from this class in order to override some of its behavior, when
implementing a custom storage.</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. It is possible to derive from this class in order to
override some of its behavior, when implementing a custom storage.</p>
<pre class="literal-block">
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::vector&lt;boost::uint8_t&gt; const&amp; file_prio);
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;
};
</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>
<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::vector&lt;boost::uint8_t&gt; const&amp; file_prio);
</pre>

10
docs/reference-Error_Codes.html
View File

@ -55,7 +55,7 @@
<div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of contents</p>
<ul class="simple">
<li><a class="reference internal" href="#libtorrent-exception" id="id37">libtorrent_exception</a></li>
<li><a class="reference internal" href="#libtorrent-exception" id="id38">libtorrent_exception</a></li>
</ul>
</div>
<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;
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();
};
</pre>
@ -216,7 +216,7 @@ matched the info-hash, but failed to be parsed</td>
<tr><td>duplicate_torrent</td>
<td>19</td>
<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><td>invalid_torrent_handle</td>
<td>20</td>
@ -918,7 +918,7 @@ URL. i.e. it doesn't contain &quot;announce.</td>
</tbody>
</table>
<a name="error_code_enum"></a></div>
<div class="section" id="id31">
<div class="section" id="id32">
<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>
<table border="1" class="docutils">
@ -1036,7 +1036,7 @@ URL. i.e. it doesn't contain &quot;announce.</td>
</tbody>
</table>
<a name="error_code_enum"></a></div>
<div class="section" id="id34">
<div class="section" id="id35">
<h2>enum error_code_enum</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/upnp.hpp">libtorrent/upnp.hpp</a>&quot;</p>
<table border="1" class="docutils">

80
docs/reference-Plugins.html
View File

@ -240,15 +240,15 @@ ability to change or override the default libtorrent behavior.</p>
struct torrent_plugin
{
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_failed</strong> (int /*index*/);
virtual void <strong>on_piece_pass</strong> (int <em>/*index*/</em>);
virtual void <strong>on_piece_failed</strong> (int <em>/*index*/</em>);
virtual void <strong>tick</strong> ();
virtual bool <strong>on_resume</strong> ();
virtual bool <strong>on_pause</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;,
int /*src*/, int /*flags*/);
int <em>/*src*/</em>, int <em>/*flags*/</em>);
};
</pre>
<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">
<h3>on_piece_failed() on_piece_pass()</h3>
<pre class="literal-block">
virtual void <strong>on_piece_pass</strong> (int /*index*/);
virtual void <strong>on_piece_failed</strong> (int /*index*/);
virtual void <strong>on_piece_pass</strong> (int <em>/*index*/</em>);
virtual void <strong>on_piece_failed</strong> (int <em>/*index*/</em>);
</pre>
<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.
@ -320,7 +320,7 @@ can start downloading.</p>
<div class="section" id="on-state">
<h3>on_state()</h3>
<pre class="literal-block">
virtual void <strong>on_state</strong> (int /*s*/);
virtual void <strong>on_state</strong> (int <em>/*s*/</em>);
</pre>
<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>
@ -330,7 +330,7 @@ enum members</p>
<h3>on_add_peer()</h3>
<pre class="literal-block">
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>
<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
@ -354,33 +354,33 @@ struct peer_plugin
{
virtual char const* <strong>type</strong> () const;
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 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_have</strong> (int /*index*/);
virtual bool <strong>on_bitfield</strong> (bitfield const&amp; /*bitfield*/);
virtual bool <strong>on_have</strong> (int <em>/*index*/</em>);
virtual bool <strong>on_bitfield</strong> (bitfield const&amp; <em>/*bitfield*/</em>);
virtual bool <strong>on_have_all</strong> ();
virtual bool <strong>on_reject</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_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_choke</strong> ();
virtual bool <strong>on_not_interested</strong> ();
virtual bool <strong>on_piece</strong> (peer_request const&amp; /*piece*/
, disk_buffer_holder&amp; /*data*/);
virtual bool <strong>on_suggest</strong> (int /*index*/);
virtual bool <strong>on_piece</strong> (peer_request const&amp; <em>/*piece*/</em>
, disk_buffer_holder&amp; <em>/*data*/</em>);
virtual bool <strong>on_suggest</strong> (int <em>/*index*/</em>);
virtual bool <strong>on_cancel</strong> (peer_request const&amp;);
virtual bool <strong>on_dont_have</strong> (int /*index*/);
virtual bool <strong>can_disconnect</strong> (error_code const&amp; /*ec*/);
virtual bool <strong>on_extended</strong> (int /*length*/, int /*msg*/,
buffer::const_interval /*body*/);
virtual bool <strong>on_unknown_message</strong> (int /*length*/, int /*msg*/,
buffer::const_interval /*body*/);
virtual void <strong>on_piece_pass</strong> (int /*index*/);
virtual void <strong>on_piece_failed</strong> (int /*index*/);
virtual bool <strong>on_dont_have</strong> (int <em>/*index*/</em>);
virtual bool <strong>can_disconnect</strong> (error_code const&amp; <em>/*ec*/</em>);
virtual bool <strong>on_extended</strong> (int <em>/*length*/</em>, int <em>/*msg*/</em>,
buffer::const_interval <em>/*body*/</em>);
virtual bool <strong>on_unknown_message</strong> (int <em>/*length*/</em>, int <em>/*msg*/</em>,
buffer::const_interval <em>/*body*/</em>);
virtual void <strong>on_piece_pass</strong> (int <em>/*index*/</em>);
virtual void <strong>on_piece_failed</strong> (int <em>/*index*/</em>);
virtual void <strong>tick</strong> ();
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">
<h3>on_disconnect()</h3>
<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>
<p>called when the peer is being disconnected.</p>
<a name="on_connected()"></a></div>
@ -421,7 +421,7 @@ called.</p>
<div class="section" id="on-handshake">
<h3>on_handshake()</h3>
<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>
<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
@ -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">
<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">
virtual bool <strong>on_have</strong> (int /*index*/);
virtual bool <strong>on_bitfield</strong> (bitfield const&amp; /*bitfield*/);
virtual bool <strong>on_have</strong> (int <em>/*index*/</em>);
virtual bool <strong>on_bitfield</strong> (bitfield const&amp; <em>/*bitfield*/</em>);
virtual bool <strong>on_have_all</strong> ();
virtual bool <strong>on_reject</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_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_choke</strong> ();
virtual bool <strong>on_not_interested</strong> ();
virtual bool <strong>on_piece</strong> (peer_request const&amp; /*piece*/
, disk_buffer_holder&amp; /*data*/);
virtual bool <strong>on_suggest</strong> (int /*index*/);
virtual bool <strong>on_piece</strong> (peer_request const&amp; <em>/*piece*/</em>
, disk_buffer_holder&amp; <em>/*data*/</em>);
virtual bool <strong>on_suggest</strong> (int <em>/*index*/</em>);
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>
<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.
@ -482,7 +482,7 @@ handler.</p>
<div class="section" id="can-disconnect">
<h3>can_disconnect()</h3>
<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>
<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>
@ -490,8 +490,8 @@ if the <a class="reference external" href="reference-Plugins.html#plugin">plugin
<div class="section" id="on-extended">
<h3>on_extended()</h3>
<pre class="literal-block">
virtual bool <strong>on_extended</strong> (int /*length*/, int /*msg*/,
buffer::const_interval /*body*/);
virtual bool <strong>on_extended</strong> (int <em>/*length*/</em>, int <em>/*msg*/</em>,
buffer::const_interval <em>/*body*/</em>);
</pre>
<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
@ -502,8 +502,8 @@ this is not called for web seeds</p>
<div class="section" id="on-unknown-message">
<h3>on_unknown_message()</h3>
<pre class="literal-block">
virtual bool <strong>on_unknown_message</strong> (int /*length*/, int /*msg*/,
buffer::const_interval /*body*/);
virtual bool <strong>on_unknown_message</strong> (int <em>/*length*/</em>, int <em>/*msg*/</em>,
buffer::const_interval <em>/*body*/</em>);
</pre>
<p>this is not called for web seeds</p>
<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">
<h3>on_piece_failed() on_piece_pass()</h3>
<pre class="literal-block">
virtual void <strong>on_piece_pass</strong> (int /*index*/);
virtual void <strong>on_piece_failed</strong> (int /*index*/);
virtual void <strong>on_piece_pass</strong> (int <em>/*index*/</em>);
virtual void <strong>on_piece_failed</strong> (int <em>/*index*/</em>);
</pre>
<p>called when a piece that this peer participated in either
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">
struct feed_item
{
**feed_item** ();
**~feed_item** ();
<strong>feed_item</strong> ();
<strong>~feed_item</strong> ();
std::string url;
std::string uuid;
@ -119,7 +119,7 @@ after adding the feed</p>
<pre class="literal-block">
struct feed_settings
{
**feed_settings** ();
<strong>feed_settings</strong> ();
std::string url;
bool auto_download;
@ -173,7 +173,7 @@ calling <a class="reference external" href="reference-RSS.html#get_feed_status()
<pre class="literal-block">
struct feed_status
{
**feed_status** ();
<strong>feed_status</strong> ();
std::string url;
std::string title;
@ -240,7 +240,7 @@ default ttl, or the ttl specified by the feed.</dd>
<pre class="literal-block">
struct feed_handle
{
**feed_handle** ();
<strong>feed_handle</strong> ();
void <strong>update_feed</strong> ();
feed_status <strong>get_feed_status</strong> () const;
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">
<p class="topic-title first">Table of contents</p>
<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="#cache-status" id="id169">cache_status</a></li>
<li><a class="reference internal" href="#session-proxy" id="id170">session_proxy</a></li>
<li><a class="reference internal" href="#id36" id="id171">session</a></li>
<li><a class="reference internal" href="#dht-lookup" id="id172">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="#utp-status" id="id174">utp_status</a></li>
<li><a class="reference internal" href="#session-status" id="id175">session_status</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="id173">cache_status</a></li>
<li><a class="reference internal" href="#session-proxy" id="id174">session_proxy</a></li>
<li><a class="reference internal" href="#id36" id="id175">session</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="id177">dht_routing_bucket</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="id179">session_status</a></li>
</ul>
</div>
<a name="add_torrent_params"></a><div class="section" id="add-torrent-params">
<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>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>.
The key fields when adding a torrent are:</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>. The key fields when adding a torrent are:</p>
<ul class="simple">
<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>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>
<p>one of those fields need to be set. Another mandatory field is <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 <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,
which requires them to support the metadata extension. For the metadata extension
to work, libtorrent must be built with extensions enabled (<tt class="docutils literal">TORRENT_DISABLE_EXTENSIONS</tt> must not be
defined). It also takes an optional <tt class="docutils literal">name</tt> argument. This may be left empty in case no
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>
<p>one of those fields need to be set. Another mandatory field is
<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
<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, which requires them to support the metadata extension. For
the metadata extension to work, libtorrent must be built with extensions
enabled (<tt class="docutils literal">TORRENT_DISABLE_EXTENSIONS</tt> must not be defined). It also
takes an optional <tt class="docutils literal">name</tt> argument. This may be left empty in case no
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">
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
{
@ -132,20 +135,20 @@ struct add_torrent_params
<a name="add_torrent_params()"></a><div class="section" id="id5">
<h2>add_torrent_params()</h2>
<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>
<p>The constructor can be used to initialize the storage constructor, which determines
the storage mechanism for the downloaded or seeding data for the torrent. For more
information, see the <tt class="docutils literal">storage</tt> field.</p>
<p>The constructor can be used to initialize the storage constructor,
which determines the storage mechanism for the downloaded or seeding
data for the torrent. For more information, see the <tt class="docutils literal">storage</tt> field.</p>
<a name="flags_t"></a></div>
<div class="section" id="enum-flags-t">
<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>
<table border="1" class="docutils">
<colgroup>
<col width="21%" />
<col width="5%" />
<col width="74%" />
<col width="27%" />
<col width="7%" />
<col width="66%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">name</th>
@ -156,84 +159,99 @@ information, see the <tt class="docutils literal">storage</tt> field.</p>
<tbody valign="top">
<tr><td>flag_seed_mode</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
for this torrent and that they all match the hashes in the torrent file. Each time
a peer requests to download a block, the piece is verified against the hash, unless
it has been verified already. If a hash fails, the torrent will automatically leave
the seed mode and recheck all the files. The use case for this mode is 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.</p>
<p>Setting <tt class="docutils literal">flag_seed_mode</tt> on a torrent without metadata (a .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><p class="first">If <tt class="docutils literal">flag_seed_mode</tt> is set, libtorrent will assume that all files
are present for this torrent and that they all match the hashes in
the torrent file. Each time a peer requests to download a block,
the piece is verified against the hash, unless it has been verified
already. If a hash fails, the torrent will automatically leave the
seed mode and recheck all the files. The use case for this mode is
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.</p>
<p>Setting <tt class="docutils literal">flag_seed_mode</tt> on a torrent without metadata (a
.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>
</tr>
<tr><td>flag_override_resume_data</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>
state of the torrent are not loaded from the resume data, but the states requested
by the flags in <tt class="docutils literal">add_torrent_params</tt> will override them.</p>
<p class="last">If you pass in resume data, the paused state of the torrent when the resume data
was saved will override the paused state you pass in here. You can override this
by setting <tt class="docutils literal">flag_override_resume_data</tt>.</p>
<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> state of the torrent are not loaded from the
resume data, but the states requested by the flags in
<tt class="docutils literal">add_torrent_params</tt> will override them.</p>
<p class="last">If you pass in resume data, the paused state of the torrent when
the resume data was saved will override the paused state you pass
in here. You can override this by setting
<tt class="docutils literal">flag_override_resume_data</tt>.</p>
</td>
</tr>
<tr><td>flag_upload_mode</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,
which means it will not make any piece requests. This state is typically entered
on disk I/O errors, and if the torrent is also auto managed, it will be taken out
of this state periodically. This mode can be used to avoid race conditions when
adjusting priorities of pieces before allowing the torrent to start downloading.</p>
<p 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><p class="first">If <tt class="docutils literal">flag_upload_mode</tt> is set, the torrent will be initialized in
upload-mode, which means it will not make any piece requests. This
state is typically entered on disk I/O errors, and if the torrent
is also auto managed, it will be taken out of this state
periodically. This mode can be used to avoid race conditions when
adjusting priorities of pieces before allowing the torrent to start
downloading.</p>
<p 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>
</tr>
<tr><td>flag_share_mode</td>
<td>8</td>
<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
merley want to improve our share ratio (i.e. increase it). A torrent started in
share mode will do its best to never download more than it uploads to the swarm.
If the swarm does not have enough demand for upload capacity, the torrent will
not 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.</p>
<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
Share mode indicates that we are not interested in downloading the
torrent, but merley want to improve our share ratio (i.e. increase
it). A torrent started in share mode will do its best to never
download more than it uploads to the swarm. If the swarm does not
have enough demand for upload capacity, the torrent will not
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.</p>
<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>
<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>
for more info.</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> for more info.</p>
</td>
</tr>
<tr><td>flag_apply_ip_filter</td>
<td>16</td>
<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). This is useful if certain torrents needs to be excempt for some reason, being
an auto-update torrent for instance.</td>
default all torrents are subject to filtering by the IP filter
(i.e. this flag is set by default). This is useful if certain
torrents needs to be excempt for some reason, being an auto-update
torrent for instance.</td>
</tr>
<tr><td>flag_paused</td>
<td>32</td>
<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
resumed. This is typically a good way of avoiding race conditions when setting
configuration options on torrents before starting them.</td>
state. I.e. it won't connect to the tracker or any of the peers
until it's resumed. This is typically a good way of avoiding race
conditions when setting configuration options on torrents before
starting them.</td>
</tr>
<tr><td>flag_auto_managed</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
at any point, regardless of how it paused. If it's important to manually control
when the torrent is paused and resumed, don't make it auto managed.</p>
<p>If <tt class="docutils literal">flag_auto_managed</tt> is set, the torrent will be queued, started and seeded
automatically by libtorrent. When this is set, the torrent should also be started
as paused. The default queue order is the order the torrents were added. They
are all downloaded in that order. For more details, see <a class="reference external" href="manual-ref.html#queuing">queuing</a>.</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><p class="first">If the torrent is auto-managed (<tt class="docutils literal">flag_auto_managed</tt>), the torrent
may be resumed at any point, regardless of how it paused. If it's
important to manually control when the torrent is paused and
resumed, don't make it auto managed.</p>
<p>If <tt class="docutils literal">flag_auto_managed</tt> is set, the torrent will be queued,
started and seeded automatically by libtorrent. When this is set,
the torrent should also be started as paused. The default queue
order is the order the torrents were added. They are all downloaded
in that order. For more details, see <a class="reference external" href="manual-ref.html#queuing">queuing</a>.</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>
</tr>
<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>
<td>256</td>
<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><td>flag_update_subscribe</td>
<td>512</td>
@ -252,16 +271,16 @@ updates when calling <a class="reference external" href="reference-Session.html#
</tr>
<tr><td>flag_super_seeding</td>
<td>1024</td>
<td>sets the torrent into super seeding mode. If the torrent
is not a 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
after adding it.</td>
<td>sets the torrent into super seeding mode. If the torrent is not a
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 after adding it.</td>
</tr>
<tr><td>flag_sequential_download</td>
<td>2048</td>
<td>sets the sequential download state for the torrent.
It has the same effect as calling <tt class="docutils literal"><span class="pre">torrent_handle::sequential_download(true)</span></tt>
on the torrent handle immediately after adding it.</td>
<td>sets the sequential download state for the torrent. It has the same
effect as calling <tt class="docutils literal"><span class="pre">torrent_handle::sequential_download(true)</span></tt> on
the torrent handle immediately after adding it.</td>
</tr>
</tbody>
</table>
@ -272,13 +291,13 @@ is used for forward binary compatibility.</dd>
</dl>
<a name="ti"></a><dl class="docutils">
<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
is set, this is required to be initiazlied.</dd>
<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 is set, this is required to be initiazlied.</dd>
</dl>
<a name="trackers"></a><dl class="docutils">
<dt>trackers</dt>
<dd>If the torrent doesn't have a tracker, but relies on the DHT to find peers, the
<tt class="docutils literal">trackers</tt> can specify tracker URLs for the torrent.</dd>
<dd>If the torrent doesn't have a tracker, but relies on the DHT to find
peers, the <tt class="docutils literal">trackers</tt> can specify tracker URLs for the torrent.</dd>
</dl>
<a name="url_seeds"></a><dl class="docutils">
<dt>url_seeds</dt>
@ -288,62 +307,71 @@ is set, this is required to be initiazlied.</dd>
<a name="name"></a>
<a name="save_path"></a><dl class="docutils">
<dt>dht_nodes name save_path</dt>
<dd>a list of hostname and port pairs, representing DHT nodes to be
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>
<dd>a list of hostname and port pairs, representing DHT nodes to be 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>
</dl>
<a name="resume_data"></a><dl class="docutils">
<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
is available. The fast-resume data can be acquired from a running torrent by calling
<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
passed in will be swapped into the running torrent instance with <tt class="docutils literal"><span class="pre">std::vector::swap()</span></tt>.</dd>
<dd>The optional parameter, <tt class="docutils literal">resume_data</tt> can be given if up to date
fast-resume data is available. The fast-resume data can be acquired
from a running torrent by calling <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 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>
<a name="storage_mode"></a><dl class="docutils">
<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>
<a name="storage"></a><dl class="docutils">
<dt>storage</dt>
<dd>can be used to customize how the data is stored. The default
storage 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
content on disk for instance. For more information 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>
<dd>can be used to customize how the data is stored. The default storage
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 content on disk for instance. For more information
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>
<a name="userdata"></a><dl class="docutils">
<dt>userdata</dt>
<dd>The <tt class="docutils literal">userdata</tt> parameter is optional and will be passed on to the extension
constructor functions, if any (see <a class="reference internal" href="#add-extension">add_extension()</a>).</dd>
<dd>The <tt class="docutils literal">userdata</tt> parameter is optional and will be passed on to the
extension constructor functions, if any (see <a class="reference internal" href="#add-extension">add_extension()</a>).</dd>
</dl>
<a name="file_priorities"></a><dl class="docutils">
<dt>file_priorities</dt>
<dd>can be set to control the initial file priorities when adding
a torrent. The semantics are the same as for <tt class="docutils literal"><span class="pre">torrent_handle::prioritize_files()</span></tt>.</dd>
<dd>can be set to control the initial file priorities when adding a
torrent. The semantics are the same as for
<tt class="docutils literal"><span class="pre">torrent_handle::prioritize_files()</span></tt>.</dd>
</dl>
<a name="trackerid"></a><dl class="docutils">
<dt>trackerid</dt>
<dd>the default tracker id to be used when announcing to trackers. By default
this is empty, and no tracker ID is used, since this is an optional argument. If
a tracker returns a tracker ID, that ID is used instead of this.</dd>
<dd>the default tracker id to be used when announcing to trackers. By
default this is empty, and no tracker ID is used, since this is an
optional argument. If a tracker returns a tracker ID, that ID is used
instead of this.</dd>
</dl>
<a name="url"></a><dl class="docutils">
<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
until the .torrent file has been downloaded. If there's any error while downloading,
the torrent will be stopped and the torrent error state (<tt class="docutils literal"><span class="pre">torrent_status::error</span></tt>)
will indicate what went wrong. The <tt class="docutils literal">url</tt> may refer to a magnet link or a regular
http URL.</p>
<p>If it refers to an HTTP URL, the info-hash for the added torrent will 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>
<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 until the .torrent file has been
downloaded. If there's any error while downloading, the torrent will
be stopped and the torrent error state (<tt class="docutils literal"><span class="pre">torrent_status::error</span></tt>)
will indicate what went wrong. The <tt class="docutils literal">url</tt> may refer to a magnet link
or a regular http URL.</p>
<p>If it refers to an HTTP URL, the info-hash for the added torrent will
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>
</dd>
</dl>
<a name="uuid"></a><dl class="docutils">
<dt>uuid</dt>
<dd>if <tt class="docutils literal">uuid</tt> is specified, it is used to find duplicates. If another torrent is already
running with the same UUID as the one being added, it will be considered a duplicate. This
is mainly useful for RSS feed items which has UUIDs specified.</dd>
<dd>if <tt class="docutils literal">uuid</tt> is specified, it is used to find duplicates. If another
torrent is already running with the same UUID as the one being added,
it will be considered a duplicate. This is mainly useful for RSS feed
items which has UUIDs specified.</dd>
</dl>
<a name="source_feed_url"></a><dl class="docutils">
<dt>source_feed_url</dt>
@ -352,7 +380,8 @@ if it comes from an RSS feed.</dd>
</dl>
<a name="flags"></a><dl class="docutils">
<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>
<a name="info_hash"></a><dl class="docutils">
<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="download_limit"></a><dl class="docutils">
<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
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">set_download_limit()</tt> functions on <a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a>. These values let you initialize
these settings when the torrent is added, instead of calling these functions immediately
following adding it.</p>
<p class="last">-1 means unlimited on these settings
just like their counterpart functions
on <a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a></p>
<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 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">set_download_limit()</tt> functions on <a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a>. These values let
you initialize these settings when the torrent is added, instead of
calling these functions immediately following adding it.</p>
<p class="last">-1 means unlimited on these settings just like their counterpart
functions on <a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a></p>
</dd>
</dl>
<a name="cache_status"></a></div>
@ -385,7 +414,7 @@ relevant for the disk io thread and disk cache.</p>
<pre class="literal-block">
struct cache_status
{
**cache_status** ();
<strong>cache_status</strong> ();
size_type blocks_written;
size_type writes;
@ -415,7 +444,7 @@ struct cache_status
<a name="cache_status()"></a><div class="section" id="id23">
<h2>cache_status()</h2>
<pre class="literal-block">
**cache_status** ();
<strong>cache_status</strong> ();
</pre>
<p>initializes all counters to 0</p>
<a name="blocks_written"></a><dl class="docutils">
@ -531,13 +560,13 @@ is done shutting down.</p>
<pre class="literal-block">
class session_proxy
{
**session_proxy** ();
<strong>session_proxy</strong> ();
};
</pre>
<a name="session_proxy()"></a><div class="section" id="id34">
<h2>session_proxy()</h2>
<pre class="literal-block">
**session_proxy** ();
<strong>session_proxy</strong> ();
</pre>
<p>default constructor, does not refer to any <a class="reference external" href="reference-Session.html#session">session</a>
implementation object.</p>
@ -554,18 +583,18 @@ torrents to participate in.</p>
<pre class="literal-block">
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)
, int flags = start_default_features | add_default_plugins
, boost::uint32_t alert_mask = alert::error_notification
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
, char const* listen_interface = &quot;0.0.0.0&quot;
, int flags = start_default_features | add_default_plugins
, int alert_mask = alert::error_notification
TORRENT_LOGPATH_ARG_DEFAULT);
**~session** ();
<strong>~session</strong> ();
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>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">
<h2>session()</h2>
<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)
, int flags = start_default_features | add_default_plugins
, boost::uint32_t alert_mask = alert::error_notification
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
, char const* listen_interface = &quot;0.0.0.0&quot;
, 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,
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
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>
<div class="section" id="id42">
<div class="section" id="id43">
<h2>~session()</h2>
<pre class="literal-block">
**~session** ();
<strong>~session</strong> ();
</pre>
<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.
@ -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.
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>
<div class="section" id="id97">
<div class="section" id="id98">
<h2>dht_get_item()</h2>
<pre class="literal-block">
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
structure.</p>
<a name="dht_put_item()"></a></div>
<div class="section" id="id99">
<div class="section" id="id100">
<h2>dht_put_item()</h2>
<pre class="literal-block">
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
<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
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,
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
@ -1288,13 +1317,13 @@ void <strong>set_proxy</strong> (proxy_settings const&amp; s);
proxy_settings <strong>proxy</strong> () const;
</pre>
<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
<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
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
session_settings.</p>
<a class="reference external" href="reference-Settings.html#session_settings">session_settings</a>.</p>
<a name="i2p_proxy()"></a>
<a name="set_i2p_proxy()"></a></div>
<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">
<p class="topic-title first">Table of contents</p>
<ul class="simple">
<li><a class="reference internal" href="#proxy-settings" id="id37">proxy_settings</a></li>
<li><a class="reference internal" href="#session-settings" id="id38">session_settings</a></li>
<li><a class="reference internal" href="#dht-settings" id="id39">dht_settings</a></li>
<li><a class="reference internal" href="#pe-settings" id="id40">pe_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="id39">session_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="id41">pe_settings</a></li>
</ul>
</div>
<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">
struct proxy_settings
{
**proxy_settings** ();
<strong>proxy_settings</strong> ();
std::string hostname;
std::string username;
@ -83,7 +83,7 @@ struct proxy_settings
<a name="proxy_settings()"></a><div class="section" id="id2">
<h2>proxy_settings()</h2>
<pre class="literal-block">
**proxy_settings** ();
<strong>proxy_settings</strong> ();
</pre>
<p>defaults constructs proxy settings, initializing it to the default
settings.</p>
@ -131,9 +131,9 @@ session::get_settings() to get the current settings.</p>
<pre class="literal-block">
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);
**~session_settings** ();
<strong>~session_settings</strong> ();
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">
<h2>~session_settings() session_settings()</h2>
<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);
**~session_settings** ();
<strong>~session_settings</strong> ();
</pre>
<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>
@ -1179,7 +1179,7 @@ until libtorrent will take it out of the upload mode, to test if the
error condition has been fixed.</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
set_upload_mode().</p>
<a class="reference external" href="reference-Core.html#set_upload_mode()">set_upload_mode()</a>.</p>
</dd>
</dl>
<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">
struct dht_settings
{
**dht_settings** ();
<strong>dht_settings</strong> ();
int max_peers_reply;
int search_branching;
@ -1761,10 +1761,10 @@ struct dht_settings
bool ignore_dark_internet;
};
</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>
<pre class="literal-block">
**dht_settings** ();
<strong>dht_settings</strong> ();
</pre>
<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">
@ -1859,7 +1859,7 @@ to peer protocol encryption.</p>
<pre class="literal-block">
struct pe_settings
{
**pe_settings** ();
<strong>pe_settings</strong> ();
enum enc_policy
{
@ -1881,10 +1881,10 @@ struct pe_settings
bool prefer_rc4;
};
</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>
<pre class="literal-block">
**pe_settings** ();
<strong>pe_settings</strong> ();
</pre>
<p>initializes the encryption settings with the default vaues</p>
<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">
<p class="topic-title first">Table of contents</p>
<ul class="simple">
<li><a class="reference internal" href="#time-duration" id="id17">time_duration</a></li>
<li><a class="reference internal" href="#ptime" id="id18">ptime</a></li>
<li><a class="reference internal" href="#time-duration" id="id18">time_duration</a></li>
<li><a class="reference internal" href="#ptime" id="id19">ptime</a></li>
</ul>
</div>
<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
that take a well defined time unit (seconds, minutes, etc.). They can
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">
<p class="first admonition-title">Note</p>
<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">
struct bitfield
{
**bitfield** (int bits);
**bitfield** (bitfield const&amp; rhs);
**bitfield** (bitfield&amp;&amp; rhs);
**bitfield** (int bits, bool val);
**bitfield** ();
**bitfield** (char const* b, int bits);
<strong>bitfield</strong> (int bits);
<strong>bitfield</strong> (bitfield const&amp; rhs);
<strong>bitfield</strong> (bitfield&amp;&amp; rhs);
<strong>bitfield</strong> (int bits, bool val);
<strong>bitfield</strong> ();
<strong>bitfield</strong> (char const* b, int bits);
void <strong>borrow_bytes</strong> (char* b, int bits);
void <strong>assign</strong> (char const* b, int bits);
bool <strong>get_bit</strong> (int index) const;
@ -90,12 +90,12 @@ struct bitfield
<a name="bitfield()"></a><div class="section" id="id3">
<h2>bitfield()</h2>
<pre class="literal-block">
**bitfield** (int bits);
**bitfield** (bitfield const&amp; rhs);
**bitfield** (bitfield&amp;&amp; rhs);
**bitfield** (int bits, bool val);
**bitfield** ();
**bitfield** (char const* b, int bits);
<strong>bitfield</strong> (int bits);
<strong>bitfield</strong> (bitfield const&amp; rhs);
<strong>bitfield</strong> (bitfield&amp;&amp; rhs);
<strong>bitfield</strong> (int bits, bool val);
<strong>bitfield</strong> ();
<strong>bitfield</strong> (char const* b, int bits);
</pre>
<p>constructs a new <a class="reference external" href="reference-Utility.html#bitfield">bitfield</a>. The default constructor creates an empty
<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">
class sha1_hash
{
**sha1_hash** ();
<strong>sha1_hash</strong> ();
static sha1_hash <strong>max</strong> ();
static sha1_hash <strong>min</strong> ();
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">
<h2>sha1_hash()</h2>
<pre class="literal-block">
**sha1_hash** ();
<strong>sha1_hash</strong> ();
</pre>
<p>constructs an all-sero sha1-hash</p>
<a name="max()"></a></div>

277
include/libtorrent/add_torrent_params.hpp
View File

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

26
include/libtorrent/alert.hpp
View File

@ -49,24 +49,22 @@ POSSIBILITY OF SUCH DAMAGE.
// OVERVIEW
//
// The pop_alert() function on session is the interface for retrieving
// alerts, warnings, messages and errors from libtorrent. If no alerts have
// been posted by libtorrent pop_alert() will return a default initialized
// ``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
// The pop_alerts() function on session is the main interface for retrieving
// alerts (warnings, messages and errors from libtorrent). If no alerts have
// been posted by libtorrent pop_alert() will return an empty list.
//
// By default, only errors are reported. set_alert_mask() can be
// used to specify which kinds of events should be reported. The alert mask
// is comprised by bits from the category_t enum.
// By default, only errors are reported. set_alert_mask() can be used to
// specify which kinds of events should be reported. The alert mask is
// 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
// alerts that belong to an enabled category are posted. Setting the alert bitmask to 0 will disable
// all alerts (except those that are non-discardable).
// Every alert belongs to one or more category. There is a small cost involved
// in posting alerts. Only alerts that belong to an enabled category are
// 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
// alerts that are generated for a specific torrent are derived from torrent_alert,
// and tracker events derive from tracker_alert.
// alerts that are generated for a specific torrent are derived from
// torrent_alert, and tracker events derive from tracker_alert.
//
#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
// 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.
//
// 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
{
// This function is declared in the header ``<libtorrent/identify_client.hpp>``. It can can be used
// to extract a string describing a client version from its peer-id. It will recognize most clients
// that have this kind of identification in the peer-id.
// This function can can be used to extract a string describing a client
// version from its peer-id. It will recognize most clients that have this
// kind of identification in the peer-id.
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
// to automate the identification of clients. It will not be able to identify peers with non-
// standard encodings. Only Azureus style, Shadow's style and Mainline style. This function is
// declared in the header ``<libtorrent/identify_client.hpp>``.
// Returns an optional fingerprint if any can be identified from the peer
// id. This can be used to automate the identification of clients. It will
// not be able to identify peers with non- standard encodings. Only Azureus
// style, Shadow's style and Mainline style.
TORRENT_EXPORT boost::optional<fingerprint> client_fingerprint(peer_id const& p);
}
#endif // TORRENT_IDENTIFY_CLIENT_HPP_INCLUDED

150
include/libtorrent/storage.hpp
View File

@ -66,9 +66,21 @@ POSSIBILITY OF SUCH DAMAGE.
// OVERVIEW
//
// 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.
// libtorrent provides a customization point for storage of data. By default,
// (``default_storage``) downloaded files are saved to disk according with the
// 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
// 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
// torrent in the way one would assume a torrent is saved to disk. Implementing
// your own storage interface makes it possible to store all data in RAM, or in
// some optimized order on disk (the order the pieces are received for instance),
// or saving multifile torrents in a single file in order to be able to take
// advantage of optimized disk-I/O.
// implementation uses regular files in the filesystem, mapping the files in
// the torrent in the way one would assume a torrent is saved to disk.
// Implementing your own storage interface makes it possible to store all
// data in RAM, or in some optimized order on disk (the order the pieces are
// received for instance), or saving multifile torrents in a single file in
// 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
// modifies some particular behavior, for instance encrypting the data before
// it's written to disk, and decrypting it when it's read again.
// It is also possible to write a thin class that uses the default storage
// but modifies some particular behavior, for instance encrypting the data
// 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
// 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
// compact allocation mode it won't).
//
// libtorrent comes with two built-in storage implementations; ``default_storage``
// and ``disabled_storage``. Their constructor functions are called default_storage_constructor()
// and ``disabled_storage_constructor`` respectively. The disabled storage does
// libtorrent comes with two built-in storage implementations;
// ``default_storage`` and ``disabled_storage``. Their constructor functions
// 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
// 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) {}
// This function is called when the storage is to be initialized. The default storage
// will create directories and empty files at this point. If ``allocate_files`` is true,
// it will also ``ftruncate`` all files to their target size.
// This function is called when the storage is to be initialized. The
// default storage will create directories and empty files at this point.
// If ``allocate_files`` is true, it will also ``ftruncate`` all files to
// their target size.
//
// Returning ``true`` indicates an error occurred.
virtual bool initialize(bool allocate_files) = 0;
// This function is called when first checking (or re-checking) the storage for a torrent.
// It should return true if any of the files that is used in this storage exists on disk.
// If so, the storage will be checked for existing pieces before starting the download.
// This function is called when first checking (or re-checking) the
// storage for a torrent. It should return true if any of the files that
// 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;
// change the priorities of files.
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``.
// It should read or write ``num_bufs`` buffers sequentially, where the size of each buffer
// is specified in the buffer array ``bufs``. The file::iovec_t type has the following members::
// These functions should read or write the data in or to the given
// ``slot`` at the given ``offset``. It should read or write ``num_bufs``
// 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
// {
// void* iov_base;
// size_t iov_len;
// };
// struct iovec_t { void* iov_base; size_t iov_len; };
//
// The return value is the number of bytes actually read or written, or -1 on failure. If
// it returns -1, the error code is expected to be set to
// The return value is the number of bytes actually read or written, or
// -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,
// except for the last buffer of the torrent. The allocated buffer can be assumed to fit a
// fully page aligned number of bytes though. This is useful when reading and writing the
// last piece of a file in unbuffered mode.
// Every buffer in ``bufs`` can be assumed to be page aligned and be of a
// page aligned size, except for the last buffer of the torrent. The
// allocated buffer can be assumed to fit a fully page aligned number of
// 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
// 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.
// The ``offset`` is aligned to 16 kiB boundries *most of the time*, but
// 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.
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);
// This function is called when a read job is queued. It gives the storage wrapper an
// opportunity to hint the operating system about this coming read. For instance, the
// storage may call ``posix_fadvise(POSIX_FADV_WILLNEED)`` or ``fcntl(F_RDADVISE)``.
// This function is called when a read job is queued. It gives the
// storage wrapper an opportunity to hint the operating system about this
// coming read. For instance, the storage may call
// ``posix_fadvise(POSIX_FADV_WILLNEED)`` or ``fcntl(F_RDADVISE)``.
virtual void hint_read(int, int, int) {}
// negative return value indicates an error
@ -251,17 +268,18 @@ namespace libtorrent
// byte at offset ``offset`` in slot ``slot``.
virtual size_type physical_offset(int slot, int offset) = 0;
// This function is optional. It is supposed to return the first piece, starting at
// ``start`` that is fully contained within a data-region on disk (i.e. non-sparse
// region). The purpose of this is to skip parts of files that can be known to contain
// zeros when checking files.
// This function is optional. It is supposed to return the first piece,
// starting at ``start`` that is fully contained within a data-region on
// disk (i.e. non-sparse region). The purpose of this is to skip parts of
// files that can be known to contain zeros when checking files.
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.
// The default storage moves the single file or the directory of the torrent.
// This function should move all the files belonging to the storage to
// 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
// ``release_files()``.
// Before moving the files, any open file handles may have to be closed,
// like ``release_files()``.
//
// returns one of:
// | no_error = 0
@ -295,9 +313,10 @@ namespace libtorrent
// Returning ``true`` indicates an error occurred.
virtual bool move_slot(int src_slot, int dst_slot) = 0;
// This function should swap the data in ``slot1`` and ``slot2``. The default
// storage uses a scratch buffer to read the data into, then moving the other
// slot and finally writing back the temporary slot's data
// This function should swap the data in ``slot1`` and ``slot2``. The
// default storage uses a scratch buffer to read the data into, then
// moving the other slot and finally writing back the temporary slot's
// data
//
// This is only used in compact mode.
//
@ -305,8 +324,8 @@ namespace libtorrent
virtual bool swap_slots(int slot1, int slot2) = 0;
// 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 be moved to ``slot1``.
// should move to ``slot2``, which should be moved to ``slot3`` which in
// turn should be moved to ``slot1``.
//
// This is only used in compact mode.
//
@ -324,12 +343,13 @@ namespace libtorrent
// ``true`` should be returned.
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.
//
// The ``disk_buffer_pool`` is used to allocate and free disk buffers. It has the
// following members::
// The ``disk_buffer_pool`` is used to allocate and free disk buffers. It
// has the following members::
//
// struct disk_buffer_pool : boost::noncopyable
// {
@ -347,13 +367,13 @@ namespace libtorrent
#ifndef TORRENT_NO_DEPRECATE
// This function is called each time a file is completely downloaded. The
// storage implementation can perform last operations on a file. The file will
// not be opened for writing after this.
// storage implementation can perform last operations on a file. The file
// will not be opened for writing after this.
//
// ``index`` is the index of the file that completed.
//
// On windows the default storage implementation clears the sparse file flag
// on the specified file.
// On windows the default storage implementation clears the sparse file
// flag on the specified file.
virtual void finalize_file(int) {}
#endif
@ -389,9 +409,9 @@ namespace libtorrent
session_settings* m_settings;
};
// The default implementation of storage_interface. Behaves as a normal bittorrent client.
// It is possible to derive from this class in order to override some of its behavior, when
// implementing a custom storage.
// The default implementation of storage_interface. Behaves as a normal
// bittorrent client. It is possible to derive from this class in order to
// override some of its behavior, when implementing a custom storage.
class TORRENT_EXPORT default_storage : public storage_interface, boost::noncopyable
{
public: