jiigen666/libtorrent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

initial support for queuing

Browse Source
This commit is contained in:
Arvid Norberg
2008-04-24 03:28:48 +00:00
parent fc7dd2c5eb
commit c043d4b21d
14 changed files with 912 additions and 521 deletions
Download Patch File Download Diff File Expand all files Collapse all files

373
docs/manual.html
View File

@@ -98,118 +98,124 @@
<li><a class="reference internal" href="#pause-resume-is-paused" id="id82">pause() resume() is_paused()</a></li>
<li><a class="reference internal" href="#resolve-countries" id="id83">resolve_countries()</a></li>
<li><a class="reference internal" href="#is-seed" id="id84">is_seed()</a></li>
<li><a class="reference internal" href="#has-metadata" id="id85">has_metadata()</a></li>
<li><a class="reference internal" href="#set-tracker-login" id="id86">set_tracker_login()</a></li>
<li><a class="reference internal" href="#trackers-replace-trackers" id="id87">trackers() replace_trackers()</a></li>
<li><a class="reference internal" href="#add-url-seed-remove-url-seed-url-seeds" id="id88">add_url_seed() remove_url_seed() url_seeds()</a></li>
<li><a class="reference internal" href="#use-interface" id="id89">use_interface()</a></li>
<li><a class="reference internal" href="#info-hash" id="id90">info_hash()</a></li>
<li><a class="reference internal" href="#id5" id="id91">set_max_uploads() set_max_connections()</a></li>
<li><a class="reference internal" href="#save-resume-data" id="id92">save_resume_data()</a></li>
<li><a class="reference internal" href="#id6" id="id93">status()</a></li>
<li><a class="reference internal" href="#get-download-queue" id="id94">get_download_queue()</a></li>
<li><a class="reference internal" href="#get-peer-info" id="id95">get_peer_info()</a></li>
<li><a class="reference internal" href="#get-torrent-info" id="id96">get_torrent_info()</a></li>
<li><a class="reference internal" href="#is-valid" id="id97">is_valid()</a></li>
<li><a class="reference internal" href="#is-auto-managed-auto-managed" id="id85">is_auto_managed() auto_managed()</a></li>
<li><a class="reference internal" href="#has-metadata" id="id86">has_metadata()</a></li>
<li><a class="reference internal" href="#set-tracker-login" id="id87">set_tracker_login()</a></li>
<li><a class="reference internal" href="#trackers-replace-trackers" id="id88">trackers() replace_trackers()</a></li>
<li><a class="reference internal" href="#add-url-seed-remove-url-seed-url-seeds" id="id89">add_url_seed() remove_url_seed() url_seeds()</a></li>
<li><a class="reference internal" href="#use-interface" id="id90">use_interface()</a></li>
<li><a class="reference internal" href="#info-hash" id="id91">info_hash()</a></li>
<li><a class="reference internal" href="#id5" id="id92">set_max_uploads() set_max_connections()</a></li>
<li><a class="reference internal" href="#save-resume-data" id="id93">save_resume_data()</a></li>
<li><a class="reference internal" href="#id6" id="id94">status()</a></li>
<li><a class="reference internal" href="#get-download-queue" id="id95">get_download_queue()</a></li>
<li><a class="reference internal" href="#get-peer-info" id="id96">get_peer_info()</a></li>
<li><a class="reference internal" href="#get-torrent-info" id="id97">get_torrent_info()</a></li>
<li><a class="reference internal" href="#is-valid" id="id98">is_valid()</a></li>
</ul>
</li>
<li><a class="reference internal" href="#torrent-status" id="id98">torrent_status</a></li>
<li><a class="reference internal" href="#peer-info" id="id99">peer_info</a></li>
<li><a class="reference internal" href="#session-settings" id="id100">session_settings</a></li>
<li><a class="reference internal" href="#pe-settings" id="id101">pe_settings</a></li>
<li><a class="reference internal" href="#proxy-settings" id="id102">proxy_settings</a></li>
<li><a class="reference internal" href="#ip-filter" id="id103">ip_filter</a><ul>
<li><a class="reference internal" href="#id9" id="id104">ip_filter()</a></li>
<li><a class="reference internal" href="#add-rule" id="id105">add_rule()</a></li>
<li><a class="reference internal" href="#access" id="id106">access()</a></li>
<li><a class="reference internal" href="#export-filter" id="id107">export_filter()</a></li>
<li><a class="reference internal" href="#torrent-status" id="id99">torrent_status</a></li>
<li><a class="reference internal" href="#peer-info" id="id100">peer_info</a></li>
<li><a class="reference internal" href="#session-settings" id="id101">session_settings</a></li>
<li><a class="reference internal" href="#pe-settings" id="id102">pe_settings</a></li>
<li><a class="reference internal" href="#proxy-settings" id="id103">proxy_settings</a></li>
<li><a class="reference internal" href="#ip-filter" id="id104">ip_filter</a><ul>
<li><a class="reference internal" href="#id9" id="id105">ip_filter()</a></li>
<li><a class="reference internal" href="#add-rule" id="id106">add_rule()</a></li>
<li><a class="reference internal" href="#access" id="id107">access()</a></li>
<li><a class="reference internal" href="#export-filter" id="id108">export_filter()</a></li>
</ul>
</li>
<li><a class="reference internal" href="#big-number" id="id108">big_number</a></li>
<li><a class="reference internal" href="#hasher" id="id109">hasher</a></li>
<li><a class="reference internal" href="#fingerprint" id="id110">fingerprint</a></li>
<li><a class="reference internal" href="#upnp-and-nat-pmp" id="id111">UPnP and NAT-PMP</a><ul>
<li><a class="reference internal" href="#add-mapping" id="id112">add_mapping</a></li>
<li><a class="reference internal" href="#delete-mapping" id="id113">delete_mapping</a></li>
<li><a class="reference internal" href="#router-model" id="id114">router_model()</a></li>
<li><a class="reference internal" href="#big-number" id="id109">big_number</a></li>
<li><a class="reference internal" href="#hasher" id="id110">hasher</a></li>
<li><a class="reference internal" href="#fingerprint" id="id111">fingerprint</a></li>
<li><a class="reference internal" href="#upnp-and-nat-pmp" id="id112">UPnP and NAT-PMP</a><ul>
<li><a class="reference internal" href="#add-mapping" id="id113">add_mapping</a></li>
<li><a class="reference internal" href="#delete-mapping" id="id114">delete_mapping</a></li>
<li><a class="reference internal" href="#router-model" id="id115">router_model()</a></li>
</ul>
</li>
<li><a class="reference internal" href="#free-functions" id="id115">free functions</a><ul>
<li><a class="reference internal" href="#identify-client" id="id116">identify_client()</a></li>
<li><a class="reference internal" href="#client-fingerprint" id="id117">client_fingerprint()</a></li>
<li><a class="reference internal" href="#bdecode-bencode" id="id118">bdecode() bencode()</a></li>
<li><a class="reference internal" href="#free-functions" id="id116">free functions</a><ul>
<li><a class="reference internal" href="#identify-client" id="id117">identify_client()</a></li>
<li><a class="reference internal" href="#client-fingerprint" id="id118">client_fingerprint()</a></li>
<li><a class="reference internal" href="#bdecode-bencode" id="id119">bdecode() bencode()</a></li>
</ul>
</li>
<li><a class="reference internal" href="#alerts" id="id119">alerts</a><ul>
<li><a class="reference internal" href="#external-ip-alert" id="id120">external_ip_alert</a></li>
<li><a class="reference internal" href="#listen-failed-alert" id="id121">listen_failed_alert</a></li>
<li><a class="reference internal" href="#portmap-error-alert" id="id122">portmap_error_alert</a></li>
<li><a class="reference internal" href="#portmap-alert" id="id123">portmap_alert</a></li>
<li><a class="reference internal" href="#file-error-alert" id="id124">file_error_alert</a></li>
<li><a class="reference internal" href="#tracker-announce-alert" id="id125">tracker_announce_alert</a></li>
<li><a class="reference internal" href="#tracker-alert" id="id126">tracker_alert</a></li>
<li><a class="reference internal" href="#tracker-error-alert" id="id127">tracker_error_alert</a></li>
<li><a class="reference internal" href="#tracker-reply-alert" id="id128">tracker_reply_alert</a></li>
<li><a class="reference internal" href="#tracker-warning-alert" id="id129">tracker_warning_alert</a></li>
<li><a class="reference internal" href="#scrape-reply-alert" id="id130">scrape_reply_alert</a></li>
<li><a class="reference internal" href="#scrape-failed-alert" id="id131">scrape_failed_alert</a></li>
<li><a class="reference internal" href="#url-seed-alert" id="id132">url_seed_alert</a></li>
<li><a class="reference internal" href="#hash-failed-alert" id="id133">hash_failed_alert</a></li>
<li><a class="reference internal" href="#peer-ban-alert" id="id134">peer_ban_alert</a></li>
<li><a class="reference internal" href="#peer-error-alert" id="id135">peer_error_alert</a></li>
<li><a class="reference internal" href="#invalid-request-alert" id="id136">invalid_request_alert</a></li>
<li><a class="reference internal" href="#torrent-finished-alert" id="id137">torrent_finished_alert</a></li>
<li><a class="reference internal" href="#metadata-failed-alert" id="id138">metadata_failed_alert</a></li>
<li><a class="reference internal" href="#metadata-received-alert" id="id139">metadata_received_alert</a></li>
<li><a class="reference internal" href="#fastresume-rejected-alert" id="id140">fastresume_rejected_alert</a></li>
<li><a class="reference internal" href="#peer-blocked-alert" id="id141">peer_blocked_alert</a></li>
<li><a class="reference internal" href="#storage-moved-alert" id="id142">storage_moved_alert</a></li>
<li><a class="reference internal" href="#torrent-paused-alert" id="id143">torrent_paused_alert</a></li>
<li><a class="reference internal" href="#save-resume-data-alert" id="id144">save_resume_data_alert</a></li>
<li><a class="reference internal" href="#dispatcher" id="id145">dispatcher</a></li>
<li><a class="reference internal" href="#alerts" id="id120">alerts</a><ul>
<li><a class="reference internal" href="#external-ip-alert" id="id121">external_ip_alert</a></li>
<li><a class="reference internal" href="#listen-failed-alert" id="id122">listen_failed_alert</a></li>
<li><a class="reference internal" href="#portmap-error-alert" id="id123">portmap_error_alert</a></li>
<li><a class="reference internal" href="#portmap-alert" id="id124">portmap_alert</a></li>
<li><a class="reference internal" href="#file-error-alert" id="id125">file_error_alert</a></li>
<li><a class="reference internal" href="#tracker-announce-alert" id="id126">tracker_announce_alert</a></li>
<li><a class="reference internal" href="#tracker-alert" id="id127">tracker_alert</a></li>
<li><a class="reference internal" href="#tracker-error-alert" id="id128">tracker_error_alert</a></li>
<li><a class="reference internal" href="#tracker-reply-alert" id="id129">tracker_reply_alert</a></li>
<li><a class="reference internal" href="#tracker-warning-alert" id="id130">tracker_warning_alert</a></li>
<li><a class="reference internal" href="#scrape-reply-alert" id="id131">scrape_reply_alert</a></li>
<li><a class="reference internal" href="#scrape-failed-alert" id="id132">scrape_failed_alert</a></li>
<li><a class="reference internal" href="#url-seed-alert" id="id133">url_seed_alert</a></li>
<li><a class="reference internal" href="#hash-failed-alert" id="id134">hash_failed_alert</a></li>
<li><a class="reference internal" href="#peer-ban-alert" id="id135">peer_ban_alert</a></li>
<li><a class="reference internal" href="#peer-error-alert" id="id136">peer_error_alert</a></li>
<li><a class="reference internal" href="#invalid-request-alert" id="id137">invalid_request_alert</a></li>
<li><a class="reference internal" href="#torrent-finished-alert" id="id138">torrent_finished_alert</a></li>
<li><a class="reference internal" href="#metadata-failed-alert" id="id139">metadata_failed_alert</a></li>
<li><a class="reference internal" href="#metadata-received-alert" id="id140">metadata_received_alert</a></li>
<li><a class="reference internal" href="#fastresume-rejected-alert" id="id141">fastresume_rejected_alert</a></li>
<li><a class="reference internal" href="#peer-blocked-alert" id="id142">peer_blocked_alert</a></li>
<li><a class="reference internal" href="#storage-moved-alert" id="id143">storage_moved_alert</a></li>
<li><a class="reference internal" href="#torrent-paused-alert" id="id144">torrent_paused_alert</a></li>
<li><a class="reference internal" href="#save-resume-data-alert" id="id145">save_resume_data_alert</a></li>
<li><a class="reference internal" href="#dispatcher" id="id146">dispatcher</a></li>
</ul>
</li>
<li><a class="reference internal" href="#exceptions" id="id146">exceptions</a><ul>
<li><a class="reference internal" href="#invalid-handle" id="id147">invalid_handle</a></li>
<li><a class="reference internal" href="#duplicate-torrent" id="id148">duplicate_torrent</a></li>
<li><a class="reference internal" href="#invalid-encoding" id="id149">invalid_encoding</a></li>
<li><a class="reference internal" href="#type-error" id="id150">type_error</a></li>
<li><a class="reference internal" href="#invalid-torrent-file" id="id151">invalid_torrent_file</a></li>
<li><a class="reference internal" href="#exceptions" id="id147">exceptions</a><ul>
<li><a class="reference internal" href="#invalid-handle" id="id148">invalid_handle</a></li>
<li><a class="reference internal" href="#duplicate-torrent" id="id149">duplicate_torrent</a></li>
<li><a class="reference internal" href="#invalid-encoding" id="id150">invalid_encoding</a></li>
<li><a class="reference internal" href="#type-error" id="id151">type_error</a></li>
<li><a class="reference internal" href="#invalid-torrent-file" id="id152">invalid_torrent_file</a></li>
</ul>
</li>
<li><a class="reference internal" href="#storage-interface" id="id152">storage_interface</a><ul>
<li><a class="reference internal" href="#initialize" id="id153">initialize()</a></li>
<li><a class="reference internal" href="#read" id="id154">read()</a></li>
<li><a class="reference internal" href="#write" id="id155">write()</a></li>
<li><a class="reference internal" href="#id11" id="id156">move_storage()</a></li>
<li><a class="reference internal" href="#verify-resume-data" id="id157">verify_resume_data()</a></li>
<li><a class="reference internal" href="#write-resume-data" id="id158">write_resume_data()</a></li>
<li><a class="reference internal" href="#move-slot" id="id159">move_slot()</a></li>
<li><a class="reference internal" href="#swap-slots" id="id160">swap_slots()</a></li>
<li><a class="reference internal" href="#swap-slots3" id="id161">swap_slots3()</a></li>
<li><a class="reference internal" href="#hash-for-slot" id="id162">hash_for_slot()</a></li>
<li><a class="reference internal" href="#release-files" id="id163">release_files()</a></li>
<li><a class="reference internal" href="#delete-files" id="id164">delete_files()</a></li>
<li><a class="reference internal" href="#storage-interface" id="id153">storage_interface</a><ul>
<li><a class="reference internal" href="#initialize" id="id154">initialize()</a></li>
<li><a class="reference internal" href="#read" id="id155">read()</a></li>
<li><a class="reference internal" href="#write" id="id156">write()</a></li>
<li><a class="reference internal" href="#id11" id="id157">move_storage()</a></li>
<li><a class="reference internal" href="#verify-resume-data" id="id158">verify_resume_data()</a></li>
<li><a class="reference internal" href="#write-resume-data" id="id159">write_resume_data()</a></li>
<li><a class="reference internal" href="#move-slot" id="id160">move_slot()</a></li>
<li><a class="reference internal" href="#swap-slots" id="id161">swap_slots()</a></li>
<li><a class="reference internal" href="#swap-slots3" id="id162">swap_slots3()</a></li>
<li><a class="reference internal" href="#hash-for-slot" id="id163">hash_for_slot()</a></li>
<li><a class="reference internal" href="#release-files" id="id164">release_files()</a></li>
<li><a class="reference internal" href="#delete-files" id="id165">delete_files()</a></li>
</ul>
</li>
<li><a class="reference internal" href="#fast-resume" id="id165">fast resume</a><ul>
<li><a class="reference internal" href="#file-format" id="id166">file format</a></li>
<li><a class="reference internal" href="#queuing" id="id166">queuing</a><ul>
<li><a class="reference internal" href="#downloading" id="id167">downloading</a></li>
<li><a class="reference internal" href="#seeding" id="id168">seeding</a></li>
</ul>
</li>
<li><a class="reference internal" href="#threads" id="id167">threads</a></li>
<li><a class="reference internal" href="#storage-allocation" id="id168">storage allocation</a><ul>
<li><a class="reference internal" href="#sparse-allocation" id="id169">sparse allocation</a></li>
<li><a class="reference internal" href="#full-allocation" id="id170">full allocation</a></li>
<li><a class="reference internal" href="#compact-allocation" id="id171">compact allocation</a></li>
<li><a class="reference internal" href="#fast-resume" id="id169">fast resume</a><ul>
<li><a class="reference internal" href="#file-format" id="id170">file format</a></li>
</ul>
</li>
<li><a class="reference internal" href="#extensions" id="id172">extensions</a><ul>
<li><a class="reference internal" href="#metadata-from-peers" id="id173">metadata from peers</a></li>
<li><a class="reference internal" href="#http-seeding" id="id174">HTTP seeding</a></li>
<li><a class="reference internal" href="#threads" id="id171">threads</a></li>
<li><a class="reference internal" href="#storage-allocation" id="id172">storage allocation</a><ul>
<li><a class="reference internal" href="#sparse-allocation" id="id173">sparse allocation</a></li>
<li><a class="reference internal" href="#full-allocation" id="id174">full allocation</a></li>
<li><a class="reference internal" href="#compact-allocation" id="id175">compact allocation</a></li>
</ul>
</li>
<li><a class="reference internal" href="#filename-checks" id="id175">filename checks</a></li>
<li><a class="reference internal" href="#acknowledgments" id="id176">acknowledgments</a></li>
<li><a class="reference internal" href="#extensions" id="id176">extensions</a><ul>
<li><a class="reference internal" href="#metadata-from-peers" id="id177">metadata from peers</a></li>
<li><a class="reference internal" href="#http-seeding" id="id178">HTTP seeding</a></li>
</ul>
</li>
<li><a class="reference internal" href="#filename-checks" id="id179">filename checks</a></li>
<li><a class="reference internal" href="#acknowledgments" id="id180">acknowledgments</a></li>
</ul>
</div>
<div class="section" id="overview">
@@ -279,25 +285,7 @@ class session: public boost::noncopyable
, std::pair&lt;int, int&gt; listen_port_range
, char const* listen_interface = 0);
torrent_handle add_torrent(
boost::intrusive_ptr&lt;torrent_info&gt; const&amp; ti
, boost::filesystem::path const&amp; save_path
, entry const&amp; resume_data = entry()
, storage_mode_t storage_mode = storage_mode_sparse
, bool paused = false
, storage_constructor_type sc = default_storage_constructor
, void* userdata = 0);
torrent_handle add_torrent(
char const* tracker_url
, sha1_hash const&amp; info_hash
, char const* name
, boost::filesystem::path const&amp; save_path
, entry const&amp; resume_data = entry()
, storage_mode_t storage_mode = storage_mode_sparse
, bool paused = false
, storage_constructor_type sc = default_storage_constructor
, void* userdata = 0);
torrent_handle add_torrent(add_torrent_params const&amp; params);
session_proxy abort();
@@ -439,34 +427,46 @@ typedef storage_interface* (&amp;storage_constructor_type)(
boost::intrusive_ptr&lt;torrent_info const&gt;, fs::path const&amp;
, file_pool&amp;);
torrent_handle add_torrent(
boost::intrusive_ptr&lt;torrent_info&gt; const&amp; ti
, boost::filesystem::path const&amp; save_path
, entry const&amp; resume_data = entry()
, storage_mode_t storage_mode = storage_mode_sparse
, bool paused = false
, storage_constructor_type sc = default_storage_constructor
, void* userdata = 0);
struct add_torrent_params
{
add_torrent_params(storage_constructor_type s);
torrent_handle add_torrent(
char const* tracker_url
, sha1_hash const&amp; info_hash
, char const* name
, boost::filesystem::path const&amp; save_path
, entry const&amp; resume_data = entry()
, storage_mode_t storage_mode = storage_mode_sparse
, bool paused = false
, storage_constructor_type sc = default_storage_constructor
, void* userdata = 0);
boost::intrusive_ptr&lt;torrent_info&gt; ti;
char const* tracker_url;
sha1_hash info_hash;
char const* name;
fs::path save_path;
entry const* resume_data;
storage_mode_t storage_mode;
bool paused;
bool auto_managed;
bool duplicate_is_error;
storage_constructor_type storage;
void* userdata;
};
torrent_handle add_torrent(add_torrent_params const&amp; params);
</pre>
</blockquote>
<p>You add torrents through the <tt class="docutils literal"><span class="pre">add_torrent()</span></tt> function where you give an
object representing the information found in the torrent file and the path where you
want to save the files. The <tt class="docutils literal"><span class="pre">save_path</span></tt> will be prepended to the directory
structure in the torrent-file.</p>
object with all the parameters.</p>
<p>The only mandatory parameter is <tt class="docutils literal"><span class="pre">save_path</span></tt> which is the directory where you
want the files to be saved. You also need to specify either the <tt class="docutils literal"><span class="pre">ti</span></tt> (the
torrent file) or <tt class="docutils literal"><span class="pre">info_hash</span></tt> (the info hash of the torrent). If you 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"><span class="pre">TORRENT_DISABLE_EXTENSIONS</span></tt> must not be
defined). It also takes an optional <tt class="docutils literal"><span class="pre">name</span></tt> argument. This may be 0 in case no
name should be assigned to the torrent. In case it's not 0, 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>If the torrent doesn't have a tracker, but relies on the DHT to find peers, the
<tt class="docutils literal"><span class="pre">tracker_url</span></tt> can be 0, otherwise you might specify a tracker url that tracks this
torrent.</p>
<p>If the torrent you are trying to add already exists in the session (is either queued
for checking, being checked or downloading) <tt class="docutils literal"><span class="pre">add_torrent()</span></tt> will throw
<a class="reference internal" href="#duplicate-torrent">duplicate_torrent</a> which derives from <tt class="docutils literal"><span class="pre">std::exception</span></tt>.</p>
<a class="reference internal" href="#duplicate-torrent">duplicate_torrent</a> which derives from <tt class="docutils literal"><span class="pre">std::exception</span></tt> unless <tt class="docutils literal"><span class="pre">duplicate_is_error</span></tt>
is set to false. In that case, <tt class="docutils literal"><span class="pre">add_torrent</span></tt> will return the handle to the existing
torrent.</p>
<p>The optional parameter, <tt class="docutils literal"><span class="pre">resume_data</span></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 internal" href="#save-resume-data">save_resume_data()</a> on <a class="reference internal" href="#torrent-handle">torrent_handle</a>. See <a class="reference internal" href="#fast-resume">fast resume</a>.</p>
@@ -490,24 +490,19 @@ downloaded.</dd>
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.</p>
<p><tt class="docutils literal"><span class="pre">storage_constructor</span></tt> can be used to customize how the data is stored. The default
<p>If <tt class="docutils literal"><span class="pre">auto_managed</span></tt> is true, this 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 internal" href="#queuing">queuing</a>.</p>
<p><tt class="docutils literal"><span class="pre">storage</span></tt> 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 <tt class="docutils literal"><span class="pre">storage_interface</span></tt>
that needs to be implemented for a custom storage, see <a class="reference internal" href="#storage-interface">storage_interface</a>.</p>
<p>The <a class="reference internal" href="#torrent-handle">torrent_handle</a> returned by <tt class="docutils literal"><span class="pre">add_torrent()</span></tt> can be used to retrieve information
about the torrent's progress, its peers etc. It is also used to abort a torrent.</p>
<p>The <tt class="docutils literal"><span class="pre">userdata</span></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>).</p>
<p>The second overload that takes a tracker url and an info-hash instead of metadata
(<tt class="docutils literal"><span class="pre">torrent_info</span></tt>) can be used with torrents where (at least some) peers support
the metadata extension. For the overload to be available, libtorrent must be built
with extensions enabled (<tt class="docutils literal"><span class="pre">TORRENT_DISABLE_EXTENSIONS</span></tt> must not be defined). It also
takes an optional <tt class="docutils literal"><span class="pre">name</span></tt> argument. This may be 0 in case no name should be assigned
to the torrent. In case it's not 0, 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>If the torrent doesn't have a tracker, but relies on the DHT to find peers, the
<tt class="docutils literal"><span class="pre">tracker_url</span></tt> can be 0.</p>
<p>The <a class="reference internal" href="#torrent-handle">torrent_handle</a> returned by <tt class="docutils literal"><span class="pre">add_torrent()</span></tt> can be used to retrieve information
about the torrent's progress, its peers etc. It is also used to abort a torrent.</p>
</div>
<div class="section" id="remove-torrent">
<h2>remove_torrent()</h2>
@@ -1679,12 +1674,8 @@ struct torrent_handle
void prioritize_files(std::vector&lt;int&gt; const&amp; files) const;
// these functions are deprecated
void filter_piece(int index, bool filter) const;
void filter_pieces(std::vector&lt;bool&gt; const&amp; bitmask) const;
bool is_piece_filtered(int index) const;
std::vector&lt;bool&gt; filtered_pieces() const;
void filter_files(std::vector&lt;bool&gt; const&amp; files) const;
bool is_auto_managed() const;
void auto_managed(bool m) const;
bool has_metadata() const;
@@ -1705,8 +1696,8 @@ it will throw <tt class="docutils literal"><span class="pre">invalid_handle</spa
<div class="warning">
<p class="first admonition-title">Warning</p>
<p class="last">All operations on a <tt class="docutils literal"><span class="pre">torrent_handle</span></tt> may throw <a class="reference internal" href="#invalid-handle">invalid_handle</a>
exception, in case the handle is no longer refering to a torrent. There are
two exceptions, <tt class="docutils literal"><span class="pre">info_hash()</span></tt> and <tt class="docutils literal"><span class="pre">is_valid()</span></tt> will never throw.
exception, in case the handle is no longer refering to a torrent. There is
one exception <tt class="docutils literal"><span class="pre">is_valid()</span></tt> will never throw.
Since the torrents are processed by a background thread, there is no
guarantee that a handle will remain valid between two calls.</p>
</div>
@@ -1936,6 +1927,18 @@ bool is_seed() const;
</blockquote>
<p>Returns true if the torrent is in seed mode (i.e. if it has finished downloading).</p>
</div>
<div class="section" id="is-auto-managed-auto-managed">
<h2>is_auto_managed() auto_managed()</h2>
<blockquote>
<pre class="literal-block">
bool is_auto_managed() const;
void auto_managed(bool m) const;
</pre>
</blockquote>
<p><tt class="docutils literal"><span class="pre">is_auto_managed()</span></tt> returns true if this torrent is currently <em>auto managed</em>.
<tt class="docutils literal"><span class="pre">auto_managed()</span></tt> changes whether the torrent is auto managed or not. For more info,
see <a class="reference internal" href="#queuing">queuing</a>.</p>
</div>
<div class="section" id="has-metadata">
<h2>has_metadata()</h2>
<blockquote>
@@ -2208,7 +2211,6 @@ it has been added to the session. Usually this is because the storage for the to
somehow invalid or if the filenames are not allowed (and hence cannot be opened/created) on
your filesystem. If such an error occurs, a <a class="reference internal" href="#file-error-alert">file_error_alert</a> is generated and all handles
that refers to that torrent will become invalid.</p>
<p><em>TODO: document storage</em></p>
</div>
</div>
<div class="section" id="torrent-status">
@@ -2289,6 +2291,8 @@ struct torrent_status
int active_time;
int seeding_time;
float seed_cycles;
};
</pre>
<p><tt class="docutils literal"><span class="pre">progress</span></tt> is a value in the range [0, 1], that represents the progress of the
@@ -2442,6 +2446,10 @@ number of seconds this torrent has been active (not paused) and the number of
seconds it has been active while being a seed. <tt class="docutils literal"><span class="pre">seeding_time</span></tt> should be &gt;=
<tt class="docutils literal"><span class="pre">active_time</span></tt> They are saved in and restored from resume data, to keep totals
across sessions.</p>
<p><tt class="docutils literal"><span class="pre">seed_cycles</span></tt> is the number of times this torrent has reached the seed limits.
It will keep being seeded, but it will rotate between torrents that haven't
completed as many cycles. The fraction part of this number is the progress
of the current cycle. For more information, see <a class="reference internal" href="#queuing">queuing</a>.</p>
</div>
<div class="section" id="peer-info">
<h1>peer_info</h1>
@@ -2814,6 +2822,13 @@ struct session_settings
int cache_expiry;
std::pair&lt;int, int&gt; outgoing_ports;
char peer_tos;
int active_downloads;
int active_seeds;
int auto_manage_interval;
float share_ratio_limit;
float seed_time_ratio_limit;
int seed_time_limit;
};
</pre>
<p><tt class="docutils literal"><span class="pre">user_agent</span></tt> this is the client identification to the tracker.
@@ -2974,6 +2989,19 @@ to peers if a previous socket to that peer and port is in <tt class="docutils li
sent to peers (including web seeds). The default value for this is <tt class="docutils literal"><span class="pre">0x0</span></tt>
(no marking). One potentially useful TOS mark is <tt class="docutils literal"><span class="pre">0x20</span></tt>, this represents
the <em>QBone scavenger service</em>. For more details, see <a class="reference external" href="http://qbone.internet2.edu/qbss/">QBSS</a>.</p>
<p><tt class="docutils literal"><span class="pre">active_downloads</span></tt> and <tt class="docutils literal"><span class="pre">active_seeds</span></tt> controls how many active seeding and
downloading torrents the queuing mechanism allows. Seeding torrents are
counted against the downloads limit but downloading torrenst are not
counted against the seed limit.</p>
<p><tt class="docutils literal"><span class="pre">auto_manage_interval</span></tt> is the number of seconds between the torrent queue
is updated, and rotated.</p>
<p><tt class="docutils literal"><span class="pre">share_ratio_limit</span></tt> is the upload / download ratio limit for considering a
seeding torrent have completed one seed cycle. See <a class="reference internal" href="#queuing">queuing</a>.</p>
<p><tt class="docutils literal"><span class="pre">seed_time_ratio_limit</span></tt> is the seeding time / downloading time ratio limit
for considering a seeding torrent to have completed one seed cycle. See <a class="reference internal" href="#queuing">queuing</a>.</p>
<p><tt class="docutils literal"><span class="pre">seed_time_limit</span></tt> is the limit on the time a torrent has been an active seed
(specified in seconds) before it is considered having completed one seed cycle.
See <a class="reference internal" href="#queuing">queuing</a>.</p>
</div>
<div class="section" id="pe-settings">
<h1>pe_settings</h1>
@@ -4247,6 +4275,43 @@ void delete_files() = 0;
<p>This function should delete all files and directories belonging to this storage.</p>
</div>
</div>
<div class="section" id="queuing">
<h1>queuing</h1>
<p>libtorrent supports <em>queuing</em>. Which means it makes sure that a limited number of
torrents are being downloaded at any given time, and once a torrent is completely
downloaded, the next in line is started.</p>
<p>Torrents that are <em>auto managed</em> are subject to the queuing and the active torrents
limits. To make a torrent auto managed, set <tt class="docutils literal"><span class="pre">auto_managed</span></tt> to true when adding the
torrent (see <a class="reference internal" href="#add-torrent">add_torrent()</a>).</p>
<p>The limits of the number of downloading and seeding torrents are controlled via
<tt class="docutils literal"><span class="pre">active_downloads</span></tt> and <tt class="docutils literal"><span class="pre">active_seeds</span></tt> in <a class="reference internal" href="#session-settings">session_settings</a>. These limits takes
non auto managed torrents into account as well. If there are are more non-auto managed
torrents being downloaded than the <tt class="docutils literal"><span class="pre">active_downloads</span></tt> setting, any auto managed
torrents will be queued until torrents are removed so that the number drops below
the limit.</p>
<p>Seeding torrents counts as downloads, but downloading torrents don't count as
seeding. So, <tt class="docutils literal"><span class="pre">active_downloads</span></tt> should typically be greater than <tt class="docutils literal"><span class="pre">active_seeds</span></tt>.
The default values are 8 active downloads and 5 active seeds.</p>
<p>At a regular interval, torrents are checked if there needs to be any re-ordering of
which torrents are active and which are queued. This interval can be controlled via
<tt class="docutils literal"><span class="pre">auto_manage_interval</span></tt> in <a class="reference internal" href="#session-settings">session_settings</a>. It defaults to every 30 seconds.</p>
<p>For queuing to work, resume data needs to be saved and restored for all torrents.
See <a class="reference internal" href="#save-resume-data">save_resume_data()</a>.</p>
<div class="section" id="downloading">
<h2>downloading</h2>
<p><strong>TODO: finish</strong></p>
</div>
<div class="section" id="seeding">
<h2>seeding</h2>
<p>Auto managed seeding torrents are rotated, so that all of them are allocated a fair
amount of seeding. Torrents with fewer completed <em>seed cycles</em> are prioritized for
seeding. A seed cycle is completed when a torrent meets either the share ratio limit
(uploaded bytes / downloaded bytes), the share time ratio (time seeding / time
downloaing) or seed time limit (time seeded).</p>
<p>The relevant settings to control these limits are <tt class="docutils literal"><span class="pre">share_ratio_limit</span></tt>,
<tt class="docutils literal"><span class="pre">seed_time_ratio_limit</span></tt> and <tt class="docutils literal"><span class="pre">seed_time_limit</span></tt> in <a class="reference internal" href="#session-settings">session_settings</a>.</p>
</div>
</div>
<div class="section" id="fast-resume">
<h1>fast resume</h1>
<p>The fast resume mechanism is a way to remember which pieces are downloaded

208
docs/manual.rst
View File

@@ -59,7 +59,6 @@ For documentation on these types, please refer to the `asio documentation`_.
.. _`asio documentation`: http://asio.sourceforge.net/asio-0.3.8/doc/asio/reference.html
session
=======
@@ -77,25 +76,7 @@ The ``session`` class has the following synopsis::
, std::pair<int, int> listen_port_range
, char const* listen_interface = 0);
torrent_handle add_torrent(
boost::intrusive_ptr<torrent_info> const& ti
, boost::filesystem::path const& save_path
, entry const& resume_data = entry()
, storage_mode_t storage_mode = storage_mode_sparse
, bool paused = false
, storage_constructor_type sc = default_storage_constructor
, void* userdata = 0);
torrent_handle add_torrent(
char const* tracker_url
, sha1_hash const& info_hash
, char const* name
, boost::filesystem::path const& save_path
, entry const& resume_data = entry()
, storage_mode_t storage_mode = storage_mode_sparse
, bool paused = false
, storage_constructor_type sc = default_storage_constructor
, void* userdata = 0);
torrent_handle add_torrent(add_torrent_params const& params);
session_proxy abort();
@@ -242,34 +223,48 @@ add_torrent()
boost::intrusive_ptr<torrent_info const>, fs::path const&
, file_pool&);
torrent_handle add_torrent(
boost::intrusive_ptr<torrent_info> const& ti
, boost::filesystem::path const& save_path
, entry const& resume_data = entry()
, storage_mode_t storage_mode = storage_mode_sparse
, bool paused = false
, storage_constructor_type sc = default_storage_constructor
, void* userdata = 0);
struct add_torrent_params
{
add_torrent_params(storage_constructor_type s);
torrent_handle add_torrent(
char const* tracker_url
, sha1_hash const& info_hash
, char const* name
, boost::filesystem::path const& save_path
, entry const& resume_data = entry()
, storage_mode_t storage_mode = storage_mode_sparse
, bool paused = false
, storage_constructor_type sc = default_storage_constructor
, void* userdata = 0);
boost::intrusive_ptr<torrent_info> ti;
char const* tracker_url;
sha1_hash info_hash;
char const* name;
fs::path save_path;
entry const* resume_data;
storage_mode_t storage_mode;
bool paused;
bool auto_managed;
bool duplicate_is_error;
storage_constructor_type storage;
void* userdata;
};
torrent_handle add_torrent(add_torrent_params const& params);
You add torrents through the ``add_torrent()`` function where you give an
object representing the information found in the torrent file and the path where you
want to save the files. The ``save_path`` will be prepended to the directory
structure in the torrent-file.
object with all the parameters.
The only mandatory parameter is ``save_path`` which is the directory where you
want the files to be saved. You also need to specify either the ``ti`` (the
torrent file) or ``info_hash`` (the info hash of the torrent). If you 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 0 in case no
name should be assigned to the torrent. In case it's not 0, the name is used for
the torrent as long as it doesn't have metadata. See ``torrent_handle::name``.
If the torrent doesn't have a tracker, but relies on the DHT to find peers, the
``tracker_url`` can be 0, otherwise you might specify a tracker url that tracks this
torrent.
If the torrent you are trying to add already exists in the session (is either queued
for checking, being checked or downloading) ``add_torrent()`` will throw
duplicate_torrent_ which derives from ``std::exception``.
duplicate_torrent_ which derives from ``std::exception`` unless ``duplicate_is_error``
is set to false. In that case, ``add_torrent`` will return the handle to the existing
torrent.
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
@@ -299,28 +294,22 @@ a paused state. I.e. it won't connect to the tracker or any of the peers until i
resumed. This is typically a good way of avoiding race conditions when setting
configuration options on torrents before starting them.
``storage_constructor`` can be used to customize how the data is stored. The default
If ``auto_managed`` is true, this 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_.
``storage`` 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`_.
The torrent_handle_ returned by ``add_torrent()`` can be used to retrieve information
about the torrent's progress, its peers etc. It is also used to abort a torrent.
The ``userdata`` parameter is optional and will be passed on to the extension
constructor functions, if any (see `add_extension()`_).
The second overload that takes a tracker url and an info-hash instead of metadata
(``torrent_info``) can be used with torrents where (at least some) peers support
the metadata extension. For the overload to be available, libtorrent must be built
with extensions enabled (``TORRENT_DISABLE_EXTENSIONS`` must not be defined). It also
takes an optional ``name`` argument. This may be 0 in case no name should be assigned
to the torrent. In case it's not 0, the name is used for the torrent as long as it doesn't
have metadata. See ``torrent_handle::name``.
If the torrent doesn't have a tracker, but relies on the DHT to find peers, the
``tracker_url`` can be 0.
The torrent_handle_ returned by ``add_torrent()`` can be used to retrieve information
about the torrent's progress, its peers etc. It is also used to abort a torrent.
remove_torrent()
@@ -1624,13 +1613,9 @@ Its declaration looks like this::
void prioritize_files(std::vector<int> const& files) const;
// these functions are deprecated
void filter_piece(int index, bool filter) const;
void filter_pieces(std::vector<bool> const& bitmask) const;
bool is_piece_filtered(int index) const;
std::vector<bool> filtered_pieces() const;
void filter_files(std::vector<bool> const& files) const;
bool is_auto_managed() const;
void auto_managed(bool m) const;
bool has_metadata() const;
boost::filesystem::path save_path() const;
@@ -1649,8 +1634,8 @@ valid handle. If you try to perform any operation on an uninitialized handle,
it will throw ``invalid_handle``.
.. warning:: All operations on a ``torrent_handle`` may throw invalid_handle_
exception, in case the handle is no longer refering to a torrent. There are
two exceptions, ``info_hash()`` and ``is_valid()`` will never throw.
exception, in case the handle is no longer refering to a torrent. There is
one exception ``is_valid()`` will never throw.
Since the torrents are processed by a background thread, there is no
guarantee that a handle will remain valid between two calls.
@@ -1894,6 +1879,17 @@ is_seed()
Returns true if the torrent is in seed mode (i.e. if it has finished downloading).
is_auto_managed() auto_managed()
--------------------------------
::
bool is_auto_managed() const;
void auto_managed(bool m) const;
``is_auto_managed()`` returns true if this torrent is currently *auto managed*.
``auto_managed()`` changes whether the torrent is auto managed or not. For more info,
see queuing_.
has_metadata()
--------------
@@ -2188,8 +2184,6 @@ somehow invalid or if the filenames are not allowed (and hence cannot be opened/
your filesystem. If such an error occurs, a file_error_alert_ is generated and all handles
that refers to that torrent will become invalid.
*TODO: document storage*
torrent_status
==============
@@ -2270,6 +2264,8 @@ It contains the following fields::
int active_time;
int seeding_time;
float seed_cycles;
};
``progress`` is a value in the range [0, 1], that represents the progress of the
@@ -2441,6 +2437,12 @@ seconds it has been active while being a seed. ``seeding_time`` should be >=
``active_time`` They are saved in and restored from resume data, to keep totals
across sessions.
``seed_cycles`` is the number of times this torrent has reached the seed limits.
It will keep being seeded, but it will rotate between torrents that haven't
completed as many cycles. The fraction part of this number is the progress
of the current cycle. For more information, see queuing_.
peer_info
=========
@@ -2812,6 +2814,13 @@ that will be sent to the tracker. The user-agent is a good way to identify your
int cache_expiry;
std::pair<int, int> outgoing_ports;
char peer_tos;
int active_downloads;
int active_seeds;
int auto_manage_interval;
float share_ratio_limit;
float seed_time_ratio_limit;
int seed_time_limit;
};
``user_agent`` this is the client identification to the tracker.
@@ -3014,6 +3023,24 @@ the *QBone scavenger service*. For more details, see QBSS_.
.. _`QBSS`: http://qbone.internet2.edu/qbss/
``active_downloads`` and ``active_seeds`` controls how many active seeding and
downloading torrents the queuing mechanism allows. Seeding torrents are
counted against the downloads limit but downloading torrenst are not
counted against the seed limit.
``auto_manage_interval`` is the number of seconds between the torrent queue
is updated, and rotated.
``share_ratio_limit`` is the upload / download ratio limit for considering a
seeding torrent have completed one seed cycle. See queuing_.
``seed_time_ratio_limit`` is the seeding time / downloading time ratio limit
for considering a seeding torrent to have completed one seed cycle. See queuing_.
``seed_time_limit`` is the limit on the time a torrent has been an active seed
(specified in seconds) before it is considered having completed one seed cycle.
See queuing_.
pe_settings
===========
@@ -4449,6 +4476,53 @@ delete_files()
This function should delete all files and directories belonging to this storage.
queuing
=======
libtorrent supports *queuing*. Which means it makes sure that a limited number of
torrents are being downloaded at any given time, and once a torrent is completely
downloaded, the next in line is started.
Torrents that are *auto managed* are subject to the queuing and the active torrents
limits. To make a torrent auto managed, set ``auto_managed`` to true when adding the
torrent (see `add_torrent()`_).
The limits of the number of downloading and seeding torrents are controlled via
``active_downloads`` and ``active_seeds`` in session_settings_. These limits takes
non auto managed torrents into account as well. If there are are more non-auto managed
torrents being downloaded than the ``active_downloads`` setting, any auto managed
torrents will be queued until torrents are removed so that the number drops below
the limit.
Seeding torrents counts as downloads, but downloading torrents don't count as
seeding. So, ``active_downloads`` should typically be greater than ``active_seeds``.
The default values are 8 active downloads and 5 active seeds.
At a regular interval, torrents are checked if there needs to be any re-ordering of
which torrents are active and which are queued. This interval can be controlled via
``auto_manage_interval`` in session_settings_. It defaults to every 30 seconds.
For queuing to work, resume data needs to be saved and restored for all torrents.
See `save_resume_data()`_.
downloading
-----------
**TODO: finish**
seeding
-------
Auto managed seeding torrents are rotated, so that all of them are allocated a fair
amount of seeding. Torrents with fewer completed *seed cycles* are prioritized for
seeding. A seed cycle is completed when a torrent meets either the share ratio limit
(uploaded bytes / downloaded bytes), the share time ratio (time seeding / time
downloaing) or seed time limit (time seeded).
The relevant settings to control these limits are ``share_ratio_limit``,
``seed_time_ratio_limit`` and ``seed_time_limit`` in session_settings_.
fast resume
===========