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

regenerate html

This commit is contained in:
Arvid Norberg 2013-07-01 03:41:36 +00:00
parent 4a88ffe0c9
commit 7cf035167b
1 changed files with 200 additions and 75 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

275
docs/manual.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.8.1: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.10: http://docutils.sourceforge.net/" />
<title>libtorrent API Documentation</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
@ -248,22 +248,6 @@ class session: public boost::noncopyable
session_settings settings() const;
void set_pe_settings(pe_settings const&amp; settings);
void set_upload_rate_limit(int bytes_per_second);
int upload_rate_limit() const;
void set_download_rate_limit(int bytes_per_second);
int download_rate_limit() const;
void set_local_upload_rate_limit(int bytes_per_second);
int local_upload_rate_limit() const;
void set_local_download_rate_limit(int bytes_per_second);
int local_download_rate_limit() const;
void set_max_uploads(int limit);
void set_max_connections(int limit);
int max_connections() const;
void set_max_half_open_connections(int limit);
int max_half_open_connections() const;
void set_proxy(proxy_settings const&amp; s);
proxy_settings proxy() const;
@ -303,9 +287,9 @@ class session: public boost::noncopyable
size_t queue_size_limit_);
void set_alert_dispatch(boost::function&lt;void(std::auto_ptr&lt;alert&gt;)&gt; const&amp; fun);
feed_handle session::add_feed(feed_settings const&amp; feed);
void session::remove_feed(feed_handle h);
void session::get_feeds(std::vector&lt;feed_handle&gt;&amp; f) const;
feed_handle add_feed(feed_settings const&amp; feed);
void remove_feed(feed_handle h);
void get_feeds(std::vector&lt;feed_handle&gt;&amp; f) const;
void add_extension(boost::function&lt;
boost::shared_ptr&lt;torrent_plugin&gt;(torrent*)&gt; ext);
@ -529,6 +513,10 @@ until the .torrent file has been downloaded. If there's any error while download
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>Once the info-hash change happens, a <a class="reference internal" href="#torrent-update-alert">torrent_update_alert</a> is posted.</p>
<p><tt class="docutils literal">dht_nodes</tt> is 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.</p>
<p>If the torrent you are trying to add already exists in the session (is either queued
@ -646,7 +634,7 @@ be taken out of upload-mode, regardless of how it got there. If it's important t
manually control when the torrent leaves upload mode, don't make it auto managed.</p>
<p><tt class="docutils literal">flag_share_mode</tt> determines if the torrent should be added in <em>share mode</em> or not.
Share mode indicates that we are not interested in downloading the torrent, but
merlely want to improve our share ratio (i.e. increase it). A torrent started in
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
@ -1172,7 +1160,7 @@ on linux, write to a pipe or an eventfd.</p>
<h2>add_feed()</h2>
<blockquote>
<pre class="literal-block">
feed_handle session::add_feed(feed_settings const&amp; feed);
feed_handle add_feed(feed_settings const&amp; feed);
</pre>
</blockquote>
<p>This adds an RSS feed to the session. The feed will be refreshed
@ -1225,7 +1213,7 @@ see <a class="reference internal" href="#feed-handle">feed_handle</a>.</p>
<h2>remove_feed()</h2>
<blockquote>
<pre class="literal-block">
void session::remove_feed(feed_handle h);
void remove_feed(feed_handle h);
</pre>
</blockquote>
<p>Removes a feed from being watched by the session. When this
@ -1236,7 +1224,7 @@ to any feed.</p>
<h2>get_feeds()</h2>
<blockquote>
<pre class="literal-block">
void session::get_feeds(std::vector&lt;feed_handle&gt;&amp; f) const;
void get_feeds(std::vector&lt;feed_handle&gt;&amp; f) const;
</pre>
</blockquote>
<p>Returns a list of all RSS feeds that are being watched by the session.</p>
@ -1806,6 +1794,11 @@ returned by <tt class="docutils literal">orig_files()</tt>.</p>
<p>If you want to rename the base name of the torrent (for a multifile torrent), you
can copy the <tt class="docutils literal">file_storage</tt> (see <a class="reference internal" href="#files-orig-files">files() orig_files()</a>), change the name, and
then use <a class="reference internal" href="#remap-files">remap_files()</a>.</p>
<p>The <tt class="docutils literal">new_filename</tt> can both be a relative path, in which case the file name
is relative to the <tt class="docutils literal">save_path</tt> of the torrent. If the <tt class="docutils literal">new_filename</tt> is
an absolute path (i.e. <tt class="docutils literal">is_complete(new_filename) == true</tt>), then the file
is detached from the <tt class="docutils literal">save_path</tt> of the torrent. In this case the file is
not moved when <a href="#id46"><span class="problematic" id="id47">move_storage_</span></a> is invoked.</p>
</div>
<div class="section" id="begin-files-end-files-rbegin-files-rend-files">
<h2>begin_files() end_files() rbegin_files() rend_files()</h2>
@ -1999,6 +1992,10 @@ struct announce_entry
int next_announce_in() const;
int min_announce_in() const;
int scrape_incomplete;
int scrape_complete;
int scrape_downloaded;
error_code last_error;
std::string message;
@ -2027,6 +2024,12 @@ this tracker. <tt class="docutils literal">min_announce_in()</tt> returns the nu
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>
<p><tt class="docutils literal">scrape_incomplete</tt>, <tt class="docutils literal">scrape_complete</tt> and <tt class="docutils literal">scrape_downloaded</tt> are either
-1 or the scrape information this tracker last responded with. <em>incomplete</em> is
the current number of downloaders in the swarm, <em>complete</em> is the current number
of seeds in the swarm and <em>downloaded</em> is the cumulative number of completed
downloads of this torrent, since the beginning of time (from this tracker's point
of view).</p>
<p>If the last time this tracker was contacted, the tracker returned a warning
or error message, <tt class="docutils literal">message</tt> contains that message.</p>
<p><tt class="docutils literal">fail_limit</tt> is the max number of failures to announce to this tracker in
@ -2178,7 +2181,10 @@ struct torrent_handle
query_accurate_download_counters = 2,
query_last_seen_complete = 4,
query_pieces = 8,
query_verified_pieces = 16
query_verified_pieces = 16,
query_torrent_file = 32,
query_name = 64,
query_save_path = 128,
};
torrent_status status(boost::uint32_t flags = 0xffffffff);
@ -2188,8 +2194,6 @@ struct torrent_handle
boost::intrusive_ptr&lt;torrent_info&gt; torrent_file() const;
bool is_valid() const;
std::string name() const;
enum save_resume_flags_t { flush_disk_cache = 1, save_info_dict = 2 };
void save_resume_data(int flags = 0) const;
bool need_save_resume_data() const;
@ -2270,9 +2274,8 @@ struct torrent_handle
bool set_metadata(char const* buf, int size) const;
std::string save_path() const;
void move_storage(std::string const&amp; save_path) const;
void move_storage(std::wstring const&amp; save_path) const;
void move_storage(std::string const&amp; save_path, int flags = 0) const;
void move_storage(std::wstring const&amp; save_path, int flags = 0) const;
void rename_file(int index, std::string) const;
void rename_file(int index, std::wstring) const;
storage_interface* get_storage_impl() const;
@ -2435,33 +2438,50 @@ fully downloaded and passed the hash check count. When specifying piece granular
the operation is a lot cheaper, since libtorrent already keeps track of this internally
and no calculation is required.</p>
</div>
<div class="section" id="save-path">
<h2>save_path()</h2>
<blockquote>
<pre class="literal-block">
std::string save_path() const;
</pre>
</blockquote>
<p><tt class="docutils literal">save_path()</tt> returns the path that was given to <a class="reference internal" href="#async-add-torrent-add-torrent">async_add_torrent() add_torrent()</a> when this torrent
was started.</p>
</div>
<div class="section" id="move-storage">
<h2>move_storage()</h2>
<blockquote>
<pre class="literal-block">
void move_storage(std::string const&amp; save_path) const;
void move_storage(std::wstring const&amp; save_path) const;
void move_storage(std::string const&amp; save_path, int flags = 0) const;
void move_storage(std::wstring const&amp; save_path, int flags = 0) const;
</pre>
</blockquote>
<p>Moves the file(s) that this torrent are currently seeding from or downloading to. If
the given <tt class="docutils literal">save_path</tt> is not located on the same drive as the original save path,
The files will be copied to the new drive and removed from their original location.
the files will be copied to the new drive and removed from their original location.
This will block all other disk IO, and other torrents download and upload rates may
drop while copying the file.</p>
<p>Since disk IO is performed in a separate thread, this operation is also asynchronous.
Once the operation completes, the <tt class="docutils literal">storage_moved_alert</tt> is generated, with the new
path as the message. If the move fails for some reason, <tt class="docutils literal">storage_moved_failed_alert</tt>
is generated instead, containing the error message.</p>
<p>The <tt class="docutils literal">flags</tt> argument determines the behavior of the copying/moving of the files
in the torrent. They are defined in <tt class="docutils literal">include/libtorrent/storage.hpp</tt>:</p>
<blockquote>
<ul class="simple">
<li><tt class="docutils literal">always_replace_files</tt> = 0</li>
<li><tt class="docutils literal">fail_if_exist</tt> = 1</li>
<li><tt class="docutils literal">dont_replace</tt> = 2</li>
</ul>
</blockquote>
<p><tt class="docutils literal">always_replace_files</tt> is the default and replaces any file that exist in both the
source directory and the target directory.</p>
<p><tt class="docutils literal">fail_if_exist</tt> first check to see that none of the copy operations would cause an
overwrite. If it would, it will fail. Otherwise it will proceed as if it was in
<tt class="docutils literal">always_replace_files</tt> mode. Note that there is an inherent race condition here.
If the files in the target directory appear after the check but before the copy
or move completes, they will be overwritten. When failing because of files already
existing in the target path, the <tt class="docutils literal">error</tt> of <tt class="docutils literal">move_storage_failed_alert</tt> is set
to <tt class="docutils literal"><span class="pre">boost::system::errc::file_exists</span></tt>.</p>
<p>The intention is that a client may use this as a probe, and if it fails, ask the user
which mode to use. The client may then re-issue the <tt class="docutils literal">move_storage</tt> call with one
of the other modes.</p>
<p><tt class="docutils literal">dont_replace</tt> always takes the existing file in the target directory, if there is
one. The source files will still be removed in that case.</p>
<p>Files that have been renamed to have absolute pahts are not moved by this function.
Keep in mind that files that don't belong to the torrent but are stored in the torrent's
directory may be moved as well. This goes for files that have been renamed to
absolute paths that still end up inside the save path.</p>
</div>
<div class="section" id="id4">
<h2>rename_file()</h2>
@ -2584,17 +2604,6 @@ will throw <a class="reference internal" href="#libtorrent-exception">libtorrent
the source mask of this peer. Typically this is one of the source flags in <a class="reference internal" href="#peer-info">peer_info</a>.
i.e. <tt class="docutils literal">tracker</tt>, <tt class="docutils literal">pex</tt>, <tt class="docutils literal">dht</tt> etc.</p>
</div>
<div class="section" id="name">
<h2>name()</h2>
<blockquote>
<pre class="literal-block">
std::string name() const;
</pre>
</blockquote>
<p>Returns the name of the torrent. i.e. the name from the metadata associated with it. In
case the torrent was started without metadata, and hasn't completely received it yet,
it returns the name given to it when added to the session. See <tt class="docutils literal"><span class="pre">session::add_torrent</span></tt>.</p>
</div>
<div class="section" id="set-upload-limit-set-download-limit-upload-limit-download-limit">
<h2>set_upload_limit() set_download_limit() upload_limit() download_limit()</h2>
<blockquote>
@ -2608,7 +2617,7 @@ int download_limit() const;
<p><tt class="docutils literal">set_upload_limit</tt> will limit the upload bandwidth used by this particular torrent to the
limit you set. It is given as the number of bytes per second the torrent is allowed to upload.
<tt class="docutils literal">set_download_limit</tt> works the same way but for download bandwidth instead of upload bandwidth.
Note that setting a higher limit on a torrent then the global limit (<tt class="docutils literal"><span class="pre">session::set_upload_rate_limit</span></tt>)
Note that setting a higher limit on a torrent then the global limit (<tt class="docutils literal"><span class="pre">session_settings::upload_rate_limit</span></tt>)
will not override the global rate limit. The torrent can never upload more than the global rate
limit.</p>
<p><tt class="docutils literal">upload_limit</tt> and <tt class="docutils literal">download_limit</tt> will return the current limit setting, for upload and
@ -2907,7 +2916,9 @@ int max_uploads() const;
</pre>
</blockquote>
<p><tt class="docutils literal">set_max_uploads()</tt> sets the maximum number of peers that's unchoked at the same time on this
torrent. If you set this to -1, there will be no limit.</p>
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 <tt class="docutils literal">unchoke_slots_limit</tt>
in <a class="reference internal" href="#session-settings">session_settings</a>.</p>
<p><tt class="docutils literal">max_uploads()</tt> returns the current settings.</p>
</div>
<div class="section" id="set-max-connections-max-connections">
@ -2921,7 +2932,8 @@ int max_connections() const;
<p><tt class="docutils literal">set_max_connections()</tt> sets the maximum number of connection this torrent will open. If all
connections are used up, incoming connections may be refused or poor connections may be closed.
This must be at least 2. The default is unlimited number of connections. If -1 is given to the
function, it means unlimited.</p>
function, it means unlimited. There is also a global limit of the number of connections, set
by <tt class="docutils literal">connections_limit</tt> in <a class="reference internal" href="#session-settings">session_settings</a>.</p>
<p><tt class="docutils literal">max_connections()</tt> returns the current settings.</p>
</div>
<div class="section" id="save-resume-data">
@ -3028,7 +3040,9 @@ while (outstanding_resume_data &gt; 0)
}
torrent_handle h = rd-&gt;handle;
std::ofstream out((h.save_path() + &quot;/&quot; + h.torrent_file()-&gt;name() + &quot;.fastresume&quot;).c_str()
torrent_status st = h.status(torrent_handle::query_save_path | torrent_handle::query_name);
std::ofstream out((st.save_path
+ &quot;/&quot; + st.name + &quot;.fastresume&quot;).c_str()
, std::ios_base::binary);
out.unsetf(std::ios_base::skipws);
bencode(std::ostream_iterator&lt;char&gt;(out), *rd-&gt;resume_data);
@ -3107,6 +3121,26 @@ if you're not interested in it (and see performance issues), you can filter them
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt><tt class="docutils literal">query_torrent_file</tt></dt>
<dd><p class="first last">includes <tt class="docutils literal">torrent_file</tt>, which is all the static information from the .torrent file.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt><tt class="docutils literal">query_name</tt></dt>
<dd><p class="first last">includes <tt class="docutils literal">name</tt>, the name of the torrent. This is either derived from the .torrent
file, or from the <tt class="docutils literal">&amp;dn=</tt> magnet link argument or possibly some other source. If the
name of the torrent is not known, this is an empty string.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt><tt class="docutils literal">query_save_path</tt></dt>
<dd><p class="first last">includes <tt class="docutils literal">save_path</tt>, the path to the directory the files of the torrent are saved to.</p>
</dd>
</dl>
</li>
</ul>
</div>
<div class="section" id="get-download-queue">
@ -3278,6 +3312,10 @@ struct torrent_status
float progress;
int progress_ppm;
std::string error;
std::string save_path;
std::string name;
boost::intrusive_ptr&lt;const torrent_info&gt; torrent_file;
boost::posix_time::time_duration next_announce;
boost::posix_time::time_duration announce_interval;
@ -3451,6 +3489,16 @@ ip, a magnet link for instance).</p>
<p><tt class="docutils literal">error</tt> may be set to an error message describing why the torrent was paused, in
case it was paused by an error. If the torrent is not paused or if it's paused but
not because of an error, this string is empty.</p>
<p><tt class="docutils literal">save_path</tt> is the path to the directory where this torrent's files are stored.
It's typically the path as was given to <a class="reference internal" href="#async-add-torrent-add-torrent">async_add_torrent() add_torrent()</a> when this torrent
was started. This field is only included if the torrent status is queried with
<tt class="docutils literal"><span class="pre">torrent_handle::query_save_path</span></tt>.</p>
<p><tt class="docutils literal">name</tt> is the name of the torrent. Typically this is derived from the .torrent file.
In case the torrent was started without metadata, and hasn't completely received it yet,
it returns the name given to it when added to the session. See <tt class="docutils literal"><span class="pre">session::add_torrent</span></tt>.
This field is only included if the torrent status is queried with <tt class="docutils literal"><span class="pre">torrent_handle::query_name</span></tt>.</p>
<p><tt class="docutils literal">torrent_file</tt> is set to point to the <tt class="docutils literal">torrent_info</tt> object for this torrent. It's
only included if the torrent status is queried with <tt class="docutils literal"><span class="pre">torrent_handle::query_torrent_file</span></tt>.</p>
<p><tt class="docutils literal">next_announce</tt> is the time until the torrent will announce itself to the tracker. And
<tt class="docutils literal">announce_interval</tt> is the time the tracker want us to wait until we announce ourself
again the next time.</p>
@ -4281,7 +4329,7 @@ struct session_settings
int write_cache_line_size;
int optimistic_disk_retry;
bool disable_hash_check;
bool disable_hash_checks;
int max_suggest_pieces;
@ -4294,7 +4342,7 @@ struct session_settings
int udp_tracker_token_expiry;
bool volatile_read_cache;
bool guided_read_cache;
bool default_min_cache_age;
bool default_cache_min_age;
int num_optimistic_unchoke_slots;
bool no_atime_storage;
@ -4315,6 +4363,7 @@ struct session_settings
bool ignore_resume_timestamps;
bool no_recheck_incomplete_resume;
bool anonymous_mode;
bool force_proxy;
int tick_interval;
int share_mode_target;
@ -4368,6 +4417,12 @@ struct session_settings
bool ban_web_seeds;
int max_http_recv_buffer_size;
bool support_share_mode;
bool support_merkle_torrents;
bool report_redundant_bytes;
std::string handshake_client_version;
bool use_disk_cache_pool;
};
</pre>
<p><tt class="docutils literal">version</tt> is automatically set to the libtorrent version you're using
@ -4560,7 +4615,7 @@ reciprocation rate of each peer individually and prefers peers that gives
the highest <em>return on investment</em>. It still allocates all upload capacity,
but shuffles it around to the best peers first. For this choker to be
efficient, you need to set a global upload rate limit
(<tt class="docutils literal"><span class="pre">session::set_upload_rate_limit()</span></tt>). For more information about this
(<tt class="docutils literal"><span class="pre">session_settings::upload_rate_limit</span></tt>). For more information about this
choker, see the <a class="reference external" href="http://bittyrant.cs.washington.edu/#papers">paper</a>.</li>
</ul>
<p><tt class="docutils literal">seed_choking_algorithm</tt> controls the seeding unchoke behavior. The available
@ -4830,7 +4885,7 @@ 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>You can explicitly take a torrent out of upload only mode using
<a class="reference internal" href="#set-upload-mode">set_upload_mode()</a>.</p>
<p><tt class="docutils literal">disable_hash_check</tt> controls if downloaded pieces are verified against
<p><tt class="docutils literal">disable_hash_checks</tt> controls if downloaded pieces are verified against
the piece hashes in the torrent file or not. The default is false, i.e.
to verify all downloaded data. It may be useful to turn this off for performance
profiling and simulation scenarios. Do not disable the hash check for regular
@ -4878,7 +4933,7 @@ of a cache line generated by peers to depend on the upload rate
you are sending to that peer. The intention is to optimize the RAM
usage of the cache, to read ahead further for peers that you're
sending faster to.</p>
<p><tt class="docutils literal">default_min_cache_age</tt> is the minimum number of seconds any read
<p><tt class="docutils literal">default_cache_min_age</tt> is the minimum number of seconds any read
cache line is kept in the cache. This defaults to one second but
may be greater if <tt class="docutils literal">guided_read_cache</tt> is enabled. Having a lower
bound on the time a cache line stays in the cache is an attempt
@ -4953,13 +5008,15 @@ mode.</p>
<p><tt class="docutils literal">anonymous_mode</tt> defaults to false. When set to true, the client tries
to hide its identity to a certain degree. The peer-ID will no longer
include the client's fingerprint. The user-agent will be reset to an
empty string. Trackers will only be used if they are using a proxy
server. The listen sockets are closed, and incoming connections will
empty string.</p>
<p>If you're using I2P, it might make sense to enable anonymous mode.</p>
<p><tt class="docutils literal">force_proxy</tt> disables any communication that's not going over a proxy.
Enabling this requires a proxy to be configured as well, see <tt class="docutils literal">set_proxy_settings</tt>.
The listen sockets are closed, and incoming connections will
only be accepted through a SOCKS5 or I2P proxy (if a peer proxy is set up and
is run on the same machine as the tracker proxy). Since no incoming connections
are accepted, NAT-PMP, UPnP, DHT and local peer discovery are all turned off
when this setting is enabled.</p>
<p>If you're using I2P, it might make sense to enable anonymous mode as well.</p>
is run on the same machine as the tracker proxy). This setting also
disabled peer country lookups, since those are done via DNS lookups that
aren't supported by proxies.</p>
<p><tt class="docutils literal">tick_interval</tt> specifies the number of milliseconds between internal
ticks. This is the frequency with which bandwidth quota is distributed to
peers. It should not be more than one second (i.e. 1000 ms). Setting this
@ -4986,7 +5043,7 @@ quite unthrottled.</p>
<p><tt class="docutils literal">dht_upload_rate_limit</tt> sets the rate limit on the DHT. This is specified in
bytes per second and defaults to 4000. For busy boxes with lots of torrents
that requires more DHT traffic, this should be raised.</p>
<p><tt class="docutils literal">unchoke_slots_limit</tt> is the mac number of unchoked peers in the session.</p>
<p><tt class="docutils literal">unchoke_slots_limit</tt> is the max number of unchoked peers in the session.</p>
<p>The number of unchoke slots may be ignored depending on what
<tt class="docutils literal">choking_algorithm</tt> is set to.</p>
<p><tt class="docutils literal">half_open_limit</tt> sets the maximum number of half-open connections
@ -5115,6 +5172,18 @@ corrupt data are banned.</p>
RAM buffers when downloading stuff over HTTP. Specifically when specifying a
URL to a .torrent file when adding a torrent or when announcing to an HTTP
tracker. The default is 2 MiB.</p>
<p><tt class="docutils literal">support_share_mode</tt> enables or disables the share mode extension. This is
enabled by default.</p>
<p><tt class="docutils literal">support_merkle_torrents</tt> enables or disables the merkle tree torrent support.
This is enabled by default.</p>
<p><tt class="docutils literal">report_redundant_bytes</tt> enables or disables reporting redundant bytes to the tracker.
This is enabled by default.</p>
<p><tt class="docutils literal">handshake_client_version</tt> is the client name advertized in the peer handshake. If
set to an empty string, the user_agent string is used.</p>
<p><tt class="docutils literal">use_disk_cache_pool</tt> enables using a pool allocator for disk cache blocks. This is
disabled by default. Enabling it makes the cache perform better at high throughput.
It also makes the cache less likely and slower at returning memory back to the system
once allocated.</p>
</div>
</div>
<div class="section" id="pe-settings">
@ -5824,6 +5893,7 @@ public:
performance_warning = <em>implementation defined</em>,
dht_notification = <em>implementation defined</em>,
stats_notification = <em>implementation defined</em>,
rss_notification = <em>implementation defined</em>,
all_categories = <em>implementation defined</em>
};
@ -5852,6 +5922,10 @@ switch (a-&gt;type())
case read_piece_alert::alert_type:
{
read_piece_alert* p = (read_piece_alert*)a.get();
if (p-&gt;ec) {
// read_piece failed
break;
}
// use p
break;
}
@ -5950,10 +6024,12 @@ is paused and an error state is set and the buffer member of the alert
is 0. If successful, <tt class="docutils literal">buffer</tt> points to a buffer containing all the data
of the piece. <tt class="docutils literal">piece</tt> is the piece index that was read. <tt class="docutils literal">size</tt> is the
number of bytes that was read.</p>
<p>If the operation fails, ec will indicat what went wrong.</p>
<pre class="literal-block">
struct read_piece_alert: torrent_alert
{
// ...
error_code ec;
boost::shared_ptr&lt;char&gt; buffer;
int piece;
int size;
@ -6170,8 +6246,9 @@ struct tracker_reply_alert: tracker_alert
int num_peers;
};
</pre>
<p>The <tt class="docutils literal">num_peers</tt> tells how many peers were returned from the tracker. This is
not necessarily all new peers, some of them may already be connected.</p>
<p>The <tt class="docutils literal">num_peers</tt> tells how many peers the tracker returned in this response. This is
not expected to be more thant the <tt class="docutils literal">num_want</tt> settings. These are not necessarily
all new peers, some of them may already be connected.</p>
</div>
<div class="section" id="tracker-warning-alert">
<h2>tracker_warning_alert</h2>
@ -6605,7 +6682,7 @@ if (h.is_valid()) {
entry te = ct.generate();
std::vector&lt;char&gt; buffer;
bencode(std::back_inserter(buffer), te);
FILE* f = fopen((to_hex(ti-&gt;info_hash().to_string()) + &quot;.torrent&quot;).c_str(), &quot;w+&quot;);
FILE* f = fopen((to_hex(ti-&gt;info_hash().to_string()) + &quot;.torrent&quot;).c_str(), &quot;wb+&quot;);
if (f) {
fwrite(&amp;buffer[0], 1, buffer.size(), f);
fclose(f);
@ -6628,8 +6705,16 @@ struct fastresume_rejected_alert: torrent_alert
</div>
<div class="section" id="peer-blocked-alert">
<h2>peer_blocked_alert</h2>
<p>This alert is generated when a peer is blocked by the IP filter. The <tt class="docutils literal">ip</tt> member is the
address that was blocked.</p>
<p>This alert is posted when an incoming peer connection, or a peer that's about to be added
to our peer list, is blocked for some reason. This could be any of:</p>
<ul class="simple">
<li>the IP filter</li>
<li>i2p mixed mode restrictions (a normal peer is not allowed on an i2p swarm)</li>
<li>the port filter</li>
<li>the peer has a low port and <tt class="docutils literal">no_connect_privileged_ports</tt> is enabled</li>
<li>the protocol of the peer is blocked (uTP/TCP blocking)</li>
</ul>
<p>The <tt class="docutils literal">ip</tt> member is the address that was blocked.</p>
<pre class="literal-block">
struct peer_blocked_alert: torrent_alert
{
@ -6878,6 +6963,23 @@ what went wrong.</dd>
</dl>
<p><tt class="docutils literal">error</tt> is an error code used for when an error occurs on the feed.</p>
</div>
<div class="section" id="rss-item-alert">
<h2>rss_item_alert</h2>
<p>This alert is posted every time a new RSS item (i.e. torrent) is received
from an RSS feed.</p>
<p>It is only posted if the <tt class="docutils literal">rss_notifications</tt> category is enabled in the
alert mask.</p>
<pre class="literal-block">
struct rss_alert : alert
{
// ...
virtual std::string message() const;
feed_handle handle;
feed_item item;
};
</pre>
</div>
<div class="section" id="incoming-connection-alert">
<h2>incoming_connection_alert</h2>
<p>The incoming connection alert is posted every time we successfully accept
@ -6961,6 +7063,23 @@ this message was posted. Note that you can map a torrent status to a specific to
via its <tt class="docutils literal">handle</tt> member. The receiving end is suggested to have all torrents sorted
by the <tt class="docutils literal">torrent_handle</tt> or hashed by it, for efficient updates.</p>
</div>
<div class="section" id="torrent-update-alert">
<h2>torrent_update_alert</h2>
<p>When a torrent changes its info-hash, this alert is posted. This only happens in very
specific cases. For instance, when a torrent is downloaded from a URL, the true info
hash is not known immediately. First the .torrent file must be downloaded and parsed.</p>
<p>Once this download completes, the <tt class="docutils literal">torrent_update_alert</tt> is posted to notify the client
of the info-hash changing.</p>
<pre class="literal-block">
struct torrent_update_alert: torrent_alert
{
// ...
sha1_hash old_ih;
sha1_hash new_ih;
};
</pre>
<p><tt class="docutils literal">old_ih</tt> and <tt class="docutils literal">new_ih</tt> are the previous and new info-hash for the torrent, respectively.</p>
</div>
</div>
<div class="section" id="alert-dispatcher">
<h1>alert dispatcher</h1>
@ -9012,6 +9131,12 @@ the pem file to include in the .torrent file.</p>
<p>The peer's certificate is located in <tt class="docutils literal">./newcert.pem</tt> and the certificate's
private key in <tt class="docutils literal">./newkey.pem</tt>.</p>
</div>
</div>
<div class="system-messages section">
<h1>Docutils System Messages</h1>
<div class="system-message" id="id46">
<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">manual.rst</tt>, line 1901); <em><a href="#id47">backlink</a></em></p>
Unknown target name: &quot;move_storage&quot;.</div>
</div>
</div>
<div id="footer">