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"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <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> <title>libtorrent API Documentation</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" /> <meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" /> <link rel="stylesheet" type="text/css" href="../../css/base.css" />
@ -248,22 +248,6 @@ class session: public boost::noncopyable
session_settings settings() const; session_settings settings() const;
void set_pe_settings(pe_settings const&amp; settings); 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); void set_proxy(proxy_settings const&amp; s);
proxy_settings proxy() const; proxy_settings proxy() const;
@ -303,9 +287,9 @@ class session: public boost::noncopyable
size_t queue_size_limit_); size_t queue_size_limit_);
void set_alert_dispatch(boost::function&lt;void(std::auto_ptr&lt;alert&gt;)&gt; const&amp; fun); 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); feed_handle add_feed(feed_settings const&amp; feed);
void session::remove_feed(feed_handle h); void remove_feed(feed_handle h);
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;
void add_extension(boost::function&lt; void add_extension(boost::function&lt;
boost::shared_ptr&lt;torrent_plugin&gt;(torrent*)&gt; ext); 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>) 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 will indicate what went wrong. The <tt class="docutils literal">url</tt> may refer to a magnet link or a regular
http URL.</p> 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 <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> 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 <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> 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. <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 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. 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 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 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> <h2>add_feed()</h2>
<blockquote> <blockquote>
<pre class="literal-block"> <pre class="literal-block">
feed_handle session::add_feed(feed_settings const&amp; feed); feed_handle add_feed(feed_settings const&amp; feed);
</pre> </pre>
</blockquote> </blockquote>
<p>This adds an RSS feed to the session. The feed will be refreshed <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> <h2>remove_feed()</h2>
<blockquote> <blockquote>
<pre class="literal-block"> <pre class="literal-block">
void session::remove_feed(feed_handle h); void remove_feed(feed_handle h);
</pre> </pre>
</blockquote> </blockquote>
<p>Removes a feed from being watched by the session. When this <p>Removes a feed from being watched by the session. When this
@ -1236,7 +1224,7 @@ to any feed.</p>
<h2>get_feeds()</h2> <h2>get_feeds()</h2>
<blockquote> <blockquote>
<pre class="literal-block"> <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> </pre>
</blockquote> </blockquote>
<p>Returns a list of all RSS feeds that are being watched by the session.</p> <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 <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 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> 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>
<div class="section" id="begin-files-end-files-rbegin-files-rend-files"> <div class="section" id="begin-files-end-files-rbegin-files-rend-files">
<h2>begin_files() end_files() rbegin_files() rend_files()</h2> <h2>begin_files() end_files() rbegin_files() rend_files()</h2>
@ -1999,6 +1992,10 @@ struct announce_entry
int next_announce_in() const; int next_announce_in() const;
int min_announce_in() const; int min_announce_in() const;
int scrape_incomplete;
int scrape_complete;
int scrape_downloaded;
error_code last_error; error_code last_error;
std::string message; 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> allowed to force another tracker update with this tracker.</p>
<p>If the last time this tracker was contacted failed, <tt class="docutils literal">last_error</tt> is the error <p>If the last time this tracker was contacted failed, <tt class="docutils literal">last_error</tt> is the error
code describing what error occurred.</p> code describing what error occurred.</p>
<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 <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> 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 <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_accurate_download_counters = 2,
query_last_seen_complete = 4, query_last_seen_complete = 4,
query_pieces = 8, 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); 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; boost::intrusive_ptr&lt;torrent_info&gt; torrent_file() const;
bool is_valid() const; bool is_valid() const;
std::string name() const;
enum save_resume_flags_t { flush_disk_cache = 1, save_info_dict = 2 }; enum save_resume_flags_t { flush_disk_cache = 1, save_info_dict = 2 };
void save_resume_data(int flags = 0) const; void save_resume_data(int flags = 0) const;
bool need_save_resume_data() const; bool need_save_resume_data() const;
@ -2270,9 +2274,8 @@ struct torrent_handle
bool set_metadata(char const* buf, int size) const; bool set_metadata(char const* buf, int size) const;
std::string save_path() const; void move_storage(std::string const&amp; save_path, int flags = 0) const;
void move_storage(std::string const&amp; save_path) const; void move_storage(std::wstring const&amp; save_path, int flags = 0) const;
void move_storage(std::wstring const&amp; save_path) const;
void rename_file(int index, std::string) const; void rename_file(int index, std::string) const;
void rename_file(int index, std::wstring) const; void rename_file(int index, std::wstring) const;
storage_interface* get_storage_impl() 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 the operation is a lot cheaper, since libtorrent already keeps track of this internally
and no calculation is required.</p> and no calculation is required.</p>
</div> </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"> <div class="section" id="move-storage">
<h2>move_storage()</h2> <h2>move_storage()</h2>
<blockquote> <blockquote>
<pre class="literal-block"> <pre class="literal-block">
void move_storage(std::string 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) const; void move_storage(std::wstring const&amp; save_path, int flags = 0) const;
</pre> </pre>
</blockquote> </blockquote>
<p>Moves the file(s) that this torrent are currently seeding from or downloading to. If <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 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 This will block all other disk IO, and other torrents download and upload rates may
drop while copying the file.</p> drop while copying the file.</p>
<p>Since disk IO is performed in a separate thread, this operation is also asynchronous. <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 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> 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> 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>
<div class="section" id="id4"> <div class="section" id="id4">
<h2>rename_file()</h2> <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>. 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> i.e. <tt class="docutils literal">tracker</tt>, <tt class="docutils literal">pex</tt>, <tt class="docutils literal">dht</tt> etc.</p>
</div> </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"> <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> <h2>set_upload_limit() set_download_limit() upload_limit() download_limit()</h2>
<blockquote> <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 <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. 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. <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 will not override the global rate limit. The torrent can never upload more than the global rate
limit.</p> 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 <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> </pre>
</blockquote> </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 <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> <p><tt class="docutils literal">max_uploads()</tt> returns the current settings.</p>
</div> </div>
<div class="section" id="set-max-connections-max-connections"> <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 <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. 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 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> <p><tt class="docutils literal">max_connections()</tt> returns the current settings.</p>
</div> </div>
<div class="section" id="save-resume-data"> <div class="section" id="save-resume-data">
@ -3028,7 +3040,9 @@ while (outstanding_resume_data &gt; 0)
} }
torrent_handle h = rd-&gt;handle; 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); , std::ios_base::binary);
out.unsetf(std::ios_base::skipws); out.unsetf(std::ios_base::skipws);
bencode(std::ostream_iterator&lt;char&gt;(out), *rd-&gt;resume_data); 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> </dd>
</dl> </dl>
</li> </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> </ul>
</div> </div>
<div class="section" id="get-download-queue"> <div class="section" id="get-download-queue">
@ -3278,6 +3312,10 @@ struct torrent_status
float progress; float progress;
int progress_ppm; int progress_ppm;
std::string error; 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 next_announce;
boost::posix_time::time_duration announce_interval; 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 <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 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> 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 <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 <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> again the next time.</p>
@ -4281,7 +4329,7 @@ struct session_settings
int write_cache_line_size; int write_cache_line_size;
int optimistic_disk_retry; int optimistic_disk_retry;
bool disable_hash_check; bool disable_hash_checks;
int max_suggest_pieces; int max_suggest_pieces;
@ -4294,7 +4342,7 @@ struct session_settings
int udp_tracker_token_expiry; int udp_tracker_token_expiry;
bool volatile_read_cache; bool volatile_read_cache;
bool guided_read_cache; bool guided_read_cache;
bool default_min_cache_age; bool default_cache_min_age;
int num_optimistic_unchoke_slots; int num_optimistic_unchoke_slots;
bool no_atime_storage; bool no_atime_storage;
@ -4315,6 +4363,7 @@ struct session_settings
bool ignore_resume_timestamps; bool ignore_resume_timestamps;
bool no_recheck_incomplete_resume; bool no_recheck_incomplete_resume;
bool anonymous_mode; bool anonymous_mode;
bool force_proxy;
int tick_interval; int tick_interval;
int share_mode_target; int share_mode_target;
@ -4368,6 +4417,12 @@ struct session_settings
bool ban_web_seeds; bool ban_web_seeds;
int max_http_recv_buffer_size; 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> </pre>
<p><tt class="docutils literal">version</tt> is automatically set to the libtorrent version you're using <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, 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 but shuffles it around to the best peers first. For this choker to be
efficient, you need to set a global upload rate limit 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> choker, see the <a class="reference external" href="http://bittyrant.cs.washington.edu/#papers">paper</a>.</li>
</ul> </ul>
<p><tt class="docutils literal">seed_choking_algorithm</tt> controls the seeding unchoke behavior. The available <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>libtorrent will only do this automatically for auto managed torrents.</p>
<p>You can explicitly take a torrent out of upload only mode using <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> <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. 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 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 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 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 usage of the cache, to read ahead further for peers that you're
sending faster to.</p> 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 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 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 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 <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 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 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 empty string.</p>
server. The listen sockets are closed, and incoming connections will <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 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 is run on the same machine as the tracker proxy). This setting also
are accepted, NAT-PMP, UPnP, DHT and local peer discovery are all turned off disabled peer country lookups, since those are done via DNS lookups that
when this setting is enabled.</p> aren't supported by proxies.</p>
<p>If you're using I2P, it might make sense to enable anonymous mode as well.</p>
<p><tt class="docutils literal">tick_interval</tt> specifies the number of milliseconds between internal <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 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 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 <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 bytes per second and defaults to 4000. For busy boxes with lots of torrents
that requires more DHT traffic, this should be raised.</p> 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 <p>The number of unchoke slots may be ignored depending on what
<tt class="docutils literal">choking_algorithm</tt> is set to.</p> <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 <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 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 URL to a .torrent file when adding a torrent or when announcing to an HTTP
tracker. The default is 2 MiB.</p> 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> </div>
<div class="section" id="pe-settings"> <div class="section" id="pe-settings">
@ -5824,6 +5893,7 @@ public:
performance_warning = <em>implementation defined</em>, performance_warning = <em>implementation defined</em>,
dht_notification = <em>implementation defined</em>, dht_notification = <em>implementation defined</em>,
stats_notification = <em>implementation defined</em>, stats_notification = <em>implementation defined</em>,
rss_notification = <em>implementation defined</em>,
all_categories = <em>implementation defined</em> all_categories = <em>implementation defined</em>
}; };
@ -5852,6 +5922,10 @@ switch (a-&gt;type())
case read_piece_alert::alert_type: case read_piece_alert::alert_type:
{ {
read_piece_alert* p = (read_piece_alert*)a.get(); read_piece_alert* p = (read_piece_alert*)a.get();
if (p-&gt;ec) {
// read_piece failed
break;
}
// use p // use p
break; 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 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 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> number of bytes that was read.</p>
<p>If the operation fails, ec will indicat what went wrong.</p>
<pre class="literal-block"> <pre class="literal-block">
struct read_piece_alert: torrent_alert struct read_piece_alert: torrent_alert
{ {
// ... // ...
error_code ec;
boost::shared_ptr&lt;char&gt; buffer; boost::shared_ptr&lt;char&gt; buffer;
int piece; int piece;
int size; int size;
@ -6170,8 +6246,9 @@ struct tracker_reply_alert: tracker_alert
int num_peers; int num_peers;
}; };
</pre> </pre>
<p>The <tt class="docutils literal">num_peers</tt> tells how many peers were returned from the tracker. This is <p>The <tt class="docutils literal">num_peers</tt> tells how many peers the tracker returned in this response. This is
not necessarily all new peers, some of them may already be connected.</p> 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>
<div class="section" id="tracker-warning-alert"> <div class="section" id="tracker-warning-alert">
<h2>tracker_warning_alert</h2> <h2>tracker_warning_alert</h2>
@ -6605,7 +6682,7 @@ if (h.is_valid()) {
entry te = ct.generate(); entry te = ct.generate();
std::vector&lt;char&gt; buffer; std::vector&lt;char&gt; buffer;
bencode(std::back_inserter(buffer), te); 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) { if (f) {
fwrite(&amp;buffer[0], 1, buffer.size(), f); fwrite(&amp;buffer[0], 1, buffer.size(), f);
fclose(f); fclose(f);
@ -6628,8 +6705,16 @@ struct fastresume_rejected_alert: torrent_alert
</div> </div>
<div class="section" id="peer-blocked-alert"> <div class="section" id="peer-blocked-alert">
<h2>peer_blocked_alert</h2> <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 <p>This alert is posted when an incoming peer connection, or a peer that's about to be added
address that was blocked.</p> 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"> <pre class="literal-block">
struct peer_blocked_alert: torrent_alert struct peer_blocked_alert: torrent_alert
{ {
@ -6878,6 +6963,23 @@ what went wrong.</dd>
</dl> </dl>
<p><tt class="docutils literal">error</tt> is an error code used for when an error occurs on the feed.</p> <p><tt class="docutils literal">error</tt> is an error code used for when an error occurs on the feed.</p>
</div> </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"> <div class="section" id="incoming-connection-alert">
<h2>incoming_connection_alert</h2> <h2>incoming_connection_alert</h2>
<p>The incoming connection alert is posted every time we successfully accept <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 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> by the <tt class="docutils literal">torrent_handle</tt> or hashed by it, for efficient updates.</p>
</div> </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>
<div class="section" id="alert-dispatcher"> <div class="section" id="alert-dispatcher">
<h1>alert dispatcher</h1> <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 <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> private key in <tt class="docutils literal">./newkey.pem</tt>.</p>
</div> </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> </div>
<div id="footer"> <div id="footer">