4906 lines
262 KiB
HTML
4906 lines
262 KiB
HTML
<?xml version="1.0" encoding="utf-8" ?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
|
|
<title>libtorrent API Documentation</title>
|
|
<meta name="author" content="Arvid Norberg, arvid@rasterbar.com" />
|
|
<link rel="stylesheet" href="style.css" type="text/css" />
|
|
</head>
|
|
<body>
|
|
<div class="document" id="libtorrent-api-documentation">
|
|
<h1 class="title">libtorrent API Documentation</h1>
|
|
<table class="docinfo" frame="void" rules="none">
|
|
<col class="docinfo-name" />
|
|
<col class="docinfo-content" />
|
|
<tbody valign="top">
|
|
<tr><th class="docinfo-name">Author:</th>
|
|
<td>Arvid Norberg, <a class="last reference" href="mailto:arvid@rasterbar.com">arvid@rasterbar.com</a></td></tr>
|
|
<tr><th class="docinfo-name">Version:</th>
|
|
<td>0.13</td></tr>
|
|
</tbody>
|
|
</table>
|
|
<div class="contents topic" id="table-of-contents">
|
|
<p class="topic-title first"><a name="table-of-contents">Table of contents</a></p>
|
|
<ul class="simple">
|
|
<li><a class="reference" href="#overview" id="id18" name="id18">overview</a></li>
|
|
<li><a class="reference" href="#network-primitives" id="id19" name="id19">network primitives</a></li>
|
|
<li><a class="reference" href="#session" id="id20" name="id20">session</a><ul>
|
|
<li><a class="reference" href="#id1" id="id21" name="id21">session()</a></li>
|
|
<li><a class="reference" href="#id2" id="id22" name="id22">~session()</a></li>
|
|
<li><a class="reference" href="#pause-resume-is-paused" id="id23" name="id23">pause() resume() is_paused()</a></li>
|
|
<li><a class="reference" href="#abort" id="id24" name="id24">abort()</a></li>
|
|
<li><a class="reference" href="#add-torrent" id="id25" name="id25">add_torrent()</a></li>
|
|
<li><a class="reference" href="#remove-torrent" id="id26" name="id26">remove_torrent()</a></li>
|
|
<li><a class="reference" href="#find-torrent-get-torrents" id="id27" name="id27">find_torrent() get_torrents()</a></li>
|
|
<li><a class="reference" href="#set-upload-rate-limit-set-download-rate-limit-upload-rate-limit-download-rate-limit" id="id28" name="id28">set_upload_rate_limit() set_download_rate_limit() upload_rate_limit() download_rate_limit()</a></li>
|
|
<li><a class="reference" href="#set-max-uploads-set-max-connections" id="id29" name="id29">set_max_uploads() set_max_connections()</a></li>
|
|
<li><a class="reference" href="#num-uploads-num-connections" id="id30" name="id30">num_uploads() num_connections()</a></li>
|
|
<li><a class="reference" href="#set-max-half-open-connections-max-half-open-connections" id="id31" name="id31">set_max_half_open_connections() max_half_open_connections()</a></li>
|
|
<li><a class="reference" href="#load-asnum-db-load-country-db-int-as-for-ip" id="id32" name="id32">load_asnum_db() load_country_db() int as_for_ip()</a></li>
|
|
<li><a class="reference" href="#load-state-state" id="id33" name="id33">load_state() state()</a></li>
|
|
<li><a class="reference" href="#set-ip-filter" id="id34" name="id34">set_ip_filter()</a></li>
|
|
<li><a class="reference" href="#status" id="id35" name="id35">status()</a></li>
|
|
<li><a class="reference" href="#get-cache-status" id="id36" name="id36">get_cache_status()</a></li>
|
|
<li><a class="reference" href="#get-cache-info" id="id37" name="id37">get_cache_info()</a></li>
|
|
<li><a class="reference" href="#is-listening-listen-port-listen-on" id="id38" name="id38">is_listening() listen_port() listen_on()</a></li>
|
|
<li><a class="reference" href="#pop-alert-set-alert-mask-wait-for-alert" id="id39" name="id39">pop_alert() set_alert_mask() wait_for_alert()</a></li>
|
|
<li><a class="reference" href="#add-extension" id="id40" name="id40">add_extension()</a></li>
|
|
<li><a class="reference" href="#set-settings-set-pe-settings" id="id41" name="id41">set_settings() set_pe_settings()</a></li>
|
|
<li><a class="reference" href="#set-peer-proxy-set-web-seed-proxy-set-tracker-proxy-set-dht-proxy" id="id42" name="id42">set_peer_proxy() set_web_seed_proxy() set_tracker_proxy() set_dht_proxy()</a></li>
|
|
<li><a class="reference" href="#peer-proxy-web-seed-proxy-tracker-proxy-dht-proxy" id="id43" name="id43">peer_proxy() web_seed_proxy() tracker_proxy() dht_proxy()</a></li>
|
|
<li><a class="reference" href="#start-dht-stop-dht-set-dht-settings-dht-state" id="id44" name="id44">start_dht() stop_dht() set_dht_settings() dht_state()</a></li>
|
|
<li><a class="reference" href="#add-dht-node-add-dht-router" id="id45" name="id45">add_dht_node() add_dht_router()</a></li>
|
|
<li><a class="reference" href="#start-lsd-stop-lsd" id="id46" name="id46">start_lsd() stop_lsd()</a></li>
|
|
<li><a class="reference" href="#start-upnp-stop-upnp" id="id47" name="id47">start_upnp() stop_upnp()</a></li>
|
|
<li><a class="reference" href="#start-natpmp-stop-natpmp" id="id48" name="id48">start_natpmp() stop_natpmp()</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#entry" id="id49" name="id49">entry</a><ul>
|
|
<li><a class="reference" href="#integer-string-list-dict-type" id="id50" name="id50">integer() string() list() dict() type()</a></li>
|
|
<li><a class="reference" href="#operator" id="id51" name="id51">operator[]</a></li>
|
|
<li><a class="reference" href="#find-key" id="id52" name="id52">find_key()</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#torrent-info" id="id53" name="id53">torrent_info</a><ul>
|
|
<li><a class="reference" href="#id3" id="id54" name="id54">torrent_info()</a></li>
|
|
<li><a class="reference" href="#add-tracker" id="id55" name="id55">add_tracker()</a></li>
|
|
<li><a class="reference" href="#files" id="id56" name="id56">files()</a></li>
|
|
<li><a class="reference" href="#begin-files-end-files-rbegin-files-rend-files" id="id57" name="id57">begin_files() end_files() rbegin_files() rend_files()</a></li>
|
|
<li><a class="reference" href="#num-files-file-at" id="id58" name="id58">num_files() file_at()</a></li>
|
|
<li><a class="reference" href="#map-block" id="id59" name="id59">map_block()</a></li>
|
|
<li><a class="reference" href="#map-file" id="id60" name="id60">map_file()</a></li>
|
|
<li><a class="reference" href="#url-seeds-add-url-seed" id="id61" name="id61">url_seeds() add_url_seed()</a></li>
|
|
<li><a class="reference" href="#trackers" id="id62" name="id62">trackers()</a></li>
|
|
<li><a class="reference" href="#total-size-piece-length-piece-size-num-pieces" id="id63" name="id63">total_size() piece_length() piece_size() num_pieces()</a></li>
|
|
<li><a class="reference" href="#hash-for-piece-hash-for-piece-ptr-info-hash" id="id64" name="id64">hash_for_piece() hash_for_piece_ptr() info_hash()</a></li>
|
|
<li><a class="reference" href="#name-comment-creation-date-creator" id="id65" name="id65">name() comment() creation_date() creator()</a></li>
|
|
<li><a class="reference" href="#priv" id="id66" name="id66">priv()</a></li>
|
|
<li><a class="reference" href="#nodes" id="id67" name="id67">nodes()</a></li>
|
|
<li><a class="reference" href="#add-node" id="id68" name="id68">add_node()</a></li>
|
|
<li><a class="reference" href="#metadata-metadata-size" id="id69" name="id69">metadata() metadata_size()</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#torrent-handle" id="id70" name="id70">torrent_handle</a><ul>
|
|
<li><a class="reference" href="#piece-priority-prioritize-pieces-piece-priorities" id="id71" name="id71">piece_priority() prioritize_pieces() piece_priorities()</a></li>
|
|
<li><a class="reference" href="#file-priority-prioritize-files-file-priorities" id="id72" name="id72">file_priority() prioritize_files() file_priorities()</a></li>
|
|
<li><a class="reference" href="#file-progress" id="id73" name="id73">file_progress()</a></li>
|
|
<li><a class="reference" href="#save-path" id="id74" name="id74">save_path()</a></li>
|
|
<li><a class="reference" href="#move-storage" id="id75" name="id75">move_storage()</a></li>
|
|
<li><a class="reference" href="#force-reannounce" id="id76" name="id76">force_reannounce()</a></li>
|
|
<li><a class="reference" href="#scrape-tracker" id="id77" name="id77">scrape_tracker()</a></li>
|
|
<li><a class="reference" href="#connect-peer" id="id78" name="id78">connect_peer()</a></li>
|
|
<li><a class="reference" href="#name" id="id79" name="id79">name()</a></li>
|
|
<li><a class="reference" href="#set-ratio" id="id80" name="id80">set_ratio()</a></li>
|
|
<li><a class="reference" href="#set-upload-limit-set-download-limit-upload-limit-download-limit" id="id81" name="id81">set_upload_limit() set_download_limit() upload_limit() download_limit()</a></li>
|
|
<li><a class="reference" href="#set-sequential-download-is-sequential-download" id="id82" name="id82">set_sequential_download() is_sequential_download()</a></li>
|
|
<li><a class="reference" href="#set-peer-upload-limit-set-peer-download-limit" id="id83" name="id83">set_peer_upload_limit() set_peer_download_limit()</a></li>
|
|
<li><a class="reference" href="#id5" id="id84" name="id84">pause() resume() is_paused()</a></li>
|
|
<li><a class="reference" href="#force-recheck" id="id85" name="id85">force_recheck()</a></li>
|
|
<li><a class="reference" href="#clear-error" id="id86" name="id86">clear_error()</a></li>
|
|
<li><a class="reference" href="#resolve-countries" id="id87" name="id87">resolve_countries()</a></li>
|
|
<li><a class="reference" href="#is-seed" id="id88" name="id88">is_seed()</a></li>
|
|
<li><a class="reference" href="#is-auto-managed-auto-managed" id="id89" name="id89">is_auto_managed() auto_managed()</a></li>
|
|
<li><a class="reference" href="#has-metadata" id="id90" name="id90">has_metadata()</a></li>
|
|
<li><a class="reference" href="#set-tracker-login" id="id91" name="id91">set_tracker_login()</a></li>
|
|
<li><a class="reference" href="#trackers-replace-trackers" id="id92" name="id92">trackers() replace_trackers()</a></li>
|
|
<li><a class="reference" href="#add-url-seed-remove-url-seed-url-seeds" id="id93" name="id93">add_url_seed() remove_url_seed() url_seeds()</a></li>
|
|
<li><a class="reference" href="#queue-position-queue-position-up-queue-position-down-queue-position-top-queue-position-bottom" id="id94" name="id94">queue_position() queue_position_up() queue_position_down() queue_position_top() queue_position_bottom()</a></li>
|
|
<li><a class="reference" href="#use-interface" id="id95" name="id95">use_interface()</a></li>
|
|
<li><a class="reference" href="#info-hash" id="id96" name="id96">info_hash()</a></li>
|
|
<li><a class="reference" href="#id6" id="id97" name="id97">set_max_uploads() set_max_connections()</a></li>
|
|
<li><a class="reference" href="#save-resume-data" id="id98" name="id98">save_resume_data()</a></li>
|
|
<li><a class="reference" href="#id7" id="id99" name="id99">status()</a></li>
|
|
<li><a class="reference" href="#get-download-queue" id="id100" name="id100">get_download_queue()</a></li>
|
|
<li><a class="reference" href="#get-peer-info" id="id101" name="id101">get_peer_info()</a></li>
|
|
<li><a class="reference" href="#get-torrent-info" id="id102" name="id102">get_torrent_info()</a></li>
|
|
<li><a class="reference" href="#is-valid" id="id103" name="id103">is_valid()</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#torrent-status" id="id104" name="id104">torrent_status</a></li>
|
|
<li><a class="reference" href="#peer-info" id="id105" name="id105">peer_info</a></li>
|
|
<li><a class="reference" href="#session-settings" id="id106" name="id106">session_settings</a></li>
|
|
<li><a class="reference" href="#pe-settings" id="id107" name="id107">pe_settings</a></li>
|
|
<li><a class="reference" href="#proxy-settings" id="id108" name="id108">proxy_settings</a></li>
|
|
<li><a class="reference" href="#ip-filter" id="id109" name="id109">ip_filter</a><ul>
|
|
<li><a class="reference" href="#id10" id="id110" name="id110">ip_filter()</a></li>
|
|
<li><a class="reference" href="#add-rule" id="id111" name="id111">add_rule()</a></li>
|
|
<li><a class="reference" href="#access" id="id112" name="id112">access()</a></li>
|
|
<li><a class="reference" href="#export-filter" id="id113" name="id113">export_filter()</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#big-number" id="id114" name="id114">big_number</a></li>
|
|
<li><a class="reference" href="#bitfield" id="id115" name="id115">bitfield</a></li>
|
|
<li><a class="reference" href="#hasher" id="id116" name="id116">hasher</a></li>
|
|
<li><a class="reference" href="#fingerprint" id="id117" name="id117">fingerprint</a></li>
|
|
<li><a class="reference" href="#upnp-and-nat-pmp" id="id118" name="id118">UPnP and NAT-PMP</a><ul>
|
|
<li><a class="reference" href="#add-mapping" id="id119" name="id119">add_mapping</a></li>
|
|
<li><a class="reference" href="#delete-mapping" id="id120" name="id120">delete_mapping</a></li>
|
|
<li><a class="reference" href="#router-model" id="id121" name="id121">router_model()</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#free-functions" id="id122" name="id122">free functions</a><ul>
|
|
<li><a class="reference" href="#identify-client" id="id123" name="id123">identify_client()</a></li>
|
|
<li><a class="reference" href="#client-fingerprint" id="id124" name="id124">client_fingerprint()</a></li>
|
|
<li><a class="reference" href="#bdecode-bencode" id="id125" name="id125">bdecode() bencode()</a></li>
|
|
<li><a class="reference" href="#add-magnet-uri" id="id126" name="id126">add_magnet_uri()</a></li>
|
|
<li><a class="reference" href="#make-magnet-uri" id="id127" name="id127">make_magnet_uri()</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#alerts" id="id128" name="id128">alerts</a><ul>
|
|
<li><a class="reference" href="#external-ip-alert" id="id129" name="id129">external_ip_alert</a></li>
|
|
<li><a class="reference" href="#listen-failed-alert" id="id130" name="id130">listen_failed_alert</a></li>
|
|
<li><a class="reference" href="#portmap-error-alert" id="id131" name="id131">portmap_error_alert</a></li>
|
|
<li><a class="reference" href="#portmap-alert" id="id132" name="id132">portmap_alert</a></li>
|
|
<li><a class="reference" href="#file-error-alert" id="id133" name="id133">file_error_alert</a></li>
|
|
<li><a class="reference" href="#tracker-announce-alert" id="id134" name="id134">tracker_announce_alert</a></li>
|
|
<li><a class="reference" href="#tracker-error-alert" id="id135" name="id135">tracker_error_alert</a></li>
|
|
<li><a class="reference" href="#tracker-reply-alert" id="id136" name="id136">tracker_reply_alert</a></li>
|
|
<li><a class="reference" href="#dht-reply-alert" id="id137" name="id137">dht_reply_alert</a></li>
|
|
<li><a class="reference" href="#tracker-warning-alert" id="id138" name="id138">tracker_warning_alert</a></li>
|
|
<li><a class="reference" href="#scrape-reply-alert" id="id139" name="id139">scrape_reply_alert</a></li>
|
|
<li><a class="reference" href="#scrape-failed-alert" id="id140" name="id140">scrape_failed_alert</a></li>
|
|
<li><a class="reference" href="#url-seed-alert" id="id141" name="id141">url_seed_alert</a></li>
|
|
<li><a class="reference" href="#hash-failed-alert" id="id142" name="id142">hash_failed_alert</a></li>
|
|
<li><a class="reference" href="#peer-ban-alert" id="id143" name="id143">peer_ban_alert</a></li>
|
|
<li><a class="reference" href="#peer-error-alert" id="id144" name="id144">peer_error_alert</a></li>
|
|
<li><a class="reference" href="#invalid-request-alert" id="id145" name="id145">invalid_request_alert</a></li>
|
|
<li><a class="reference" href="#torrent-finished-alert" id="id146" name="id146">torrent_finished_alert</a></li>
|
|
<li><a class="reference" href="#metadata-failed-alert" id="id147" name="id147">metadata_failed_alert</a></li>
|
|
<li><a class="reference" href="#metadata-received-alert" id="id148" name="id148">metadata_received_alert</a></li>
|
|
<li><a class="reference" href="#fastresume-rejected-alert" id="id149" name="id149">fastresume_rejected_alert</a></li>
|
|
<li><a class="reference" href="#peer-blocked-alert" id="id150" name="id150">peer_blocked_alert</a></li>
|
|
<li><a class="reference" href="#storage-moved-alert" id="id151" name="id151">storage_moved_alert</a></li>
|
|
<li><a class="reference" href="#torrent-paused-alert" id="id152" name="id152">torrent_paused_alert</a></li>
|
|
<li><a class="reference" href="#torrent-resumed-alert" id="id153" name="id153">torrent_resumed_alert</a></li>
|
|
<li><a class="reference" href="#save-resume-data-alert" id="id154" name="id154">save_resume_data_alert</a></li>
|
|
<li><a class="reference" href="#save-resume-data-failed-alert" id="id155" name="id155">save_resume_data_failed_alert</a></li>
|
|
<li><a class="reference" href="#dispatcher" id="id156" name="id156">dispatcher</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#exceptions" id="id157" name="id157">exceptions</a><ul>
|
|
<li><a class="reference" href="#invalid-handle" id="id158" name="id158">invalid_handle</a></li>
|
|
<li><a class="reference" href="#duplicate-torrent" id="id159" name="id159">duplicate_torrent</a></li>
|
|
<li><a class="reference" href="#invalid-encoding" id="id160" name="id160">invalid_encoding</a></li>
|
|
<li><a class="reference" href="#type-error" id="id161" name="id161">type_error</a></li>
|
|
<li><a class="reference" href="#invalid-torrent-file" id="id162" name="id162">invalid_torrent_file</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#storage-interface" id="id163" name="id163">storage_interface</a><ul>
|
|
<li><a class="reference" href="#initialize" id="id164" name="id164">initialize()</a></li>
|
|
<li><a class="reference" href="#read" id="id165" name="id165">read()</a></li>
|
|
<li><a class="reference" href="#write" id="id166" name="id166">write()</a></li>
|
|
<li><a class="reference" href="#id12" id="id167" name="id167">move_storage()</a></li>
|
|
<li><a class="reference" href="#verify-resume-data" id="id168" name="id168">verify_resume_data()</a></li>
|
|
<li><a class="reference" href="#write-resume-data" id="id169" name="id169">write_resume_data()</a></li>
|
|
<li><a class="reference" href="#move-slot" id="id170" name="id170">move_slot()</a></li>
|
|
<li><a class="reference" href="#swap-slots" id="id171" name="id171">swap_slots()</a></li>
|
|
<li><a class="reference" href="#swap-slots3" id="id172" name="id172">swap_slots3()</a></li>
|
|
<li><a class="reference" href="#hash-for-slot" id="id173" name="id173">hash_for_slot()</a></li>
|
|
<li><a class="reference" href="#release-files" id="id174" name="id174">release_files()</a></li>
|
|
<li><a class="reference" href="#delete-files" id="id175" name="id175">delete_files()</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#magnet-links" id="id176" name="id176">magnet links</a></li>
|
|
<li><a class="reference" href="#queuing" id="id177" name="id177">queuing</a><ul>
|
|
<li><a class="reference" href="#downloading" id="id178" name="id178">downloading</a></li>
|
|
<li><a class="reference" href="#seeding" id="id179" name="id179">seeding</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#fast-resume" id="id180" name="id180">fast resume</a><ul>
|
|
<li><a class="reference" href="#file-format" id="id181" name="id181">file format</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#threads" id="id182" name="id182">threads</a></li>
|
|
<li><a class="reference" href="#storage-allocation" id="id183" name="id183">storage allocation</a><ul>
|
|
<li><a class="reference" href="#sparse-allocation" id="id184" name="id184">sparse allocation</a></li>
|
|
<li><a class="reference" href="#full-allocation" id="id185" name="id185">full allocation</a></li>
|
|
<li><a class="reference" href="#compact-allocation" id="id186" name="id186">compact allocation</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#extensions" id="id187" name="id187">extensions</a><ul>
|
|
<li><a class="reference" href="#metadata-from-peers" id="id188" name="id188">metadata from peers</a></li>
|
|
<li><a class="reference" href="#http-seeding" id="id189" name="id189">HTTP seeding</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#filename-checks" id="id190" name="id190">filename checks</a></li>
|
|
<li><a class="reference" href="#acknowledgments" id="id191" name="id191">acknowledgments</a></li>
|
|
</ul>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a id="overview" name="overview">overview</a></h1>
|
|
<p>The interface of libtorrent consists of a few classes. The main class is
|
|
the <tt class="docutils literal"><span class="pre">session</span></tt>, it contains the main loop that serves all torrents.</p>
|
|
<p>The basic usage is as follows:</p>
|
|
<ul>
|
|
<li><p class="first">construct a session</p>
|
|
</li>
|
|
<li><p class="first">start DHT, LSD, UPnP, NAT-PMP etc (see <a class="reference" href="#start-dht-stop-dht-set-dht-settings-dht-state">start_dht() stop_dht() set_dht_settings() dht_state()</a>
|
|
<a class="reference" href="#start-lsd-stop-lsd">start_lsd() stop_lsd()</a>, <a class="reference" href="#start-upnp-stop-upnp">start_upnp() stop_upnp()</a> and <a class="reference" href="#start-natpmp-stop-natpmp">start_natpmp() stop_natpmp()</a>)</p>
|
|
</li>
|
|
<li><p class="first">parse .torrent-files and add them to the session (see <a class="reference" href="#bdecode-bencode">bdecode() bencode()</a> and <a class="reference" href="#add-torrent">add_torrent()</a>)</p>
|
|
</li>
|
|
<li><p class="first">main loop (see <a class="reference" href="#session">session</a>)</p>
|
|
<blockquote>
|
|
<ul class="simple">
|
|
<li>query the torrent_handles for progress (see <a class="reference" href="#torrent-handle">torrent_handle</a>)</li>
|
|
<li>query the session for information</li>
|
|
<li>add and remove torrents from the session at run-time</li>
|
|
</ul>
|
|
</blockquote>
|
|
</li>
|
|
<li><p class="first">save resume data for all torrent_handles (optional, see
|
|
<a class="reference" href="#save-resume-data">save_resume_data()</a>)</p>
|
|
</li>
|
|
<li><p class="first">destruct session object</p>
|
|
</li>
|
|
</ul>
|
|
<p>Each class and function is described in this manual.</p>
|
|
<p>For a description on how to create torrent files, see <a class="reference" href="make_torrent.html">make_torrent</a>.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a id="network-primitives" name="network-primitives">network primitives</a></h1>
|
|
<p>There are a few typedefs in the <tt class="docutils literal"><span class="pre">libtorrent</span></tt> namespace which pulls
|
|
in network types from the <tt class="docutils literal"><span class="pre">asio</span></tt> namespace. These are:</p>
|
|
<pre class="literal-block">
|
|
typedef asio::ip::address address;
|
|
typedef asio::ip::address_v4 address_v4;
|
|
typedef asio::ip::address_v6 address_v6;
|
|
using asio::ip::tcp;
|
|
using asio::ip::udp;
|
|
</pre>
|
|
<p>These are declared in the <tt class="docutils literal"><span class="pre"><libtorrent/socket.hpp></span></tt> header.</p>
|
|
<p>The <tt class="docutils literal"><span class="pre">using</span></tt> statements will give easy access to:</p>
|
|
<pre class="literal-block">
|
|
tcp::endpoint
|
|
udp::endpoint
|
|
</pre>
|
|
<p>Which are the endpoint types used in libtorrent. An endpoint is an address
|
|
with an associated port.</p>
|
|
<p>For documentation on these types, please refer to the <a class="reference" href="http://asio.sourceforge.net/asio-0.3.8/doc/asio/reference.html">asio documentation</a>.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a id="session" name="session">session</a></h1>
|
|
<p>The <tt class="docutils literal"><span class="pre">session</span></tt> class has the following synopsis:</p>
|
|
<pre class="literal-block">
|
|
class session: public boost::noncopyable
|
|
{
|
|
|
|
session(fingerprint const& print
|
|
= libtorrent::fingerprint(
|
|
"LT", 0, 1, 0, 0));
|
|
|
|
session(
|
|
fingerprint const& print
|
|
, std::pair<int, int> listen_port_range
|
|
, char const* listen_interface = 0);
|
|
|
|
torrent_handle add_torrent(add_torrent_params const& params);
|
|
|
|
void pause();
|
|
void resume();
|
|
bool is_paused() const;
|
|
|
|
session_proxy abort();
|
|
|
|
enum options_t
|
|
{
|
|
none = 0,
|
|
delete_files = 1
|
|
};
|
|
|
|
void remove_torrent(torrent_handle const& h, int options = none);
|
|
torrent_handle find_torrent(sha_hash const& ih);
|
|
std::vector<torrent_handle> get_torrents() const;
|
|
|
|
void set_settings(session_settings const& settings);
|
|
void set_pe_settings(pe_settings const& 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_max_uploads(int limit);
|
|
void set_max_connections(int limit);
|
|
void set_max_half_open_connections(int limit);
|
|
int max_half_open_connections() const;
|
|
|
|
void set_peer_proxy(proxy_settings const& s);
|
|
void set_web_seed_proxy(proxy_settings const& s);
|
|
void set_tracker_proxy(proxy_settings const& s);
|
|
|
|
proxy_settings const& peer_proxy() const;
|
|
proxy_settings const& web_seed_proxy() const;
|
|
proxy_settings const& tracker_proxy() const;
|
|
|
|
int num_uploads() const;
|
|
int num_connections() const;
|
|
|
|
bool load_asnum_db(char const* file);
|
|
bool load_country_db(char const* file);
|
|
int as_for_ip(address const& adr);
|
|
|
|
void load_state(entry const& ses_state);
|
|
entry state() const;
|
|
|
|
void set_ip_filter(ip_filter const& f);
|
|
|
|
session_status status() const;
|
|
cache_status get_cache_status() const;
|
|
|
|
bool is_listening() const;
|
|
unsigned short listen_port() const;
|
|
bool listen_on(
|
|
std::pair<int, int> const& port_range
|
|
, char const* interface = 0);
|
|
|
|
std::auto_ptr<alert> pop_alert();
|
|
alert const* wait_for_alert(time_duration max_wait);
|
|
void set_alert_mask(int m);
|
|
|
|
void add_extension(boost::function<
|
|
boost::shared_ptr<torrent_plugin>(torrent*)> ext);
|
|
|
|
void start_dht();
|
|
void stop_dht();
|
|
void set_dht_settings(
|
|
dht_settings const& settings);
|
|
entry dht_state() const;
|
|
void add_dht_node(std::pair<std::string
|
|
, int> const& node);
|
|
void add_dht_router(std::pair<std::string
|
|
, int> const& node);
|
|
|
|
void start_lsd();
|
|
void stop_lsd();
|
|
|
|
upnp* start_upnp();
|
|
void stop_upnp();
|
|
|
|
natpmp* start_natpmp();
|
|
void stop_natpmp();
|
|
};
|
|
</pre>
|
|
<p>Once it's created, the session object will spawn the main thread that will do all the work.
|
|
The main thread will be idle as long it doesn't have any torrents to participate in.</p>
|
|
<div class="section">
|
|
<h2><a id="id1" name="id1">session()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
session(fingerprint const& print
|
|
= libtorrent::fingerprint("LT", 0, 1, 0, 0));
|
|
session(fingerprint const& print
|
|
, std::pair<int, int> listen_port_range
|
|
, char const* listen_interface = 0);
|
|
</pre>
|
|
</blockquote>
|
|
<p>If the fingerprint in the first overload is omited, the client will get a default
|
|
fingerprint stating the version of libtorrent. The fingerprint is a short string that will be
|
|
used in the peer-id to identify the client and the client's version. For more details see the
|
|
<a class="reference" href="#fingerprint">fingerprint</a> class. The constructor that only takes a fingerprint will not open a
|
|
listen port for the session, to get it running you'll have to call <tt class="docutils literal"><span class="pre">session::listen_on()</span></tt>.
|
|
The other constructor, that takes a port range and an interface as well as the fingerprint
|
|
will automatically try to listen on a port on the given interface. For more information about
|
|
the parameters, see <tt class="docutils literal"><span class="pre">listen_on()</span></tt> function.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="id2" name="id2">~session()</a></h2>
|
|
<p>The destructor of session will notify all trackers that our torrents have been shut down.
|
|
If some trackers are down, they will time out. All this before the destructor of session
|
|
returns. So, it's advised that any kind of interface (such as windows) are closed before
|
|
destructing the session object. Because it can take a few second for it to finish. The
|
|
timeout can be set with <tt class="docutils literal"><span class="pre">set_settings()</span></tt>.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="pause-resume-is-paused" name="pause-resume-is-paused">pause() resume() is_paused()</a></h2>
|
|
<blockquote>
|
|
<dl class="docutils">
|
|
<dt>::</dt>
|
|
<dd>void pause();
|
|
void resume();
|
|
bool is_paused() const;</dd>
|
|
</dl>
|
|
</blockquote>
|
|
<p>Pausing the session has the same effect as pausing every torrent in it. Resuming
|
|
will restore the torrents to their previous paused state. i.e. the session pause
|
|
state is separate from the torrent pause state. A torrent is inactive if it is
|
|
paused or if the session is paused.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="abort" name="abort">abort()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
session_proxy abort();
|
|
</pre>
|
|
</blockquote>
|
|
<p>In case you want to destruct the session asynchrounously, you can request a session
|
|
destruction proxy. If you don't do this, the destructor of the session object will
|
|
block while the trackers are contacted. If you keep one <tt class="docutils literal"><span class="pre">session_proxy</span></tt> to the
|
|
session when destructing it, the destructor will not block, but start to close down
|
|
the session, the destructor of the proxy will then synchronize the threads. So, the
|
|
destruction of the session is performed from the <tt class="docutils literal"><span class="pre">session</span></tt> destructor call until the
|
|
<tt class="docutils literal"><span class="pre">session_proxy</span></tt> destructor call. The <tt class="docutils literal"><span class="pre">session_proxy</span></tt> does not have any operations
|
|
on it (since the session is being closed down, no operations are allowed on it). The
|
|
only valid operation is calling the destructor:</p>
|
|
<pre class="literal-block">
|
|
class session_proxy
|
|
{
|
|
public:
|
|
session_proxy();
|
|
~session_proxy()
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="add-torrent" name="add-torrent">add_torrent()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
typedef storage_interface* (&storage_constructor_type)(
|
|
file_storage const&, fs::path const&, file_pool&);
|
|
|
|
struct add_torrent_params
|
|
{
|
|
add_torrent_params(storage_constructor_type s);
|
|
|
|
boost::intrusive_ptr<torrent_info> ti;
|
|
char const* tracker_url;
|
|
sha1_hash info_hash;
|
|
char const* name;
|
|
fs::path save_path;
|
|
std::vector<char>* 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);
|
|
</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 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" 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" href="#save-resume-data">save_resume_data()</a> on <a class="reference" href="#torrent-handle">torrent_handle</a>. See <a class="reference" href="#fast-resume">fast resume</a>. The <tt class="docutils literal"><span class="pre">vector</span></tt> that is
|
|
passed in will be swapped into the running torrent instance with <tt class="docutils literal"><span class="pre">std::vector::swap()</span></tt>.</p>
|
|
<p>The <tt class="docutils literal"><span class="pre">storage_mode</span></tt> parameter refers to the layout of the storage for this torrent.
|
|
There are 3 different modes:</p>
|
|
<dl class="docutils">
|
|
<dt>storage_mode_sparse</dt>
|
|
<dd>All pieces will be written to the place where they belong and sparse files
|
|
will be used. This is the recommended, and default mode.</dd>
|
|
<dt>storage_mode_allocate</dt>
|
|
<dd>All pieces will be allocated, zeroes will be written to the files, before
|
|
the data is downloaded and written to the file. This might be useful for
|
|
filesystems that don't support sparse files.</dd>
|
|
<dt>storage_mode_compact</dt>
|
|
<dd>The storage will grow as more pieces are downloaded, and pieces
|
|
are rearranged to finally be in their correct places once the entire torrent has been
|
|
downloaded.</dd>
|
|
</dl>
|
|
<p>For more information, see <a class="reference" href="#storage-allocation">storage allocation</a>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">paused</span></tt> is a boolean that specifies whether or not the torrent is to be started in
|
|
a paused state. I.e. it won't connect to the tracker or any of the peers until it's
|
|
resumed. This is typically a good way of avoiding race conditions when setting
|
|
configuration options on torrents before starting them.</p>
|
|
<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" 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" href="#storage-interface">storage_interface</a>.</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" href="#add-extension">add_extension()</a>).</p>
|
|
<p>The <a class="reference" 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">
|
|
<h2><a id="remove-torrent" name="remove-torrent">remove_torrent()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void remove_torrent(torrent_handle const& h, int options = none);
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">remove_torrent()</span></tt> will close all peer connections associated with the torrent and tell
|
|
the tracker that we've stopped participating in the swarm. The optional second argument
|
|
<tt class="docutils literal"><span class="pre">options</span></tt> can be used to delete all the files downloaded by this torrent. To do this, pass
|
|
in the value <tt class="docutils literal"><span class="pre">session::delete_files</span></tt>. The removal of the torrent is asyncronous, there is
|
|
no guarantee that adding the same torrent immediately after it was removed will not throw
|
|
a <a class="reference" href="#duplicate-torrent">duplicate_torrent</a> exception.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="find-torrent-get-torrents" name="find-torrent-get-torrents">find_torrent() get_torrents()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
torrent_handle find_torrent(sha_hash const& ih);
|
|
std::vector<torrent_handle> get_torrents() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">find_torrent()</span></tt> looks for a torrent with the given info-hash. In case there
|
|
is such a torrent in the session, a torrent_handle to that torrent is returned.
|
|
In case the torrent cannot be found, an invalid torrent_handle is returned.</p>
|
|
<p>See <tt class="docutils literal"><span class="pre">torrent_handle::is_valid()</span></tt> to know if the torrent was found or not.</p>
|
|
<p><tt class="docutils literal"><span class="pre">get_torrents()</span></tt> returns a vector of torrent_handles to all the torrents
|
|
currently in the session.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="set-upload-rate-limit-set-download-rate-limit-upload-rate-limit-download-rate-limit" name="set-upload-rate-limit-set-download-rate-limit-upload-rate-limit-download-rate-limit">set_upload_rate_limit() set_download_rate_limit() upload_rate_limit() download_rate_limit()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void set_upload_rate_limit(int bytes_per_second);
|
|
void set_download_rate_limit(int bytes_per_second);
|
|
int upload_rate_limit() const;
|
|
int download_rate_limit() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">set_upload_rate_limit()</span></tt> set the maximum number of bytes allowed to be
|
|
sent to peers per second. This bandwidth is distributed among all the peers. If
|
|
you don't want to limit upload rate, you can set this to -1 (the default).
|
|
<tt class="docutils literal"><span class="pre">set_download_rate_limit()</span></tt> works the same way but for download rate instead
|
|
of upload rate.
|
|
<tt class="docutils literal"><span class="pre">download_rate_limit()</span></tt> and <tt class="docutils literal"><span class="pre">upload_rate_limit()</span></tt> returns the previously
|
|
set limits.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="set-max-uploads-set-max-connections" name="set-max-uploads-set-max-connections">set_max_uploads() set_max_connections()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void set_max_uploads(int limit);
|
|
void set_max_connections(int limit);
|
|
</pre>
|
|
</blockquote>
|
|
<p>These functions will set a global limit on the number of unchoked peers (uploads)
|
|
and the number of connections opened. The number of connections is set to a hard
|
|
minimum of at least two connections per torrent, so if you set a too low
|
|
connections limit, and open too many torrents, the limit will not be met. The
|
|
number of uploads is at least one per torrent.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="num-uploads-num-connections" name="num-uploads-num-connections">num_uploads() num_connections()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
int num_uploads() const;
|
|
int num_connections() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>Returns the number of currently unchoked peers and the number of connections
|
|
(including half-open ones) respectively.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="set-max-half-open-connections-max-half-open-connections" name="set-max-half-open-connections-max-half-open-connections">set_max_half_open_connections() max_half_open_connections()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void set_max_half_open_connections(int limit);
|
|
int max_half_open_connections() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>Sets the maximum number of half-open connections libtorrent will have when
|
|
connecting to peers. A half-open connection is one where connect() has been
|
|
called, but the connection still hasn't been established (nor failed). Windows
|
|
XP Service Pack 2 sets a default, system wide, limit of the number of half-open
|
|
connections to 10. So, this limit can be used to work nicer together with
|
|
other network applications on that system. The default is to have no limit,
|
|
and passing -1 as the limit, means to have no limit. When limiting the number
|
|
of simultaneous connection attempts, peers will be put in a queue waiting for
|
|
their turn to get connected.</p>
|
|
<p><tt class="docutils literal"><span class="pre">max_half_open_connections()</span></tt> returns the set limit. This limit defaults
|
|
to 8 on windows.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="load-asnum-db-load-country-db-int-as-for-ip" name="load-asnum-db-load-country-db-int-as-for-ip">load_asnum_db() load_country_db() int as_for_ip()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
bool load_asnum_db(char const* file);
|
|
bool load_country_db(char const* file);
|
|
int as_for_ip(address const& adr);
|
|
</pre>
|
|
</blockquote>
|
|
<p>These functions are not available if <tt class="docutils literal"><span class="pre">TORRENT_DISABLE_GEO_IP</span></tt> is defined. They
|
|
expects a path to the <a class="reference" href="http://www.maxmind.com/app/asnum">MaxMind ASN database</a> and <a class="reference" href="http://www.maxmind.com/app/geolitecountry">MaxMind GeoIP database</a>
|
|
respectively. This will be used to look up which AS and country peers belong to.</p>
|
|
<p><tt class="docutils literal"><span class="pre">as_for_ip</span></tt> returns the AS number for the IP address specified. If the IP is not
|
|
in the database or the ASN database is not loaded, 0 is returned.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="load-state-state" name="load-state-state">load_state() state()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void load_state(entry const& ses_state);
|
|
entry state() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>These functions loads and save session state. Currently, the only state
|
|
that's stored is peak download rates for ASes. This map is used to
|
|
determine which order to connect to peers.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="set-ip-filter" name="set-ip-filter">set_ip_filter()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void set_ip_filter(ip_filter const& filter);
|
|
</pre>
|
|
</blockquote>
|
|
<p>Sets a filter that will be used to reject and accept incoming as well as outgoing
|
|
connections based on their originating ip address. The default filter will allow
|
|
connections to any ip address. To build a set of rules for which addresses are
|
|
accepted and not, see <a class="reference" href="#ip-filter">ip_filter</a>.</p>
|
|
<p>Each time a peer is blocked because of the IP filter, a <a class="reference" href="#peer-blocked-alert">peer_blocked_alert</a> is
|
|
generated.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="status" name="status">status()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
session_status status() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">status()</span></tt> returns session wide-statistics and status. The <tt class="docutils literal"><span class="pre">session_status</span></tt>
|
|
struct has the following members:</p>
|
|
<pre class="literal-block">
|
|
struct session_status
|
|
{
|
|
bool has_incoming_connections;
|
|
|
|
float upload_rate;
|
|
float download_rate;
|
|
|
|
float payload_upload_rate;
|
|
float payload_download_rate;
|
|
|
|
size_type total_download;
|
|
size_type total_upload;
|
|
|
|
size_type total_redundant_bytes;
|
|
size_type total_failed_bytes;
|
|
|
|
size_type total_payload_download;
|
|
size_type total_payload_upload;
|
|
|
|
int num_peers;
|
|
int num_unchoked;
|
|
int allowed_upload_slots;
|
|
|
|
int dht_nodes;
|
|
int dht_cache_nodes;
|
|
int dht_torrents;
|
|
int dht_global_nodes;
|
|
};
|
|
</pre>
|
|
<p><tt class="docutils literal"><span class="pre">has_incoming_connections</span></tt> is false as long as no incoming connections have been
|
|
established on the listening socket. Every time you change the listen port, this will
|
|
be reset to false.</p>
|
|
<p><tt class="docutils literal"><span class="pre">upload_rate</span></tt>, <tt class="docutils literal"><span class="pre">download_rate</span></tt>, <tt class="docutils literal"><span class="pre">payload_download_rate</span></tt> and <tt class="docutils literal"><span class="pre">payload_upload_rate</span></tt>
|
|
are the total download and upload rates accumulated from all torrents. The payload
|
|
versions is the payload download only.</p>
|
|
<p><tt class="docutils literal"><span class="pre">total_download</span></tt> and <tt class="docutils literal"><span class="pre">total_upload</span></tt> are the total number of bytes downloaded and
|
|
uploaded to and from all torrents. <tt class="docutils literal"><span class="pre">total_payload_download</span></tt> and <tt class="docutils literal"><span class="pre">total_payload_upload</span></tt>
|
|
are the same thing but where only the payload is considered.</p>
|
|
<p><tt class="docutils literal"><span class="pre">total_redundant_bytes</span></tt> is the number of bytes that has been received more than once.
|
|
This can happen if a request from a peer times out and is requested from a different
|
|
peer, and then received again from the first one. To make this lower, increase the
|
|
<tt class="docutils literal"><span class="pre">request_timeout</span></tt> and the <tt class="docutils literal"><span class="pre">piece_timeout</span></tt> in the session settings.</p>
|
|
<p><tt class="docutils literal"><span class="pre">total_failed_bytes</span></tt> is the number of bytes that was downloaded which later failed
|
|
the hash-check.</p>
|
|
<p><tt class="docutils literal"><span class="pre">num_peers</span></tt> is the total number of peer connections this session has. This includes
|
|
incoming connections that still hasn't sent their handshake or outgoing connections
|
|
that still hasn't completed the TCP connection. This number may be slightly higher
|
|
than the sum of all peers of all torrents because the incoming connections may not
|
|
be assigned a torrent yet.</p>
|
|
<p><tt class="docutils literal"><span class="pre">num_unchoked</span></tt> is the current number of unchoked peers.
|
|
<tt class="docutils literal"><span class="pre">allowed_upload_slots</span></tt> is the current allowed number of unchoked peers.</p>
|
|
<p><tt class="docutils literal"><span class="pre">dht_nodes</span></tt>, <tt class="docutils literal"><span class="pre">dht_cache_nodes</span></tt> and <tt class="docutils literal"><span class="pre">dht_torrents</span></tt> are only available when
|
|
built with DHT support. They are all set to 0 if the DHT isn't running. When
|
|
the DHT is running, <tt class="docutils literal"><span class="pre">dht_nodes</span></tt> is set to the number of nodes in the routing
|
|
table. This number only includes <em>active</em> nodes, not cache nodes. The
|
|
<tt class="docutils literal"><span class="pre">dht_cache_nodes</span></tt> is set to the number of nodes in the node cache. These nodes
|
|
are used to replace the regular nodes in the routing table in case any of them
|
|
becomes unresponsive.</p>
|
|
<p><tt class="docutils literal"><span class="pre">dht_torrents</span></tt> are the number of torrents tracked by the DHT at the moment.</p>
|
|
<p><tt class="docutils literal"><span class="pre">dht_global_nodes</span></tt> is an estimation of the total number of nodes in the DHT
|
|
network.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="get-cache-status" name="get-cache-status">get_cache_status()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
cache_status get_cache_status() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>Returns status of the disk cache for this session.</p>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
struct cache_status
|
|
{
|
|
size_type blocks_written;
|
|
size_type writes;
|
|
size_type blocks_read;
|
|
size_type blocks_read_hit;
|
|
size_type reads;
|
|
int cache_size;
|
|
int read_cache_size;
|
|
};
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">blocks_written</span></tt> is the total number of 16 KiB blocks written to disk
|
|
since this session was started.</p>
|
|
<p><tt class="docutils literal"><span class="pre">writes</span></tt> is the total number of write operations performed since this
|
|
session was started.</p>
|
|
<p>The ratio (<tt class="docutils literal"><span class="pre">blocks_written</span></tt> - <tt class="docutils literal"><span class="pre">writes</span></tt>) / <tt class="docutils literal"><span class="pre">blocks_written</span></tt> represents
|
|
the number of saved write operations per total write operations. i.e. a kind
|
|
of cache hit ratio for the write cahe.</p>
|
|
<p><tt class="docutils literal"><span class="pre">blocks_read</span></tt> is the number of blocks that were requested from the
|
|
bittorrent engine (from peers), that were served from disk or cache.</p>
|
|
<p><tt class="docutils literal"><span class="pre">blocks_read_hit</span></tt> is the number of blocks that were served from cache.</p>
|
|
<p>The ratio <tt class="docutils literal"><span class="pre">blocks_read_hit</span></tt> / <tt class="docutils literal"><span class="pre">blocks_read</span></tt> is the cache hit ratio
|
|
for the read cache.</p>
|
|
<p><tt class="docutils literal"><span class="pre">cache_size</span></tt> is the number of 16 KiB blocks currently in the disk cache.
|
|
This includes both read and write cache.</p>
|
|
<p><tt class="docutils literal"><span class="pre">read_cache_size</span></tt> is the number of 16KiB blocks in the read cache.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="get-cache-info" name="get-cache-info">get_cache_info()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void get_cache_info(sha1_hash const& ih
|
|
, std::vector<cached_piece_info>& ret) const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">get_cache_info()</span></tt> fills out the supplied vector with information for
|
|
each piece that is currently in the disk cache for the torrent with the
|
|
specified info-hash (<tt class="docutils literal"><span class="pre">ih</span></tt>).</p>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
struct cached_piece_info
|
|
{
|
|
int piece;
|
|
std::vector<bool> blocks;
|
|
ptime last_use;
|
|
enum kind_t { read_cache = 0, write_cache = 1 };
|
|
kind_t kind;
|
|
};
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">piece</span></tt> is the piece index for this cache entry.</p>
|
|
<p><tt class="docutils literal"><span class="pre">blocks</span></tt> has one entry for each block in this piece. <tt class="docutils literal"><span class="pre">true</span></tt> represents
|
|
the data for that block being in the disk cache and <tt class="docutils literal"><span class="pre">false</span></tt> means it's not.</p>
|
|
<p><tt class="docutils literal"><span class="pre">last_use</span></tt> is the time when a block was last written to this piece. The older
|
|
a piece is, the more likely it is to be flushed to disk.</p>
|
|
<p><tt class="docutils literal"><span class="pre">kind</span></tt> specifies if this piece is part of the read cache or the write cache.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="is-listening-listen-port-listen-on" name="is-listening-listen-port-listen-on">is_listening() listen_port() listen_on()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
bool is_listening() const;
|
|
unsigned short listen_port() const;
|
|
bool listen_on(
|
|
std::pair<int, int> const& port_range
|
|
, char const* interface = 0);
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">is_listening()</span></tt> will tell you whether or not the session has successfully
|
|
opened a listening port. If it hasn't, this function will return false, and
|
|
then you can use <tt class="docutils literal"><span class="pre">listen_on()</span></tt> to make another try.</p>
|
|
<p><tt class="docutils literal"><span class="pre">listen_port()</span></tt> returns the port we ended up listening on. Since you just pass
|
|
a port-range to the constructor and to <tt class="docutils literal"><span class="pre">listen_on()</span></tt>, to know which port it
|
|
ended up using, you have to ask the session using this function.</p>
|
|
<p><tt class="docutils literal"><span class="pre">listen_on()</span></tt> will change the listen port and/or the listen interface. If the
|
|
session is already listening on a port, this socket will be closed and a new socket
|
|
will be opened with these new settings. The port range is the ports it will try
|
|
to listen on, if the first port fails, it will continue trying the next port within
|
|
the range and so on. The interface parameter can be left as 0, in that case the
|
|
os will decide which interface to listen on, otherwise it should be the ip-address
|
|
of the interface you want the listener socket bound to. <tt class="docutils literal"><span class="pre">listen_on()</span></tt> returns true
|
|
if it managed to open the socket, and false if it failed. If it fails, it will also
|
|
generate an appropriate alert (<a class="reference" href="#listen-failed-alert">listen_failed_alert</a>).</p>
|
|
<p>The interface parameter can also be a hostname that will resolve to the device you
|
|
want to listen on.</p>
|
|
<p>If you're also starting the DHT, it is a good idea to do that after you've called
|
|
<tt class="docutils literal"><span class="pre">listen_on()</span></tt>, since the default listen port for the DHT is the same as the tcp
|
|
listen socket. If you start the DHT first, it will assume the tcp port is free and
|
|
open the udp socket on that port, then later, when <tt class="docutils literal"><span class="pre">listen_on()</span></tt> is called, it
|
|
may turn out that the tcp port is in use. That results in the DHT and the bittorrent
|
|
socket listening on different ports. If the DHT is active when <tt class="docutils literal"><span class="pre">listen_on</span></tt> is
|
|
called, the udp port will be rebound to the new port, if it was configured to use
|
|
the same port as the tcp socket, and if the listen_on call failed to bind to the
|
|
same port that the udp uses.</p>
|
|
<p>The reason why it's a good idea to run the DHT and the bittorrent socket on the same
|
|
port is because that is an assumption that may be used to increase performance. One
|
|
way to accelerate the connecting of peers on windows may be to first ping all peers
|
|
with a DHT ping packet, and connect to those that responds first. On windows one
|
|
can only connect to a few peers at a time because of a built in limitation (in XP
|
|
Service pack 2).</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="pop-alert-set-alert-mask-wait-for-alert" name="pop-alert-set-alert-mask-wait-for-alert">pop_alert() set_alert_mask() wait_for_alert()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
std::auto_ptr<alert> pop_alert();
|
|
alert const* wait_for_alert(time_duration max_wait);
|
|
void set_alert_mask(int m);
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">pop_alert()</span></tt> is used to ask the session if any errors or events has occurred. With
|
|
<tt class="docutils literal"><span class="pre">set_alert_mask()</span></tt> you can filter which alerts to receive through <tt class="docutils literal"><span class="pre">pop_alert()</span></tt>.
|
|
For information about the alert categories, see <a class="reference" href="#alerts">alerts</a>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">wait_for_alert</span></tt> blocks until an alert is available, or for no more than <tt class="docutils literal"><span class="pre">max_wait</span></tt>
|
|
time. If <tt class="docutils literal"><span class="pre">wait_for_alert</span></tt> returns because of the time-out, and no alerts are available,
|
|
it returns 0. If at least one alert was generated, a pointer to that alert is returned.
|
|
The alert is not popped, any subsequent calls to <tt class="docutils literal"><span class="pre">wait_for_alert</span></tt> will return the
|
|
same pointer until the alert is popped by calling <tt class="docutils literal"><span class="pre">pop_alert</span></tt>. This is useful for
|
|
leaving any alert dispatching mechanism independent of this blocking call, the dispatcher
|
|
can be called and it can pop the alert independently.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="add-extension" name="add-extension">add_extension()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void add_extension(boost::function<
|
|
boost::shared_ptr<torrent_plugin>(torrent*, void*)> ext);
|
|
</pre>
|
|
</blockquote>
|
|
<p>This function adds an extension to this session. The argument is a function
|
|
object that is called with a <tt class="docutils literal"><span class="pre">torrent*</span></tt> and which should return a
|
|
<tt class="docutils literal"><span class="pre">boost::shared_ptr<torrent_plugin></span></tt>. To write custom plugins, see
|
|
<a class="reference" href="libtorrent_plugins.html">libtorrent plugins</a>. The main plugins implemented in libtorrent are:</p>
|
|
<dl class="docutils">
|
|
<dt>metadata extension</dt>
|
|
<dd>Allows peers to download the metadata (.torren files) from the swarm
|
|
directly. Makes it possible to join a swarm with just a tracker and
|
|
info-hash.</dd>
|
|
</dl>
|
|
<pre class="literal-block">
|
|
#include <libtorrent/extensions/metadata_transfer.hpp>
|
|
ses.add_extension(&libtorrent::create_metadata_plugin);
|
|
</pre>
|
|
<dl class="docutils">
|
|
<dt>uTorrent metadata</dt>
|
|
<dd>Same as <tt class="docutils literal"><span class="pre">metadata</span> <span class="pre">extension</span></tt> but compatible with uTorrent.</dd>
|
|
</dl>
|
|
<pre class="literal-block">
|
|
#include <libtorrent/extensions/ut_metadata.hpp>
|
|
ses.add_extension(&libtorrent::create_ut_metadata_plugin);
|
|
</pre>
|
|
<dl class="docutils">
|
|
<dt>uTorrent peer exchange</dt>
|
|
<dd>Exchanges peers between clients.</dd>
|
|
</dl>
|
|
<pre class="literal-block">
|
|
#include <libtorrent/extensions/ut_pex.hpp>
|
|
ses.add_extension(&libtorrent::create_ut_pex_plugin);
|
|
</pre>
|
|
<dl class="docutils">
|
|
<dt>smart ban plugin</dt>
|
|
<dd>A plugin that, with a small overhead, can ban peers
|
|
that sends bad data with very high accuracy. Should
|
|
eliminate most problems on poisoned torrents.</dd>
|
|
</dl>
|
|
<pre class="literal-block">
|
|
#include <libtorrent/extensions/smart_ban.hpp>
|
|
ses.add_extension(&libtorrent::create_smart_ban_plugin);
|
|
</pre>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="set-settings-set-pe-settings" name="set-settings-set-pe-settings">set_settings() set_pe_settings()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void set_settings(session_settings const& settings);
|
|
void set_pe_settings(pe_settings const& settings);
|
|
</pre>
|
|
</blockquote>
|
|
<p>Sets the session settings and the packet encryption settings respectively.
|
|
See <a class="reference" href="#session-settings">session_settings</a> and <a class="reference" href="#pe-settings">pe_settings</a> for more information on available
|
|
options.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="set-peer-proxy-set-web-seed-proxy-set-tracker-proxy-set-dht-proxy" name="set-peer-proxy-set-web-seed-proxy-set-tracker-proxy-set-dht-proxy">set_peer_proxy() set_web_seed_proxy() set_tracker_proxy() set_dht_proxy()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void set_peer_proxy(proxy_settings const& s);
|
|
void set_web_seed_proxy(proxy_settings const& s);
|
|
void set_tracker_proxy(proxy_settings const& s);
|
|
void set_dht_proxy(proxy_settings const& s);
|
|
</pre>
|
|
</blockquote>
|
|
<p>The <tt class="docutils literal"><span class="pre">set_dht_proxy</span></tt> is not available when DHT is disabled. These functions
|
|
sets the proxy settings for different kinds of connections, bittorrent peers,
|
|
web seeds, trackers and the DHT traffic.</p>
|
|
<p><tt class="docutils literal"><span class="pre">set_peer_proxy</span></tt> affects regular bittorrent peers. <tt class="docutils literal"><span class="pre">set_web_seed_proxy</span></tt>
|
|
affects only web seeds. see <a class="reference" href="#http-seeding">HTTP seeding</a>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">set_tracker_proxy</span></tt> only affects HTTP tracker connections (UDP tracker
|
|
connections are affected if the given proxy supports UDP, e.g. SOCKS5).</p>
|
|
<p><tt class="docutils literal"><span class="pre">set_dht_proxy</span></tt> affects the DHT messages. Since they are sent over UDP,
|
|
it only has any effect if the proxy supports UDP.</p>
|
|
<p>For more information on what settings are available for proxies, see
|
|
<a class="reference" href="#proxy-settings">proxy_settings</a>.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="peer-proxy-web-seed-proxy-tracker-proxy-dht-proxy" name="peer-proxy-web-seed-proxy-tracker-proxy-dht-proxy">peer_proxy() web_seed_proxy() tracker_proxy() dht_proxy()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
proxy_settings const& peer_proxy() const;
|
|
proxy_settings const& web_seed_proxy() const;
|
|
proxy_settings const& tracker_proxy() const;
|
|
proxy_settings const& dht_proxy() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>These functions returns references to their respective current settings.</p>
|
|
<p>The <tt class="docutils literal"><span class="pre">dht_proxy</span></tt> is not available when DHT is disabled.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="start-dht-stop-dht-set-dht-settings-dht-state" name="start-dht-stop-dht-set-dht-settings-dht-state">start_dht() stop_dht() set_dht_settings() dht_state()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void start_dht(entry const& startup_state);
|
|
void stop_dht();
|
|
void set_dht_settings(dht_settings const& settings);
|
|
entry dht_state() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>These functions are not available in case <tt class="docutils literal"><span class="pre">TORRENT_DISABLE_DHT</span></tt> is
|
|
defined. <tt class="docutils literal"><span class="pre">start_dht</span></tt> starts the dht node and makes the trackerless service
|
|
available to torrents. The startup state is optional and can contain nodes
|
|
and the node id from the previous session. The dht node state is a bencoded
|
|
dictionary with the following entries:</p>
|
|
<dl class="docutils">
|
|
<dt><tt class="docutils literal"><span class="pre">nodes</span></tt></dt>
|
|
<dd>A list of strings, where each string is a node endpoint encoded in binary. If
|
|
the string is 6 bytes long, it is an IPv4 address of 4 bytes, encoded in
|
|
network byte order (big endian), followed by a 2 byte port number (also
|
|
network byte order). If the string is 18 bytes long, it is 16 bytes of IPv6
|
|
address followed by a 2 bytes port number (also network byte order).</dd>
|
|
<dt><tt class="docutils literal"><span class="pre">node-id</span></tt></dt>
|
|
<dd>The node id written as a readable string as a hexadecimal number.</dd>
|
|
</dl>
|
|
<p><tt class="docutils literal"><span class="pre">dht_state</span></tt> will return the current state of the dht node, this can be used
|
|
to start up the node again, passing this entry to <tt class="docutils literal"><span class="pre">start_dht</span></tt>. It is a good
|
|
idea to save this to disk when the session is closed, and read it up again
|
|
when starting.</p>
|
|
<p>If the port the DHT is supposed to listen on is already in use, and exception
|
|
is thrown, <tt class="docutils literal"><span class="pre">asio::error</span></tt>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">stop_dht</span></tt> stops the dht node.</p>
|
|
<p><tt class="docutils literal"><span class="pre">add_dht_node</span></tt> adds a node to the routing table. This can be used if your
|
|
client has its own source of bootstrapping nodes.</p>
|
|
<p><tt class="docutils literal"><span class="pre">set_dht_settings</span></tt> sets some parameters availavle to the dht node. The
|
|
struct has the following members:</p>
|
|
<pre class="literal-block">
|
|
struct dht_settings
|
|
{
|
|
int max_peers_reply;
|
|
int search_branching;
|
|
int service_port;
|
|
int max_fail_count;
|
|
};
|
|
</pre>
|
|
<p><tt class="docutils literal"><span class="pre">max_peers_reply</span></tt> is the maximum number of peers the node will send in
|
|
response to a <tt class="docutils literal"><span class="pre">get_peers</span></tt> message from another node.</p>
|
|
<p><tt class="docutils literal"><span class="pre">search_branching</span></tt> is the number of concurrent search request the node will
|
|
send when announcing and refreshing the routing table. This parameter is
|
|
called alpha in the kademlia paper.</p>
|
|
<p><tt class="docutils literal"><span class="pre">service_port</span></tt> is the udp port the node will listen to. This will default
|
|
to 0, which means the udp listen port will be the same as the tcp listen
|
|
port. This is in general a good idea, since some NAT implementations
|
|
reserves the udp port for any mapped tcp port, and vice versa. NAT-PMP
|
|
guarantees this for example.</p>
|
|
<p><tt class="docutils literal"><span class="pre">max_fail_count</span></tt> is the maximum number of failed tries to contact a node
|
|
before it is removed from the routing table. If there are known working nodes
|
|
that are ready to replace a failing node, it will be replaced immediately,
|
|
this limit is only used to clear out nodes that don't have any node that can
|
|
replace them.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="add-dht-node-add-dht-router" name="add-dht-node-add-dht-router">add_dht_node() add_dht_router()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void add_dht_node(std::pair<std::string, int> const& node);
|
|
void add_dht_router(std::pair<std::string, int> const& node);
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">add_dht_node</span></tt> takes a host name and port pair. That endpoint will be
|
|
pinged, and if a valid DHT reply is received, the node will be added to
|
|
the routing table.</p>
|
|
<p><tt class="docutils literal"><span class="pre">add_dht_router</span></tt> adds the given endpoint to a list of DHT router nodes.
|
|
If a search is ever made while the routing table is empty, those nodes will
|
|
be used as backups. Nodes in the router node list will also never be added
|
|
to the regular routing table, which effectively means they are only used
|
|
for bootstrapping, to keep the load off them.</p>
|
|
<p>An example routing node that you could typically add is
|
|
<tt class="docutils literal"><span class="pre">router.bittorrent.com</span></tt>.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="start-lsd-stop-lsd" name="start-lsd-stop-lsd">start_lsd() stop_lsd()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void start_lsd();
|
|
void stop_lsd();
|
|
</pre>
|
|
</blockquote>
|
|
<p>Starts and stops Local Service Discovery. This service will broadcast
|
|
the infohashes of all the non-private torrents on the local network to
|
|
look for peers on the same swarm within multicast reach.</p>
|
|
<p>It is turned off by default.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="start-upnp-stop-upnp" name="start-upnp-stop-upnp">start_upnp() stop_upnp()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
upnp* start_upnp();
|
|
void stop_upnp();
|
|
</pre>
|
|
</blockquote>
|
|
<p>Starts and stops the UPnP service. When started, the listen port and the DHT
|
|
port are attempted to be forwarded on local UPnP router devices.</p>
|
|
<p>The upnp object returned by <tt class="docutils literal"><span class="pre">start_upnp()</span></tt> can be used to add and remove
|
|
arbitrary port mappings. Mapping status is returned through the
|
|
<a class="reference" href="#portmap-alert">portmap_alert</a> and the <a class="reference" href="#portmap-error-alert">portmap_error_alert</a>. The object will be valid until
|
|
<tt class="docutils literal"><span class="pre">stop_upnp()</span></tt> is called. See <a class="reference" href="#upnp-and-nat-pmp">UPnP and NAT-PMP</a>.</p>
|
|
<p>It is off by default.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="start-natpmp-stop-natpmp" name="start-natpmp-stop-natpmp">start_natpmp() stop_natpmp()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
natpmp* start_natpmp();
|
|
void stop_natpmp();
|
|
</pre>
|
|
</blockquote>
|
|
<p>Starts and stops the NAT-PMP service. When started, the listen port and the DHT
|
|
port are attempted to be forwarded on the router through NAT-PMP.</p>
|
|
<p>The natpmp object returned by <tt class="docutils literal"><span class="pre">start_natpmp()</span></tt> can be used to add and remove
|
|
arbitrary port mappings. Mapping status is returned through the
|
|
<a class="reference" href="#portmap-alert">portmap_alert</a> and the <a class="reference" href="#portmap-error-alert">portmap_error_alert</a>. The object will be valid until
|
|
<tt class="docutils literal"><span class="pre">stop_natpmp()</span></tt> is called. See <a class="reference" href="#upnp-and-nat-pmp">UPnP and NAT-PMP</a>.</p>
|
|
<p>It is off by default.</p>
|
|
</div>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a id="entry" name="entry">entry</a></h1>
|
|
<p>The <tt class="docutils literal"><span class="pre">entry</span></tt> class represents one node in a bencoded hierarchy. It works as a
|
|
variant type, it can be either a list, a dictionary (<tt class="docutils literal"><span class="pre">std::map</span></tt>), an integer
|
|
or a string. This is its synopsis:</p>
|
|
<pre class="literal-block">
|
|
class entry
|
|
{
|
|
public:
|
|
|
|
typedef std::map<std::string, entry> dictionary_type;
|
|
typedef std::string string_type;
|
|
typedef std::list<entry> list_type;
|
|
typedef size_type integer_type;
|
|
|
|
enum data_type
|
|
{
|
|
int_t,
|
|
string_t,
|
|
list_t,
|
|
dictionary_t,
|
|
undefined_t
|
|
};
|
|
|
|
data_type type() const;
|
|
|
|
entry(dictionary_type const&);
|
|
entry(string_type const&);
|
|
entry(list_type const&);
|
|
entry(integer_type const&);
|
|
|
|
entry();
|
|
entry(data_type t);
|
|
entry(entry const& e);
|
|
~entry();
|
|
|
|
void operator=(entry const& e);
|
|
void operator=(dictionary_type const&);
|
|
void operator=(string_type const&);
|
|
void operator=(list_type const&);
|
|
void operator=(integer_type const&);
|
|
|
|
integer_type& integer();
|
|
integer_type const& integer() const;
|
|
string_type& string();
|
|
string_type const& string() const;
|
|
list_type& list();
|
|
list_type const& list() const;
|
|
dictionary_type& dict();
|
|
dictionary_type const& dict() const;
|
|
|
|
// these functions requires that the entry
|
|
// is a dictionary, otherwise they will throw
|
|
entry& operator[](char const* key);
|
|
entry& operator[](std::string const& key);
|
|
entry const& operator[](char const* key) const;
|
|
entry const& operator[](std::string const& key) const;
|
|
entry* find_key(char const* key);
|
|
entry const* find_key(char const* key) const;
|
|
|
|
void print(std::ostream& os, int indent = 0) const;
|
|
};
|
|
</pre>
|
|
<p><em>TODO: finish documentation of entry.</em></p>
|
|
<div class="section">
|
|
<h2><a id="integer-string-list-dict-type" name="integer-string-list-dict-type">integer() string() list() dict() type()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
integer_type& integer();
|
|
integer_type const& integer() const;
|
|
string_type& string();
|
|
string_type const& string() const;
|
|
list_type& list();
|
|
list_type const& list() const;
|
|
dictionary_type& dict();
|
|
dictionary_type const& dict() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>The <tt class="docutils literal"><span class="pre">integer()</span></tt>, <tt class="docutils literal"><span class="pre">string()</span></tt>, <tt class="docutils literal"><span class="pre">list()</span></tt> and <tt class="docutils literal"><span class="pre">dict()</span></tt> functions
|
|
are accessors that return the respective type. If the <tt class="docutils literal"><span class="pre">entry</span></tt> object isn't of the
|
|
type you request, the accessor will throw <a class="reference" href="#type-error">type_error</a> (which derives from
|
|
<tt class="docutils literal"><span class="pre">std::runtime_error</span></tt>). You can ask an <tt class="docutils literal"><span class="pre">entry</span></tt> for its type through the
|
|
<tt class="docutils literal"><span class="pre">type()</span></tt> function.</p>
|
|
<p>The <tt class="docutils literal"><span class="pre">print()</span></tt> function is there for debug purposes only.</p>
|
|
<p>If you want to create an <tt class="docutils literal"><span class="pre">entry</span></tt> you give it the type you want it to have in its
|
|
constructor, and then use one of the non-const accessors to get a reference which you then
|
|
can assign the value you want it to have.</p>
|
|
<p>The typical code to get info from a torrent file will then look like this:</p>
|
|
<pre class="literal-block">
|
|
entry torrent_file;
|
|
// ...
|
|
|
|
// throws if this is not a dictionary
|
|
entry::dictionary_type const& dict = torrent_file.dict();
|
|
entry::dictionary_type::const_iterator i;
|
|
i = dict.find("announce");
|
|
if (i != dict.end())
|
|
{
|
|
std::string tracker_url = i->second.string();
|
|
std::cout << tracker_url << "\n";
|
|
}
|
|
</pre>
|
|
<p>The following code is equivalent, but a little bit shorter:</p>
|
|
<pre class="literal-block">
|
|
entry torrent_file;
|
|
// ...
|
|
|
|
// throws if this is not a dictionary
|
|
if (entry* i = torrent_file.find_key("announce"))
|
|
{
|
|
std::string tracker_url = i->string();
|
|
std::cout << tracker_url << "\n";
|
|
}
|
|
</pre>
|
|
<p>To make it easier to extract information from a torrent file, the class <a class="reference" href="#torrent-info">torrent_info</a>
|
|
exists.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="operator" name="operator">operator[]</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
entry& operator[](char const* key);
|
|
entry& operator[](std::string const& key);
|
|
entry const& operator[](char const* key) const;
|
|
entry const& operator[](std::string const& key) const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>All of these functions requires the entry to be a dictionary, if it isn't they
|
|
will throw <tt class="docutils literal"><span class="pre">libtorrent::type_error</span></tt>.</p>
|
|
<p>The non-const versions of the <tt class="docutils literal"><span class="pre">operator[]</span></tt> will return a reference to either
|
|
the existing element at the given key or, if there is no element with the
|
|
given key, a reference to a newly inserted element at that key.</p>
|
|
<p>The const version of <tt class="docutils literal"><span class="pre">operator[]</span></tt> will only return a reference to an
|
|
existing element at the given key. If the key is not found, it will throw
|
|
<tt class="docutils literal"><span class="pre">libtorrent::type_error</span></tt>.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="find-key" name="find-key">find_key()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
entry* find_key(char const* key);
|
|
entry const* find_key(char const* key) const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>These functions requires the entry to be a dictionary, if it isn't they
|
|
will throw <tt class="docutils literal"><span class="pre">libtorrent::type_error</span></tt>.</p>
|
|
<p>They will look for an element at the given key in the dictionary, if the
|
|
element cannot be found, they will return 0. If an element with the given
|
|
key is found, the return a pointer to it.</p>
|
|
</div>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a id="torrent-info" name="torrent-info">torrent_info</a></h1>
|
|
<p>In previous versions of libtorrent, this class was also used for creating
|
|
torrent files. This functionality has been moved to <tt class="docutils literal"><span class="pre">create_torrent</span></tt>, see
|
|
<a class="reference" href="make_torrent.html">make_torrent</a>.</p>
|
|
<p>The <tt class="docutils literal"><span class="pre">torrent_info</span></tt> has the following synopsis:</p>
|
|
<pre class="literal-block">
|
|
class torrent_info
|
|
{
|
|
public:
|
|
|
|
torrent_info(sha1_hash const& info_hash);
|
|
torrent_info(lazy_entry const& torrent_file);
|
|
torrent_info(char const* buffer, int size);
|
|
torrent_info(boost::filesystem::path const& filename);
|
|
|
|
void add_tracker(std::string const& url, int tier = 0);
|
|
std::vector<announce_entry> const& trackers() const;
|
|
|
|
file_storage const& files() const;
|
|
|
|
typedef file_storage::iterator file_iterator;
|
|
typedef file_storage::reverse_iterator reverse_file_iterator;
|
|
|
|
file_iterator begin_files() const;
|
|
file_iterator end_files() const;
|
|
reverse_file_iterator rbegin_files() const;
|
|
reverse_file_iterator rend_files() const;
|
|
|
|
int num_files() const;
|
|
file_entry const& file_at(int index) const;
|
|
|
|
std::vector<file_slice> map_block(int piece, size_type offset
|
|
, int size) const;
|
|
peer_request map_file(int file_index, size_type file_offset
|
|
, int size) const;
|
|
|
|
bool priv() const;
|
|
|
|
std::vector<std::string> const& url_seeds() const;
|
|
|
|
size_type total_size() const;
|
|
int piece_length() const;
|
|
int num_pieces() const;
|
|
sha1_hash const& info_hash() const;
|
|
std::string const& name() const;
|
|
std::string const& comment() const;
|
|
std::string const& creator() const;
|
|
|
|
std::vector<std::pair<std::string, int> > const& nodes() const;
|
|
void add_node(std::pair<std::string, int> const& node);
|
|
|
|
boost::optional<boost::posix_time::ptime>
|
|
creation_date() const;
|
|
|
|
int piece_size(unsigned int index) const;
|
|
sha1_hash const& hash_for_piece(unsigned int index) const;
|
|
char const* hash_for_piece_ptr(unsigned int index) const;
|
|
|
|
boost::shared_array<char> metadata() const;
|
|
int metadata_size() const;
|
|
};
|
|
</pre>
|
|
<div class="section">
|
|
<h2><a id="id3" name="id3">torrent_info()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
torrent_info(sha1_hash const& info_hash);
|
|
torrent_info(lazy_entry const& torrent_file);
|
|
torrent_info(char const* buffer, int size);
|
|
torrent_info(boost::filesystem::path const& filename);
|
|
</pre>
|
|
</blockquote>
|
|
<p>The constructor that takes an info-hash will initialize the info-hash to the given value,
|
|
but leave all other fields empty. This is used internally when downloading torrents without
|
|
the metadata. The metadata will be created by libtorrent as soon as it has been downloaded
|
|
from the swarm.</p>
|
|
<p>The constructor that takes a <tt class="docutils literal"><span class="pre">lazy_entry</span></tt> will create a <tt class="docutils literal"><span class="pre">torrent_info</span></tt> object from the
|
|
information found in the given torrent_file. The <tt class="docutils literal"><span class="pre">lazy_entry</span></tt> represents a tree node in
|
|
an bencoded file. To load an ordinary .torrent file
|
|
into a <tt class="docutils literal"><span class="pre">lazy_entry</span></tt>, use lazy_bdecode(), see <a class="reference" href="#bdecode-bencode">bdecode() bencode()</a>.</p>
|
|
<p>The version that takes a buffer pointer and a size will decode it as a .torrent file and
|
|
initialize the torrent_info object for you.</p>
|
|
<p>The version that takes a filename will simply load the torrent file and decode it inside
|
|
the constructor, for convenience. This might not be the most suitable for applications that
|
|
want to be able to report detailed errors on what might go wrong.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="add-tracker" name="add-tracker">add_tracker()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void add_tracker(std::string const& url, int tier = 0);
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">add_tracker()</span></tt> adds a tracker to the announce-list. The <tt class="docutils literal"><span class="pre">tier</span></tt> determines the order in
|
|
which the trackers are to be tried. For more information see <a class="reference" href="#trackers">trackers()</a>.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="files" name="files">files()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
file_storage const& file() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>The <tt class="docutils literal"><span class="pre">file_storage</span></tt> object contains the information on how to map the pieces to
|
|
files. It is separated from the <tt class="docutils literal"><span class="pre">torrent_info</span></tt> object because when creating torrents
|
|
a storage object needs to be created without having a torrent file. When renaming files
|
|
in a storage, the storage needs to make its own copy of the <tt class="docutils literal"><span class="pre">file_storage</span></tt> in order
|
|
to make its mapping differ from the one in the torrent file.</p>
|
|
<p>For more information on the <tt class="docutils literal"><span class="pre">file_storage</span></tt> object, see the separate document on how
|
|
to create torrents.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="begin-files-end-files-rbegin-files-rend-files" name="begin-files-end-files-rbegin-files-rend-files">begin_files() end_files() rbegin_files() rend_files()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
file_iterator begin_files() const;
|
|
file_iterator end_files() const;
|
|
reverse_file_iterator rbegin_files() const;
|
|
reverse_file_iterator rend_files() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>This class will need some explanation. First of all, to get a list of all files
|
|
in the torrent, you can use <tt class="docutils literal"><span class="pre">begin_files()</span></tt>, <tt class="docutils literal"><span class="pre">end_files()</span></tt>,
|
|
<tt class="docutils literal"><span class="pre">rbegin_files()</span></tt> and <tt class="docutils literal"><span class="pre">rend_files()</span></tt>. These will give you standard vector
|
|
iterators with the type <tt class="docutils literal"><span class="pre">file_entry</span></tt>.</p>
|
|
<pre class="literal-block">
|
|
struct file_entry
|
|
{
|
|
boost::filesystem::path path;
|
|
size_type offset;
|
|
size_type size;
|
|
size_type file_base;
|
|
boost::shared_ptr<const boost::filesystem::path> orig_path;
|
|
};
|
|
</pre>
|
|
<p>The <tt class="docutils literal"><span class="pre">path</span></tt> is the full (relative) path of each file. i.e. if it is a multi-file
|
|
torrent, all the files starts with a directory with the same name as <tt class="docutils literal"><span class="pre">torrent_info::name()</span></tt>.
|
|
The filenames are encoded with UTF-8.</p>
|
|
<p><tt class="docutils literal"><span class="pre">size</span></tt> is the size of the file (in bytes) and <tt class="docutils literal"><span class="pre">offset</span></tt> is the byte offset
|
|
of the file within the torrent. i.e. the sum of all the sizes of the files
|
|
before it in the list.</p>
|
|
<p><tt class="docutils literal"><span class="pre">file_base</span></tt> is the offset in the file where the storage should start. The normal
|
|
case is to have this set to 0, so that the storage starts saving data at the start
|
|
if the file. In cases where multiple files are mapped into the same file though,
|
|
the <tt class="docutils literal"><span class="pre">file_base</span></tt> should be set to an offset so that the different regions do
|
|
not overlap. This is used when mapping "unselected" files into a so-called part
|
|
file.</p>
|
|
<p><tt class="docutils literal"><span class="pre">orig_path</span></tt> is set to 0 in case the path element is an exact copy of that
|
|
found in the metadata. In case the path in the original metadata was
|
|
incorrectly encoded, and had to be fixed in order to be acceptable utf-8,
|
|
the original string is preserved in <tt class="docutils literal"><span class="pre">orig_path</span></tt>. The reason to keep it
|
|
is to be able to reproduce the info-section exactly, with the correct
|
|
info-hash.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="num-files-file-at" name="num-files-file-at">num_files() file_at()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
int num_files() const;
|
|
file_entry const& file_at(int index) const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>If you need index-access to files you can use the <tt class="docutils literal"><span class="pre">num_files()</span></tt> and <tt class="docutils literal"><span class="pre">file_at()</span></tt>
|
|
to access files using indices.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="map-block" name="map-block">map_block()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
std::vector<file_slice> map_block(int piece, size_type offset
|
|
, int size) const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>This function will map a piece index, a byte offset within that piece and
|
|
a size (in bytes) into the corresponding files with offsets where that data
|
|
for that piece is supposed to be stored.</p>
|
|
<p>The file slice struct looks like this:</p>
|
|
<pre class="literal-block">
|
|
struct file_slice
|
|
{
|
|
int file_index;
|
|
size_type offset;
|
|
size_type size;
|
|
};
|
|
</pre>
|
|
<p>The <tt class="docutils literal"><span class="pre">file_index</span></tt> refers to the index of the file (in the torrent_info).
|
|
To get the path and filename, use <tt class="docutils literal"><span class="pre">file_at()</span></tt> and give the <tt class="docutils literal"><span class="pre">file_index</span></tt>
|
|
as argument. The <tt class="docutils literal"><span class="pre">offset</span></tt> is the byte offset in the file where the range
|
|
starts, and <tt class="docutils literal"><span class="pre">size</span></tt> is the number of bytes this range is. The size + offset
|
|
will never be greater than the file size.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="map-file" name="map-file">map_file()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
peer_request map_file(int file_index, size_type file_offset
|
|
, int size) const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>This function will map a range in a specific file into a range in the torrent.
|
|
The <tt class="docutils literal"><span class="pre">file_offset</span></tt> parameter is the offset in the file, given in bytes, where
|
|
0 is the start of the file.
|
|
The <tt class="docutils literal"><span class="pre">peer_request</span></tt> structure looks like this:</p>
|
|
<pre class="literal-block">
|
|
struct peer_request
|
|
{
|
|
int piece;
|
|
int start;
|
|
int length;
|
|
bool operator==(peer_request const& r) const;
|
|
};
|
|
</pre>
|
|
<p><tt class="docutils literal"><span class="pre">piece</span></tt> is the index of the piece in which the range starts.
|
|
<tt class="docutils literal"><span class="pre">start</span></tt> is the offset within that piece where the range starts.
|
|
<tt class="docutils literal"><span class="pre">length</span></tt> is the size of the range, in bytes.</p>
|
|
<p>The input range is assumed to be valid within the torrent. <tt class="docutils literal"><span class="pre">file_offset</span></tt>
|
|
+ <tt class="docutils literal"><span class="pre">size</span></tt> is not allowed to be greater than the file size. <tt class="docutils literal"><span class="pre">file_index</span></tt>
|
|
must refer to a valid file, i.e. it cannot be >= <tt class="docutils literal"><span class="pre">num_files()</span></tt>.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="url-seeds-add-url-seed" name="url-seeds-add-url-seed">url_seeds() add_url_seed()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
std::vector<std::string> const& url_seeds() const;
|
|
void add_url_seed(std::string const& url);
|
|
</pre>
|
|
</blockquote>
|
|
<p>If there are any url-seeds in this torrent, <tt class="docutils literal"><span class="pre">url_seeds()</span></tt> will return a
|
|
vector of those urls. If you're creating a torrent file, <tt class="docutils literal"><span class="pre">add_url_seed()</span></tt>
|
|
adds one url to the list of url-seeds. Currently, the only transport protocol
|
|
supported for the url is http.</p>
|
|
<p>See <a class="reference" href="#http-seeding">HTTP seeding</a> for more information.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="trackers" name="trackers">trackers()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
std::vector<announce_entry> const& trackers() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>The <tt class="docutils literal"><span class="pre">trackers()</span></tt> function will return a sorted vector of <tt class="docutils literal"><span class="pre">announce_entry</span></tt>.
|
|
Each announce entry contains a string, which is the tracker url, and a tier index. The
|
|
tier index is the high-level priority. No matter which trackers that works or not, the
|
|
ones with lower tier will always be tried before the one with higher tier number.</p>
|
|
<pre class="literal-block">
|
|
struct announce_entry
|
|
{
|
|
announce_entry(std::string const& url);
|
|
std::string url;
|
|
int tier;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="total-size-piece-length-piece-size-num-pieces" name="total-size-piece-length-piece-size-num-pieces">total_size() piece_length() piece_size() num_pieces()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
size_type total_size() const;
|
|
int piece_length() const;
|
|
int piece_size(unsigned int index) const;
|
|
int num_pieces() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">total_size()</span></tt>, <tt class="docutils literal"><span class="pre">piece_length()</span></tt> and <tt class="docutils literal"><span class="pre">num_pieces()</span></tt> returns the total
|
|
number of bytes the torrent-file represents (all the files in it), the number of byte for
|
|
each piece and the total number of pieces, respectively. The difference between
|
|
<tt class="docutils literal"><span class="pre">piece_size()</span></tt> and <tt class="docutils literal"><span class="pre">piece_length()</span></tt> is that <tt class="docutils literal"><span class="pre">piece_size()</span></tt> takes
|
|
the piece index as argument and gives you the exact size of that piece. It will always
|
|
be the same as <tt class="docutils literal"><span class="pre">piece_length()</span></tt> except in the case of the last piece, which may
|
|
be smaller.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="hash-for-piece-hash-for-piece-ptr-info-hash" name="hash-for-piece-hash-for-piece-ptr-info-hash">hash_for_piece() hash_for_piece_ptr() info_hash()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
size_type piece_size(unsigned int index) const;
|
|
sha1_hash const& hash_for_piece(unsigned int index) const;
|
|
char const* hash_for_piece_ptr(unsigned int index) const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">hash_for_piece()</span></tt> takes a piece-index and returns the 20-bytes sha1-hash for that
|
|
piece and <tt class="docutils literal"><span class="pre">info_hash()</span></tt> returns the 20-bytes sha1-hash for the info-section of the
|
|
torrent file. For more information on the <tt class="docutils literal"><span class="pre">sha1_hash</span></tt>, see the <a class="reference" href="#big-number">big_number</a> class.
|
|
<tt class="docutils literal"><span class="pre">hash_for_piece_ptr()</span></tt> returns a pointer to the 20 byte sha1 digest for the piece.
|
|
Note that the string is not null-terminated.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="name-comment-creation-date-creator" name="name-comment-creation-date-creator">name() comment() creation_date() creator()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
std::string const& name() const;
|
|
std::string const& comment() const;
|
|
boost::optional<boost::posix_time::ptime> creation_date() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">name()</span></tt> returns the name of the torrent.</p>
|
|
<p><tt class="docutils literal"><span class="pre">comment()</span></tt> returns the comment associated with the torrent. If there's no comment,
|
|
it will return an empty string. <tt class="docutils literal"><span class="pre">creation_date()</span></tt> returns a <a class="reference" href="http://www.boost.org/doc/html/date_time/posix_time.html#date_time.posix_time.ptime_class">boost::posix_time::ptime</a>
|
|
object, representing the time when this torrent file was created. If there's no time stamp
|
|
in the torrent file, this will return a date of January 1:st 1970.</p>
|
|
<p>Both the name and the comment is UTF-8 encoded strings.</p>
|
|
<p><tt class="docutils literal"><span class="pre">creator()</span></tt> returns the creator string in the torrent. If there is no creator string
|
|
it will return an empty string.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="priv" name="priv">priv()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
bool priv() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">priv()</span></tt> returns true if this torrent is private. i.e., it should not be
|
|
distributed on the trackerless network (the kademlia DHT).</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="nodes" name="nodes">nodes()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
std::vector<std::pair<std::string, int> > const& nodes() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>If this torrent contains any DHT nodes, they are put in this vector in their original
|
|
form (host name and port number).</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="add-node" name="add-node">add_node()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void add_node(std::pair<std::string, int> const& node);
|
|
</pre>
|
|
</blockquote>
|
|
<p>This is used when creating torrent. Use this to add a known DHT node. It may
|
|
be used, by the client, to bootstrap into the DHT network.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="metadata-metadata-size" name="metadata-metadata-size">metadata() metadata_size()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
boost::shared_array<char> metadata() const;
|
|
int metadata_size() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">metadata()</span></tt> returns a the raw info section of the torrent file. The size
|
|
of the metadata is returned by <tt class="docutils literal"><span class="pre">metadata_size()</span></tt>.</p>
|
|
</div>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a id="torrent-handle" name="torrent-handle">torrent_handle</a></h1>
|
|
<p>You will usually have to store your torrent handles somewhere, since it's the
|
|
object through which you retrieve information about the torrent and aborts the torrent.
|
|
Its declaration looks like this:</p>
|
|
<pre class="literal-block">
|
|
struct torrent_handle
|
|
{
|
|
torrent_handle();
|
|
|
|
torrent_status status();
|
|
void file_progress(std::vector<size_type>& fp);
|
|
void get_download_queue(std::vector<partial_piece_info>& queue) const;
|
|
void get_peer_info(std::vector<peer_info>& v) const;
|
|
torrent_info const& get_torrent_info() const;
|
|
bool is_valid() const;
|
|
|
|
std::string name() const;
|
|
|
|
void save_resume_data() const;
|
|
void force_reannounce() const;
|
|
void force_reannounce(boost::posix_time::time_duration) const;
|
|
void scrape_tracker() const;
|
|
void connect_peer(asio::ip::tcp::endpoint const& adr, int source = 0) const;
|
|
|
|
void set_tracker_login(std::string const& username
|
|
, std::string const& password) const;
|
|
|
|
std::vector<announce_entry> const& trackers() const;
|
|
void replace_trackers(std::vector<announce_entry> const&);
|
|
|
|
void add_url_seed(std::string const& url);
|
|
void remove_url_seed(std::string const& url);
|
|
std::set<std::string> url_seeds() const;
|
|
|
|
void set_ratio(float ratio) const;
|
|
void set_max_uploads(int max_uploads) const;
|
|
void set_max_connections(int max_connections) const;
|
|
void set_upload_limit(int limit) const;
|
|
int upload_limit() const;
|
|
void set_download_limit(int limit) const;
|
|
int download_limit() const;
|
|
void set_sequential_download(bool sd) const;
|
|
bool is_sequential_download() const;
|
|
|
|
void set_peer_upload_limit(asio::ip::tcp::endpoint ip, int limit) const;
|
|
void set_peer_download_limit(asio::ip::tcp::endpoint ip, int limit) const;
|
|
|
|
int queue_position() const;
|
|
void queue_position_up() const;
|
|
void queue_position_down() const;
|
|
void queue_position_top() const;
|
|
void queue_position_bottom() const;
|
|
|
|
void use_interface(char const* net_interface) const;
|
|
|
|
void pause() const;
|
|
void resume() const;
|
|
bool is_paused() const;
|
|
bool is_seed() const;
|
|
void force_recheck() const;
|
|
void clear_error() const;
|
|
|
|
void resolve_countries(bool r);
|
|
bool resolve_countries() const;
|
|
|
|
void piece_priority(int index, int priority) const;
|
|
int piece_priority(int index) const;
|
|
void prioritize_pieces(std::vector<int> const& pieces) const;
|
|
std::vector<int> piece_priorities() const;
|
|
|
|
void file_priority(int index, int priority) const;
|
|
int file_priority(int index) const;
|
|
void prioritize_files(std::vector<int> const& files) const;
|
|
std::vector<int> file_priorities() const;
|
|
|
|
bool is_auto_managed() const;
|
|
void auto_managed(bool m) const;
|
|
|
|
bool has_metadata() const;
|
|
|
|
boost::filesystem::path save_path() const;
|
|
void move_storage(boost::filesystem::path const& save_path) const;
|
|
|
|
sha1_hash info_hash() const;
|
|
|
|
bool operator==(torrent_handle const&) const;
|
|
bool operator!=(torrent_handle const&) const;
|
|
bool operator<(torrent_handle const&) const;
|
|
};
|
|
</pre>
|
|
<p>The default constructor will initialize the handle to an invalid state. Which
|
|
means you cannot perform any operation on it, unless you first assign it a
|
|
valid handle. If you try to perform any operation on an uninitialized handle,
|
|
it will throw <tt class="docutils literal"><span class="pre">invalid_handle</span></tt>.</p>
|
|
<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" href="#invalid-handle">invalid_handle</a>
|
|
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>
|
|
<div class="section">
|
|
<h2><a id="piece-priority-prioritize-pieces-piece-priorities" name="piece-priority-prioritize-pieces-piece-priorities">piece_priority() prioritize_pieces() piece_priorities()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void piece_priority(int index, int priority) const;
|
|
int piece_priority(int index) const;
|
|
void prioritize_pieces(std::vector<int> const& pieces) const;
|
|
std::vector<int> piece_priorities() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>These functions are used to set and get the prioritiy of individual pieces.
|
|
By default all pieces have priority 1. That means that the random rarest
|
|
first algorithm is effectively active for all pieces. You may however
|
|
change the priority of individual pieces. There are 8 different priority
|
|
levels:</p>
|
|
<blockquote>
|
|
<ol class="arabic simple" start="0">
|
|
<li>piece is not downloaded at all</li>
|
|
<li>normal priority. Download order is dependent on availability</li>
|
|
<li>higher than normal priority. Pieces are preferred over pieces with
|
|
the same availability, but not over pieces with lower availability</li>
|
|
<li>pieces are as likely to be picked as partial pieces.</li>
|
|
<li>pieces are preferred over partial pieces, but not over pieces with
|
|
lower availability</li>
|
|
<li><em>currently the same as 4</em></li>
|
|
<li>piece is as likely to be picked as any piece with availability 1</li>
|
|
<li>maximum priority, availability is disregarded, the piece is preferred
|
|
over any other piece with lower priority</li>
|
|
</ol>
|
|
</blockquote>
|
|
<p>The exact definitions of these priorities are implementation details, and
|
|
subject to change. The interface guarantees that higher number means higher
|
|
priority, and that 0 means do not download.</p>
|
|
<p><tt class="docutils literal"><span class="pre">piece_priority</span></tt> sets or gets the priority for an individual piece,
|
|
specified by <tt class="docutils literal"><span class="pre">index</span></tt>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">prioritize_pieces</span></tt> takes a vector of integers, one integer per piece in
|
|
the torrent. All the piece priorities will be updated with the priorities
|
|
in the vector.</p>
|
|
<p><tt class="docutils literal"><span class="pre">piece_priorities</span></tt> returns a vector with one element for each piece in the
|
|
torrent. Each element is the current priority of that piece.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="file-priority-prioritize-files-file-priorities" name="file-priority-prioritize-files-file-priorities">file_priority() prioritize_files() file_priorities()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void file_priority(int index, int priority) const;
|
|
int file_priority(int index) const;
|
|
void prioritize_files(std::vector<int> const& files) const;
|
|
std::vector<int> file_priorities() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">index</span></tt> must be in the range [0, number_of_files).</p>
|
|
<p><tt class="docutils literal"><span class="pre">file_priority</span></tt> queries or sets the priority of file <tt class="docutils literal"><span class="pre">index</span></tt>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">prioritize_files</span></tt> takes a vector that has at as many elements as there are
|
|
files in the torrent. Each entry is the priority of that file. The function
|
|
sets the priorities of all the pieces in the torrent based on the vector.</p>
|
|
<p><tt class="docutils literal"><span class="pre">file_priorities</span></tt> returns a vector with the priorities of all files.</p>
|
|
<p>The priority values are the same as for <tt class="docutils literal"><span class="pre">piece_priority</span></tt>.</p>
|
|
<p>Whenever a file priority is changed, all other piece priorities are reset
|
|
to match the file priorities. In order to maintain sepcial priorities for
|
|
particular pieces, <tt class="docutils literal"><span class="pre">piece_priority</span></tt> has to be called again for those pieces.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="file-progress" name="file-progress">file_progress()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void file_progress(std::vector<size_type>& fp);
|
|
</pre>
|
|
</blockquote>
|
|
<p>This function fills in the supplied vector with the the number of bytes downloaded
|
|
of each file in this torrent. The progress values are ordered the same as the files
|
|
in the <a class="reference" href="#torrent-info">torrent_info</a>. This operation is not very cheap. Its complexity is <em>O(n + mj)</em>.
|
|
Where <em>n</em> is the number of files, <em>m</em> is the number of downloading pieces and <em>j</em>
|
|
is the number of blocks in a piece.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="save-path" name="save-path">save_path()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
boost::filesystem::path save_path() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">save_path()</span></tt> returns the path that was given to <a class="reference" href="#add-torrent">add_torrent()</a> when this torrent
|
|
was started.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="move-storage" name="move-storage">move_storage()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void move_storage(boost::filesystem::path const& save_path) const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>Moves the file(s) that this torrent are currently seeding from or downloading to. This
|
|
operation will only have the desired effect if the given <tt class="docutils literal"><span class="pre">save_path</span></tt> is located on
|
|
the same drive as the original save path. Since disk IO is performed in a separate
|
|
thread, this operation is also asynchronous. Once the operation completes, the
|
|
<tt class="docutils literal"><span class="pre">storage_moved_alert</span></tt> is generated, with the new path as the message.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="force-reannounce" name="force-reannounce">force_reannounce()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void force_reannounce() const;
|
|
void force_reannounce(boost::posix_time::time_duration) const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">force_reannounce()</span></tt> will force this torrent to do another tracker request, to receive new
|
|
peers. The second overload of <tt class="docutils literal"><span class="pre">force_reannounce</span></tt> that takes a <tt class="docutils literal"><span class="pre">time_duration</span></tt> as
|
|
argument will schedule a reannounce in that amount of time from now.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="scrape-tracker" name="scrape-tracker">scrape_tracker()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void scrape_tracker() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">scrape_tracker()</span></tt> will send a scrape request to the tracker. A scrape request queries the
|
|
tracker for statistics such as total number of incomplete peers, complete peers, number of
|
|
downloads etc.</p>
|
|
<p>This request will specifically update the <tt class="docutils literal"><span class="pre">num_complete</span></tt> and <tt class="docutils literal"><span class="pre">num_incomplete</span></tt> fields in
|
|
the <a class="reference" href="#torrent-status">torrent_status</a> struct once it completes. When it completes, it will generate a
|
|
<a class="reference" href="#scrape-reply-alert">scrape_reply_alert</a>. If it fails, it will generate a <a class="reference" href="#scrape-failed-alert">scrape_failed_alert</a>.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="connect-peer" name="connect-peer">connect_peer()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void connect_peer(asio::ip::tcp::endpoint const& adr, int source = 0) const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">connect_peer()</span></tt> is a way to manually connect to peers that one believe is a part of the
|
|
torrent. If the peer does not respond, or is not a member of this torrent, it will simply
|
|
be disconnected. No harm can be done by using this other than an unnecessary connection
|
|
attempt is made. If the torrent is uninitialized or in queued or checking mode, this
|
|
will throw <a class="reference" href="#invalid-handle">invalid_handle</a>. The second (optional) argument will be bitwised ORed into
|
|
the source mask of this peer. Typically this is one of the source flags in <a class="reference" href="#peer-info">peer_info</a>.
|
|
i.e. <tt class="docutils literal"><span class="pre">tracker</span></tt>, <tt class="docutils literal"><span class="pre">pex</span></tt>, <tt class="docutils literal"><span class="pre">dht</span></tt> etc.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="name" name="name">name()</a></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">
|
|
<h2><a id="set-ratio" name="set-ratio">set_ratio()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void set_ratio(float ratio) const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">set_ratio()</span></tt> sets the desired download / upload ratio. If set to 0, it is considered being
|
|
infinite. i.e. the client will always upload as much as it can, no matter how much it gets back
|
|
in return. With this setting it will work much like the standard clients.</p>
|
|
<p>Besides 0, the ratio can be set to any number greater than or equal to 1. It means how much to
|
|
attempt to upload in return for each download. e.g. if set to 2, the client will try to upload
|
|
2 bytes for every byte received. The default setting for this is 0, which will make it work
|
|
as a standard client.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="set-upload-limit-set-download-limit-upload-limit-download-limit" name="set-upload-limit-set-download-limit-upload-limit-download-limit">set_upload_limit() set_download_limit() upload_limit() download_limit()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void set_upload_limit(int limit) const;
|
|
void set_download_limit(int limit) const;
|
|
int upload_limit() const;
|
|
int download_limit() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">set_upload_limit</span></tt> will limit the upload bandwidth used by this particular torrent to the
|
|
limit you set. It is given as the number of bytes per second the torrent is allowed to upload.
|
|
<tt class="docutils literal"><span class="pre">set_download_limit</span></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>)
|
|
will not override the global rate limit. The torrent can never upload more than the global rate
|
|
limit.</p>
|
|
<p><tt class="docutils literal"><span class="pre">upload_limit</span></tt> and <tt class="docutils literal"><span class="pre">download_limit</span></tt> will return the current limit setting, for upload and
|
|
download, respectively.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="set-sequential-download-is-sequential-download" name="set-sequential-download-is-sequential-download">set_sequential_download() is_sequential_download()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void set_sequential_download(bool sd);
|
|
bool is_sequential_download() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">set_sequential_download()</span></tt> enables or disables <em>sequential download</em>. When enabled, the piece
|
|
picker will pick pieces in sequence instead of rarest first.</p>
|
|
<p>Enabling sequential download will affect the piece distribution negatively in the swarm. It should be
|
|
used sparingly.</p>
|
|
<p><tt class="docutils literal"><span class="pre">is_sequential_download()</span></tt> returns true if this torrent is downloading in sequence, and false
|
|
otherwise.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="set-peer-upload-limit-set-peer-download-limit" name="set-peer-upload-limit-set-peer-download-limit">set_peer_upload_limit() set_peer_download_limit()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void set_peer_upload_limit(asio::ip::tcp::endpoint ip, int limit) const;
|
|
void set_peer_download_limit(asio::ip::tcp::endpoint ip, int limit) const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>Works like <tt class="docutils literal"><span class="pre">set_upload_limit</span></tt> and <tt class="docutils literal"><span class="pre">set_download_limit</span></tt> respectively, but controls individual
|
|
peer instead of the whole torrent.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="id5" name="id5">pause() resume() is_paused()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void pause() const;
|
|
void resume() const;
|
|
bool is_paused() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">pause()</span></tt>, and <tt class="docutils literal"><span class="pre">resume()</span></tt> will disconnect all peers and reconnect all peers respectively.
|
|
When a torrent is paused, it will however remember all share ratios to all peers and remember
|
|
all potential (not connected) peers. You can use <tt class="docutils literal"><span class="pre">is_paused()</span></tt> to determine if a torrent
|
|
is currently paused. Torrents may be paused automatically if there is a file error (e.g. disk full)
|
|
or something similar. See <a class="reference" href="#file-error-alert">file_error_alert</a>.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="force-recheck" name="force-recheck">force_recheck()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void force_recheck() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">force_recheck</span></tt> puts the torrent back in a state where it assumes to have no resume data.
|
|
All peers will be disconnected and the torrent will stop announcing to the tracker. The torrent
|
|
will be added to the checking queue, and will be checked (all the files will be read and
|
|
compared to the piece hashes). Once the check is complete, the torrent will start connecting
|
|
to peers again, as normal.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="clear-error" name="clear-error">clear_error()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void clear_error() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>If the torrent is in an error state (i.e. <tt class="docutils literal"><span class="pre">torrent_status::error</span></tt> is non-empty), this
|
|
will clear the error and start the torrent again.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="resolve-countries" name="resolve-countries">resolve_countries()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void resolve_countries(bool r);
|
|
bool resolve_countries() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>Sets or gets the flag that derermines if countries should be resolved for the peers of this
|
|
torrent. It defaults to false. If it is set to true, the <a class="reference" href="#peer-info">peer_info</a> structure for the peers
|
|
in this torrent will have their <tt class="docutils literal"><span class="pre">country</span></tt> member set. See <a class="reference" href="#peer-info">peer_info</a> for more information
|
|
on how to interpret this field.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="is-seed" name="is-seed">is_seed()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
bool is_seed() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>Returns true if the torrent is in seed mode (i.e. if it has finished downloading).</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="is-auto-managed-auto-managed" name="is-auto-managed-auto-managed">is_auto_managed() auto_managed()</a></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" href="#queuing">queuing</a>.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="has-metadata" name="has-metadata">has_metadata()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
bool has_metadata() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>Returns true if this torrent has metadata (either it was started from a .torrent file or the
|
|
metadata has been downloaded). The only scenario where this can return false is when the torrent
|
|
was started torrent-less (i.e. with just an info-hash and tracker ip). Note that if the torrent
|
|
doesn't have metadata, the member <a class="reference" href="#get-torrent-info">get_torrent_info()</a> will throw.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="set-tracker-login" name="set-tracker-login">set_tracker_login()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void set_tracker_login(std::string const& username
|
|
, std::string const& password) const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">set_tracker_login()</span></tt> sets a username and password that will be sent along in the HTTP-request
|
|
of the tracker announce. Set this if the tracker requires authorization.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="trackers-replace-trackers" name="trackers-replace-trackers">trackers() replace_trackers()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
std::vector<announce_entry> const& trackers() const;
|
|
void replace_trackers(std::vector<announce_entry> const&) const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">trackers()</span></tt> will return the list of trackers for this torrent. The
|
|
announce entry contains both a string <tt class="docutils literal"><span class="pre">url</span></tt> which specify the announce url
|
|
for the tracker as well as an int <tt class="docutils literal"><span class="pre">tier</span></tt>, which is specifies the order in
|
|
which this tracker is tried. If you want libtorrent to use another list of
|
|
trackers for this torrent, you can use <tt class="docutils literal"><span class="pre">replace_trackers()</span></tt> which takes
|
|
a list of the same form as the one returned from <tt class="docutils literal"><span class="pre">trackers()</span></tt> and will
|
|
replace it. If you want an immediate effect, you have to call
|
|
<a class="reference" href="#force-reannounce">force_reannounce()</a>.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="add-url-seed-remove-url-seed-url-seeds" name="add-url-seed-remove-url-seed-url-seeds">add_url_seed() remove_url_seed() url_seeds()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void add_url_seed(std::string const& url);
|
|
void remove_url_seed(std::string const& url);
|
|
std::set<std::string> url_seeds() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">add_url_seed()</span></tt> adds another url to the torrent's list of url seeds. If the
|
|
given url already exists in that list, the call has no effect. The torrent
|
|
will connect to the server and try to download pieces from it, unless it's
|
|
paused, queued, checking or seeding. <tt class="docutils literal"><span class="pre">remove_url_seed()</span></tt> removes the given
|
|
url if it exists already. <tt class="docutils literal"><span class="pre">url_seeds()</span></tt> return a set of the url seeds
|
|
currently in this torrent. Note that urls that fails may be removed
|
|
automatically from the list.</p>
|
|
<p>See <a class="reference" href="#http-seeding">HTTP seeding</a> for more information.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="queue-position-queue-position-up-queue-position-down-queue-position-top-queue-position-bottom" name="queue-position-queue-position-up-queue-position-down-queue-position-top-queue-position-bottom">queue_position() queue_position_up() queue_position_down() queue_position_top() queue_position_bottom()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
int queue_position() const;
|
|
void queue_position_up() const;
|
|
void queue_position_down() const;
|
|
void queue_position_top() const;
|
|
void queue_position_bottom() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>Every torrent that is added is assigned a queue position exactly one greater than
|
|
the greatest queue position of all existing torrents. Torrents that are being
|
|
seeded have -1 as their queue position, since they're no longer in line to be downloaded.</p>
|
|
<p>When a torrent is removed or turns into a seed, all torrents with greater queue positions
|
|
have their positions decreased to fill in the space in the sequence.</p>
|
|
<p><tt class="docutils literal"><span class="pre">queue_position()</span></tt> returns the torrent's position in the download queue. The torrents
|
|
with the smallest numbers are the ones that are being downloaded. The smaller number,
|
|
the closer the torrent is to the front of the line to be started.</p>
|
|
<p>The <tt class="docutils literal"><span class="pre">queue_position_*()</span></tt> functions adjust the torrents position in the queue. Up means
|
|
closer to the front and down means closer to the back of the queue. Top and bottom refers
|
|
to the front and the back of the queue respectively.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="use-interface" name="use-interface">use_interface()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void use_interface(char const* net_interface) const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">use_interface()</span></tt> sets the network interface this torrent will use when it opens outgoing
|
|
connections. By default, it uses the same interface as the <a class="reference" href="#session">session</a> uses to listen on. The
|
|
parameter must be a string containing an ip-address (either an IPv4 or IPv6 address). If
|
|
the string does not conform to this format and exception is thrown.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="info-hash" name="info-hash">info_hash()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
sha1_hash info_hash() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">info_hash()</span></tt> returns the info-hash for the torrent.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="id6" name="id6">set_max_uploads() set_max_connections()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void set_max_uploads(int max_uploads) const;
|
|
void set_max_connections(int max_connections) const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">set_max_uploads()</span></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>
|
|
<p><tt class="docutils literal"><span class="pre">set_max_connections()</span></tt> sets the maximum number of connection this torrent will open. If all
|
|
connections are used up, incoming connections may be refused or poor connections may be closed.
|
|
This must be at least 2. The default is unlimited number of connections. If -1 is given to the
|
|
function, it means unlimited.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="save-resume-data" name="save-resume-data">save_resume_data()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void save_resume_data() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">save_resume_data()</span></tt> generates fast-resume data and returns it as an <a class="reference" href="#entry">entry</a>. This <a class="reference" href="#entry">entry</a>
|
|
is suitable for being bencoded. For more information about how fast-resume works, see <a class="reference" href="#fast-resume">fast resume</a>.</p>
|
|
<p>This operation is asynchronous, <tt class="docutils literal"><span class="pre">save_resume_data</span></tt> will return immediately. The resume data
|
|
is delivered when it's done through an <a class="reference" href="#save-resume-data-alert">save_resume_data_alert</a>.</p>
|
|
<p>The fast resume data will be empty in the following cases:</p>
|
|
<blockquote>
|
|
<ol class="arabic simple">
|
|
<li>The torrent handle is invalid.</li>
|
|
<li>The torrent is checking (or is queued for checking) its storage, it will obviously
|
|
not be ready to write resume data.</li>
|
|
<li>The torrent hasn't received valid metadata and was started without metadata
|
|
(see libtorrent's <a class="reference" href="#metadata-from-peers">metadata from peers</a> extension)</li>
|
|
</ol>
|
|
</blockquote>
|
|
<p>Note that by the time you receive the fast resume data, it may already be invalid if the torrent
|
|
is still downloading! The recommended practice is to first pause the torrent, then generate the
|
|
fast resume data, and then close it down. Make sure to not <a class="reference" href="#remove-torrent">remove_torrent()</a> before you receive
|
|
the <a class="reference" href="#save-resume-data-alert">save_resume_data_alert</a> though. Only pause the torrent before you save the resume data
|
|
if you will remove the torrent afterwards. There's no need to pause when saving intermittent
|
|
resume data.</p>
|
|
<p>In full allocation mode the reume data is never invalidated by subsequent
|
|
writes to the files, since pieces won't move around. This means that you don't need to
|
|
pause before writing resume data in full or sparse mode. If you don't, however, any data written to
|
|
disk after you saved resume data and before the <a class="reference" href="#session">session</a> closed is lost.</p>
|
|
<p>It also means that if the resume data is out dated, libtorrent will not re-check the files, but assume
|
|
that it is fairly recent. The assumption is that it's better to loose a little bit than to re-check
|
|
the entire file.</p>
|
|
<p>It is still a good idea to save resume data periodically during download as well as when
|
|
closing down.</p>
|
|
<p>Example code to pause and save resume data for all torrents and wait for the alerts:</p>
|
|
<pre class="literal-block">
|
|
int num_resume_data = 0;
|
|
std::vector<torrent_handle> handles = ses.get_torrents();
|
|
for (std::vector<torrent_handle>::iterator i = handles.begin();
|
|
i != handles.end(); ++i)
|
|
{
|
|
torrent_handle& h = *i;
|
|
if (!h.has_metadata()) continue;
|
|
|
|
h.pause();
|
|
h.save_resume_data();
|
|
++num_resume_data;
|
|
}
|
|
|
|
while (num_resume_data > 0)
|
|
{
|
|
alert const* a = ses.wait_for_alert(seconds(10));
|
|
|
|
// if we don't get an alert within 10 seconds, abort
|
|
if (a == 0) break;
|
|
|
|
std::auto_ptr<alert> holder = ses.pop_alert();
|
|
save_resume_data_alert const* rd = dynamic_cast<save_resume_data_alert const*>(a);
|
|
if (rd == 0)
|
|
{
|
|
process_alert(a);
|
|
continue;
|
|
}
|
|
|
|
torrent_handle h = rd->handle;
|
|
boost::filesystem::ofstream out(h.save_path()
|
|
/ (h.get_torrent_info().name() + ".fastresume"), std::ios_base::binary);
|
|
out.unsetf(std::ios_base::skipws);
|
|
bencode(std::ostream_iterator<char>(out), *rd->resume_data);
|
|
--num_resume_data;
|
|
}
|
|
</pre>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="id7" name="id7">status()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
torrent_status status() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">status()</span></tt> will return a structure with information about the status of this
|
|
torrent. If the <a class="reference" href="#torrent-handle">torrent_handle</a> is invalid, it will throw <a class="reference" href="#invalid-handle">invalid_handle</a> exception.
|
|
See <a class="reference" href="#torrent-status">torrent_status</a>.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="get-download-queue" name="get-download-queue">get_download_queue()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void get_download_queue(std::vector<partial_piece_info>& queue) const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">get_download_queue()</span></tt> takes a non-const reference to a vector which it will fill with
|
|
information about pieces that are partially downloaded or not downloaded at all but partially
|
|
requested. The entry in the vector (<tt class="docutils literal"><span class="pre">partial_piece_info</span></tt>) looks like this:</p>
|
|
<pre class="literal-block">
|
|
struct partial_piece_info
|
|
{
|
|
int piece_index;
|
|
int blocks_in_piece;
|
|
block_info blocks[256];
|
|
enum state_t { none, slow, medium, fast };
|
|
state_t piece_state;
|
|
};
|
|
</pre>
|
|
<p><tt class="docutils literal"><span class="pre">piece_index</span></tt> is the index of the piece in question. <tt class="docutils literal"><span class="pre">blocks_in_piece</span></tt> is the
|
|
number of blocks in this particular piece. This number will be the same for most pieces, but
|
|
the last piece may have fewer blocks than the standard pieces.</p>
|
|
<p><tt class="docutils literal"><span class="pre">piece_state</span></tt> is set to either <tt class="docutils literal"><span class="pre">fast</span></tt>, <tt class="docutils literal"><span class="pre">medium</span></tt>, <tt class="docutils literal"><span class="pre">slow</span></tt> or <tt class="docutils literal"><span class="pre">none</span></tt>. It tells which
|
|
download rate category the peers downloading this piece falls into. <tt class="docutils literal"><span class="pre">none</span></tt> means that no
|
|
peer is currently downloading any part of the piece. Peers prefer picking pieces from
|
|
the same category as themselves. The reason for this is to keep the number of partially
|
|
downloaded pieces down. Pieces set to <tt class="docutils literal"><span class="pre">none</span></tt> can be converted into any of <tt class="docutils literal"><span class="pre">fast</span></tt>,
|
|
<tt class="docutils literal"><span class="pre">medium</span></tt> or <tt class="docutils literal"><span class="pre">slow</span></tt> as soon as a peer want to download from it.</p>
|
|
<pre class="literal-block">
|
|
struct block_info
|
|
{
|
|
enum block_state_t
|
|
{ none, requested, writing, finished };
|
|
|
|
tcp::endpoint peer;
|
|
unsigned state:2;
|
|
unsigned num_peers:14;
|
|
};
|
|
</pre>
|
|
<p>The <tt class="docutils literal"><span class="pre">block_info</span></tt> array contains data for each individual block in the piece. Each block has
|
|
a state (<tt class="docutils literal"><span class="pre">state</span></tt>) which is any of:</p>
|
|
<ul class="simple">
|
|
<li><tt class="docutils literal"><span class="pre">none</span></tt> - This block has not been downloaded or requested form any peer.</li>
|
|
<li><tt class="docutils literal"><span class="pre">requested</span></tt> - The block has been requested, but not completely downloaded yet.</li>
|
|
<li><tt class="docutils literal"><span class="pre">writing</span></tt> - The block has been downloaded and is currently queued for being written to disk.</li>
|
|
<li><tt class="docutils literal"><span class="pre">finished</span></tt> - The block has been written to disk.</li>
|
|
</ul>
|
|
<p>The <tt class="docutils literal"><span class="pre">peer</span></tt> field is the ip address of the peer this block was downloaded from.
|
|
<tt class="docutils literal"><span class="pre">num_peers</span></tt> is the number of peers that is currently requesting this block. Typically this
|
|
is 0 or 1, but at the end of the torrent blocks may be requested by more peers in parallel to
|
|
speed things up.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="get-peer-info" name="get-peer-info">get_peer_info()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void get_peer_info(std::vector<peer_info>&) const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">get_peer_info()</span></tt> takes a reference to a vector that will be cleared and filled
|
|
with one entry for each peer connected to this torrent, given the handle is valid. If the
|
|
<a class="reference" href="#torrent-handle">torrent_handle</a> is invalid, it will throw <a class="reference" href="#invalid-handle">invalid_handle</a> exception. Each entry in
|
|
the vector contains information about that particular peer. See <a class="reference" href="#peer-info">peer_info</a>.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="get-torrent-info" name="get-torrent-info">get_torrent_info()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
torrent_info const& get_torrent_info() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>Returns a const reference to the <a class="reference" href="#torrent-info">torrent_info</a> object associated with this torrent.
|
|
This reference is valid as long as the <a class="reference" href="#torrent-handle">torrent_handle</a> is valid, no longer. If the
|
|
<a class="reference" href="#torrent-handle">torrent_handle</a> is invalid or if it doesn't have any metadata, <a class="reference" href="#invalid-handle">invalid_handle</a>
|
|
exception will be thrown. The torrent may be in a state without metadata only if
|
|
it was started without a .torrent file, i.e. by using the libtorrent extension of
|
|
just supplying a tracker and info-hash.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="is-valid" name="is-valid">is_valid()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
bool is_valid() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>Returns true if this handle refers to a valid torrent and false if it hasn't been initialized
|
|
or if the torrent it refers to has been aborted. Note that a handle may become invalid after
|
|
it has been added to the session. Usually this is because the storage for the torrent is
|
|
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" href="#file-error-alert">file_error_alert</a> is generated and all handles
|
|
that refers to that torrent will become invalid.</p>
|
|
</div>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a id="torrent-status" name="torrent-status">torrent_status</a></h1>
|
|
<p>It contains the following fields:</p>
|
|
<pre class="literal-block">
|
|
struct torrent_status
|
|
{
|
|
enum state_t
|
|
{
|
|
queued_for_checking,
|
|
checking_files,
|
|
downloading_metadata,
|
|
downloading,
|
|
finished,
|
|
seeding,
|
|
allocating
|
|
};
|
|
|
|
state_t state;
|
|
bool paused;
|
|
float progress;
|
|
std::string error;
|
|
|
|
boost::posix_time::time_duration next_announce;
|
|
boost::posix_time::time_duration announce_interval;
|
|
|
|
std::string current_tracker;
|
|
|
|
size_type total_download;
|
|
size_type total_upload;
|
|
|
|
size_type total_payload_download;
|
|
size_type total_payload_upload;
|
|
|
|
size_type total_failed_bytes;
|
|
size_type total_redundant_bytes;
|
|
|
|
float download_rate;
|
|
float upload_rate;
|
|
|
|
float download_payload_rate;
|
|
float upload_payload_rate;
|
|
|
|
int num_peers;
|
|
|
|
int num_complete;
|
|
int num_incomplete;
|
|
|
|
int list_seeds;
|
|
int list_peers;
|
|
|
|
int connect_candidates;
|
|
|
|
bitfield pieces;
|
|
int num_pieces;
|
|
|
|
size_type total_done;
|
|
size_type total_wanted_done;
|
|
size_type total_wanted;
|
|
|
|
int num_seeds;
|
|
float distributed_copies;
|
|
|
|
int block_size;
|
|
|
|
int num_uploads;
|
|
int num_connections;
|
|
int uploads_limit;
|
|
int connections_limit;
|
|
|
|
storage_mode_t storage_mode;
|
|
|
|
int up_bandwidth_queue;
|
|
int down_bandwidth_queue;
|
|
|
|
size_type all_time_upload;
|
|
size_type all_time_download;
|
|
|
|
int active_time;
|
|
int seeding_time;
|
|
|
|
int seed_rank;
|
|
|
|
int last_scrape;
|
|
|
|
bool has_incoming;
|
|
};
|
|
</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
|
|
torrent's current task. It may be checking files or downloading. The torrent's
|
|
current task is in the <tt class="docutils literal"><span class="pre">state</span></tt> member, it will be one of the following:</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="31%" />
|
|
<col width="69%" />
|
|
</colgroup>
|
|
<tbody valign="top">
|
|
<tr><td><tt class="docutils literal"><span class="pre">queued_for_checking</span></tt></td>
|
|
<td>The torrent is in the queue for being checked. But there
|
|
currently is another torrent that are being checked.
|
|
This torrent will wait for its turn.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">checking_files</span></tt></td>
|
|
<td>The torrent has not started its download yet, and is
|
|
currently checking existing files.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">downloading_metadata</span></tt></td>
|
|
<td>The torrent is trying to download metadata from peers.
|
|
This assumes the metadata_transfer extension is in use.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">downloading</span></tt></td>
|
|
<td>The torrent is being downloaded. This is the state
|
|
most torrents will be in most of the time. The progress
|
|
meter will tell how much of the files that has been
|
|
downloaded.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">finished</span></tt></td>
|
|
<td>In this state the torrent has finished downloading but
|
|
still doesn't have the entire torrent. i.e. some pieces
|
|
are filtered and won't get downloaded.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">seeding</span></tt></td>
|
|
<td>In this state the torrent has finished downloading and
|
|
is a pure seeder.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">allocating</span></tt></td>
|
|
<td>If the torrent was started in full allocation mode, this
|
|
indicates that the (disk) storage for the torrent is
|
|
allocated.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>When downloading, the progress is <tt class="docutils literal"><span class="pre">total_wanted_done</span></tt> / <tt class="docutils literal"><span class="pre">total_wanted</span></tt>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">paused</span></tt> is set to true if the torrent is paused and false otherwise.</p>
|
|
<p><tt class="docutils literal"><span class="pre">error</span></tt> may be set to an error message describing why the torrent was paused, in
|
|
case it was paused by an error. If the torrent is not paused or if it's paused but
|
|
not because of an error, this string is empty.</p>
|
|
<p><tt class="docutils literal"><span class="pre">next_announce</span></tt> is the time until the torrent will announce itself to the tracker. And
|
|
<tt class="docutils literal"><span class="pre">announce_interval</span></tt> is the time the tracker want us to wait until we announce ourself
|
|
again the next time.</p>
|
|
<p><tt class="docutils literal"><span class="pre">current_tracker</span></tt> is the URL of the last working tracker. If no tracker request has
|
|
been successful yet, it's set to an empty string.</p>
|
|
<p><tt class="docutils literal"><span class="pre">total_download</span></tt> and <tt class="docutils literal"><span class="pre">total_upload</span></tt> is the number of bytes downloaded and
|
|
uploaded to all peers, accumulated, <em>this session</em> only.</p>
|
|
<p><tt class="docutils literal"><span class="pre">total_payload_download</span></tt> and <tt class="docutils literal"><span class="pre">total_payload_upload</span></tt> counts the amount of bytes
|
|
send and received this session, but only the actual payload data (i.e the interesting
|
|
data), these counters ignore any protocol overhead.</p>
|
|
<p><tt class="docutils literal"><span class="pre">total_failed_bytes</span></tt> is the number of bytes that has been downloaded and that
|
|
has failed the piece hash test. In other words, this is just how much crap that
|
|
has been downloaded.</p>
|
|
<p><tt class="docutils literal"><span class="pre">total_redundant_bytes</span></tt> is the number of bytes that has been downloaded even
|
|
though that data already was downloaded. The reason for this is that in some
|
|
situations the same data can be downloaded by mistake. When libtorrent sends
|
|
requests to a peer, and the peer doesn't send a response within a certain
|
|
timeout, libtorrent will re-request that block. Another situation when
|
|
libtorrent may re-request blocks is when the requests it sends out are not
|
|
replied in FIFO-order (it will re-request blocks that are skipped by an out of
|
|
order block). This is supposed to be as low as possible.</p>
|
|
<p><tt class="docutils literal"><span class="pre">pieces</span></tt> is the bitmask that represents which pieces we have (set to true) and
|
|
the pieces we don't have. It's a pointer and may be set to 0 if the torrent isn't
|
|
downloading or seeding.</p>
|
|
<p><tt class="docutils literal"><span class="pre">num_pieces</span></tt> is the number of pieces that has been downloaded. It is equivalent
|
|
to: <tt class="docutils literal"><span class="pre">std::accumulate(pieces->begin(),</span> <span class="pre">pieces->end())</span></tt>. So you don't have to
|
|
count yourself. This can be used to see if anything has updated since last time
|
|
if you want to keep a graph of the pieces up to date.</p>
|
|
<p><tt class="docutils literal"><span class="pre">download_rate</span></tt> and <tt class="docutils literal"><span class="pre">upload_rate</span></tt> are the total rates for all peers for this
|
|
torrent. These will usually have better precision than summing the rates from
|
|
all peers. The rates are given as the number of bytes per second. The
|
|
<tt class="docutils literal"><span class="pre">download_payload_rate</span></tt> and <tt class="docutils literal"><span class="pre">upload_payload_rate</span></tt> respectively is the
|
|
total transfer rate of payload only, not counting protocol chatter. This might
|
|
be slightly smaller than the other rates, but if projected over a long time
|
|
(e.g. when calculating ETA:s) the difference may be noticeable.</p>
|
|
<p><tt class="docutils literal"><span class="pre">num_peers</span></tt> is the number of peers this torrent currently is connected to.
|
|
Peer connections that are in the half-open state (is attempting to connect)
|
|
or are queued for later connection attempt do not count. Although they are
|
|
visible in the peer list when you call <a class="reference" href="#get-peer-info">get_peer_info()</a>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">num_complete</span></tt> and <tt class="docutils literal"><span class="pre">num_incomplete</span></tt> are set to -1 if the tracker did not
|
|
send any scrape data in its announce reply. This data is optional and may
|
|
not be available from all trackers. If these are not -1, they are the total
|
|
number of peers that are seeding (complete) and the total number of peers
|
|
that are still downloading (incomplete) this torrent.</p>
|
|
<p><tt class="docutils literal"><span class="pre">list_seeds</span></tt> and <tt class="docutils literal"><span class="pre">list_peers</span></tt> are the number of seeds in our peer list
|
|
and the total number of peers (including seeds) respectively. We are not
|
|
necessarily connected to all the peers in our peer list. This is the number
|
|
of peers we know of in total, including banned peers and peers that we have
|
|
failed to connect to.</p>
|
|
<p><tt class="docutils literal"><span class="pre">connect_candidates</span></tt> is the number of peers in this torrent's peer list
|
|
that is a candidate to be connected to. i.e. It has fewer connect attempts
|
|
than the max fail count, it is not a seed if we are a seed, it is not banned
|
|
etc. If this is 0, it means we don't know of any more peers that we can try.</p>
|
|
<p><tt class="docutils literal"><span class="pre">total_done</span></tt> is the total number of bytes of the file(s) that we have. All
|
|
this does not necessarily has to be downloaded during this session (that's
|
|
<tt class="docutils literal"><span class="pre">total_payload_download</span></tt>).</p>
|
|
<p><tt class="docutils literal"><span class="pre">total_wanted_done</span></tt> is the number of bytes we have downloaded, only counting the
|
|
pieces that we actually want to download. i.e. excluding any pieces that we have but
|
|
are filtered as not wanted.</p>
|
|
<p><tt class="docutils literal"><span class="pre">total_wanted</span></tt> is the total number of bytes we want to download. This is also
|
|
excluding pieces that have been filtered.</p>
|
|
<p><tt class="docutils literal"><span class="pre">num_seeds</span></tt> is the number of peers that are seeding that this client is
|
|
currently connected to.</p>
|
|
<p><tt class="docutils literal"><span class="pre">distributed_copies</span></tt> is the number of distributed copies of the torrent.
|
|
Note that one copy may be spread out among many peers. The integer part
|
|
tells how many copies there are currently of the rarest piece(s) among the
|
|
peers this client is connected to. The fractional part tells the share of
|
|
pieces that have more copies than the rarest piece(s). For example: 2.5 would
|
|
mean that the rarest pieces have only 2 copies among the peers this torrent is
|
|
connected to, and that 50% of all the pieces have more than two copies.</p>
|
|
<p>If we are a seed, the piece picker is deallocated as an optimization, and
|
|
piece availability is no longer tracked. In this case the distributed
|
|
copies is set to -1.</p>
|
|
<p><tt class="docutils literal"><span class="pre">block_size</span></tt> is the size of a block, in bytes. A block is a sub piece, it
|
|
is the number of bytes that each piece request asks for and the number of
|
|
bytes that each bit in the <tt class="docutils literal"><span class="pre">partial_piece_info</span></tt>'s bitset represents
|
|
(see <a class="reference" href="#get-download-queue">get_download_queue()</a>). This is typically 16 kB, but it may be
|
|
larger if the pieces are larger.</p>
|
|
<p><tt class="docutils literal"><span class="pre">num_uploads</span></tt> is the number of unchoked peers in this torrent.</p>
|
|
<p><tt class="docutils literal"><span class="pre">num_connections</span></tt> is the number of peer connections this torrent has, including
|
|
half-open connections that hasn't completed the bittorrent handshake yet. This is
|
|
always <= <tt class="docutils literal"><span class="pre">num_peers</span></tt>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">uploads_limit</span></tt> is the set limit of upload slots (unchoked peers) for this torrent.</p>
|
|
<p><tt class="docutils literal"><span class="pre">connections_limit</span></tt> is the set limit of number of connections for this torrent.</p>
|
|
<p><tt class="docutils literal"><span class="pre">storage_mode</span></tt> is one of <tt class="docutils literal"><span class="pre">storage_mode_allocate</span></tt>, <tt class="docutils literal"><span class="pre">storage_mode_sparse</span></tt> or
|
|
<tt class="docutils literal"><span class="pre">storage_mode_compact</span></tt>. Identifies which storage mode this torrent is being saved
|
|
with. See <a class="reference" href="#storage-allocation">Storage allocation</a>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">up_bandwidth_queue</span></tt> and <tt class="docutils literal"><span class="pre">down_bandwidth_queue</span></tt> are the number of peers in this
|
|
torrent that are waiting for more bandwidth quota from the torrent rate limiter.
|
|
This can determine if the rate you get from this torrent is bound by the torrents
|
|
limit or not. If there is no limit set on this torrent, the peers might still be
|
|
waiting for bandwidth quota from the global limiter, but then they are counted in
|
|
the <tt class="docutils literal"><span class="pre">session_status</span></tt> object.</p>
|
|
<p><tt class="docutils literal"><span class="pre">all_time_upload</span></tt> and <tt class="docutils literal"><span class="pre">all_time_download</span></tt> are accumulated upload and download
|
|
byte counters. They are saved in and restored from resume data to keep totals
|
|
across sessions.</p>
|
|
<p><tt class="docutils literal"><span class="pre">active_time</span></tt> and <tt class="docutils literal"><span class="pre">seeding_time</span></tt> are second counters. They keep track of the
|
|
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 >=
|
|
<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_rank</span></tt> is a rank of how important it is to seed the torrent, it is used
|
|
to determine which torrents to seed and which to queue. It is based on the peer
|
|
to seed ratio from the tracker scrape. For more information, see <a class="reference" href="#queuing">queuing</a>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">last_scrape</span></tt> is the number of seconds since this torrent acquired scrape data.
|
|
If it has never done that, this value is -1.</p>
|
|
<p><tt class="docutils literal"><span class="pre">has_incoming</span></tt> is true if there has ever been an incoming connection attempt
|
|
to this torrent.'</p>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a id="peer-info" name="peer-info">peer_info</a></h1>
|
|
<p>It contains the following fields:</p>
|
|
<pre class="literal-block">
|
|
struct peer_info
|
|
{
|
|
enum
|
|
{
|
|
interesting = 0x1,
|
|
choked = 0x2,
|
|
remote_interested = 0x4,
|
|
remote_choked = 0x8,
|
|
supports_extensions = 0x10,
|
|
local_connection = 0x20,
|
|
handshake = 0x40,
|
|
connecting = 0x80,
|
|
queued = 0x100,
|
|
on_parole = 0x200,
|
|
seed = 0x400,
|
|
optimistic_unchoke = 0x800,
|
|
snubbed = 0x1000,
|
|
upload_only = 0x2000,
|
|
rc4_encrypted = 0x100000,
|
|
plaintext_encrypted = 0x200000
|
|
};
|
|
|
|
unsigned int flags;
|
|
|
|
enum peer_source_flags
|
|
{
|
|
tracker = 0x1,
|
|
dht = 0x2,
|
|
pex = 0x4,
|
|
lsd = 0x8
|
|
};
|
|
|
|
int source;
|
|
|
|
enum bw_state { bw_idle, bw_torrent, bw_global, bw_network };
|
|
|
|
char read_state;
|
|
char write_state;
|
|
|
|
asio::ip::tcp::endpoint ip;
|
|
float up_speed;
|
|
float down_speed;
|
|
float payload_up_speed;
|
|
float payload_down_speed;
|
|
size_type total_download;
|
|
size_type total_upload;
|
|
peer_id pid;
|
|
bitfield pieces;
|
|
int upload_limit;
|
|
int download_limit;
|
|
|
|
time_duration last_request;
|
|
time_duration last_active;
|
|
int request_timeout;
|
|
|
|
int send_buffer_size;
|
|
int used_send_buffer;
|
|
|
|
int receive_buffer_size;
|
|
int used_receive_buffer;
|
|
|
|
int num_hashfails;
|
|
|
|
char country[2];
|
|
|
|
std::string inet_as_name;
|
|
int inet_as;
|
|
|
|
size_type load_balancing;
|
|
|
|
int requests_in_buffer;
|
|
int download_queue_length;
|
|
int upload_queue_length;
|
|
|
|
int failcount;
|
|
|
|
int downloading_piece_index;
|
|
int downloading_block_index;
|
|
int downloading_progress;
|
|
int downloading_total;
|
|
|
|
std::string client;
|
|
|
|
enum
|
|
{
|
|
standard_bittorrent = 0,
|
|
web_seed = 1
|
|
};
|
|
int connection_type;
|
|
|
|
int remote_dl_rate;
|
|
|
|
int pending_disk_bytes;
|
|
|
|
int send_quota;
|
|
int receive_quota;
|
|
|
|
int rtt;
|
|
|
|
int download_rate_peak;
|
|
int upload_rate_peak;
|
|
|
|
};
|
|
</pre>
|
|
<p>The <tt class="docutils literal"><span class="pre">flags</span></tt> attribute tells you in which state the peer is. It is set to
|
|
any combination of the enums above. The following table describes each flag:</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="31%" />
|
|
<col width="69%" />
|
|
</colgroup>
|
|
<tbody valign="top">
|
|
<tr><td><tt class="docutils literal"><span class="pre">interesting</span></tt></td>
|
|
<td><strong>we</strong> are interested in pieces from this peer.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">choked</span></tt></td>
|
|
<td><strong>we</strong> have choked this peer.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">remote_interested</span></tt></td>
|
|
<td>the peer is interested in <strong>us</strong></td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">remote_choked</span></tt></td>
|
|
<td>the peer has choked <strong>us</strong>.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">support_extensions</span></tt></td>
|
|
<td>means that this peer supports the
|
|
<a class="reference" href="extension_protocol.html">extension protocol</a>.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">local_connection</span></tt></td>
|
|
<td>The connection was initiated by us, the peer has a
|
|
listen port open, and that port is the same as in the
|
|
address of this peer. If this flag is not set, this
|
|
peer connection was opened by this peer connecting to
|
|
us.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">handshake</span></tt></td>
|
|
<td>The connection is opened, and waiting for the
|
|
handshake. Until the handshake is done, the peer
|
|
cannot be identified.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">connecting</span></tt></td>
|
|
<td>The connection is in a half-open state (i.e. it is
|
|
being connected).</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">queued</span></tt></td>
|
|
<td>The connection is currently queued for a connection
|
|
attempt. This may happen if there is a limit set on
|
|
the number of half-open TCP connections.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">on_parole</span></tt></td>
|
|
<td>The peer has participated in a piece that failed the
|
|
hash check, and is now "on parole", which means we're
|
|
only requesting whole pieces from this peer until
|
|
it either fails that piece or proves that it doesn't
|
|
send bad data.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">seed</span></tt></td>
|
|
<td>This peer is a seed (it has all the pieces).</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">optimistic_unchoke</span></tt></td>
|
|
<td>This peer is subject to an optimistic unchoke. It has
|
|
been unchoked for a while to see if it might unchoke
|
|
us in return an earn an upload/unchoke slot. If it
|
|
doesn't within some period of time, it will be choked
|
|
and another peer will be optimistically unchoked.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">snubbed</span></tt></td>
|
|
<td>This peer has recently failed to send a block within
|
|
the request timeout from when the request was sent.
|
|
We're currently picking one block at a time from this
|
|
peer.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">upload_only</span></tt></td>
|
|
<td>This peer has either explicitly (with an extension)
|
|
or implicitly (by becoming a seed) told us that it
|
|
will not downloading anything more, regardless of
|
|
which pieces we have.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p><tt class="docutils literal"><span class="pre">source</span></tt> is a combination of flags describing from which sources this peer
|
|
was received. The flags are:</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="30%" />
|
|
<col width="70%" />
|
|
</colgroup>
|
|
<tbody valign="top">
|
|
<tr><td><tt class="docutils literal"><span class="pre">tracker</span></tt></td>
|
|
<td>The peer was received from the tracker.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">dht</span></tt></td>
|
|
<td>The peer was received from the kademlia DHT.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">pex</span></tt></td>
|
|
<td>The peer was received from the peer exchange
|
|
extension.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">lsd</span></tt></td>
|
|
<td>The peer was received from the local service
|
|
discovery (The peer is on the local network).</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">resume_data</span></tt></td>
|
|
<td>The peer was added from the fast resume data.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p><tt class="docutils literal"><span class="pre">read_state</span></tt> and <tt class="docutils literal"><span class="pre">write_state</span></tt> indicates what state this peer is in with regards
|
|
to sending and receiving data. The states are declared in the <tt class="docutils literal"><span class="pre">bw_state</span></tt> enum and
|
|
defines as follows:</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="30%" />
|
|
<col width="70%" />
|
|
</colgroup>
|
|
<tbody valign="top">
|
|
<tr><td><tt class="docutils literal"><span class="pre">bw_idle</span></tt></td>
|
|
<td>The peer is not waiting for any external events to
|
|
send or receive data.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">bw_torrent</span></tt></td>
|
|
<td>The peer is waiting for the torrent to receive
|
|
bandwidth quota in order to forward the bandwidth
|
|
request to the global manager.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">bw_global</span></tt></td>
|
|
<td>The peer is waiting for the global bandwidth manager
|
|
to receive more quota in order to handle the request.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">bw_network</span></tt></td>
|
|
<td>The peer has quota and is currently waiting for a
|
|
network read or write operation to complete. This is
|
|
the state all peers are in if there are no bandwidth
|
|
limits.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>The <tt class="docutils literal"><span class="pre">ip</span></tt> field is the IP-address to this peer. The type is an asio endpoint. For
|
|
more info, see the <a class="reference" href="http://asio.sf.net">asio</a> documentation.</p>
|
|
<p><tt class="docutils literal"><span class="pre">up_speed</span></tt> and <tt class="docutils literal"><span class="pre">down_speed</span></tt> contains the current upload and download speed
|
|
we have to and from this peer (including any protocol messages). The transfer rates
|
|
of payload data only are found in <tt class="docutils literal"><span class="pre">payload_up_speed</span></tt> and <tt class="docutils literal"><span class="pre">payload_down_speed</span></tt>.
|
|
These figures are updated approximately once every second.</p>
|
|
<p><tt class="docutils literal"><span class="pre">total_download</span></tt> and <tt class="docutils literal"><span class="pre">total_upload</span></tt> are the total number of bytes downloaded
|
|
from and uploaded to this peer. These numbers do not include the protocol chatter, but only
|
|
the payload data.</p>
|
|
<p><tt class="docutils literal"><span class="pre">pid</span></tt> is the peer's id as used in the bit torrent protocol. This id can be used to
|
|
extract 'fingerprints' from the peer. Sometimes it can tell you which client the peer
|
|
is using. See identify_client()_</p>
|
|
<p><tt class="docutils literal"><span class="pre">pieces</span></tt> is a bitfield, with one bit per piece in the torrent.
|
|
Each bit tells you if the peer has that piece (if it's set to 1)
|
|
or if the peer miss that piece (set to 0).</p>
|
|
<p><tt class="docutils literal"><span class="pre">seed</span></tt> is true if this peer is a seed.</p>
|
|
<p><tt class="docutils literal"><span class="pre">upload_limit</span></tt> is the number of bytes per second we are allowed to send to this
|
|
peer every second. It may be -1 if there's no local limit on the peer. The global
|
|
limit and the torrent limit is always enforced anyway.</p>
|
|
<p><tt class="docutils literal"><span class="pre">download_limit</span></tt> is the number of bytes per second this peer is allowed to
|
|
receive. -1 means it's unlimited.</p>
|
|
<p><tt class="docutils literal"><span class="pre">last_request</span></tt> and <tt class="docutils literal"><span class="pre">last_active</span></tt> is the time since we last sent a request
|
|
to this peer and since any transfer occurred with this peer, respectively.</p>
|
|
<p><tt class="docutils literal"><span class="pre">request_timeout</span></tt> is the number of seconds until the current front piece request
|
|
will time out. This timeout can be adjusted through <tt class="docutils literal"><span class="pre">session_settings::request_timeout</span></tt>.
|
|
-1 means that there is not outstanding request.</p>
|
|
<p><tt class="docutils literal"><span class="pre">send_buffer_size</span></tt> and <tt class="docutils literal"><span class="pre">used_send_buffer</span></tt> is the number of bytes allocated
|
|
and used for the peer's send buffer, respectively.</p>
|
|
<p><tt class="docutils literal"><span class="pre">receive_buffer_size</span></tt> and <tt class="docutils literal"><span class="pre">used_receive_buffer</span></tt> are the number of bytes
|
|
allocated and used as receive buffer, respectively.</p>
|
|
<p><tt class="docutils literal"><span class="pre">num_hashfails</span></tt> is the number of pieces this peer has participated in
|
|
sending us that turned out to fail the hash check.</p>
|
|
<p><tt class="docutils literal"><span class="pre">country</span></tt> is the two letter <a class="reference" href="http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html">ISO 3166 country code</a> for the country the peer
|
|
is connected from. If the country hasn't been resolved yet, both chars are set
|
|
to 0. If the resolution failed for some reason, the field is set to "--". If the
|
|
resolution service returns an invalid country code, it is set to "!!".
|
|
The <tt class="docutils literal"><span class="pre">countries.nerd.dk</span></tt> service is used to look up countries. This field will
|
|
remain set to 0 unless the torrent is set to resolve countries, see <a class="reference" href="#resolve-countries">resolve_countries()</a>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">inet_as_name</span></tt> is the name of the AS this peer is located in. This might be
|
|
an empty string if there is no name in the geo ip database.</p>
|
|
<p><tt class="docutils literal"><span class="pre">inet_as</span></tt> is the AS number the peer is located in.</p>
|
|
<p><tt class="docutils literal"><span class="pre">load_balancing</span></tt> is a measurement of the balancing of free download (that we get)
|
|
and free upload that we give. Every peer gets a certain amount of free upload, but
|
|
this member says how much <em>extra</em> free upload this peer has got. If it is a negative
|
|
number it means that this was a peer from which we have got this amount of free
|
|
download.</p>
|
|
<p><tt class="docutils literal"><span class="pre">requests_in_buffer</span></tt> is the number of requests messages that are currently in the
|
|
send buffer waiting to be sent.</p>
|
|
<p><tt class="docutils literal"><span class="pre">download_queue_length</span></tt> is the number of piece-requests we have sent to this peer
|
|
that hasn't been answered with a piece yet.</p>
|
|
<p><tt class="docutils literal"><span class="pre">upload_queue_length</span></tt> is the number of piece-requests we have received from this peer
|
|
that we haven't answered with a piece yet.</p>
|
|
<p><tt class="docutils literal"><span class="pre">failcount</span></tt> is the number of times this peer has "failed". i.e. failed to connect
|
|
or disconnected us. The failcount is decremented when we see this peer in a tracker
|
|
response or peer exchange message.</p>
|
|
<p>You can know which piece, and which part of that piece, that is currently being
|
|
downloaded from a specific peer by looking at the next four members.
|
|
<tt class="docutils literal"><span class="pre">downloading_piece_index</span></tt> is the index of the piece that is currently being downloaded.
|
|
This may be set to -1 if there's currently no piece downloading from this peer. If it is
|
|
>= 0, the other three members are valid. <tt class="docutils literal"><span class="pre">downloading_block_index</span></tt> is the index of the
|
|
block (or sub-piece) that is being downloaded. <tt class="docutils literal"><span class="pre">downloading_progress</span></tt> is the number
|
|
of bytes of this block we have received from the peer, and <tt class="docutils literal"><span class="pre">downloading_total</span></tt> is
|
|
the total number of bytes in this block.</p>
|
|
<p><tt class="docutils literal"><span class="pre">client</span></tt> is a string describing the software at the other end of the connection.
|
|
In some cases this information is not available, then it will contain a string
|
|
that may give away something about which software is running in the other end.
|
|
In the case of a web seed, the server type and version will be a part of this
|
|
string.</p>
|
|
<p><tt class="docutils literal"><span class="pre">connection_type</span></tt> can currently be one of <tt class="docutils literal"><span class="pre">standard_bittorrent</span></tt> or
|
|
<tt class="docutils literal"><span class="pre">web_seed</span></tt>. These are currently the only implemented protocols.</p>
|
|
<p><tt class="docutils literal"><span class="pre">remote_dl_rate</span></tt> is an estimate of the rate this peer is downloading at, in
|
|
bytes per second.</p>
|
|
<p><tt class="docutils literal"><span class="pre">pending_disk_bytes</span></tt> is the number of bytes this peer has pending in the
|
|
disk-io thread. Downloaded and waiting to be written to disk. This is what
|
|
is capped by <tt class="docutils literal"><span class="pre">session_settings::max_outstanding_disk_bytes_per_connection</span></tt>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">send_quota</span></tt> and <tt class="docutils literal"><span class="pre">receive_quota</span></tt> are the number of bytes this peer has been
|
|
assigned to be allowed to send and receive until it has to request more quota
|
|
from the bandwidth manager.</p>
|
|
<p><tt class="docutils literal"><span class="pre">rtt</span></tt> is an estimated round trip time to this peer, in milliseconds. It is
|
|
estimated by timing the the tcp <tt class="docutils literal"><span class="pre">connect()</span></tt>. It may be 0 for incoming connections.</p>
|
|
<p><tt class="docutils literal"><span class="pre">download_rate_peak</span></tt> and <tt class="docutils literal"><span class="pre">upload_rate_peak</span></tt> are the highest download and upload
|
|
rates seen on this connection. They are given in bytes per second. This number is
|
|
reset to 0 on reconnect.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a id="session-settings" name="session-settings">session_settings</a></h1>
|
|
<p>You have some control over tracker requests through the <tt class="docutils literal"><span class="pre">session_settings</span></tt> object. You
|
|
create it and fill it with your settings and then use <tt class="docutils literal"><span class="pre">session::set_settings()</span></tt>
|
|
to apply them. You have control over proxy and authorization settings and also the user-agent
|
|
that will be sent to the tracker. The user-agent is a good way to identify your client.</p>
|
|
<pre class="literal-block">
|
|
struct session_settings
|
|
{
|
|
session_settings();
|
|
std::string user_agent;
|
|
int tracker_completion_timeout;
|
|
int tracker_receive_timeout;
|
|
int stop_tracker_timeout;
|
|
int tracker_maximum_response_length;
|
|
|
|
int piece_timeout;
|
|
float request_queue_time;
|
|
int max_allowed_in_request_queue;
|
|
int max_out_request_queue;
|
|
int whole_pieces_threshold;
|
|
int peer_timeout;
|
|
int urlseed_timeout;
|
|
int urlseed_pipeline_size;
|
|
int file_pool_size;
|
|
bool allow_multiple_connections_per_ip;
|
|
int max_failcount;
|
|
int min_reconnect_time;
|
|
int peer_connect_timeout;
|
|
bool ignore_limits_on_local_network;
|
|
int connection_speed;
|
|
bool send_redundant_have;
|
|
bool lazy_bitfields;
|
|
int inactivity_timeout;
|
|
int unchoke_interval;
|
|
int optimistic_unchoke_multiplier;
|
|
address announce_ip;
|
|
int num_want;
|
|
int initial_picker_threshold;
|
|
int allowed_fast_set_size;
|
|
int max_outstanding_disk_bytes_per_connection;
|
|
int handshake_timeout;
|
|
bool use_dht_as_fallback;
|
|
bool free_torrent_hashes;
|
|
bool upnp_ignore_nonrouters;
|
|
int send_buffer_watermark;
|
|
bool auto_upload_slots;
|
|
bool use_parole_mode;
|
|
int cache_size;
|
|
int cache_expiry;
|
|
std::pair<int, int> outgoing_ports;
|
|
char peer_tos;
|
|
|
|
int active_downloads;
|
|
int active_seeds;
|
|
int active_limit;
|
|
bool dont_count_slow_torrents;
|
|
int auto_manage_interval;
|
|
float share_ratio_limit;
|
|
float seed_time_ratio_limit;
|
|
int seed_time_limit;
|
|
bool close_redundant_connections;
|
|
|
|
int auto_scrape_interval;
|
|
int auto_scrape_min_interval;
|
|
|
|
int max_peerlist_size;
|
|
|
|
int min_announce_interval;
|
|
};
|
|
</pre>
|
|
<p><tt class="docutils literal"><span class="pre">user_agent</span></tt> this is the client identification to the tracker.
|
|
The recommended format of this string is:
|
|
"ClientName/ClientVersion libtorrent/libtorrentVersion".
|
|
This name will not only be used when making HTTP requests, but also when
|
|
sending extended headers to peers that support that extension.</p>
|
|
<p><tt class="docutils literal"><span class="pre">tracker_completion_timeout</span></tt> is the number of seconds the tracker
|
|
connection will wait from when it sent the request until it considers the
|
|
tracker to have timed-out. Default value is 60 seconds.</p>
|
|
<p><tt class="docutils literal"><span class="pre">tracker_receive_timeout</span></tt> is the number of seconds to wait to receive
|
|
any data from the tracker. If no data is received for this number of
|
|
seconds, the tracker will be considered as having timed out. If a tracker
|
|
is down, this is the kind of timeout that will occur. The default value
|
|
is 20 seconds.</p>
|
|
<p><tt class="docutils literal"><span class="pre">stop_tracker_timeout</span></tt> is the time to wait for tracker responses when
|
|
shutting down the session object. This is given in seconds. Default is
|
|
10 seconds.</p>
|
|
<p><tt class="docutils literal"><span class="pre">tracker_maximum_response_length</span></tt> is the maximum number of bytes in a
|
|
tracker response. If a response size passes this number it will be rejected
|
|
and the connection will be closed. On gzipped responses this size is measured
|
|
on the uncompressed data. So, if you get 20 bytes of gzip response that'll
|
|
expand to 2 megs, it will be interrupted before the entire response has been
|
|
uncompressed (given your limit is lower than 2 megs). Default limit is
|
|
1 megabyte.</p>
|
|
<p><tt class="docutils literal"><span class="pre">piece_timeout</span></tt> controls the number of seconds from a request is sent until
|
|
it times out if no piece response is returned.</p>
|
|
<p><tt class="docutils literal"><span class="pre">request_queue_time</span></tt> is the length of the request queue given in the number
|
|
of seconds it should take for the other end to send all the pieces. i.e. the
|
|
actual number of requests depends on the download rate and this number.</p>
|
|
<p><tt class="docutils literal"><span class="pre">max_allowed_in_request_queue</span></tt> is the number of outstanding block requests
|
|
a peer is allowed to queue up in the client. If a peer sends more requests
|
|
than this (before the first one has been handled) the last request will be
|
|
dropped. The higher this is, the faster upload speeds the client can get to a
|
|
single peer.</p>
|
|
<p><tt class="docutils literal"><span class="pre">max_out_request_queue</span></tt> is the maximum number of outstanding requests to
|
|
send to a peer. This limit takes precedence over <tt class="docutils literal"><span class="pre">request_queue_time</span></tt>. i.e.
|
|
no matter the download speed, the number of outstanding requests will never
|
|
exceed this limit.</p>
|
|
<p><tt class="docutils literal"><span class="pre">whole_pieces_threshold</span></tt> is a limit in seconds. if a whole piece can be
|
|
downloaded in at least this number of seconds from a specific peer, the
|
|
peer_connection will prefer requesting whole pieces at a time from this peer.
|
|
The benefit of this is to better utilize disk caches by doing localized
|
|
accesses and also to make it easier to identify bad peers if a piece fails
|
|
the hash check.</p>
|
|
<p><tt class="docutils literal"><span class="pre">peer_timeout</span></tt> is the number of seconds the peer connection should
|
|
wait (for any activity on the peer connection) before closing it due
|
|
to time out. This defaults to 120 seconds, since that's what's specified
|
|
in the protocol specification. After half the time out, a keep alive message
|
|
is sent.</p>
|
|
<p><tt class="docutils literal"><span class="pre">urlseed_timeout</span></tt> is the same as <tt class="docutils literal"><span class="pre">peer_timeout</span></tt> but applies only to
|
|
url seeds. This value defaults to 20 seconds.</p>
|
|
<p><tt class="docutils literal"><span class="pre">urlseed_pipeline_size</span></tt> controls the pipelining with the web server. When
|
|
using persistent connections to HTTP 1.1 servers, the client is allowed to
|
|
send more requests before the first response is received. This number controls
|
|
the number of outstanding requests to use with url-seeds. Default is 5.</p>
|
|
<p><tt class="docutils literal"><span class="pre">file_pool_size</span></tt> is the the upper limit on the total number of files this
|
|
session will keep open. The reason why files are left open at all is that
|
|
some anti virus software hooks on every file close, and scans the file for
|
|
viruses. deferring the closing of the files will be the difference between
|
|
a usable system and a completely hogged down system. Most operating systems
|
|
also has a limit on the total number of file descriptors a process may have
|
|
open. It is usually a good idea to find this limit and set the number of
|
|
connections and the number of files limits so their sum is slightly below it.</p>
|
|
<p><tt class="docutils literal"><span class="pre">allow_multiple_connections_per_ip</span></tt> determines if connections from the
|
|
same IP address as existing connections should be rejected or not. Multiple
|
|
connections from the same IP address is not allowed by default, to prevent
|
|
abusive behavior by peers. It may be useful to allow such connections in
|
|
cases where simulations are run on the same machie, and all peers in a
|
|
swarm has the same IP address.</p>
|
|
<p><tt class="docutils literal"><span class="pre">max_failcount</span></tt> is the maximum times we try to connect to a peer before
|
|
stop connecting again. If a peer succeeds, the failcounter is reset. If
|
|
a peer is retrieved from a peer source (other than DHT) the failcount is
|
|
decremented by one, allowing another try.</p>
|
|
<p><tt class="docutils literal"><span class="pre">min_reconnect_time</span></tt> is the time to wait between connection attempts. If
|
|
the peer fails, the time is multiplied by fail counter.</p>
|
|
<p><tt class="docutils literal"><span class="pre">peer_connect_timeout</span></tt> the number of seconds to wait after a connection
|
|
attempt is initiated to a peer until it is considered as having timed out.
|
|
The default is 10 seconds. This setting is especially important in case
|
|
the number of half-open connections are limited, since stale half-open
|
|
connection may delay the connection of other peers considerably.</p>
|
|
<p><tt class="docutils literal"><span class="pre">ignore_limits_on_local_network</span></tt>, if set to true, upload, download and
|
|
unchoke limits are ignored for peers on the local network.</p>
|
|
<p><tt class="docutils literal"><span class="pre">connection_speed</span></tt> is the number of connection attempts that
|
|
are made per second. If a number <= 0 is specified, it will default to
|
|
200 connections per second.</p>
|
|
<p><tt class="docutils literal"><span class="pre">send_redundant_have</span></tt> controls if have messages will be sent
|
|
to peers that already have the piece. This is typically not necessary,
|
|
but it might be necessary for collecting statistics in some cases.
|
|
Default is false.</p>
|
|
<p><tt class="docutils literal"><span class="pre">lazy_bitfields</span></tt> prevents outgoing bitfields from being full. If the
|
|
client is seed, a few bits will be set to 0, and later filled in with
|
|
have-messages. This is to prevent certain ISPs from stopping people
|
|
from seeding.</p>
|
|
<p><tt class="docutils literal"><span class="pre">inactivity_timeout</span></tt>, if a peer is uninteresting and uninterested
|
|
for longer than this number of seconds, it will be disconnected.
|
|
Default is 10 minutes</p>
|
|
<p><tt class="docutils literal"><span class="pre">unchoke_interval</span></tt> is the number of seconds between chokes/unchokes.
|
|
On this interval, peers are re-evaluated for being choked/unchoked. This
|
|
is defined as 30 seconds in the protocol, and it should be significantly
|
|
longer than what it takes for TCP to ramp up to it's max rate.</p>
|
|
<p><tt class="docutils literal"><span class="pre">optimistic_unchoke_multiplier</span></tt> is the number of unchoke intervals between
|
|
each <em>optimistic</em> unchoke interval. On this timer, the currently optimistically
|
|
unchoked peer will change.</p>
|
|
<p><tt class="docutils literal"><span class="pre">announce_ip</span></tt> is the ip address passed along to trackers as the <tt class="docutils literal"><span class="pre">&ip=</span></tt> parameter.
|
|
If left as the default (default constructed), that parameter is ommited.</p>
|
|
<p><tt class="docutils literal"><span class="pre">num_want</span></tt> is the number of peers we want from each tracker request. It defines
|
|
what is sent as the <tt class="docutils literal"><span class="pre">&num_want=</span></tt> parameter to the tracker.</p>
|
|
<p><tt class="docutils literal"><span class="pre">initial_picker_threshold</span></tt> specifies the number of pieces we need before we
|
|
switch to rarest first picking. This defaults to 4, which means the 4 first
|
|
pieces in any torrent are picked at random, the following pieces are picked
|
|
in rarest first order.</p>
|
|
<p><tt class="docutils literal"><span class="pre">allowed_fast_set_size</span></tt> is the number of pieces we allow peers to download
|
|
from us without being unchoked.</p>
|
|
<p><tt class="docutils literal"><span class="pre">max_outstanding_disk_bytes_per_connection</span></tt> is the number of bytes each
|
|
connection is allowed to have waiting in the disk I/O queue before it is
|
|
throttled back. This limit is meant to stop fast internet connections to
|
|
queue up bufferes indefinitely on slow hard-drives or storage.</p>
|
|
<p><tt class="docutils literal"><span class="pre">handshake_timeout</span></tt> specifies the number of seconds we allow a peer to
|
|
delay responding to a protocol handshake. If no response is received within
|
|
this time, the connection is closed.</p>
|
|
<p><tt class="docutils literal"><span class="pre">use_dht_as_fallback</span></tt> determines how the DHT is used. If this is true
|
|
(which it is by default), the DHT will only be used for torrents where
|
|
all trackers in its tracker list has failed. Either by an explicit error
|
|
message or a time out.</p>
|
|
<p><tt class="docutils literal"><span class="pre">free_torrent_hashes</span></tt> determines whether or not the torrent's piece hashes
|
|
are kept in memory after the torrent becomes a seed or not. If it is set to
|
|
<tt class="docutils literal"><span class="pre">true</span></tt> the hashes are freed once the torrent is a seed (they're not
|
|
needed anymore since the torrent won't download anything more). If it's set
|
|
to false they are not freed. If they are freed, the <a class="reference" href="#torrent-info">torrent_info</a> returned
|
|
by get_torrent_info() will return an object that may be incomplete, that
|
|
cannot be passed back to <a class="reference" href="#add-torrent">add_torrent()</a> for instance.</p>
|
|
<p><tt class="docutils literal"><span class="pre">upnp_ignore_nonrouters</span></tt> indicates whether or not the UPnP implementation
|
|
should ignore any broadcast response from a device whose address is not the
|
|
configured router for this machine. i.e. it's a way to not talk to other
|
|
people's routers by mistake.</p>
|
|
<p><tt class="docutils literal"><span class="pre">send_buffer_waterbark</span></tt> is the upper limit of the send buffer low-watermark.
|
|
if the send buffer has fewer bytes than this, we'll read another 16kB block
|
|
onto it. If set too small, upload rate capacity will suffer. If set too high,
|
|
memory will be wasted. The actual watermark may be lower than this in case
|
|
the upload rate is low, this is the upper limit.</p>
|
|
<p><tt class="docutils literal"><span class="pre">auto_upload_slots</span></tt> defaults to true. When true, if there is a global upload
|
|
limit set and the current upload rate is less than 90% of that, another upload
|
|
slot is opened. If the upload rate has been saturated for an extended period
|
|
of time, on upload slot is closed. The number of upload slots will never be
|
|
less than what has been set by <tt class="docutils literal"><span class="pre">session::set_max_uploads()</span></tt>. To query the
|
|
current number of upload slots, see <tt class="docutils literal"><span class="pre">session_status::allowed_upload_slots</span></tt>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">use_parole_mode</span></tt> specifies if parole mode should be used. Parole mode means
|
|
that peers that participate in pieces that fail the hash check are put in a mode
|
|
where they are only allowed to download whole pieces. If the whole piece a peer
|
|
in parole mode fails the hash check, it is banned. If a peer participates in a
|
|
piece that passes the hash check, it is taken out of parole mode.</p>
|
|
<p><tt class="docutils literal"><span class="pre">cache_size</span></tt> is the disk write cache. It is specified in units of 16 KiB blocks.
|
|
It defaults to 512 (= 8 MB).</p>
|
|
<p><tt class="docutils literal"><span class="pre">cache_expiry</span></tt> is the number of seconds from the last cached write to a piece
|
|
in the write cache, to when it's forcefully flushed to disk. Default is 60 second.</p>
|
|
<p><tt class="docutils literal"><span class="pre">outgoing_ports</span></tt>, if set to something other than (0, 0) is a range of ports
|
|
used to bind outgoing sockets to. This may be useful for users whose router
|
|
allows them to assign QoS classes to traffic based on its local port. It is
|
|
a range instead of a single port because of the problems with failing to reconnect
|
|
to peers if a previous socket to that peer and port is in <tt class="docutils literal"><span class="pre">TIME_WAIT</span></tt> state.</p>
|
|
<p><tt class="docutils literal"><span class="pre">peer_tos</span></tt> determines the TOS byte set in the IP header of every packet
|
|
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" 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. The target number of active
|
|
torrents is <tt class="docutils literal"><span class="pre">max(active_downloads,</span> <span class="pre">active_seeds)</span></tt>. <tt class="docutils literal"><span class="pre">active_downloads</span></tt> and
|
|
<tt class="docutils literal"><span class="pre">active_seeds</span></tt> are upper limits on the number of downloading torrents and
|
|
seeding torrents respectively. Setting the value to -1 will mean unlimited.</p>
|
|
<p>For example if there are 10 seeding torrents and 10 downloading torrents, and
|
|
<tt class="docutils literal"><span class="pre">active_downloads</span></tt> is 4 and <tt class="docutils literal"><span class="pre">active_seeds</span></tt> is 4, there will be no seed
|
|
active, but 4 downloading torrents. If the settings are <tt class="docutils literal"><span class="pre">active_downloads</span></tt> = 2
|
|
and <tt class="docutils literal"><span class="pre">active_seeds</span></tt> = 4, then there will be 2 downloading torrenst and 2 seeding
|
|
torrents active. Torrents that are not auto managed are also counted against these
|
|
limits. If there are non-auto managed torrents that use up all the slots, no
|
|
auto managed torrent will be activated.</p>
|
|
<p>if <tt class="docutils literal"><span class="pre">dont_count_slow_torrents</span></tt> is true, torrents without any payload transfers are
|
|
not subject to the <tt class="docutils literal"><span class="pre">active_seeds</span></tt> and <tt class="docutils literal"><span class="pre">active_downloads</span></tt> limits. This is intended
|
|
to make it more likely to utilize all available bandwidth, and avoid having torrents
|
|
that don't transfer anything block the active slots.</p>
|
|
<p><tt class="docutils literal"><span class="pre">active_limit</span></tt> is a hard limit on the number of active seeds. This applies even to
|
|
slow torrents.</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 met the seed limit criteria. See <a class="reference" 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 met the seed limit criteria. See <a class="reference" 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 met the seed limit criteria.
|
|
See <a class="reference" href="#queuing">queuing</a>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">close_redundant_connections</span></tt> specifies whether libtorrent should close
|
|
connections where both ends have no utility in keeping the connection open.
|
|
For instance if both ends have completed their downloads, there's no point
|
|
in keeping it open. This defaults to <tt class="docutils literal"><span class="pre">true</span></tt>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">auto_scrape_interval</span></tt> is the number of seconds between scrapes of
|
|
queued torrents (auto managed and paused torrents). Auto managed
|
|
torrents that are paused, are scraped regularly in order to keep
|
|
track of their downloader/seed ratio. This ratio is used to determine
|
|
which torrents to seed and which to pause.</p>
|
|
<p><tt class="docutils literal"><span class="pre">auto_scrape_min_interval</span></tt> is the minimum number of seconds between any
|
|
automatic scrape (regardless of torrent). In case there are a large number
|
|
of paused auto managed torrents, this puts a limit on how often a scrape
|
|
request is sent.</p>
|
|
<p><tt class="docutils literal"><span class="pre">max_peerlist_size</span></tt> is the maximum number of peers in the list of
|
|
known peers. These peers are not necessarily connected, so this number
|
|
should be much greater than the maximum number of connected peers.
|
|
Peers are evicted from the cache when the list grows passed 90% of
|
|
this limit, and once the size hits the limit, peers are no longer
|
|
added to the list.</p>
|
|
<p><tt class="docutils literal"><span class="pre">min_announce_interval</span></tt> is the minimum allowed announce interval
|
|
for a tracker. This is specified in seconds, defaults to 5 minutes and
|
|
is used as a sanity check on what is returned from a tracker. It
|
|
mitigates hammering misconfigured trackers.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a id="pe-settings" name="pe-settings">pe_settings</a></h1>
|
|
<p>The <tt class="docutils literal"><span class="pre">pe_settings</span></tt> structure is used to control the settings related
|
|
to peer protocol encryption:</p>
|
|
<pre class="literal-block">
|
|
struct pe_settings
|
|
{
|
|
pe_settings();
|
|
|
|
enum enc_policy
|
|
{
|
|
forced,
|
|
enabled,
|
|
disabled
|
|
};
|
|
|
|
enum enc_level
|
|
{
|
|
plaintext,
|
|
rc4,
|
|
both
|
|
};
|
|
|
|
enc_policy out_enc_policy;
|
|
enc_policy in_enc_policy;
|
|
enc_level allowed_enc_level;
|
|
bool prefer_rc4;
|
|
};
|
|
</pre>
|
|
<p><tt class="docutils literal"><span class="pre">in_enc_policy</span></tt> and <tt class="docutils literal"><span class="pre">out_enc_policy</span></tt> control the settings for incoming
|
|
and outgoing connections respectively. The settings for these are:</p>
|
|
<blockquote>
|
|
<ul class="simple">
|
|
<li><tt class="docutils literal"><span class="pre">forced</span></tt> - Only encrypted connections are allowed. Incoming connections
|
|
that are not encrypted are closed and if the encrypted outgoing connection
|
|
fails, a non-encrypted retry will not be made.</li>
|
|
<li><tt class="docutils literal"><span class="pre">enabled</span></tt> - encrypted connections are enabled, but non-encrypted
|
|
connections are allowed. An incoming non-encrypted connection will
|
|
be accepted, and if an outgoing encrypted connection fails, a non-
|
|
encrypted connection will be tried.</li>
|
|
<li><tt class="docutils literal"><span class="pre">disabled</span></tt> - only non-encrypted connections are allowed.</li>
|
|
</ul>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">allowed_enc_level</span></tt> determines the encryption level of the
|
|
connections. This setting will adjust which encryption scheme is
|
|
offered to the other peer, as well as which encryption scheme is
|
|
selected by the client. The settings are:</p>
|
|
<blockquote>
|
|
<ul class="simple">
|
|
<li><tt class="docutils literal"><span class="pre">plaintext</span></tt> - only the handshake is encrypted, the bulk of the traffic
|
|
remains unchanged.</li>
|
|
<li><tt class="docutils literal"><span class="pre">rc4</span></tt> - the entire stream is encrypted with RC4</li>
|
|
<li><tt class="docutils literal"><span class="pre">both</span></tt> - both RC4 and plaintext connections are allowed.</li>
|
|
</ul>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">prefer_rc4</span></tt> can be set to true if you want to prefer the RC4 encrypted stream.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a id="proxy-settings" name="proxy-settings">proxy_settings</a></h1>
|
|
<p>The <tt class="docutils literal"><span class="pre">proxy_settings</span></tt> structs contains the information needed to
|
|
direct certain traffic to a proxy.</p>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
struct proxy_settings
|
|
{
|
|
proxy_settings();
|
|
|
|
std::string hostname;
|
|
int port;
|
|
|
|
std::string username;
|
|
std::string password;
|
|
|
|
enum proxy_type
|
|
{
|
|
none,
|
|
socks4,
|
|
socks5,
|
|
socks5_pw,
|
|
http,
|
|
http_pw
|
|
};
|
|
|
|
proxy_type type;
|
|
};
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">hostname</span></tt> is the name or IP of the proxy server. <tt class="docutils literal"><span class="pre">port</span></tt> is the
|
|
port number the proxy listens to. If required, <tt class="docutils literal"><span class="pre">username</span></tt> and <tt class="docutils literal"><span class="pre">password</span></tt>
|
|
can be set to authenticate with the proxy.</p>
|
|
<p>The <tt class="docutils literal"><span class="pre">type</span></tt> tells libtorrent what kind of proxy server it is. The following
|
|
options are available:</p>
|
|
<blockquote>
|
|
<ul class="simple">
|
|
<li><tt class="docutils literal"><span class="pre">none</span></tt> - This is the default, no proxy server is used, all other fields
|
|
are ignored.</li>
|
|
<li><tt class="docutils literal"><span class="pre">socks4</span></tt> - The server is assumed to be a <a class="reference" href="http://www.ufasoft.com/doc/socks4_protocol.htm">SOCKS4 server</a> that
|
|
requires a username.</li>
|
|
<li><tt class="docutils literal"><span class="pre">socks5</span></tt> - The server is assumed to be a SOCKS5 server (<a class="reference" href="http://www.faqs.org/rfcs/rfc1928.html">RFC 1928</a>) that
|
|
does not require any authentication. The username and password are ignored.</li>
|
|
<li><tt class="docutils literal"><span class="pre">socks5_pw</span></tt> - The server is assumed to be a SOCKS5 server that supports
|
|
plain text username and password authentication (<a class="reference" href="http://www.faqs.org/rfcs/rfc1929.html">RFC 1929</a>). The username
|
|
and password specified may be sent to the proxy if it requires.</li>
|
|
<li><tt class="docutils literal"><span class="pre">http</span></tt> - The server is assumed to be an HTTP proxy. If the transport used
|
|
for the connection is non-HTTP, the server is assumed to support the
|
|
<a class="reference" href="draft-luotonen-web-proxy-tunneling-01.txt">CONNECT</a> method. i.e. for web seeds and HTTP trackers, a plain proxy will
|
|
suffice. The proxy is assumed to not require authorization. The username
|
|
and password will not be used.</li>
|
|
<li><tt class="docutils literal"><span class="pre">http_pw</span></tt> - The server is assumed to be an HTTP proxy that requires
|
|
user authorization. The username and password will be sent to the proxy.</li>
|
|
</ul>
|
|
</blockquote>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a id="ip-filter" name="ip-filter">ip_filter</a></h1>
|
|
<p>The <tt class="docutils literal"><span class="pre">ip_filter</span></tt> class is a set of rules that uniquely categorizes all
|
|
ip addresses as allowed or disallowed. The default constructor creates
|
|
a single rule that allows all addresses (0.0.0.0 - 255.255.255.255 for
|
|
the IPv4 range, and the equivalent range covering all addresses for the
|
|
IPv6 range).</p>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
template <class Addr>
|
|
struct ip_range
|
|
{
|
|
Addr first;
|
|
Addr last;
|
|
int flags;
|
|
};
|
|
|
|
class ip_filter
|
|
{
|
|
public:
|
|
enum access_flags { blocked = 1 };
|
|
|
|
ip_filter();
|
|
void add_rule(address first, address last, int flags);
|
|
int access(address const& addr) const;
|
|
|
|
typedef boost::tuple<std::vector<ip_range<address_v4> >
|
|
, std::vector<ip_range<address_v6> > > filter_tuple_t;
|
|
|
|
filter_tuple_t export_filter() const;
|
|
};
|
|
</pre>
|
|
</blockquote>
|
|
<div class="section">
|
|
<h2><a id="id10" name="id10">ip_filter()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
ip_filter()
|
|
</pre>
|
|
</blockquote>
|
|
<p>Creates a default filter that doesn't filter any address.</p>
|
|
<p>postcondition:
|
|
<tt class="docutils literal"><span class="pre">access(x)</span> <span class="pre">==</span> <span class="pre">0</span></tt> for every <tt class="docutils literal"><span class="pre">x</span></tt></p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="add-rule" name="add-rule">add_rule()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void add_rule(address first, address last, int flags);
|
|
</pre>
|
|
</blockquote>
|
|
<p>Adds a rule to the filter. <tt class="docutils literal"><span class="pre">first</span></tt> and <tt class="docutils literal"><span class="pre">last</span></tt> defines a range of
|
|
ip addresses that will be marked with the given flags. The <tt class="docutils literal"><span class="pre">flags</span></tt>
|
|
can currently be 0, which means allowed, or <tt class="docutils literal"><span class="pre">ip_filter::blocked</span></tt>, which
|
|
means disallowed.</p>
|
|
<p>precondition:
|
|
<tt class="docutils literal"><span class="pre">first.is_v4()</span> <span class="pre">==</span> <span class="pre">last.is_v4()</span> <span class="pre">&&</span> <span class="pre">first.is_v6()</span> <span class="pre">==</span> <span class="pre">last.is_v6()</span></tt></p>
|
|
<p>postcondition:
|
|
<tt class="docutils literal"><span class="pre">access(x)</span> <span class="pre">==</span> <span class="pre">flags</span></tt> for every <tt class="docutils literal"><span class="pre">x</span></tt> in the range [<tt class="docutils literal"><span class="pre">first</span></tt>, <tt class="docutils literal"><span class="pre">last</span></tt>]</p>
|
|
<p>This means that in a case of overlapping ranges, the last one applied takes
|
|
precedence.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="access" name="access">access()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
int access(address const& addr) const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>Returns the access permissions for the given address (<tt class="docutils literal"><span class="pre">addr</span></tt>). The permission
|
|
can currently be 0 or <tt class="docutils literal"><span class="pre">ip_filter::blocked</span></tt>. The complexity of this operation
|
|
is O(<tt class="docutils literal"><span class="pre">log</span></tt> n), where n is the minimum number of non-overlapping ranges to describe
|
|
the current filter.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="export-filter" name="export-filter">export_filter()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
boost::tuple<std::vector<ip_range<address_v4> >
|
|
, std::vector<ip_range<address_v6> > > export_filter() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>This function will return the current state of the filter in the minimum number of
|
|
ranges possible. They are sorted from ranges in low addresses to high addresses. Each
|
|
entry in the returned vector is a range with the access control specified in its
|
|
<tt class="docutils literal"><span class="pre">flags</span></tt> field.</p>
|
|
<p>The return value is a tuple containing two range-lists. One for IPv4 addresses
|
|
and one for IPv6 addresses.</p>
|
|
</div>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a id="big-number" name="big-number">big_number</a></h1>
|
|
<p>Both the <tt class="docutils literal"><span class="pre">peer_id</span></tt> and <tt class="docutils literal"><span class="pre">sha1_hash</span></tt> types are typedefs of the class
|
|
<tt class="docutils literal"><span class="pre">big_number</span></tt>. It represents 20 bytes of data. Its synopsis follows:</p>
|
|
<pre class="literal-block">
|
|
class big_number
|
|
{
|
|
public:
|
|
bool operator==(const big_number& n) const;
|
|
bool operator!=(const big_number& n) const;
|
|
bool operator<(const big_number& n) const;
|
|
|
|
const unsigned char* begin() const;
|
|
const unsigned char* end() const;
|
|
|
|
unsigned char* begin();
|
|
unsigned char* end();
|
|
};
|
|
</pre>
|
|
<p>The iterators gives you access to individual bytes.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a id="bitfield" name="bitfield">bitfield</a></h1>
|
|
<p>The bitfiled type stores any number of bits as a bitfield in an array.</p>
|
|
<pre class="literal-block">
|
|
class bitfield
|
|
{
|
|
bitfield();
|
|
bitfield(int bits);
|
|
bitfield(int bits, bool val);
|
|
bitfield(char const* bytes, int bits);
|
|
bitfield(bitfield const& rhs);
|
|
|
|
void borrow_bytes(char* bytes, int bits);
|
|
~bitfield();
|
|
|
|
void assign(char const* bytes, int bits);
|
|
|
|
bool operator[](int index) const;
|
|
|
|
bool get_bit(int index) const;
|
|
|
|
void clear_bit(int index);
|
|
void set_bit(int index);
|
|
|
|
std::size_t size() const;
|
|
bool empty() const;
|
|
|
|
char const* bytes() const;
|
|
|
|
bitfield& operator=(bitfield const& rhs);
|
|
|
|
int count() const;
|
|
|
|
typedef const_iterator;
|
|
const_iterator begin() const;
|
|
const_iterator end() const;
|
|
|
|
void resize(int bits, bool val);
|
|
void set_all();
|
|
void clear_all();
|
|
void resize(int bits);
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a id="hasher" name="hasher">hasher</a></h1>
|
|
<p>This class creates sha1-hashes. Its declaration looks like this:</p>
|
|
<pre class="literal-block">
|
|
class hasher
|
|
{
|
|
public:
|
|
hasher();
|
|
hasher(char const* data, unsigned int len);
|
|
|
|
void update(char const* data, unsigned int len);
|
|
sha1_hash final();
|
|
void reset();
|
|
};
|
|
</pre>
|
|
<p>You use it by first instantiating it, then call <tt class="docutils literal"><span class="pre">update()</span></tt> to feed it
|
|
with data. i.e. you don't have to keep the entire buffer of which you want to
|
|
create the hash in memory. You can feed the hasher parts of it at a time. When
|
|
You have fed the hasher with all the data, you call <tt class="docutils literal"><span class="pre">final()</span></tt> and it
|
|
will return the sha1-hash of the data.</p>
|
|
<p>The constructor that takes a <tt class="docutils literal"><span class="pre">char</span> <span class="pre">const*</span></tt> and an integer will construct the
|
|
sha1 context and feed it the data passed in.</p>
|
|
<p>If you want to reuse the hasher object once you have created a hash, you have to
|
|
call <tt class="docutils literal"><span class="pre">reset()</span></tt> to reinitialize it.</p>
|
|
<p>The sha1-algorithm used was implemented by Steve Reid and released as public domain.
|
|
For more info, see <tt class="docutils literal"><span class="pre">src/sha1.cpp</span></tt>.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a id="fingerprint" name="fingerprint">fingerprint</a></h1>
|
|
<p>The fingerprint class represents information about a client and its version. It is used
|
|
to encode this information into the client's peer id.</p>
|
|
<p>This is the class declaration:</p>
|
|
<pre class="literal-block">
|
|
struct fingerprint
|
|
{
|
|
fingerprint(const char* id_string, int major, int minor
|
|
, int revision, int tag);
|
|
|
|
std::string to_string() const;
|
|
|
|
char name[2];
|
|
char major_version;
|
|
char minor_version;
|
|
char revision_version;
|
|
char tag_version;
|
|
|
|
};
|
|
</pre>
|
|
<p>The constructor takes a <tt class="docutils literal"><span class="pre">char</span> <span class="pre">const*</span></tt> that should point to a string constant containing
|
|
exactly two characters. These are the characters that should be unique for your client. Make
|
|
sure not to clash with anybody else. Here are some taken id's:</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="30%" />
|
|
<col width="70%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr><th class="head">id chars</th>
|
|
<th class="head">client</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<tr><td>'AZ'</td>
|
|
<td>Azureus</td>
|
|
</tr>
|
|
<tr><td>'LT'</td>
|
|
<td>libtorrent (default)</td>
|
|
</tr>
|
|
<tr><td>'BX'</td>
|
|
<td>BittorrentX</td>
|
|
</tr>
|
|
<tr><td>'MT'</td>
|
|
<td>Moonlight Torrent</td>
|
|
</tr>
|
|
<tr><td>'TS'</td>
|
|
<td>Torrent Storm</td>
|
|
</tr>
|
|
<tr><td>'SS'</td>
|
|
<td>Swarm Scope</td>
|
|
</tr>
|
|
<tr><td>'XT'</td>
|
|
<td>Xan Torrent</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>There's currently an informal directory of client id's <a class="reference" href="http://wiki.theory.org/BitTorrentSpecification#peer_id">here</a>.</p>
|
|
<p>The <tt class="docutils literal"><span class="pre">major</span></tt>, <tt class="docutils literal"><span class="pre">minor</span></tt>, <tt class="docutils literal"><span class="pre">revision</span></tt> and <tt class="docutils literal"><span class="pre">tag</span></tt> parameters are used to identify the
|
|
version of your client. All these numbers must be within the range [0, 9].</p>
|
|
<p><tt class="docutils literal"><span class="pre">to_string()</span></tt> will generate the actual string put in the peer-id, and return it.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a id="upnp-and-nat-pmp" name="upnp-and-nat-pmp">UPnP and NAT-PMP</a></h1>
|
|
<p>The <tt class="docutils literal"><span class="pre">upnp</span></tt> and <tt class="docutils literal"><span class="pre">natpmp</span></tt> classes contains the state for all UPnP and NAT-PMP mappings,
|
|
by default 1 or two mappings are made by libtorrent, one for the listen port and one
|
|
for the DHT port (UDP).</p>
|
|
<pre class="literal-block">
|
|
class upnp
|
|
{
|
|
public:
|
|
|
|
enum protocol_type { none = 0, udp = 1, tcp = 2 };
|
|
int add_mapping(protocol_type p, int external_port, int local_port);
|
|
void delete_mapping(int mapping_index);
|
|
|
|
void discover_device();
|
|
void close();
|
|
|
|
std::string router_model();
|
|
};
|
|
|
|
class natpmp
|
|
{
|
|
public:
|
|
|
|
enum protocol_type { none = 0, udp = 1, tcp = 2 };
|
|
int add_mapping(protocol_type p, int external_port, int local_port);
|
|
void delete_mapping(int mapping_index);
|
|
|
|
void close();
|
|
void rebind(address const& listen_interface);
|
|
};
|
|
</pre>
|
|
<p><tt class="docutils literal"><span class="pre">discover_device()</span></tt>, <tt class="docutils literal"><span class="pre">close()</span></tt> and <tt class="docutils literal"><span class="pre">rebind()</span></tt> are for internal uses and should
|
|
not be called directly by clients.</p>
|
|
<div class="section">
|
|
<h2><a id="add-mapping" name="add-mapping">add_mapping</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
int add_mapping(protocol_type p, int external_port, int local_port);
|
|
</pre>
|
|
</blockquote>
|
|
<p>Attempts to add a port mapping for the specified protocol. Valid protocols are
|
|
<tt class="docutils literal"><span class="pre">upnp::tcp</span></tt> and <tt class="docutils literal"><span class="pre">upnp::udp</span></tt> for the UPnP class and <tt class="docutils literal"><span class="pre">natpmp::tcp</span></tt> and
|
|
<tt class="docutils literal"><span class="pre">natpmp::udp</span></tt> for the NAT-PMP class.</p>
|
|
<p><tt class="docutils literal"><span class="pre">external_port</span></tt> is the port on the external address that will be mapped. This
|
|
is a hint, you are not guaranteed that this port will be available, and it may
|
|
end up being something else. In the <a class="reference" href="#portmap-alert">portmap_alert</a> notification, the actual
|
|
external port is reported.</p>
|
|
<p><tt class="docutils literal"><span class="pre">local_port</span></tt> is the port in the local machine that the mapping should forward
|
|
to.</p>
|
|
<p>The return value is an index that identifies this port mapping. This is used
|
|
to refer to mappings that fails or succeeds in the <a class="reference" href="#portmap-error-alert">portmap_error_alert</a> and
|
|
<a class="reference" href="#portmap-alert">portmap_alert</a> respectively. If The mapping fails immediately, the return value
|
|
is -1, which means failure. There will not be any error alert notification for
|
|
mappings that fail with a -1 return value.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="delete-mapping" name="delete-mapping">delete_mapping</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void delete_mapping(int mapping_index);
|
|
</pre>
|
|
</blockquote>
|
|
<p>This function removes a port mapping. <tt class="docutils literal"><span class="pre">mapping_index</span></tt> is the index that refers
|
|
to the mapping you want to remove, which was returned from <a class="reference" href="#add-mapping">add_mapping</a>.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="router-model" name="router-model">router_model()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
std::string router_model();
|
|
</pre>
|
|
</blockquote>
|
|
<p>This is only available for UPnP routers. If the model is advertized by
|
|
the router, it can be queried through this function.</p>
|
|
</div>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a id="free-functions" name="free-functions">free functions</a></h1>
|
|
<div class="section">
|
|
<h2><a id="identify-client" name="identify-client">identify_client()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
std::string identify_client(peer_id const& id);
|
|
</pre>
|
|
</blockquote>
|
|
<p>This function is declared in the header <tt class="docutils literal"><span class="pre"><libtorrent/identify_client.hpp></span></tt>. It can can be used
|
|
to extract a string describing a client version from its peer-id. It will recognize most clients
|
|
that have this kind of identification in the peer-id.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="client-fingerprint" name="client-fingerprint">client_fingerprint()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
boost::optional<fingerprint> client_fingerprint(peer_id const& p);
|
|
</pre>
|
|
</blockquote>
|
|
<p>Returns an optional fingerprint if any can be identified from the peer id. This can be used
|
|
to automate the identification of clients. It will not be able to identify peers with non-
|
|
standard encodings. Only Azureus style, Shadow's style and Mainline style. This function is
|
|
declared in the header <tt class="docutils literal"><span class="pre"><libtorrent/identify_client.hpp></span></tt>.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="bdecode-bencode" name="bdecode-bencode">bdecode() bencode()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
template<class InIt> entry bdecode(InIt start, InIt end);
|
|
template<class OutIt> void bencode(OutIt out, const entry& e);
|
|
</pre>
|
|
</blockquote>
|
|
<p>These functions will encode data to <a class="reference" href="http://wiki.theory.org/index.php/BitTorrentSpecification">bencoded</a> or decode <a class="reference" href="http://wiki.theory.org/index.php/BitTorrentSpecification">bencoded</a> data.</p>
|
|
<p>The <a class="reference" href="#entry">entry</a> class is the internal representation of the bencoded data
|
|
and it can be used to retrieve information, an <a class="reference" href="#entry">entry</a> can also be build by
|
|
the program and given to <tt class="docutils literal"><span class="pre">bencode()</span></tt> to encode it into the <tt class="docutils literal"><span class="pre">OutIt</span></tt>
|
|
iterator.</p>
|
|
<p>The <tt class="docutils literal"><span class="pre">OutIt</span></tt> and <tt class="docutils literal"><span class="pre">InIt</span></tt> are iterators
|
|
(<a class="reference" href="http://www.sgi.com/tech/stl/InputIterator.html">InputIterator</a> and <a class="reference" href="http://www.sgi.com/tech/stl/OutputIterator.html">OutputIterator</a> respectively). They
|
|
are templates and are usually instantiated as <a class="reference" href="http://www.sgi.com/tech/stl/ostream_iterator.html">ostream_iterator</a>,
|
|
<a class="reference" href="http://www.sgi.com/tech/stl/back_insert_iterator.html">back_insert_iterator</a> or <a class="reference" href="http://www.sgi.com/tech/stl/istream_iterator.html">istream_iterator</a>. These
|
|
functions will assume that the iterator refers to a character
|
|
(<tt class="docutils literal"><span class="pre">char</span></tt>). So, if you want to encode entry <tt class="docutils literal"><span class="pre">e</span></tt> into a buffer
|
|
in memory, you can do it like this:</p>
|
|
<pre class="literal-block">
|
|
std::vector<char> buffer;
|
|
bencode(std::back_inserter(buf), e);
|
|
</pre>
|
|
<p>If you want to decode a torrent file from a buffer in memory, you can do it like this:</p>
|
|
<pre class="literal-block">
|
|
std::vector<char> buffer;
|
|
// ...
|
|
entry e = bdecode(buf.begin(), buf.end());
|
|
</pre>
|
|
<p>Or, if you have a raw char buffer:</p>
|
|
<pre class="literal-block">
|
|
const char* buf;
|
|
// ...
|
|
entry e = bdecode(buf, buf + data_size);
|
|
</pre>
|
|
<p>Now we just need to know how to retrieve information from the <a class="reference" href="#entry">entry</a>.</p>
|
|
<p>If <tt class="docutils literal"><span class="pre">bdecode()</span></tt> encounters invalid encoded data in the range given to it
|
|
it will throw <a class="reference" href="#invalid-encoding">invalid_encoding</a>.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="add-magnet-uri" name="add-magnet-uri">add_magnet_uri()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
torrent_handle add_magnet_uri(session& ses, std::string const& uri
|
|
add_torrent_params p);
|
|
</pre>
|
|
</blockquote>
|
|
<p>This function parses the magnet URI (<tt class="docutils literal"><span class="pre">uri</span></tt>) as a bittorrent magnet link,
|
|
and adds the torrent to the specified session (<tt class="docutils literal"><span class="pre">ses</span></tt>). It returns the
|
|
handle to the newly added torrent, or an invalid handle in case parsing
|
|
failed. To control some initial settings of the torrent, sepcify those in
|
|
the <tt class="docutils literal"><span class="pre">add_torrent_params</span></tt>, <tt class="docutils literal"><span class="pre">p</span></tt>. See <a class="reference" href="#add-torrent">add_torrent()</a>.</p>
|
|
<p>For more information about magnet links, see <a class="reference" href="#magnet-links">magnet links</a>.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="make-magnet-uri" name="make-magnet-uri">make_magnet_uri()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
std::string make_magnet_uri(torrent_handle const& handle);
|
|
</pre>
|
|
</blockquote>
|
|
<p>Generates a magnet URI from the specified torrent. If the torrent
|
|
handle is invalid, an empty string is returned.</p>
|
|
<p>For more information about magnet links, see <a class="reference" href="#magnet-links">magnet links</a>.</p>
|
|
</div>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a id="alerts" name="alerts">alerts</a></h1>
|
|
<p>The <tt class="docutils literal"><span class="pre">pop_alert()</span></tt> function on session is the interface for retrieving
|
|
alerts, warnings, messages and errors from libtorrent. If no alerts have
|
|
been posted by libtorrent <tt class="docutils literal"><span class="pre">pop_alert()</span></tt> will return a default initialized
|
|
<tt class="docutils literal"><span class="pre">auto_ptr</span></tt> object. If there is an alert in libtorrent's queue, the alert
|
|
from the front of the queue is popped and returned.
|
|
You can then use the alert object and query</p>
|
|
<p>By default, only errors are reported. <tt class="docutils literal"><span class="pre">session::set_alert_mask()</span></tt> can be
|
|
used to specify which kinds of events should be reported. The alert mask
|
|
is a bitmask with the following bits:</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="32%" />
|
|
<col width="68%" />
|
|
</colgroup>
|
|
<tbody valign="top">
|
|
<tr><td><tt class="docutils literal"><span class="pre">error_notification</span></tt></td>
|
|
<td><p class="first">Enables alerts that report an error. This includes:</p>
|
|
<ul class="last simple">
|
|
<li>tracker errors</li>
|
|
<li>tracker warnings</li>
|
|
<li>file errors</li>
|
|
<li>resume data failures</li>
|
|
<li>web seed errors</li>
|
|
<li>.torrent files errors</li>
|
|
<li>listen socket errors</li>
|
|
<li>port mapping errors</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">peer_notification</span></tt></td>
|
|
<td>Enables alerts when peers send invalid requests, get banned or
|
|
snubbed.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">port_mapping_notification</span></tt></td>
|
|
<td>Enables alerts for port mapping events. For NAT-PMP and UPnP.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">storage_notification</span></tt></td>
|
|
<td>Enables alerts for events related to the storage. File errors and
|
|
synchronization events for moving the storage, renaming files etc.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">tracker_notification</span></tt></td>
|
|
<td>Enables all tracker events. Includes announcing to trackers,
|
|
receiving responses, warnings and errors.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">debug_notification</span></tt></td>
|
|
<td>Low level alerts for when peers are connected and disconnected.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">status_notification</span></tt></td>
|
|
<td>Enables alerts for when a torrent or the session changes state.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">progress_notification</span></tt></td>
|
|
<td>Alerts for when blocks are requested and completed. Also when
|
|
pieces are completed.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">ip_block_notification</span></tt></td>
|
|
<td>Alerts when a peer is blocked by the ip blocker or port blocker.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">all_categories</span></tt></td>
|
|
<td>The full bitmask, representing all available categories.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>Every alert belongs to one or more category. There is a small cost involved in posting alerts. Only
|
|
alerts that belong to an enabled category are posted. Setting the alert bitmask to 0 will disable
|
|
all alerts</p>
|
|
<p>When you get an alert, you can use <tt class="docutils literal"><span class="pre">typeid()</span></tt> or <tt class="docutils literal"><span class="pre">dynamic_cast<></span></tt> to get more detailed
|
|
information on exactly which type it is. i.e. what kind of error it is. You can also use a
|
|
<a class="reference" href="#dispatcher">dispatcher</a> mechanism that's available in libtorrent.</p>
|
|
<p>All alert types are defined in the <tt class="docutils literal"><span class="pre"><libtorrent/alert_types.hpp></span></tt> header file.</p>
|
|
<p>The <tt class="docutils literal"><span class="pre">alert</span></tt> class is the base class that specific messages are derived from. This
|
|
is its synopsis:</p>
|
|
<pre class="literal-block">
|
|
class alert
|
|
{
|
|
public:
|
|
|
|
enum category_t
|
|
{
|
|
error_notification = <em>implementation defined</em>,
|
|
peer_notification = <em>implementation defined</em>,
|
|
port_mapping_notification = <em>implementation defined</em>,
|
|
storage_notification = <em>implementation defined</em>,
|
|
tracker_notification = <em>implementation defined</em>,
|
|
debug_notification = <em>implementation defined</em>,
|
|
status_notification = <em>implementation defined</em>,
|
|
progress_notification = <em>implementation defined</em>,
|
|
ip_block_notification = <em>implementation defined</em>,
|
|
|
|
all_categories = <em>implementation defined</em>
|
|
};
|
|
|
|
ptime timestamp() const;
|
|
|
|
virtual ~alert();
|
|
|
|
virtual std::string message() const = 0;
|
|
virtual char const* what() const = 0;
|
|
virtual int category() const = 0;
|
|
virtual std::auto_ptr<alert> clone() const = 0;
|
|
};
|
|
</pre>
|
|
<p><tt class="docutils literal"><span class="pre">what()</span></tt> returns a string literal describing the type of the alert. It does
|
|
not include any information that might be bundled with the alert.</p>
|
|
<p><tt class="docutils literal"><span class="pre">category()</span></tt> returns a bitmask specifying which categories this alert belong to.</p>
|
|
<p><tt class="docutils literal"><span class="pre">clone()</span></tt> returns a pointer to a copy of the alert.</p>
|
|
<p><tt class="docutils literal"><span class="pre">message()</span></tt> generate a string describing the alert and the information bundled
|
|
with it. This is mainly intended for debug and development use. It is not suitable
|
|
to use this for applications that may be localized. Instead, handle each alert
|
|
type individually and extract and render the information from the alert depending
|
|
on the locale.</p>
|
|
<p>There's another alert base class that most alerts derives from, all the
|
|
alerts that are generated for a specific torrent are derived from:</p>
|
|
<pre class="literal-block">
|
|
struct torrent_alert: alert
|
|
{
|
|
// ...
|
|
torrent_handle handle;
|
|
};
|
|
</pre>
|
|
<p>There's also a base class for all alerts referring to tracker events:</p>
|
|
<pre class="literal-block">
|
|
struct tracker_alert: torrent_alert
|
|
{
|
|
// ...
|
|
std::string url;
|
|
};
|
|
</pre>
|
|
<p>The specific alerts are:</p>
|
|
<div class="section">
|
|
<h2><a id="external-ip-alert" name="external-ip-alert">external_ip_alert</a></h2>
|
|
<p>Whenever libtorrent learns about the machines external IP, this alert is
|
|
generated. The external IP address can be acquired from the tracker (if it
|
|
supports that) or from peers that supports the extension protocol.
|
|
The address can be accessed through the <tt class="docutils literal"><span class="pre">external_address</span></tt> member.</p>
|
|
<pre class="literal-block">
|
|
struct external_ip_alert: alert
|
|
{
|
|
// ...
|
|
address external_address;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="listen-failed-alert" name="listen-failed-alert">listen_failed_alert</a></h2>
|
|
<p>This alert is generated when none of the ports, given in the port range, to
|
|
<a class="reference" href="#session">session</a> can be opened for listening. This alert doesn't have any extra
|
|
data members.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="portmap-error-alert" name="portmap-error-alert">portmap_error_alert</a></h2>
|
|
<p>This alert is generated when a NAT router was successfully found but some
|
|
part of the port mapping request failed. It contains a text message that
|
|
may help the user figure out what is wrong. This alert is not generated in
|
|
case it appears the client is not running on a NAT:ed network or if it
|
|
appears there is no NAT router that can be remote controlled to add port
|
|
mappings.</p>
|
|
<p><tt class="docutils literal"><span class="pre">mapping</span></tt> refers to the mapping index of the port map that failed, i.e.
|
|
the index returned from <a class="reference" href="#add-mapping">add_mapping</a>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">type</span></tt> is 0 for NAT-PMP and 1 for UPnP.</p>
|
|
<pre class="literal-block">
|
|
struct portmap_error_alert: alert
|
|
{
|
|
// ...
|
|
int mapping;
|
|
int type;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="portmap-alert" name="portmap-alert">portmap_alert</a></h2>
|
|
<p>This alert is generated when a NAT router was successfully found and
|
|
a port was successfully mapped on it. On a NAT:ed network with a NAT-PMP
|
|
capable router, this is typically generated once when mapping the TCP
|
|
port and, if DHT is enabled, when the UDP port is mapped.</p>
|
|
<p><tt class="docutils literal"><span class="pre">mapping</span></tt> refers to the mapping index of the port map that failed, i.e.
|
|
the index returned from <a class="reference" href="#add-mapping">add_mapping</a>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">external_port</span></tt> is the external port allocated for the mapping.</p>
|
|
<p><tt class="docutils literal"><span class="pre">type</span></tt> is 0 for NAT-PMP and 1 for UPnP.</p>
|
|
<pre class="literal-block">
|
|
struct portmap_alert: alert
|
|
{
|
|
// ...
|
|
int mapping;
|
|
int external_port;
|
|
int type;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="file-error-alert" name="file-error-alert">file_error_alert</a></h2>
|
|
<p>If the storage fails to read or write files that it needs access to, this alert is
|
|
generated and the torrent is paused.</p>
|
|
<p><tt class="docutils literal"><span class="pre">file</span></tt> is the path to the file that was accessed when the error occurred.</p>
|
|
<p><tt class="docutils literal"><span class="pre">msg</span></tt> is the error message received from the OS.</p>
|
|
<pre class="literal-block">
|
|
struct file_error_alert: torrent_alert
|
|
{
|
|
// ...
|
|
std::string file;
|
|
std::string msg;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="tracker-announce-alert" name="tracker-announce-alert">tracker_announce_alert</a></h2>
|
|
<p>This alert is generated each time a tracker announce is sent (or attempted to be sent).
|
|
There are no extra data members in this alert. The url can be found in the base class
|
|
however.</p>
|
|
<pre class="literal-block">
|
|
struct tracker_announce_alert: tracker_alert
|
|
{
|
|
// ...
|
|
int event;
|
|
};
|
|
</pre>
|
|
<p>Event specifies what event was sent to the tracker. It is defined as:</p>
|
|
<ol class="arabic simple" start="0">
|
|
<li>None</li>
|
|
<li>Completed</li>
|
|
<li>Started</li>
|
|
<li>Stopped</li>
|
|
</ol>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="tracker-error-alert" name="tracker-error-alert">tracker_error_alert</a></h2>
|
|
<p>This alert is generated on tracker time outs, premature disconnects, invalid response or
|
|
a HTTP response other than "200 OK". From the alert you can get the handle to the torrent
|
|
the tracker belongs to.</p>
|
|
<p>The <tt class="docutils literal"><span class="pre">times_in_row</span></tt> member says how many times in a row this tracker has failed.
|
|
<tt class="docutils literal"><span class="pre">status_code</span></tt> is the code returned from the HTTP server. 401 means the tracker needs
|
|
authentication, 404 means not found etc. If the tracker timed out, the code will be set
|
|
to 0.</p>
|
|
<pre class="literal-block">
|
|
struct tracker_error_alert: tracker_alert
|
|
{
|
|
// ...
|
|
int times_in_row;
|
|
int status_code;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="tracker-reply-alert" name="tracker-reply-alert">tracker_reply_alert</a></h2>
|
|
<p>This alert is only for informational purpose. It is generated when a tracker announce
|
|
succeeds. It is generated regardless what kind of tracker was used, be it UDP, HTTP or
|
|
the DHT.</p>
|
|
<pre class="literal-block">
|
|
struct tracker_reply_alert: tracker_alert
|
|
{
|
|
// ...
|
|
int num_peers;
|
|
};
|
|
</pre>
|
|
<p>The <tt class="docutils literal"><span class="pre">num_peers</span></tt> tells how many peers were returned from the tracker. This is
|
|
not necessarily all new peers, some of them may already be connected.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="dht-reply-alert" name="dht-reply-alert">dht_reply_alert</a></h2>
|
|
<p>This alert is generated each time the DHT receives peers from a node. <tt class="docutils literal"><span class="pre">num_peers</span></tt>
|
|
is the number of peers we received in this packet. Typically these packets are
|
|
received from multiple DHT nodes, and so the alerts are typically generated
|
|
a few at a time.</p>
|
|
<pre class="literal-block">
|
|
struct dht_reply_alert: tracker_alert
|
|
{
|
|
// ...
|
|
int num_peers;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="tracker-warning-alert" name="tracker-warning-alert">tracker_warning_alert</a></h2>
|
|
<p>This alert is triggered if the tracker reply contains a warning field. Usually this
|
|
means that the tracker announce was successful, but the tracker has a message to
|
|
the client. The <tt class="docutils literal"><span class="pre">msg</span></tt> string in the alert contains the warning message from
|
|
the tracker.</p>
|
|
<pre class="literal-block">
|
|
struct tracker_warning_alert: tracker_alert
|
|
{
|
|
// ...
|
|
std::string msg;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="scrape-reply-alert" name="scrape-reply-alert">scrape_reply_alert</a></h2>
|
|
<p>This alert is generated when a scrape request succeeds. <tt class="docutils literal"><span class="pre">incomplete</span></tt>
|
|
and <tt class="docutils literal"><span class="pre">complete</span></tt> is the data returned in the scrape response. These numbers
|
|
may be -1 if the reponse was malformed.</p>
|
|
<pre class="literal-block">
|
|
struct scrape_reply_alert: tracker_alert
|
|
{
|
|
// ...
|
|
int incomplete;
|
|
int complete;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="scrape-failed-alert" name="scrape-failed-alert">scrape_failed_alert</a></h2>
|
|
<p>If a scrape request fails, this alert is generated. This might be due
|
|
to the tracker timing out, refusing connection or returning an http response
|
|
code indicating an error. <tt class="docutils literal"><span class="pre">msg</span></tt> contains a message describing the error.</p>
|
|
<pre class="literal-block">
|
|
struct scrape_failed_alert: tracker_alert
|
|
{
|
|
// ...
|
|
std::string msg;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="url-seed-alert" name="url-seed-alert">url_seed_alert</a></h2>
|
|
<p>This alert is generated when a HTTP seed name lookup fails.</p>
|
|
<p>It contains <tt class="docutils literal"><span class="pre">url</span></tt> to the HTTP seed that failed along with an error message.</p>
|
|
<pre class="literal-block">
|
|
struct url_seed_alert: torrent_alert
|
|
{
|
|
// ...
|
|
std::string url;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="hash-failed-alert" name="hash-failed-alert">hash_failed_alert</a></h2>
|
|
<p>This alert is generated when a finished piece fails its hash check. You can get the handle
|
|
to the torrent which got the failed piece and the index of the piece itself from the alert.</p>
|
|
<pre class="literal-block">
|
|
struct hash_failed_alert: torrent_alert
|
|
{
|
|
// ...
|
|
int piece_index;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="peer-ban-alert" name="peer-ban-alert">peer_ban_alert</a></h2>
|
|
<p>This alert is generated when a peer is banned because it has sent too many corrupt pieces
|
|
to us. <tt class="docutils literal"><span class="pre">ip</span></tt> is the endpoint to the peer that was banned.</p>
|
|
<pre class="literal-block">
|
|
struct peer_ban_alert: torrent_alert
|
|
{
|
|
// ...
|
|
asio::ip::tcp::endpoint ip;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="peer-error-alert" name="peer-error-alert">peer_error_alert</a></h2>
|
|
<p>This alert is generated when a peer sends invalid data over the peer-peer protocol. The peer
|
|
will be disconnected, but you get its ip address from the alert, to identify it.</p>
|
|
<pre class="literal-block">
|
|
struct peer_error_alert: torrent_alert
|
|
{
|
|
// ...
|
|
asio::ip::tcp::endpoint ip;
|
|
peer_id id;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="invalid-request-alert" name="invalid-request-alert">invalid_request_alert</a></h2>
|
|
<p>This is a debug alert that is generated by an incoming invalid piece request.
|
|
<tt class="docutils literal"><span class="pre">ìp</span></tt> is the address of the peer and the <tt class="docutils literal"><span class="pre">request</span></tt> is the actual incoming
|
|
request from the peer.</p>
|
|
<pre class="literal-block">
|
|
struct invalid_request_alert: torrent_alert
|
|
{
|
|
invalid_request_alert(
|
|
peer_request const& r
|
|
, torrent_handle const& h
|
|
, asio::ip::tcp::endpoint const& send
|
|
, peer_id const& pid
|
|
, std::string const& msg);
|
|
|
|
virtual std::auto_ptr<alert> clone() const;
|
|
|
|
asio::ip::tcp::endpoint ip;
|
|
peer_request request;
|
|
peer_id id;
|
|
};
|
|
|
|
|
|
struct peer_request
|
|
{
|
|
int piece;
|
|
int start;
|
|
int length;
|
|
bool operator==(peer_request const& r) const;
|
|
};
|
|
</pre>
|
|
<p>The <tt class="docutils literal"><span class="pre">peer_request</span></tt> contains the values the client sent in its <tt class="docutils literal"><span class="pre">request</span></tt> message. <tt class="docutils literal"><span class="pre">piece</span></tt> is
|
|
the index of the piece it want data from, <tt class="docutils literal"><span class="pre">start</span></tt> is the offset within the piece where the data
|
|
should be read, and <tt class="docutils literal"><span class="pre">length</span></tt> is the amount of data it wants.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="torrent-finished-alert" name="torrent-finished-alert">torrent_finished_alert</a></h2>
|
|
<p>This alert is generated when a torrent switches from being a downloader to a seed.
|
|
It will only be generated once per torrent. It contains a torrent_handle to the
|
|
torrent in question.</p>
|
|
<p>There are no additional data members in this alert.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="metadata-failed-alert" name="metadata-failed-alert">metadata_failed_alert</a></h2>
|
|
<p>This alert is generated when the metadata has been completely received and the info-hash
|
|
failed to match it. i.e. the metadata that was received was corrupt. libtorrent will
|
|
automatically retry to fetch it in this case. This is only relevant when running a
|
|
torrent-less download, with the metadata extension provided by libtorrent.</p>
|
|
<p>There are no additional data members in this alert.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="metadata-received-alert" name="metadata-received-alert">metadata_received_alert</a></h2>
|
|
<p>This alert is generated when the metadata has been completely received and the torrent
|
|
can start downloading. It is not generated on torrents that are started with metadata, but
|
|
only those that needs to download it from peers (when utilizing the libtorrent extension).</p>
|
|
<p>There are no additional data members in this alert.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="fastresume-rejected-alert" name="fastresume-rejected-alert">fastresume_rejected_alert</a></h2>
|
|
<p>This alert is generated when a fastresume file has been passed to <tt class="docutils literal"><span class="pre">add_torrent</span></tt> but the
|
|
files on disk did not match the fastresume file. The string explains the reason why the
|
|
resume file was rejected.</p>
|
|
<pre class="literal-block">
|
|
struct fastresume_rejected_alert: torrent_alert
|
|
{
|
|
// ...
|
|
std::string msg;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="peer-blocked-alert" name="peer-blocked-alert">peer_blocked_alert</a></h2>
|
|
<p>This alert is generated when a peer is blocked by the IP filter. The <tt class="docutils literal"><span class="pre">ip</span></tt> member is the
|
|
address that was blocked.</p>
|
|
<pre class="literal-block">
|
|
struct peer_blocked_alert: alert
|
|
{
|
|
// ...
|
|
address ip;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="storage-moved-alert" name="storage-moved-alert">storage_moved_alert</a></h2>
|
|
<p>The <tt class="docutils literal"><span class="pre">storage_moved_alert</span></tt> is generated when all the disk IO has completed and the
|
|
files have been moved, as an effect of a call to <tt class="docutils literal"><span class="pre">torrent_handle::move_storage</span></tt>. This
|
|
is useful to synchronize with the actual disk. The <tt class="docutils literal"><span class="pre">path</span></tt> member is the new path of
|
|
the storage.</p>
|
|
<pre class="literal-block">
|
|
struct storage_moved_alert: torrent_alert
|
|
{
|
|
// ...
|
|
std::string path;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="torrent-paused-alert" name="torrent-paused-alert">torrent_paused_alert</a></h2>
|
|
<p>This alert is generated as a response to a <tt class="docutils literal"><span class="pre">torrent_handle::pause</span></tt> request. It is
|
|
generated once all disk IO is complete and the files in the torrent have been closed.
|
|
This is useful for synchronizing with the disk.</p>
|
|
<p>There are no additional data members in this alert.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="torrent-resumed-alert" name="torrent-resumed-alert">torrent_resumed_alert</a></h2>
|
|
<p>This alert is generated as a response to a <tt class="docutils literal"><span class="pre">torrent_handle::resume</span></tt> request. It is
|
|
generated when a torrent goes from a paused state to an active state.</p>
|
|
<p>There are no additional data members in this alert.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="save-resume-data-alert" name="save-resume-data-alert">save_resume_data_alert</a></h2>
|
|
<p>This alert is generated as a response to a <tt class="docutils literal"><span class="pre">torrent_handle::save_resume_data</span></tt> request.
|
|
It is generated once the disk IO thread is done writing the state for this torrent.
|
|
The <tt class="docutils literal"><span class="pre">resume_data</span></tt> member points to the resume data.</p>
|
|
<pre class="literal-block">
|
|
struct save_resume_data_alert: torrent_alert
|
|
{
|
|
// ...
|
|
boost::shared_ptr<entry> resume_data;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="save-resume-data-failed-alert" name="save-resume-data-failed-alert">save_resume_data_failed_alert</a></h2>
|
|
<p>This alert is generated instead of <tt class="docutils literal"><span class="pre">save_resume_data_alert</span></tt> if there was an error
|
|
generating the resume data. <tt class="docutils literal"><span class="pre">msg</span></tt> describes what went wrong.</p>
|
|
<pre class="literal-block">
|
|
struct save_resume_data_failed_alert: torrent_alert
|
|
{
|
|
// ...
|
|
std::string msg;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="dispatcher" name="dispatcher">dispatcher</a></h2>
|
|
<p>The <tt class="docutils literal"><span class="pre">handle_alert</span></tt> class is defined in <tt class="docutils literal"><span class="pre"><libtorrent/alert.hpp></span></tt>.</p>
|
|
<p>Examples usage:</p>
|
|
<pre class="literal-block">
|
|
struct my_handler
|
|
{
|
|
void operator()(portmap_error_alert const& a)
|
|
{
|
|
std::cout << "Portmapper: " << a.msg << std::endl;
|
|
}
|
|
|
|
void operator()(tracker_warning_alert const& a)
|
|
{
|
|
std::cout << "Tracker warning: " << a.msg << std::endl;
|
|
}
|
|
|
|
void operator()(torrent_finished_alert const& a)
|
|
{
|
|
// write fast resume data
|
|
// ...
|
|
|
|
std::cout << a.handle.get_torrent_info().name() << "completed"
|
|
<< std::endl;
|
|
}
|
|
};
|
|
</pre>
|
|
<pre class="literal-block">
|
|
std::auto_ptr<alert> a;
|
|
a = ses.pop_alert();
|
|
my_handler h;
|
|
while (a.get())
|
|
{
|
|
handle_alert<portmap_error_alert
|
|
, tracker_warning_alert
|
|
, torrent_finished_alert
|
|
>::handle_alert(h, a);
|
|
a = ses.pop_alert();
|
|
}
|
|
</pre>
|
|
<p>In this example 3 alert types are used. You can use any number of template
|
|
parameters to select between more types. If the number of types are more than
|
|
15, you can define <tt class="docutils literal"><span class="pre">TORRENT_MAX_ALERT_TYPES</span></tt> to a greater number before
|
|
including <tt class="docutils literal"><span class="pre"><libtorrent/alert.hpp></span></tt>.</p>
|
|
</div>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a id="exceptions" name="exceptions">exceptions</a></h1>
|
|
<p>There are a number of exceptions that can be thrown from different places in libtorrent,
|
|
here's a complete list with description.</p>
|
|
<div class="section">
|
|
<h2><a id="invalid-handle" name="invalid-handle">invalid_handle</a></h2>
|
|
<p>This exception is thrown when querying information from a <a class="reference" href="#torrent-handle">torrent_handle</a> that hasn't
|
|
been initialized or that has become invalid.</p>
|
|
<pre class="literal-block">
|
|
struct invalid_handle: std::exception
|
|
{
|
|
const char* what() const throw();
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="duplicate-torrent" name="duplicate-torrent">duplicate_torrent</a></h2>
|
|
<p>This is thrown by <a class="reference" href="#add-torrent">add_torrent()</a> if the torrent already has been added to
|
|
the session. Since <a class="reference" href="#remove-torrent">remove_torrent()</a> is asynchronous, this exception may
|
|
be thrown if the torrent is removed and then immediately added again.</p>
|
|
<pre class="literal-block">
|
|
struct duplicate_torrent: std::exception
|
|
{
|
|
const char* what() const throw();
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="invalid-encoding" name="invalid-encoding">invalid_encoding</a></h2>
|
|
<p>This is thrown by <tt class="docutils literal"><span class="pre">bdecode()</span></tt> if the input data is not a valid bencoding.</p>
|
|
<pre class="literal-block">
|
|
struct invalid_encoding: std::exception
|
|
{
|
|
const char* what() const throw();
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="type-error" name="type-error">type_error</a></h2>
|
|
<p>This is thrown from the accessors of <tt class="docutils literal"><span class="pre">entry</span></tt> if the data type of the <tt class="docutils literal"><span class="pre">entry</span></tt> doesn't
|
|
match the type you want to extract from it.</p>
|
|
<pre class="literal-block">
|
|
struct type_error: std::runtime_error
|
|
{
|
|
type_error(const char* error);
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="invalid-torrent-file" name="invalid-torrent-file">invalid_torrent_file</a></h2>
|
|
<p>This exception is thrown from the constructor of <tt class="docutils literal"><span class="pre">torrent_info</span></tt> if the given bencoded information
|
|
doesn't meet the requirements on what information has to be present in a torrent file.</p>
|
|
<pre class="literal-block">
|
|
struct invalid_torrent_file: std::exception
|
|
{
|
|
const char* what() const throw();
|
|
};
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a id="storage-interface" name="storage-interface">storage_interface</a></h1>
|
|
<p>The storage interface is a pure virtual class that can be implemented to
|
|
change the behavior of the actual file storage. The interface looks like
|
|
this:</p>
|
|
<pre class="literal-block">
|
|
struct storage_interface
|
|
{
|
|
virtual void initialize(bool allocate_files) = 0;
|
|
virtual size_type read(char* buf, int slot, int offset, int size) = 0;
|
|
virtual void write(const char* buf, int slot, int offset, int size) = 0;
|
|
virtual bool move_storage(fs::path save_path) = 0;
|
|
virtual bool verify_resume_data(lazy_entry& rd, std::string& error) = 0;
|
|
virtual void write_resume_data(entry& rd) const = 0;
|
|
virtual void move_slot(int src_slot, int dst_slot) = 0;
|
|
virtual void swap_slots(int slot1, int slot2) = 0;
|
|
virtual void swap_slots3(int slot1, int slot2, int slot3) = 0;
|
|
virtual sha1_hash hash_for_slot(int slot, partial_hash& h, int piece_size) = 0;
|
|
virtual void release_files() = 0;
|
|
virtual void delete_files() = 0;
|
|
virtual ~storage_interface() {}
|
|
};
|
|
</pre>
|
|
<div class="section">
|
|
<h2><a id="initialize" name="initialize">initialize()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void initialize(bool allocate_files) = 0;
|
|
</pre>
|
|
</blockquote>
|
|
<p>This function is called when the storage is to be initialized. The default storage
|
|
will create directories and empty files at this point. If <tt class="docutils literal"><span class="pre">allocate_files</span></tt> is true,
|
|
it will also <tt class="docutils literal"><span class="pre">ftruncate</span></tt> all files to their target size.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="read" name="read">read()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
size_type read(char* buf, int slot, int offset, int size) = 0;
|
|
</pre>
|
|
</blockquote>
|
|
<p>This function should read the data in the given slot and at the given offset
|
|
and <tt class="docutils literal"><span class="pre">size</span></tt> number of bytes. The data is to be copied to <tt class="docutils literal"><span class="pre">buf</span></tt>.</p>
|
|
<p>The return value is the number of bytes actually read.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="write" name="write">write()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void write(const char* buf, int slot, int offset, int size) = 0;
|
|
</pre>
|
|
</blockquote>
|
|
<p>This function should write the data in <tt class="docutils literal"><span class="pre">buf</span></tt> to the given slot (<tt class="docutils literal"><span class="pre">slot</span></tt>) at offset
|
|
<tt class="docutils literal"><span class="pre">offset</span></tt> in that slot. The buffer size is <tt class="docutils literal"><span class="pre">size</span></tt>.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="id12" name="id12">move_storage()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
bool move_storage(fs::path save_path) = 0;
|
|
</pre>
|
|
</blockquote>
|
|
<p>This function should move all the files belonging to the storage to the new save_path.
|
|
The default storage moves the single file or the directory of the torrent.</p>
|
|
<p>Before moving the files, any open file handles may have to be closed, like
|
|
<tt class="docutils literal"><span class="pre">release_files()</span></tt>.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="verify-resume-data" name="verify-resume-data">verify_resume_data()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
bool verify_resume_data(entry& rd, std::string& error) = 0;
|
|
</pre>
|
|
</blockquote>
|
|
<p>This function should verify the resume data <tt class="docutils literal"><span class="pre">rd</span></tt> with the files
|
|
on disk. If the resume data seems to be up-to-date, return true. If
|
|
not, set <tt class="docutils literal"><span class="pre">error</span></tt> to a description of what mismatched and return false.</p>
|
|
<p>The default storage may compare file sizes and time stamps of the files.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="write-resume-data" name="write-resume-data">write_resume_data()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void write_resume_data(entry& rd) const = 0;
|
|
</pre>
|
|
</blockquote>
|
|
<p>This function should fill in resume data, the current state of the
|
|
storage, in <tt class="docutils literal"><span class="pre">rd</span></tt>. The default storage adds file timestamps and
|
|
sizes.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="move-slot" name="move-slot">move_slot()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void move_slot(int src_slot, int dst_slot) = 0;
|
|
</pre>
|
|
</blockquote>
|
|
<p>This function should copy or move the data in slot <tt class="docutils literal"><span class="pre">src_slot</span></tt> to
|
|
the slot <tt class="docutils literal"><span class="pre">dst_slot</span></tt>. This is only used in compact mode.</p>
|
|
<p>If the storage caches slots, this could be implemented more
|
|
efficient than reading and writing the data.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="swap-slots" name="swap-slots">swap_slots()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void swap_slots(int slot1, int slot2) = 0;
|
|
</pre>
|
|
</blockquote>
|
|
<p>This function should swap the data in <tt class="docutils literal"><span class="pre">slot1</span></tt> and <tt class="docutils literal"><span class="pre">slot2</span></tt>. The default
|
|
storage uses a scratch buffer to read the data into, then moving the other
|
|
slot and finally writing back the temporary slot's data</p>
|
|
<p>This is only used in compact mode.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="swap-slots3" name="swap-slots3">swap_slots3()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void swap_slots3(int slot1, int slot2, int slot3) = 0;
|
|
</pre>
|
|
</blockquote>
|
|
<p>This function should do a 3-way swap, or shift of the slots. <tt class="docutils literal"><span class="pre">slot1</span></tt>
|
|
should move to <tt class="docutils literal"><span class="pre">slot2</span></tt>, which should be moved to <tt class="docutils literal"><span class="pre">slot3</span></tt> which in turn
|
|
should be moved to <tt class="docutils literal"><span class="pre">slot1</span></tt>.</p>
|
|
<p>This is only used in compact mode.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="hash-for-slot" name="hash-for-slot">hash_for_slot()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
sha1_hash hash_for_slot(int slot, partial_hash& h, int piece_size) = 0;
|
|
</pre>
|
|
</blockquote>
|
|
<p>The function should read the remaining bytes of the slot and hash it with the
|
|
sha-1 state in <tt class="docutils literal"><span class="pre">partion_hash</span></tt>. The <tt class="docutils literal"><span class="pre">partial_hash</span></tt> struct looks like this:</p>
|
|
<pre class="literal-block">
|
|
struct partial_hash
|
|
{
|
|
partial_hash();
|
|
int offset;
|
|
hasher h;
|
|
};
|
|
</pre>
|
|
<p><tt class="docutils literal"><span class="pre">offset</span></tt> is the number of bytes in the slot that has already been hashed, and
|
|
<tt class="docutils literal"><span class="pre">h</span></tt> is the sha-1 state of that hash. <tt class="docutils literal"><span class="pre">piece_size</span></tt> is the size of the piece
|
|
that is stored in the given slot.</p>
|
|
<p>The function should return the hash of the piece stored in the slot.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="release-files" name="release-files">release_files()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void release_files() = 0;
|
|
</pre>
|
|
</blockquote>
|
|
<p>This function should release all the file handles that it keeps open to files
|
|
belonging to this storage. The default implementation just calls
|
|
<tt class="docutils literal"><span class="pre">file_pool::release_files(this)</span></tt>.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="delete-files" name="delete-files">delete_files()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void delete_files() = 0;
|
|
</pre>
|
|
</blockquote>
|
|
<p>This function should delete all files and directories belonging to this storage.</p>
|
|
</div>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a id="magnet-links" name="magnet-links">magnet links</a></h1>
|
|
<p>Magnet links are URIs that includes an info-hash, a display name and optionally
|
|
a tracker url. The idea behind magnet links is that an end user can click on a
|
|
link in a browser and have it handled by a bittorrent application, to start a
|
|
download, without any .torrent file.</p>
|
|
<p>The format of the magnet URI is:</p>
|
|
<p><strong>magnet:?xt=urn:btih:</strong> <em>Base32 encoded info-hash</em> [ <strong>&dn=</strong> <em>name of download</em> ] [ <strong>&tr=</strong> <em>tracker URL</em> ]*</p>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a id="queuing" name="queuing">queuing</a></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" 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>, <tt class="docutils literal"><span class="pre">active_seeds</span></tt> and <tt class="docutils literal"><span class="pre">active_limit</span></tt> in <a class="reference" href="#session-settings">session_settings</a>.
|
|
These limits takes non auto managed torrents into account as well. If there 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>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" 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" href="#save-resume-data">save_resume_data()</a>.</p>
|
|
<div class="section">
|
|
<h2><a id="downloading" name="downloading">downloading</a></h2>
|
|
<p>Torrents that are currently being downloaded or incomplete (with bytes still to download)
|
|
are queued. The torrents in the front of the queue are started to be actively downloaded
|
|
and the rest are ordered with regards to their queue position. Any newly added torrent
|
|
is placed at the end of the queue. Once a torrent is removed or turns into a seed, its
|
|
queue position is -1 and all torrents that used to be after it in the queue, decreases their
|
|
position in order to fill the gap.</p>
|
|
<p>The queue positions are always in a sequence without any gaps.</p>
|
|
<p>Lower queue position means closer to the front of the queue, and will be started sooner than
|
|
torrents with higher queue positions.</p>
|
|
<p>To query a torrent for its position in the queue, or change its position, see:
|
|
<a class="reference" href="#queue-position-queue-position-up-queue-position-down-queue-position-top-queue-position-bottom">queue_position() queue_position_up() queue_position_down() queue_position_top() queue_position_bottom()</a>.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="seeding" name="seeding">seeding</a></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" href="#session-settings">session_settings</a>.</p>
|
|
</div>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a id="fast-resume" name="fast-resume">fast resume</a></h1>
|
|
<p>The fast resume mechanism is a way to remember which pieces are downloaded
|
|
and where they are put between sessions. You can generate fast resume data by
|
|
calling <a class="reference" href="#save-resume-data">save_resume_data()</a> on <a class="reference" href="#torrent-handle">torrent_handle</a>. You can
|
|
then save this data to disk and use it when resuming the torrent. libtorrent
|
|
will not check the piece hashes then, and rely on the information given in the
|
|
fast-resume data. The fast-resume data also contains information about which
|
|
blocks, in the unfinished pieces, were downloaded, so it will not have to
|
|
start from scratch on the partially downloaded pieces.</p>
|
|
<p>To use the fast-resume data you simply give it to <a class="reference" href="#add-torrent">add_torrent()</a>, and it
|
|
will skip the time consuming checks. It may have to do the checking anyway, if
|
|
the fast-resume data is corrupt or doesn't fit the storage for that torrent,
|
|
then it will not trust the fast-resume data and just do the checking.</p>
|
|
<div class="section">
|
|
<h2><a id="file-format" name="file-format">file format</a></h2>
|
|
<p>The file format is a bencoded dictionary containing the following fields:</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="26%" />
|
|
<col width="74%" />
|
|
</colgroup>
|
|
<tbody valign="top">
|
|
<tr><td><tt class="docutils literal"><span class="pre">file-format</span></tt></td>
|
|
<td>string: "libtorrent resume file"</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">file-version</span></tt></td>
|
|
<td>integer: 1</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">info-hash</span></tt></td>
|
|
<td>string, the info hash of the torrent this data is saved for.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">blocks</span> <span class="pre">per</span> <span class="pre">piece</span></tt></td>
|
|
<td>integer, the number of blocks per piece. Must be: piece_size
|
|
/ (16 * 1024). Clamped to be within the range [1, 256]. It
|
|
is the number of blocks per (normal sized) piece. Usually
|
|
each block is 16 * 1024 bytes in size. But if piece size is
|
|
greater than 4 megabytes, the block size will increase.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">pieces</span></tt></td>
|
|
<td>A string with piece flags, one character per piece.
|
|
Bit 1 means we have that piece.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">slots</span></tt></td>
|
|
<td><p class="first">list of integers. The list maps slots to piece indices. It
|
|
tells which piece is on which slot. If piece index is -2 it
|
|
means it is free, that there's no piece there. If it is -1,
|
|
means the slot isn't allocated on disk yet. The pieces have
|
|
to meet the following requirement:</p>
|
|
<p class="last">If there's a slot at the position of the piece index,
|
|
the piece must be located in that slot.</p>
|
|
</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">peers</span></tt></td>
|
|
<td><p class="first">list of dictionaries. Each dictionary has the following
|
|
layout:</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="18%" />
|
|
<col width="82%" />
|
|
</colgroup>
|
|
<tbody valign="top">
|
|
<tr><td><tt class="docutils literal"><span class="pre">ip</span></tt></td>
|
|
<td>string, the ip address of the peer. This is
|
|
not a binary representation of the ip
|
|
address, but the string representation. It
|
|
may be an IPv6 string or an IPv4 string.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">port</span></tt></td>
|
|
<td>integer, the listen port of the peer</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p class="last">These are the local peers we were connected to when this
|
|
fast-resume data was saved.</p>
|
|
</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">unfinished</span></tt></td>
|
|
<td><p class="first">list of dictionaries. Each dictionary represents an
|
|
piece, and has the following layout:</p>
|
|
<table border="1" class="last docutils">
|
|
<colgroup>
|
|
<col width="23%" />
|
|
<col width="77%" />
|
|
</colgroup>
|
|
<tbody valign="top">
|
|
<tr><td><tt class="docutils literal"><span class="pre">piece</span></tt></td>
|
|
<td>integer, the index of the piece this entry
|
|
refers to.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">bitmask</span></tt></td>
|
|
<td>string, a binary bitmask representing the
|
|
blocks that have been downloaded in this
|
|
piece.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">adler32</span></tt></td>
|
|
<td>The adler32 checksum of the data in the
|
|
blocks specified by <tt class="docutils literal"><span class="pre">bitmask</span></tt>.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">file</span> <span class="pre">sizes</span></tt></td>
|
|
<td>list where each entry corresponds to a file in the file list
|
|
in the metadata. Each entry has a list of two values, the
|
|
first value is the size of the file in bytes, the second
|
|
is the time stamp when the last time someone wrote to it.
|
|
This information is used to compare with the files on disk.
|
|
All the files must match exactly this information in order
|
|
to consider the resume data as current. Otherwise a full
|
|
re-check is issued.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">allocation</span></tt></td>
|
|
<td>The allocation mode for the storage. Can be either <tt class="docutils literal"><span class="pre">full</span></tt>
|
|
or <tt class="docutils literal"><span class="pre">compact</span></tt>. If this is full, the file sizes and
|
|
timestamps are disregarded. Pieces are assumed not to have
|
|
moved around even if the files have been modified after the
|
|
last resume data checkpoint.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a id="threads" name="threads">threads</a></h1>
|
|
<p>libtorrent starts 2 or 3 threads.</p>
|
|
<blockquote>
|
|
<ul class="simple">
|
|
<li>The first thread is the main thread that will sit
|
|
idle in a <tt class="docutils literal"><span class="pre">select()</span></tt> call most of the time. This thread runs the main loop
|
|
that will send and receive data on all connections.</li>
|
|
<li>The second thread is a hash-check thread. Whenever a torrent is added it will
|
|
first be passed to this thread for checking the files that may already have been
|
|
downloaded. If there is any resume data this thread will make sure it is valid
|
|
and matches the files. Once the torrent has been checked, it is passed on to the
|
|
main thread that will start it. The hash-check thread has a queue of torrents,
|
|
it will only check one torrent at a time.</li>
|
|
<li>The third thread is spawned by asio on systems that don't support
|
|
non-blocking host name resolution to simulate non-blocking behavior.</li>
|
|
</ul>
|
|
</blockquote>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a id="storage-allocation" name="storage-allocation">storage allocation</a></h1>
|
|
<p>There are three modes in which storage (files on disk) are allocated in libtorrent.</p>
|
|
<ol class="arabic simple">
|
|
<li>The traditional <em>full allocation</em> mode, where the entire files are filled up with
|
|
zeros before anything is downloaded. libtorrent will look for sparse files support
|
|
in the filesystem that is used for storage, and use sparse files or file system
|
|
zero fill support if present. This means that on NTFS, full allocation mode will
|
|
only allocate storage for the downloaded pieces.</li>
|
|
<li>The <em>compact allocation</em> mode, where only files are allocated for actual
|
|
pieces that have been downloaded. This is the default allocation mode in libtorrent.</li>
|
|
<li>The <em>sparce allocation</em>, sparse files are used, and pieces are downloaded directly
|
|
to where they belong. This is the recommended (and default) mode.</li>
|
|
</ol>
|
|
<p>The allocation mode is selected when a torrent is started. It is passed as an
|
|
argument to <tt class="docutils literal"><span class="pre">session::add_torrent()</span></tt> (see <a class="reference" href="#add-torrent">add_torrent()</a>).</p>
|
|
<p>The decision to use full allocation or compact allocation typically depends on whether
|
|
any files are filtered and if the filesystem supports sparse files.</p>
|
|
<div class="section">
|
|
<h2><a id="sparse-allocation" name="sparse-allocation">sparse allocation</a></h2>
|
|
<p>On filesystems that supports sparse files, this allocation mode will only use
|
|
as much space as has been downloaded.</p>
|
|
<blockquote>
|
|
<ul class="simple">
|
|
<li>It does not require an allocation pass on startup.</li>
|
|
<li>It supports skipping files (setting prioirty to 0 to not download).</li>
|
|
<li>Fast resume data will remain valid even when file time stamps are out of date.</li>
|
|
</ul>
|
|
</blockquote>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="full-allocation" name="full-allocation">full allocation</a></h2>
|
|
<p>When a torrent is started in full allocation mode, the checker thread (see <a class="reference" href="#threads">threads</a>)
|
|
will make sure that the entire storage is allocated, and fill any gaps with zeros.
|
|
This will be skipped if the filesystem supports sparse files or automatic zero filling.
|
|
It will of course still check for existing pieces and fast resume data. The main
|
|
drawbacks of this mode are:</p>
|
|
<blockquote>
|
|
<ul class="simple">
|
|
<li>It may take longer to start the torrent, since it will need to fill the files
|
|
with zeros on some systems. This delay is linearly dependent on the size of
|
|
the download.</li>
|
|
<li>The download may occupy unnecessary disk space between download sessions. In case
|
|
sparse files are not supported.</li>
|
|
<li>Disk caches usually perform extremely poorly with random access to large files
|
|
and may slow down a download considerably.</li>
|
|
</ul>
|
|
</blockquote>
|
|
<p>The benefits of this mode are:</p>
|
|
<blockquote>
|
|
<ul class="simple">
|
|
<li>Downloaded pieces are written directly to their final place in the files and the
|
|
total number of disk operations will be fewer and may also play nicer to
|
|
filesystems' file allocation, and reduce fragmentation.</li>
|
|
<li>No risk of a download failing because of a full disk during download. Unless
|
|
sparse files are being used.</li>
|
|
<li>The fast resume data will be more likely to be usable, regardless of crashes or
|
|
out of date data, since pieces won't move around.</li>
|
|
<li>Can be used with the filter files feature.</li>
|
|
</ul>
|
|
</blockquote>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="compact-allocation" name="compact-allocation">compact allocation</a></h2>
|
|
<p>The compact allocation will only allocate as much storage as it needs to keep the
|
|
pieces downloaded so far. This means that pieces will be moved around to be placed
|
|
at their final position in the files while downloading (to make sure the completed
|
|
download has all its pieces in the correct place). So, the main drawbacks are:</p>
|
|
<blockquote>
|
|
<ul class="simple">
|
|
<li>More disk operations while downloading since pieces are moved around.</li>
|
|
<li>Potentially more fragmentation in the filesystem.</li>
|
|
<li>Cannot be used while filtering files.</li>
|
|
</ul>
|
|
</blockquote>
|
|
<p>The benefits though, are:</p>
|
|
<blockquote>
|
|
<ul class="simple">
|
|
<li>No startup delay, since the files doesn't need allocating.</li>
|
|
<li>The download will not use unnecessary disk space.</li>
|
|
<li>Disk caches perform much better than in full allocation and raises the download
|
|
speed limit imposed by the disk.</li>
|
|
<li>Works well on filesystems that doesn't support sparse files.</li>
|
|
</ul>
|
|
</blockquote>
|
|
<p>The algorithm that is used when allocating pieces and slots isn't very complicated.
|
|
For the interested, a description follows.</p>
|
|
<p>storing a piece:</p>
|
|
<ol class="arabic simple">
|
|
<li>let <strong>A</strong> be a newly downloaded piece, with index <strong>n</strong>.</li>
|
|
<li>let <strong>s</strong> be the number of slots allocated in the file we're
|
|
downloading to. (the number of pieces it has room for).</li>
|
|
<li>if <strong>n</strong> >= <strong>s</strong> then allocate a new slot and put the piece there.</li>
|
|
<li>if <strong>n</strong> < <strong>s</strong> then allocate a new slot, move the data at
|
|
slot <strong>n</strong> to the new slot and put <strong>A</strong> in slot <strong>n</strong>.</li>
|
|
</ol>
|
|
<p>allocating a new slot:</p>
|
|
<ol class="arabic simple">
|
|
<li>if there's an unassigned slot (a slot that doesn't
|
|
contain any piece), return that slot index.</li>
|
|
<li>append the new slot at the end of the file (or find an unused slot).</li>
|
|
<li>let <strong>i</strong> be the index of newly allocated slot</li>
|
|
<li>if we have downloaded piece index <strong>i</strong> already (to slot <strong>j</strong>) then<ol class="arabic">
|
|
<li>move the data at slot <strong>j</strong> to slot <strong>i</strong>.</li>
|
|
<li>return slot index <strong>j</strong> as the newly allocated free slot.</li>
|
|
</ol>
|
|
</li>
|
|
<li>return <strong>i</strong> as the newly allocated slot.</li>
|
|
</ol>
|
|
</div>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a id="extensions" name="extensions">extensions</a></h1>
|
|
<p>These extensions all operates within the <a class="reference" href="extension_protocol.html">extension protocol</a>. The
|
|
name of the extension is the name used in the extension-list packets,
|
|
and the payload is the data in the extended message (not counting the
|
|
length-prefix, message-id nor extension-id).</p>
|
|
<p>Note that since this protocol relies on one of the reserved bits in the
|
|
handshake, it may be incompatible with future versions of the mainline
|
|
bittorrent client.</p>
|
|
<p>These are the extensions that are currently implemented.</p>
|
|
<div class="section">
|
|
<h2><a id="metadata-from-peers" name="metadata-from-peers">metadata from peers</a></h2>
|
|
<p>Extension name: "LT_metadata"</p>
|
|
<p>The point with this extension is that you don't have to distribute the
|
|
metadata (.torrent-file) separately. The metadata can be distributed
|
|
through the bittorrent swarm. The only thing you need to download such
|
|
a torrent is the tracker url and the info-hash of the torrent.</p>
|
|
<p>It works by assuming that the initial seeder has the metadata and that
|
|
the metadata will propagate through the network as more peers join.</p>
|
|
<p>There are three kinds of messages in the metadata extension. These packets
|
|
are put as payload to the extension message. The three packets are:</p>
|
|
<blockquote>
|
|
<ul class="simple">
|
|
<li>request metadata</li>
|
|
<li>metadata</li>
|
|
<li>don't have metadata</li>
|
|
</ul>
|
|
</blockquote>
|
|
<p>request metadata:</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="17%" />
|
|
<col width="23%" />
|
|
<col width="61%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr><th class="head">size</th>
|
|
<th class="head">name</th>
|
|
<th class="head">description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<tr><td>uint8_t</td>
|
|
<td>msg_type</td>
|
|
<td>Determines the kind of message this is
|
|
0 means 'request metadata'</td>
|
|
</tr>
|
|
<tr><td>uint8_t</td>
|
|
<td>start</td>
|
|
<td>The start of the metadata block that
|
|
is requested. It is given in 256:ths
|
|
of the total size of the metadata,
|
|
since the requesting client don't know
|
|
the size of the metadata.</td>
|
|
</tr>
|
|
<tr><td>uint8_t</td>
|
|
<td>size</td>
|
|
<td>The size of the metadata block that is
|
|
requested. This is also given in
|
|
256:ths of the total size of the
|
|
metadata. The size is given as size-1.
|
|
That means that if this field is set
|
|
0, the request wants one 256:th of the
|
|
metadata.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>metadata:</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="17%" />
|
|
<col width="23%" />
|
|
<col width="61%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr><th class="head">size</th>
|
|
<th class="head">name</th>
|
|
<th class="head">description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<tr><td>uint8_t</td>
|
|
<td>msg_type</td>
|
|
<td>1 means 'metadata'</td>
|
|
</tr>
|
|
<tr><td>int32_t</td>
|
|
<td>total_size</td>
|
|
<td>The total size of the metadata, given
|
|
in number of bytes.</td>
|
|
</tr>
|
|
<tr><td>int32_t</td>
|
|
<td>offset</td>
|
|
<td>The offset of where the metadata block
|
|
in this message belongs in the final
|
|
metadata. This is given in bytes.</td>
|
|
</tr>
|
|
<tr><td>uint8_t[]</td>
|
|
<td>metadata</td>
|
|
<td>The actual metadata block. The size of
|
|
this part is given implicit by the
|
|
length prefix in the bittorrent
|
|
protocol packet.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>Don't have metadata:</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="17%" />
|
|
<col width="23%" />
|
|
<col width="61%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr><th class="head">size</th>
|
|
<th class="head">name</th>
|
|
<th class="head">description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<tr><td>uint8_t</td>
|
|
<td>msg_type</td>
|
|
<td>2 means 'I don't have metadata'.
|
|
This message is sent as a reply to a
|
|
metadata request if the the client
|
|
doesn't have any metadata.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<div class="section">
|
|
<h2><a id="http-seeding" name="http-seeding">HTTP seeding</a></h2>
|
|
<p>The HTTP seed extension implements <a class="reference" href="http://www.getright.com/seedtorrent.html">this specification</a>.</p>
|
|
<p>The libtorrent implementation assumes that, if the URL ends with a slash
|
|
('/'), the filename should be appended to it in order to request pieces from
|
|
that file. The way this works is that if the torrent is a single-file torrent,
|
|
only that filename is appended. If the torrent is a multi-file torrent, the
|
|
torrent's name '/' the file name is appended. This is the same directory
|
|
structure that libtorrent will download torrents into.</p>
|
|
</div>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a id="filename-checks" name="filename-checks">filename checks</a></h1>
|
|
<p>Boost.Filesystem will by default check all its paths to make sure they conform
|
|
to filename requirements on many platforms. If you don't want this check, you can
|
|
set it to either only check for native filesystem requirements or turn it off
|
|
altogether. You can use:</p>
|
|
<pre class="literal-block">
|
|
boost::filesystem::path::default_name_check(boost::filesystem::native);
|
|
</pre>
|
|
<p>for example. For more information, see the <a class="reference" href="http://www.boost.org/libs/filesystem/doc/index.htm">Boost.Filesystem docs</a>.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a id="acknowledgments" name="acknowledgments">acknowledgments</a></h1>
|
|
<p>Written by Arvid Norberg. Copyright © 2003-2006</p>
|
|
<p>Contributions by Magnus Jonsson, Daniel Wallin and Cory Nelson</p>
|
|
<p>Lots of testing, suggestions and contributions by Massaroddel and Tianhao Qiu.</p>
|
|
<p>Big thanks to Michael Wojciechowski and Peter Koeleman for making the autotools
|
|
scripts.</p>
|
|
<p>Thanks to Reimond Retz for bugfixes, suggestions and testing</p>
|
|
<p>Thanks to <a class="reference" href="http://www.cs.umu.se">University of Umeå</a> for providing development and test hardware.</p>
|
|
<p>Project is hosted by sourceforge.</p>
|
|
<p><a class="reference" href="http://sourceforge.net"><img alt="sf_logo" src="http://sourceforge.net/sflogo.php?group_id=7994" /></a></p>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html>
|