docs/manual.html

   1 <?xml version="1.0" encoding="utf-8" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   6 <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
   7 <title>libtorrent API Documentation</title>
   8 <meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
   9 <link rel="stylesheet" href="style.css" type="text/css" />
  10 </head>
  11 <body>
  12 <div class="document" id="libtorrent-api-documentation">
  13 <h1 class="title">libtorrent API Documentation</h1>
  14 <table class="docinfo" frame="void" rules="none">
  15 <col class="docinfo-name" />
  16 <col class="docinfo-content" />
  17 <tbody valign="top">
  18 <tr><th class="docinfo-name">Author:</th>
  19 <td>Arvid Norberg, <a class="last reference" href="mailto:arvid&#64;rasterbar.com">arvid&#64;rasterbar.com</a></td></tr>
  20 <tr><th class="docinfo-name">Version:</th>
  21 <td>0.13</td></tr>
  22 </tbody>
  23 </table>
  24 <div class="contents topic" id="table-of-contents">
  25 <p class="topic-title first"><a name="table-of-contents">Table of contents</a></p>
  26 <ul class="simple">
  27 <li><a class="reference" href="#overview" id="id18" name="id18">overview</a></li>
  28 <li><a class="reference" href="#network-primitives" id="id19" name="id19">network primitives</a></li>
  29 <li><a class="reference" href="#session" id="id20" name="id20">session</a><ul>
  30 <li><a class="reference" href="#id1" id="id21" name="id21">session()</a></li>
  31 <li><a class="reference" href="#id2" id="id22" name="id22">~session()</a></li>
  32 <li><a class="reference" href="#pause-resume-is-paused" id="id23" name="id23">pause() resume() is_paused()</a></li>
  33 <li><a class="reference" href="#abort" id="id24" name="id24">abort()</a></li>
  34 <li><a class="reference" href="#add-torrent" id="id25" name="id25">add_torrent()</a></li>
  35 <li><a class="reference" href="#remove-torrent" id="id26" name="id26">remove_torrent()</a></li>
  36 <li><a class="reference" href="#find-torrent-get-torrents" id="id27" name="id27">find_torrent() get_torrents()</a></li>
  37 <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>
  38 <li><a class="reference" href="#set-max-uploads-set-max-connections" id="id29" name="id29">set_max_uploads() set_max_connections()</a></li>
  39 <li><a class="reference" href="#num-uploads-num-connections" id="id30" name="id30">num_uploads() num_connections()</a></li>
  40 <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>
  41 <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>
  42 <li><a class="reference" href="#load-state-state" id="id33" name="id33">load_state() state()</a></li>
  43 <li><a class="reference" href="#set-ip-filter" id="id34" name="id34">set_ip_filter()</a></li>
  44 <li><a class="reference" href="#status" id="id35" name="id35">status()</a></li>
  45 <li><a class="reference" href="#get-cache-status" id="id36" name="id36">get_cache_status()</a></li>
  46 <li><a class="reference" href="#get-cache-info" id="id37" name="id37">get_cache_info()</a></li>
  47 <li><a class="reference" href="#is-listening-listen-port-listen-on" id="id38" name="id38">is_listening() listen_port() listen_on()</a></li>
  48 <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>
  49 <li><a class="reference" href="#add-extension" id="id40" name="id40">add_extension()</a></li>
  50 <li><a class="reference" href="#set-settings-set-pe-settings" id="id41" name="id41">set_settings() set_pe_settings()</a></li>
  51 <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>
  52 <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>
  53 <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>
  54 <li><a class="reference" href="#add-dht-node-add-dht-router" id="id45" name="id45">add_dht_node() add_dht_router()</a></li>
  55 <li><a class="reference" href="#start-lsd-stop-lsd" id="id46" name="id46">start_lsd() stop_lsd()</a></li>
  56 <li><a class="reference" href="#start-upnp-stop-upnp" id="id47" name="id47">start_upnp() stop_upnp()</a></li>
  57 <li><a class="reference" href="#start-natpmp-stop-natpmp" id="id48" name="id48">start_natpmp() stop_natpmp()</a></li>
  58 </ul>
  59 </li>
  60 <li><a class="reference" href="#entry" id="id49" name="id49">entry</a><ul>
  61 <li><a class="reference" href="#integer-string-list-dict-type" id="id50" name="id50">integer() string() list() dict() type()</a></li>
  62 <li><a class="reference" href="#operator" id="id51" name="id51">operator[]</a></li>
  63 <li><a class="reference" href="#find-key" id="id52" name="id52">find_key()</a></li>
  64 </ul>
  65 </li>
  66 <li><a class="reference" href="#torrent-info" id="id53" name="id53">torrent_info</a><ul>
  67 <li><a class="reference" href="#id3" id="id54" name="id54">torrent_info()</a></li>
  68 <li><a class="reference" href="#add-tracker" id="id55" name="id55">add_tracker()</a></li>
  69 <li><a class="reference" href="#files" id="id56" name="id56">files()</a></li>
  70 <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>
  71 <li><a class="reference" href="#num-files-file-at" id="id58" name="id58">num_files() file_at()</a></li>
  72 <li><a class="reference" href="#map-block" id="id59" name="id59">map_block()</a></li>
  73 <li><a class="reference" href="#map-file" id="id60" name="id60">map_file()</a></li>
  74 <li><a class="reference" href="#url-seeds-add-url-seed" id="id61" name="id61">url_seeds() add_url_seed()</a></li>
  75 <li><a class="reference" href="#trackers" id="id62" name="id62">trackers()</a></li>
  76 <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>
  77 <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>
  78 <li><a class="reference" href="#name-comment-creation-date-creator" id="id65" name="id65">name() comment() creation_date() creator()</a></li>
  79 <li><a class="reference" href="#priv" id="id66" name="id66">priv()</a></li>
  80 <li><a class="reference" href="#nodes" id="id67" name="id67">nodes()</a></li>
  81 <li><a class="reference" href="#add-node" id="id68" name="id68">add_node()</a></li>
  82 <li><a class="reference" href="#metadata-metadata-size" id="id69" name="id69">metadata() metadata_size()</a></li>
  83 </ul>
  84 </li>
  85 <li><a class="reference" href="#torrent-handle" id="id70" name="id70">torrent_handle</a><ul>
  86 <li><a class="reference" href="#piece-priority-prioritize-pieces-piece-priorities-prioritize-files" id="id71" name="id71">piece_priority() prioritize_pieces() piece_priorities() prioritize_files()</a></li>
  87 <li><a class="reference" href="#file-progress" id="id72" name="id72">file_progress()</a></li>
  88 <li><a class="reference" href="#save-path" id="id73" name="id73">save_path()</a></li>
  89 <li><a class="reference" href="#move-storage" id="id74" name="id74">move_storage()</a></li>
  90 <li><a class="reference" href="#force-reannounce" id="id75" name="id75">force_reannounce()</a></li>
  91 <li><a class="reference" href="#scrape-tracker" id="id76" name="id76">scrape_tracker()</a></li>
  92 <li><a class="reference" href="#connect-peer" id="id77" name="id77">connect_peer()</a></li>
  93 <li><a class="reference" href="#name" id="id78" name="id78">name()</a></li>
  94 <li><a class="reference" href="#set-ratio" id="id79" name="id79">set_ratio()</a></li>
  95 <li><a class="reference" href="#set-upload-limit-set-download-limit-upload-limit-download-limit" id="id80" name="id80">set_upload_limit() set_download_limit() upload_limit() download_limit()</a></li>
  96 <li><a class="reference" href="#set-sequential-download-is-sequential-download" id="id81" name="id81">set_sequential_download() is_sequential_download()</a></li>
  97 <li><a class="reference" href="#set-peer-upload-limit-set-peer-download-limit" id="id82" name="id82">set_peer_upload_limit() set_peer_download_limit()</a></li>
  98 <li><a class="reference" href="#id5" id="id83" name="id83">pause() resume() is_paused()</a></li>
  99 <li><a class="reference" href="#force-recheck" id="id84" name="id84">force_recheck()</a></li>
 100 <li><a class="reference" href="#clear-error" id="id85" name="id85">clear_error()</a></li>
 101 <li><a class="reference" href="#resolve-countries" id="id86" name="id86">resolve_countries()</a></li>
 102 <li><a class="reference" href="#is-seed" id="id87" name="id87">is_seed()</a></li>
 103 <li><a class="reference" href="#is-auto-managed-auto-managed" id="id88" name="id88">is_auto_managed() auto_managed()</a></li>
 104 <li><a class="reference" href="#has-metadata" id="id89" name="id89">has_metadata()</a></li>
 105 <li><a class="reference" href="#set-tracker-login" id="id90" name="id90">set_tracker_login()</a></li>
 106 <li><a class="reference" href="#trackers-replace-trackers" id="id91" name="id91">trackers() replace_trackers()</a></li>
 107 <li><a class="reference" href="#add-url-seed-remove-url-seed-url-seeds" id="id92" name="id92">add_url_seed() remove_url_seed() url_seeds()</a></li>
 108 <li><a class="reference" href="#queue-position-queue-position-up-queue-position-down-queue-position-top-queue-position-bottom" id="id93" name="id93">queue_position() queue_position_up() queue_position_down() queue_position_top() queue_position_bottom()</a></li>
 109 <li><a class="reference" href="#use-interface" id="id94" name="id94">use_interface()</a></li>
 110 <li><a class="reference" href="#info-hash" id="id95" name="id95">info_hash()</a></li>
 111 <li><a class="reference" href="#id6" id="id96" name="id96">set_max_uploads() set_max_connections()</a></li>
 112 <li><a class="reference" href="#save-resume-data" id="id97" name="id97">save_resume_data()</a></li>
 113 <li><a class="reference" href="#id7" id="id98" name="id98">status()</a></li>
 114 <li><a class="reference" href="#get-download-queue" id="id99" name="id99">get_download_queue()</a></li>
 115 <li><a class="reference" href="#get-peer-info" id="id100" name="id100">get_peer_info()</a></li>
 116 <li><a class="reference" href="#get-torrent-info" id="id101" name="id101">get_torrent_info()</a></li>
 117 <li><a class="reference" href="#is-valid" id="id102" name="id102">is_valid()</a></li>
 118 </ul>
 119 </li>
 120 <li><a class="reference" href="#torrent-status" id="id103" name="id103">torrent_status</a></li>
 121 <li><a class="reference" href="#peer-info" id="id104" name="id104">peer_info</a></li>
 122 <li><a class="reference" href="#session-settings" id="id105" name="id105">session_settings</a></li>
 123 <li><a class="reference" href="#pe-settings" id="id106" name="id106">pe_settings</a></li>
 124 <li><a class="reference" href="#proxy-settings" id="id107" name="id107">proxy_settings</a></li>
 125 <li><a class="reference" href="#ip-filter" id="id108" name="id108">ip_filter</a><ul>
 126 <li><a class="reference" href="#id10" id="id109" name="id109">ip_filter()</a></li>
 127 <li><a class="reference" href="#add-rule" id="id110" name="id110">add_rule()</a></li>
 128 <li><a class="reference" href="#access" id="id111" name="id111">access()</a></li>
 129 <li><a class="reference" href="#export-filter" id="id112" name="id112">export_filter()</a></li>
 130 </ul>
 131 </li>
 132 <li><a class="reference" href="#big-number" id="id113" name="id113">big_number</a></li>
 133 <li><a class="reference" href="#bitfield" id="id114" name="id114">bitfield</a></li>
 134 <li><a class="reference" href="#hasher" id="id115" name="id115">hasher</a></li>
 135 <li><a class="reference" href="#fingerprint" id="id116" name="id116">fingerprint</a></li>
 136 <li><a class="reference" href="#upnp-and-nat-pmp" id="id117" name="id117">UPnP and NAT-PMP</a><ul>
 137 <li><a class="reference" href="#add-mapping" id="id118" name="id118">add_mapping</a></li>
 138 <li><a class="reference" href="#delete-mapping" id="id119" name="id119">delete_mapping</a></li>
 139 <li><a class="reference" href="#router-model" id="id120" name="id120">router_model()</a></li>
 140 </ul>
 141 </li>
 142 <li><a class="reference" href="#free-functions" id="id121" name="id121">free functions</a><ul>
 143 <li><a class="reference" href="#identify-client" id="id122" name="id122">identify_client()</a></li>
 144 <li><a class="reference" href="#client-fingerprint" id="id123" name="id123">client_fingerprint()</a></li>
 145 <li><a class="reference" href="#bdecode-bencode" id="id124" name="id124">bdecode() bencode()</a></li>
 146 </ul>
 147 </li>
 148 <li><a class="reference" href="#alerts" id="id125" name="id125">alerts</a><ul>
 149 <li><a class="reference" href="#external-ip-alert" id="id126" name="id126">external_ip_alert</a></li>
 150 <li><a class="reference" href="#listen-failed-alert" id="id127" name="id127">listen_failed_alert</a></li>
 151 <li><a class="reference" href="#portmap-error-alert" id="id128" name="id128">portmap_error_alert</a></li>
 152 <li><a class="reference" href="#portmap-alert" id="id129" name="id129">portmap_alert</a></li>
 153 <li><a class="reference" href="#file-error-alert" id="id130" name="id130">file_error_alert</a></li>
 154 <li><a class="reference" href="#tracker-announce-alert" id="id131" name="id131">tracker_announce_alert</a></li>
 155 <li><a class="reference" href="#tracker-error-alert" id="id132" name="id132">tracker_error_alert</a></li>
 156 <li><a class="reference" href="#tracker-reply-alert" id="id133" name="id133">tracker_reply_alert</a></li>
 157 <li><a class="reference" href="#dht-reply-alert" id="id134" name="id134">dht_reply_alert</a></li>
 158 <li><a class="reference" href="#tracker-warning-alert" id="id135" name="id135">tracker_warning_alert</a></li>
 159 <li><a class="reference" href="#scrape-reply-alert" id="id136" name="id136">scrape_reply_alert</a></li>
 160 <li><a class="reference" href="#scrape-failed-alert" id="id137" name="id137">scrape_failed_alert</a></li>
 161 <li><a class="reference" href="#url-seed-alert" id="id138" name="id138">url_seed_alert</a></li>
 162 <li><a class="reference" href="#hash-failed-alert" id="id139" name="id139">hash_failed_alert</a></li>
 163 <li><a class="reference" href="#peer-ban-alert" id="id140" name="id140">peer_ban_alert</a></li>
 164 <li><a class="reference" href="#peer-error-alert" id="id141" name="id141">peer_error_alert</a></li>
 165 <li><a class="reference" href="#invalid-request-alert" id="id142" name="id142">invalid_request_alert</a></li>
 166 <li><a class="reference" href="#torrent-finished-alert" id="id143" name="id143">torrent_finished_alert</a></li>
 167 <li><a class="reference" href="#metadata-failed-alert" id="id144" name="id144">metadata_failed_alert</a></li>
 168 <li><a class="reference" href="#metadata-received-alert" id="id145" name="id145">metadata_received_alert</a></li>
 169 <li><a class="reference" href="#fastresume-rejected-alert" id="id146" name="id146">fastresume_rejected_alert</a></li>
 170 <li><a class="reference" href="#peer-blocked-alert" id="id147" name="id147">peer_blocked_alert</a></li>
 171 <li><a class="reference" href="#storage-moved-alert" id="id148" name="id148">storage_moved_alert</a></li>
 172 <li><a class="reference" href="#torrent-paused-alert" id="id149" name="id149">torrent_paused_alert</a></li>
 173 <li><a class="reference" href="#torrent-resumed-alert" id="id150" name="id150">torrent_resumed_alert</a></li>
 174 <li><a class="reference" href="#save-resume-data-alert" id="id151" name="id151">save_resume_data_alert</a></li>
 175 <li><a class="reference" href="#save-resume-data-failed-alert" id="id152" name="id152">save_resume_data_failed_alert</a></li>
 176 <li><a class="reference" href="#dispatcher" id="id153" name="id153">dispatcher</a></li>
 177 </ul>
 178 </li>
 179 <li><a class="reference" href="#exceptions" id="id154" name="id154">exceptions</a><ul>
 180 <li><a class="reference" href="#invalid-handle" id="id155" name="id155">invalid_handle</a></li>
 181 <li><a class="reference" href="#duplicate-torrent" id="id156" name="id156">duplicate_torrent</a></li>
 182 <li><a class="reference" href="#invalid-encoding" id="id157" name="id157">invalid_encoding</a></li>
 183 <li><a class="reference" href="#type-error" id="id158" name="id158">type_error</a></li>
 184 <li><a class="reference" href="#invalid-torrent-file" id="id159" name="id159">invalid_torrent_file</a></li>
 185 </ul>
 186 </li>
 187 <li><a class="reference" href="#storage-interface" id="id160" name="id160">storage_interface</a><ul>
 188 <li><a class="reference" href="#initialize" id="id161" name="id161">initialize()</a></li>
 189 <li><a class="reference" href="#read" id="id162" name="id162">read()</a></li>
 190 <li><a class="reference" href="#write" id="id163" name="id163">write()</a></li>
 191 <li><a class="reference" href="#id12" id="id164" name="id164">move_storage()</a></li>
 192 <li><a class="reference" href="#verify-resume-data" id="id165" name="id165">verify_resume_data()</a></li>
 193 <li><a class="reference" href="#write-resume-data" id="id166" name="id166">write_resume_data()</a></li>
 194 <li><a class="reference" href="#move-slot" id="id167" name="id167">move_slot()</a></li>
 195 <li><a class="reference" href="#swap-slots" id="id168" name="id168">swap_slots()</a></li>
 196 <li><a class="reference" href="#swap-slots3" id="id169" name="id169">swap_slots3()</a></li>
 197 <li><a class="reference" href="#hash-for-slot" id="id170" name="id170">hash_for_slot()</a></li>
 198 <li><a class="reference" href="#release-files" id="id171" name="id171">release_files()</a></li>
 199 <li><a class="reference" href="#delete-files" id="id172" name="id172">delete_files()</a></li>
 200 </ul>
 201 </li>
 202 <li><a class="reference" href="#queuing" id="id173" name="id173">queuing</a><ul>
 203 <li><a class="reference" href="#downloading" id="id174" name="id174">downloading</a></li>
 204 <li><a class="reference" href="#seeding" id="id175" name="id175">seeding</a></li>
 205 </ul>
 206 </li>
 207 <li><a class="reference" href="#fast-resume" id="id176" name="id176">fast resume</a><ul>
 208 <li><a class="reference" href="#file-format" id="id177" name="id177">file format</a></li>
 209 </ul>
 210 </li>
 211 <li><a class="reference" href="#threads" id="id178" name="id178">threads</a></li>
 212 <li><a class="reference" href="#storage-allocation" id="id179" name="id179">storage allocation</a><ul>
 213 <li><a class="reference" href="#sparse-allocation" id="id180" name="id180">sparse allocation</a></li>
 214 <li><a class="reference" href="#full-allocation" id="id181" name="id181">full allocation</a></li>
 215 <li><a class="reference" href="#compact-allocation" id="id182" name="id182">compact allocation</a></li>
 216 </ul>
 217 </li>
 218 <li><a class="reference" href="#extensions" id="id183" name="id183">extensions</a><ul>
 219 <li><a class="reference" href="#metadata-from-peers" id="id184" name="id184">metadata from peers</a></li>
 220 <li><a class="reference" href="#http-seeding" id="id185" name="id185">HTTP seeding</a></li>
 221 </ul>
 222 </li>
 223 <li><a class="reference" href="#filename-checks" id="id186" name="id186">filename checks</a></li>
 224 <li><a class="reference" href="#acknowledgments" id="id187" name="id187">acknowledgments</a></li>
 225 </ul>
 226 </div>
 227 <div class="section">
 228 <h1><a id="overview" name="overview">overview</a></h1>
 229 <p>The interface of libtorrent consists of a few classes. The main class is
 230 the <tt class="docutils literal"><span class="pre">session</span></tt>, it contains the main loop that serves all torrents.</p>
 231 <p>The basic usage is as follows:</p>
 232 <ul>
 233 <li><p class="first">construct a session</p>
 234 </li>
 235 <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>
 236 <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>
 237 </li>
 238 <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>
 239 </li>
 240 <li><p class="first">main loop (see <a class="reference" href="#session">session</a>)</p>
 241 <blockquote>
 242 <ul class="simple">
 243 <li>query the torrent_handles for progress (see <a class="reference" href="#torrent-handle">torrent_handle</a>)</li>
 244 <li>query the session for information</li>
 245 <li>add and remove torrents from the session at run-time</li>
 246 </ul>
 247 </blockquote>
 248 </li>
 249 <li><p class="first">save resume data for all torrent_handles (optional, see
 250 <a class="reference" href="#save-resume-data">save_resume_data()</a>)</p>
 251 </li>
 252 <li><p class="first">destruct session object</p>
 253 </li>
 254 </ul>
 255 <p>Each class and function is described in this manual.</p>
 256 <p>For a description on how to create torrent files, see <a class="reference" href="make_torrent.html">make_torrent</a>.</p>
 257 </div>
 258 <div class="section">
 259 <h1><a id="network-primitives" name="network-primitives">network primitives</a></h1>
 260 <p>There are a few typedefs in the <tt class="docutils literal"><span class="pre">libtorrent</span></tt> namespace which pulls
 261 in network types from the <tt class="docutils literal"><span class="pre">asio</span></tt> namespace. These are:</p>
 262 <pre class="literal-block">
 263 typedef asio::ip::address address;
 264 typedef asio::ip::address_v4 address_v4;
 265 typedef asio::ip::address_v6 address_v6;
 266 using asio::ip::tcp;
 267 using asio::ip::udp;
 268 </pre>
 269 <p>These are declared in the <tt class="docutils literal"><span class="pre">&lt;libtorrent/socket.hpp&gt;</span></tt> header.</p>
 270 <p>The <tt class="docutils literal"><span class="pre">using</span></tt> statements will give easy access to:</p>
 271 <pre class="literal-block">
 272 tcp::endpoint
 273 udp::endpoint
 274 </pre>
 275 <p>Which are the endpoint types used in libtorrent. An endpoint is an address
 276 with an associated port.</p>
 277 <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>
 278 </div>
 279 <div class="section">
 280 <h1><a id="session" name="session">session</a></h1>
 281 <p>The <tt class="docutils literal"><span class="pre">session</span></tt> class has the following synopsis:</p>
 282 <pre class="literal-block">
 283 class session: public boost::noncopyable
 284 {
 285
 286         session(fingerprint const&amp; print
 287                 = libtorrent::fingerprint(
 288                 &quot;LT&quot;, 0, 1, 0, 0));
 289
 290         session(
 291                 fingerprint const&amp; print
 292                 , std::pair&lt;int, int&gt; listen_port_range
 293                 , char const* listen_interface = 0);
 294
 295         torrent_handle add_torrent(add_torrent_params const&amp; params);
 296
 297         void pause();
 298         void resume();
 299         bool is_paused() const;
 300
 301         session_proxy abort();
 302
 303         enum options_t
 304         {
 305                 none = 0,
 306                 delete_files = 1
 307         };
 308
 309         void remove_torrent(torrent_handle const&amp; h, int options = none);
 310         torrent_handle find_torrent(sha_hash const&amp; ih);
 311         std::vector&lt;torrent_handle&gt; get_torrents() const;
 312
 313         void set_settings(session_settings const&amp; settings);
 314         void set_pe_settings(pe_settings const&amp; settings);
 315
 316         void set_upload_rate_limit(int bytes_per_second);
 317         int upload_rate_limit() const;
 318         void set_download_rate_limit(int bytes_per_second);
 319         int download_rate_limit() const;
 320         void set_max_uploads(int limit);
 321         void set_max_connections(int limit);
 322         void set_max_half_open_connections(int limit);
 323         int max_half_open_connections() const;
 324
 325         void set_peer_proxy(proxy_settings const&amp; s);
 326         void set_web_seed_proxy(proxy_settings const&amp; s);
 327         void set_tracker_proxy(proxy_settings const&amp; s);
 328
 329         proxy_settings const&amp; peer_proxy() const;
 330         proxy_settings const&amp; web_seed_proxy() const;
 331         proxy_settings const&amp; tracker_proxy() const;
 332
 333         int num_uploads() const;
 334         int num_connections() const;
 335
 336         bool load_asnum_db(char const* file);
 337         bool load_country_db(char const* file);
 338         int as_for_ip(address const&amp; adr);
 339
 340         void load_state(entry const&amp; ses_state);
 341         entry state() const;
 342
 343         void set_ip_filter(ip_filter const&amp; f);
 344
 345         session_status status() const;
 346         cache_status get_cache_status() const;
 347
 348         bool is_listening() const;
 349         unsigned short listen_port() const;
 350         bool listen_on(
 351                 std::pair&lt;int, int&gt; const&amp; port_range
 352                 , char const* interface = 0);
 353
 354         std::auto_ptr&lt;alert&gt; pop_alert();
 355         alert const* wait_for_alert(time_duration max_wait);
 356         void set_alert_mask(int m);
 357
 358         void add_extension(boost::function&lt;
 359                 boost::shared_ptr&lt;torrent_plugin&gt;(torrent*)&gt; ext);
 360
 361         void start_dht();
 362         void stop_dht();
 363         void set_dht_settings(
 364                 dht_settings const&amp; settings);
 365         entry dht_state() const;
 366         void add_dht_node(std::pair&lt;std::string
 367                 , int&gt; const&amp; node);
 368         void add_dht_router(std::pair&lt;std::string
 369                 , int&gt; const&amp; node);
 370
 371         void start_lsd();
 372         void stop_lsd();
 373
 374         upnp* start_upnp();
 375         void stop_upnp();
 376
 377         natpmp* start_natpmp();
 378         void stop_natpmp();
 379 };
 380 </pre>
 381 <p>Once it's created, the session object will spawn the main thread that will do all the work.
 382 The main thread will be idle as long it doesn't have any torrents to participate in.</p>
 383 <div class="section">
 384 <h2><a id="id1" name="id1">session()</a></h2>
 385 <blockquote>
 386 <pre class="literal-block">
 387 session(fingerprint const&amp; print
 388         = libtorrent::fingerprint(&quot;LT&quot;, 0, 1, 0, 0));
 389 session(fingerprint const&amp; print
 390         , std::pair&lt;int, int&gt; listen_port_range
 391         , char const* listen_interface = 0);
 392 </pre>
 393 </blockquote>
 394 <p>If the fingerprint in the first overload is omited, the client will get a default
 395 fingerprint stating the version of libtorrent. The fingerprint is a short string that will be
 396 used in the peer-id to identify the client and the client's version. For more details see the
 397 <a class="reference" href="#fingerprint">fingerprint</a> class. The constructor that only takes a fingerprint will not open a
 398 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>.
 399 The other constructor, that takes a port range and an interface as well as the fingerprint
 400 will automatically try to listen on a port on the given interface. For more information about
 401 the parameters, see <tt class="docutils literal"><span class="pre">listen_on()</span></tt> function.</p>
 402 </div>
 403 <div class="section">
 404 <h2><a id="id2" name="id2">~session()</a></h2>
 405 <p>The destructor of session will notify all trackers that our torrents have been shut down.
 406 If some trackers are down, they will time out. All this before the destructor of session
 407 returns. So, it's advised that any kind of interface (such as windows) are closed before
 408 destructing the session object. Because it can take a few second for it to finish. The
 409 timeout can be set with <tt class="docutils literal"><span class="pre">set_settings()</span></tt>.</p>
 410 </div>
 411 <div class="section">
 412 <h2><a id="pause-resume-is-paused" name="pause-resume-is-paused">pause() resume() is_paused()</a></h2>
 413 <blockquote>
 414 <dl class="docutils">
 415 <dt>::</dt>
 416 <dd>void pause();
 417 void resume();
 418 bool is_paused() const;</dd>
 419 </dl>
 420 </blockquote>
 421 <p>Pausing the session has the same effect as pausing every torrent in it. Resuming
 422 will restore the torrents to their previous paused state. i.e. the session pause
 423 state is separate from the torrent pause state. A torrent is inactive if it is
 424 paused or if the session is paused.</p>
 425 </div>
 426 <div class="section">
 427 <h2><a id="abort" name="abort">abort()</a></h2>
 428 <blockquote>
 429 <pre class="literal-block">
 430 session_proxy abort();
 431 </pre>
 432 </blockquote>
 433 <p>In case you want to destruct the session asynchrounously, you can request a session
 434 destruction proxy. If you don't do this, the destructor of the session object will
 435 block while the trackers are contacted. If you keep one <tt class="docutils literal"><span class="pre">session_proxy</span></tt> to the
 436 session when destructing it, the destructor will not block, but start to close down
 437 the session, the destructor of the proxy will then synchronize the threads. So, the
 438 destruction of the session is performed from the <tt class="docutils literal"><span class="pre">session</span></tt> destructor call until the
 439 <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
 440 on it (since the session is being closed down, no operations are allowed on it). The
 441 only valid operation is calling the destructor:</p>
 442 <pre class="literal-block">
 443 class session_proxy
 444 {
 445 public:
 446         session_proxy();
 447         ~session_proxy()
 448 };
 449 </pre>
 450 </div>
 451 <div class="section">
 452 <h2><a id="add-torrent" name="add-torrent">add_torrent()</a></h2>
 453 <blockquote>
 454 <pre class="literal-block">
 455 typedef storage_interface* (&amp;storage_constructor_type)(
 456         file_storage const&amp;, fs::path const&amp;, file_pool&amp;);
 457
 458 struct add_torrent_params
 459 {
 460         add_torrent_params(storage_constructor_type s);
 461
 462         boost::intrusive_ptr&lt;torrent_info&gt; ti;
 463         char const* tracker_url;
 464         sha1_hash info_hash;
 465         char const* name;
 466         fs::path save_path;
 467         std::vector&lt;char&gt;* resume_data;
 468         storage_mode_t storage_mode;
 469         bool paused;
 470         bool auto_managed;
 471         bool duplicate_is_error;
 472         storage_constructor_type storage;
 473         void* userdata;
 474 };
 475
 476 torrent_handle add_torrent(add_torrent_params const&amp; params);
 477 </pre>
 478 </blockquote>
 479 <p>You add torrents through the <tt class="docutils literal"><span class="pre">add_torrent()</span></tt> function where you give an
 480 object with all the parameters.</p>
 481 <p>The only mandatory parameter is <tt class="docutils literal"><span class="pre">save_path</span></tt> which is the directory where you
 482 want the files to be saved. You also need to specify either the <tt class="docutils literal"><span class="pre">ti</span></tt> (the
 483 torrent file) or <tt class="docutils literal"><span class="pre">info_hash</span></tt> (the info hash of the torrent). If you specify the
 484 info-hash, the torrent file will be downloaded from peers, which requires them to
 485 support the metadata extension. For the metadata extension to work, libtorrent must
 486 be built with extensions enabled (<tt class="docutils literal"><span class="pre">TORRENT_DISABLE_EXTENSIONS</span></tt> must not be
 487 defined). It also takes an optional <tt class="docutils literal"><span class="pre">name</span></tt> argument. This may be 0 in case no
 488 name should be assigned to the torrent. In case it's not 0, the name is used for
 489 the torrent as long as it doesn't have metadata. See <tt class="docutils literal"><span class="pre">torrent_handle::name</span></tt>.</p>
 490 <p>If the torrent doesn't have a tracker, but relies on the DHT to find peers, the
 491 <tt class="docutils literal"><span class="pre">tracker_url</span></tt> can be 0, otherwise you might specify a tracker url that tracks this
 492 torrent.</p>
 493 <p>If the torrent you are trying to add already exists in the session (is either queued
 494 for checking, being checked or downloading) <tt class="docutils literal"><span class="pre">add_torrent()</span></tt> will throw
 495 <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>
 496 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
 497 torrent.</p>
 498 <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
 499 is available. The fast-resume data can be acquired from a running torrent by calling
 500 <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
 501 passed in will be swapped into the running torrent instance with <tt class="docutils literal"><span class="pre">std::vector::swap()</span></tt>.</p>
 502 <p>The <tt class="docutils literal"><span class="pre">storage_mode</span></tt> parameter refers to the layout of the storage for this torrent.
 503 There are 3 different modes:</p>
 504 <dl class="docutils">
 505 <dt>storage_mode_sparse</dt>
 506 <dd>All pieces will be written to the place where they belong and sparse files
 507 will be used. This is the recommended, and default mode.</dd>
 508 <dt>storage_mode_allocate</dt>
 509 <dd>All pieces will be allocated, zeroes will be written to the files, before
 510 the data is downloaded and written to the file. This might be useful for
 511 filesystems that don't support sparse files.</dd>
 512 <dt>storage_mode_compact</dt>
 513 <dd>The storage will grow as more pieces are downloaded, and pieces
 514 are rearranged to finally be in their correct places once the entire torrent has been
 515 downloaded.</dd>
 516 </dl>
 517 <p>For more information, see <a class="reference" href="#storage-allocation">storage allocation</a>.</p>
 518 <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
 519 a paused state. I.e. it won't connect to the tracker or any of the peers until it's
 520 resumed. This is typically a good way of avoiding race conditions when setting
 521 configuration options on torrents before starting them.</p>
 522 <p>If <tt class="docutils literal"><span class="pre">auto_managed</span></tt> is true, this torrent will be queued, started and seeded
 523 automatically by libtorrent. When this is set, the torrent should also be started
 524 as paused. The default queue order is the order the torrents were added. They
 525 are all downloaded in that order. For more details, see <a class="reference" href="#queuing">queuing</a>.</p>
 526 <p><tt class="docutils literal"><span class="pre">storage</span></tt> can be used to customize how the data is stored. The default
 527 storage will simply write the data to the files it belongs to, but it could be
 528 overridden to save everything to a single file at a specific location or encrypt the
 529 content on disk for instance. For more information about the <tt class="docutils literal"><span class="pre">storage_interface</span></tt>
 530 that needs to be implemented for a custom storage, see <a class="reference" href="#storage-interface">storage_interface</a>.</p>
 531 <p>The <tt class="docutils literal"><span class="pre">userdata</span></tt> parameter is optional and will be passed on to the extension
 532 constructor functions, if any (see <a class="reference" href="#add-extension">add_extension()</a>).</p>
 533 <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
 534 about the torrent's progress, its peers etc. It is also used to abort a torrent.</p>
 535 </div>
 536 <div class="section">
 537 <h2><a id="remove-torrent" name="remove-torrent">remove_torrent()</a></h2>
 538 <blockquote>
 539 <pre class="literal-block">
 540 void remove_torrent(torrent_handle const&amp; h, int options = none);
 541 </pre>
 542 </blockquote>
 543 <p><tt class="docutils literal"><span class="pre">remove_torrent()</span></tt> will close all peer connections associated with the torrent and tell
 544 the tracker that we've stopped participating in the swarm. The optional second argument
 545 <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
 546 in the value <tt class="docutils literal"><span class="pre">session::delete_files</span></tt>. The removal of the torrent is asyncronous, there is
 547 no guarantee that adding the same torrent immediately after it was removed will not throw
 548 a <a class="reference" href="#duplicate-torrent">duplicate_torrent</a> exception.</p>
 549 </div>
 550 <div class="section">
 551 <h2><a id="find-torrent-get-torrents" name="find-torrent-get-torrents">find_torrent() get_torrents()</a></h2>
 552 <blockquote>
 553 <pre class="literal-block">
 554 torrent_handle find_torrent(sha_hash const&amp; ih);
 555 std::vector&lt;torrent_handle&gt; get_torrents() const;
 556 </pre>
 557 </blockquote>
 558 <p><tt class="docutils literal"><span class="pre">find_torrent()</span></tt> looks for a torrent with the given info-hash. In case there
 559 is such a torrent in the session, a torrent_handle to that torrent is returned.
 560 In case the torrent cannot be found, an invalid torrent_handle is returned.</p>
 561 <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>
 562 <p><tt class="docutils literal"><span class="pre">get_torrents()</span></tt> returns a vector of torrent_handles to all the torrents
 563 currently in the session.</p>
 564 </div>
 565 <div class="section">
 566 <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>
 567 <blockquote>
 568 <pre class="literal-block">
 569 void set_upload_rate_limit(int bytes_per_second);
 570 void set_download_rate_limit(int bytes_per_second);
 571 int upload_rate_limit() const;
 572 int download_rate_limit() const;
 573 </pre>
 574 </blockquote>
 575 <p><tt class="docutils literal"><span class="pre">set_upload_rate_limit()</span></tt> set the maximum number of bytes allowed to be
 576 sent to peers per second. This bandwidth is distributed among all the peers. If
 577 you don't want to limit upload rate, you can set this to -1 (the default).
 578 <tt class="docutils literal"><span class="pre">set_download_rate_limit()</span></tt> works the same way but for download rate instead
 579 of upload rate.
 580 <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
 581 set limits.</p>
 582 </div>
 583 <div class="section">
 584 <h2><a id="set-max-uploads-set-max-connections" name="set-max-uploads-set-max-connections">set_max_uploads() set_max_connections()</a></h2>
 585 <blockquote>
 586 <pre class="literal-block">
 587 void set_max_uploads(int limit);
 588 void set_max_connections(int limit);
 589 </pre>
 590 </blockquote>
 591 <p>These functions will set a global limit on the number of unchoked peers (uploads)
 592 and the number of connections opened. The number of connections is set to a hard
 593 minimum of at least two connections per torrent, so if you set a too low
 594 connections limit, and open too many torrents, the limit will not be met. The
 595 number of uploads is at least one per torrent.</p>
 596 </div>
 597 <div class="section">
 598 <h2><a id="num-uploads-num-connections" name="num-uploads-num-connections">num_uploads() num_connections()</a></h2>
 599 <blockquote>
 600 <pre class="literal-block">
 601 int num_uploads() const;
 602 int num_connections() const;
 603 </pre>
 604 </blockquote>
 605 <p>Returns the number of currently unchoked peers and the number of connections
 606 (including half-open ones) respectively.</p>
 607 </div>
 608 <div class="section">
 609 <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>
 610 <blockquote>
 611 <pre class="literal-block">
 612 void set_max_half_open_connections(int limit);
 613 int max_half_open_connections() const;
 614 </pre>
 615 </blockquote>
 616 <p>Sets the maximum number of half-open connections libtorrent will have when
 617 connecting to peers. A half-open connection is one where connect() has been
 618 called, but the connection still hasn't been established (nor failed). Windows
 619 XP Service Pack 2 sets a default, system wide, limit of the number of half-open
 620 connections to 10. So, this limit can be used to work nicer together with
 621 other network applications on that system. The default is to have no limit,
 622 and passing -1 as the limit, means to have no limit. When limiting the number
 623 of simultaneous connection attempts, peers will be put in a queue waiting for
 624 their turn to get connected.</p>
 625 <p><tt class="docutils literal"><span class="pre">max_half_open_connections()</span></tt> returns the set limit. This limit defaults
 626 to 8 on windows.</p>
 627 </div>
 628 <div class="section">
 629 <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>
 630 <blockquote>
 631 <pre class="literal-block">
 632 bool load_asnum_db(char const* file);
 633 bool load_country_db(char const* file);
 634 int as_for_ip(address const&amp; adr);
 635 </pre>
 636 </blockquote>
 637 <p>These functions are not available if <tt class="docutils literal"><span class="pre">TORRENT_DISABLE_GEO_IP</span></tt> is defined. They
 638 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>
 639 respectively. This will be used to look up which AS and country peers belong to.</p>
 640 <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
 641 in the database or the ASN database is not loaded, 0 is returned.</p>
 642 </div>
 643 <div class="section">
 644 <h2><a id="load-state-state" name="load-state-state">load_state() state()</a></h2>
 645 <blockquote>
 646 <pre class="literal-block">
 647 void load_state(entry const&amp; ses_state);
 648 entry state() const;
 649 </pre>
 650 </blockquote>
 651 <p>These functions loads and save session state. Currently, the only state
 652 that's stored is peak download rates for ASes. This map is used to
 653 determine which order to connect to peers.</p>
 654 </div>
 655 <div class="section">
 656 <h2><a id="set-ip-filter" name="set-ip-filter">set_ip_filter()</a></h2>
 657 <blockquote>
 658 <pre class="literal-block">
 659 void set_ip_filter(ip_filter const&amp; filter);
 660 </pre>
 661 </blockquote>
 662 <p>Sets a filter that will be used to reject and accept incoming as well as outgoing
 663 connections based on their originating ip address. The default filter will allow
 664 connections to any ip address. To build a set of rules for which addresses are
 665 accepted and not, see <a class="reference" href="#ip-filter">ip_filter</a>.</p>
 666 <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
 667 generated.</p>
 668 </div>
 669 <div class="section">
 670 <h2><a id="status" name="status">status()</a></h2>
 671 <blockquote>
 672 <pre class="literal-block">
 673 session_status status() const;
 674 </pre>
 675 </blockquote>
 676 <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>
 677 struct has the following members:</p>
 678 <pre class="literal-block">
 679 struct session_status
 680 {
 681         bool has_incoming_connections;
 682
 683         float upload_rate;
 684         float download_rate;
 685
 686         float payload_upload_rate;
 687         float payload_download_rate;
 688
 689         size_type total_download;
 690         size_type total_upload;
 691
 692         size_type total_redundant_bytes;
 693         size_type total_failed_bytes;
 694
 695         size_type total_payload_download;
 696         size_type total_payload_upload;
 697
 698         int num_peers;
 699         int num_unchoked;
 700         int allowed_upload_slots;
 701
 702         int dht_nodes;
 703         int dht_cache_nodes;
 704         int dht_torrents;
 705         int dht_global_nodes;
 706 };
 707 </pre>
 708 <p><tt class="docutils literal"><span class="pre">has_incoming_connections</span></tt> is false as long as no incoming connections have been
 709 established on the listening socket. Every time you change the listen port, this will
 710 be reset to false.</p>
 711 <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>
 712 are the total download and upload rates accumulated from all torrents. The payload
 713 versions is the payload download only.</p>
 714 <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
 715 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>
 716 are the same thing but where only the payload is considered.</p>
 717 <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.
 718 This can happen if a request from a peer times out and is requested from a different
 719 peer, and then received again from the first one. To make this lower, increase the
 720 <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>
 721 <p><tt class="docutils literal"><span class="pre">total_failed_bytes</span></tt> is the number of bytes that was downloaded which later failed
 722 the hash-check.</p>
 723 <p><tt class="docutils literal"><span class="pre">num_peers</span></tt> is the total number of peer connections this session has. This includes
 724 incoming connections that still hasn't sent their handshake or outgoing connections
 725 that still hasn't completed the TCP connection. This number may be slightly higher
 726 than the sum of all peers of all torrents because the incoming connections may not
 727 be assigned a torrent yet.</p>
 728 <p><tt class="docutils literal"><span class="pre">num_unchoked</span></tt> is the current number of unchoked peers.
 729 <tt class="docutils literal"><span class="pre">allowed_upload_slots</span></tt> is the current allowed number of unchoked peers.</p>
 730 <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
 731 built with DHT support. They are all set to 0 if the DHT isn't running. When
 732 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
 733 table. This number only includes <em>active</em> nodes, not cache nodes. The
 734 <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
 735 are used to replace the regular nodes in the routing table in case any of them
 736 becomes unresponsive.</p>
 737 <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>
 738 <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
 739 network.</p>
 740 </div>
 741 <div class="section">
 742 <h2><a id="get-cache-status" name="get-cache-status">get_cache_status()</a></h2>
 743 <blockquote>
 744 <pre class="literal-block">
 745 cache_status get_cache_status() const;
 746 </pre>
 747 </blockquote>
 748 <p>Returns status of the disk cache for this session.</p>
 749 <blockquote>
 750 <pre class="literal-block">
 751 struct cache_status
 752 {
 753         size_type blocks_written;
 754         size_type writes;
 755         size_type blocks_read;
 756         size_type blocks_read_hit;
 757         size_type reads;
 758         int cache_size;
 759         int read_cache_size;
 760 };
 761 </pre>
 762 </blockquote>
 763 <p><tt class="docutils literal"><span class="pre">blocks_written</span></tt> is the total number of 16 KiB blocks written to disk
 764 since this session was started.</p>
 765 <p><tt class="docutils literal"><span class="pre">writes</span></tt> is the total number of write operations performed since this
 766 session was started.</p>
 767 <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
 768 the number of saved write operations per total write operations. i.e. a kind
 769 of cache hit ratio for the write cahe.</p>
 770 <p><tt class="docutils literal"><span class="pre">blocks_read</span></tt> is the number of blocks that were requested from the
 771 bittorrent engine (from peers), that were served from disk or cache.</p>
 772 <p><tt class="docutils literal"><span class="pre">blocks_read_hit</span></tt> is the number of blocks that were served from cache.</p>
 773 <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
 774 for the read cache.</p>
 775 <p><tt class="docutils literal"><span class="pre">cache_size</span></tt> is the number of 16 KiB blocks currently in the disk cache.
 776 This includes both read and write cache.</p>
 777 <p><tt class="docutils literal"><span class="pre">read_cache_size</span></tt> is the number of 16KiB blocks in the read cache.</p>
 778 </div>
 779 <div class="section">
 780 <h2><a id="get-cache-info" name="get-cache-info">get_cache_info()</a></h2>
 781 <blockquote>
 782 <pre class="literal-block">
 783 void get_cache_info(sha1_hash const&amp; ih
 784         , std::vector&lt;cached_piece_info&gt;&amp; ret) const;
 785 </pre>
 786 </blockquote>
 787 <p><tt class="docutils literal"><span class="pre">get_cache_info()</span></tt> fills out the supplied vector with information for
 788 each piece that is currently in the disk cache for the torrent with the
 789 specified info-hash (<tt class="docutils literal"><span class="pre">ih</span></tt>).</p>
 790 <blockquote>
 791 <pre class="literal-block">
 792 struct cached_piece_info
 793 {
 794         int piece;
 795         std::vector&lt;bool&gt; blocks;
 796         ptime last_use;
 797         enum kind_t { read_cache = 0, write_cache = 1 };
 798         kind_t kind;
 799 };
 800 </pre>
 801 </blockquote>
 802 <p><tt class="docutils literal"><span class="pre">piece</span></tt> is the piece index for this cache entry.</p>
 803 <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
 804 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>
 805 <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
 806 a piece is, the more likely it is to be flushed to disk.</p>
 807 <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>
 808 </div>
 809 <div class="section">
 810 <h2><a id="is-listening-listen-port-listen-on" name="is-listening-listen-port-listen-on">is_listening() listen_port() listen_on()</a></h2>
 811 <blockquote>
 812 <pre class="literal-block">
 813 bool is_listening() const;
 814 unsigned short listen_port() const;
 815 bool listen_on(
 816         std::pair&lt;int, int&gt; const&amp; port_range
 817         , char const* interface = 0);
 818 </pre>
 819 </blockquote>
 820 <p><tt class="docutils literal"><span class="pre">is_listening()</span></tt> will tell you whether or not the session has successfully
 821 opened a listening port. If it hasn't, this function will return false, and
 822 then you can use <tt class="docutils literal"><span class="pre">listen_on()</span></tt> to make another try.</p>
 823 <p><tt class="docutils literal"><span class="pre">listen_port()</span></tt> returns the port we ended up listening on. Since you just pass
 824 a port-range to the constructor and to <tt class="docutils literal"><span class="pre">listen_on()</span></tt>, to know which port it
 825 ended up using, you have to ask the session using this function.</p>
 826 <p><tt class="docutils literal"><span class="pre">listen_on()</span></tt> will change the listen port and/or the listen interface. If the
 827 session is already listening on a port, this socket will be closed and a new socket
 828 will be opened with these new settings. The port range is the ports it will try
 829 to listen on, if the first port fails, it will continue trying the next port within
 830 the range and so on. The interface parameter can be left as 0, in that case the
 831 os will decide which interface to listen on, otherwise it should be the ip-address
 832 of the interface you want the listener socket bound to. <tt class="docutils literal"><span class="pre">listen_on()</span></tt> returns true
 833 if it managed to open the socket, and false if it failed. If it fails, it will also
 834 generate an appropriate alert (<a class="reference" href="#listen-failed-alert">listen_failed_alert</a>).</p>
 835 <p>The interface parameter can also be a hostname that will resolve to the device you
 836 want to listen on.</p>
 837 <p>If you're also starting the DHT, it is a good idea to do that after you've called
 838 <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
 839 listen socket. If you start the DHT first, it will assume the tcp port is free and
 840 open the udp socket on that port, then later, when <tt class="docutils literal"><span class="pre">listen_on()</span></tt> is called, it
 841 may turn out that the tcp port is in use. That results in the DHT and the bittorrent
 842 socket listening on different ports. If the DHT is active when <tt class="docutils literal"><span class="pre">listen_on</span></tt> is
 843 called, the udp port will be rebound to the new port, if it was configured to use
 844 the same port as the tcp socket, and if the listen_on call failed to bind to the
 845 same port that the udp uses.</p>
 846 <p>The reason why it's a good idea to run the DHT and the bittorrent socket on the same
 847 port is because that is an assumption that may be used to increase performance. One
 848 way to accelerate the connecting of peers on windows may be to first ping all peers
 849 with a DHT ping packet, and connect to those that responds first. On windows one
 850 can only connect to a few peers at a time because of a built in limitation (in XP
 851 Service pack 2).</p>
 852 </div>
 853 <div class="section">
 854 <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>
 855 <blockquote>
 856 <pre class="literal-block">
 857 std::auto_ptr&lt;alert&gt; pop_alert();
 858 alert const* wait_for_alert(time_duration max_wait);
 859 void set_alert_mask(int m);
 860 </pre>
 861 </blockquote>
 862 <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
 863 <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>.
 864 For information about the alert categories, see <a class="reference" href="#alerts">alerts</a>.</p>
 865 <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>
 866 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,
 867 it returns 0. If at least one alert was generated, a pointer to that alert is returned.
 868 The alert is not popped, any subsequent calls to <tt class="docutils literal"><span class="pre">wait_for_alert</span></tt> will return the
 869 same pointer until the alert is popped by calling <tt class="docutils literal"><span class="pre">pop_alert</span></tt>. This is useful for
 870 leaving any alert dispatching mechanism independent of this blocking call, the dispatcher
 871 can be called and it can pop the alert independently.</p>
 872 </div>
 873 <div class="section">
 874 <h2><a id="add-extension" name="add-extension">add_extension()</a></h2>
 875 <blockquote>
 876 <pre class="literal-block">
 877 void add_extension(boost::function&lt;
 878         boost::shared_ptr&lt;torrent_plugin&gt;(torrent*, void*)&gt; ext);
 879 </pre>
 880 </blockquote>
 881 <p>This function adds an extension to this session. The argument is a function
 882 object that is called with a <tt class="docutils literal"><span class="pre">torrent*</span></tt> and which should return a
 883 <tt class="docutils literal"><span class="pre">boost::shared_ptr&lt;torrent_plugin&gt;</span></tt>. To write custom plugins, see
 884 <a class="reference" href="libtorrent_plugins.html">libtorrent plugins</a>. The main plugins implemented in libtorrent are:</p>
 885 <dl class="docutils">
 886 <dt>metadata extension</dt>
 887 <dd>Allows peers to download the metadata (.torren files) from the swarm
 888 directly. Makes it possible to join a swarm with just a tracker and
 889 info-hash.</dd>
 890 </dl>
 891 <pre class="literal-block">
 892 #include &lt;libtorrent/extensions/metadata_transfer.hpp&gt;
 893 ses.add_extension(&amp;libtorrent::create_metadata_plugin);
 894 </pre>
 895 <dl class="docutils">
 896 <dt>uTorrent metadata</dt>
 897 <dd>Same as <tt class="docutils literal"><span class="pre">metadata</span> <span class="pre">extension</span></tt> but compatible with uTorrent.</dd>
 898 </dl>
 899 <pre class="literal-block">
 900 #include &lt;libtorrent/extensions/ut_metadata.hpp&gt;
 901 ses.add_extension(&amp;libtorrent::create_ut_metadata_plugin);
 902 </pre>
 903 <dl class="docutils">
 904 <dt>uTorrent peer exchange</dt>
 905 <dd>Exchanges peers between clients.</dd>
 906 </dl>
 907 <pre class="literal-block">
 908 #include &lt;libtorrent/extensions/ut_pex.hpp&gt;
 909 ses.add_extension(&amp;libtorrent::create_ut_pex_plugin);
 910 </pre>
 911 <dl class="docutils">
 912 <dt>smart ban plugin</dt>
 913 <dd>A plugin that, with a small overhead, can ban peers
 914 that sends bad data with very high accuracy. Should
 915 eliminate most problems on poisoned torrents.</dd>
 916 </dl>
 917 <pre class="literal-block">
 918 #include &lt;libtorrent/extensions/smart_ban.hpp&gt;
 919 ses.add_extension(&amp;libtorrent::create_smart_ban_plugin);
 920 </pre>
 921 </div>
 922 <div class="section">
 923 <h2><a id="set-settings-set-pe-settings" name="set-settings-set-pe-settings">set_settings() set_pe_settings()</a></h2>
 924 <blockquote>
 925 <pre class="literal-block">
 926 void set_settings(session_settings const&amp; settings);
 927 void set_pe_settings(pe_settings const&amp; settings);
 928 </pre>
 929 </blockquote>
 930 <p>Sets the session settings and the packet encryption settings respectively.
 931 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
 932 options.</p>
 933 </div>
 934 <div class="section">
 935 <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>
 936 <blockquote>
 937 <pre class="literal-block">
 938 void set_peer_proxy(proxy_settings const&amp; s);
 939 void set_web_seed_proxy(proxy_settings const&amp; s);
 940 void set_tracker_proxy(proxy_settings const&amp; s);
 941 void set_dht_proxy(proxy_settings const&amp; s);
 942 </pre>
 943 </blockquote>
 944 <p>The <tt class="docutils literal"><span class="pre">set_dht_proxy</span></tt> is not available when DHT is disabled. These functions
 945 sets the proxy settings for different kinds of connections, bittorrent peers,
 946 web seeds, trackers and the DHT traffic.</p>
 947 <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>
 948 affects only web seeds. see <a class="reference" href="#http-seeding">HTTP seeding</a>.</p>
 949 <p><tt class="docutils literal"><span class="pre">set_tracker_proxy</span></tt> only affects HTTP tracker connections (UDP tracker
 950 connections are affected if the given proxy supports UDP, e.g. SOCKS5).</p>
 951 <p><tt class="docutils literal"><span class="pre">set_dht_proxy</span></tt> affects the DHT messages. Since they are sent over UDP,
 952 it only has any effect if the proxy supports UDP.</p>
 953 <p>For more information on what settings are available for proxies, see
 954 <a class="reference" href="#proxy-settings">proxy_settings</a>.</p>
 955 </div>
 956 <div class="section">
 957 <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>
 958 <blockquote>
 959 <pre class="literal-block">
 960 proxy_settings const&amp; peer_proxy() const;
 961 proxy_settings const&amp; web_seed_proxy() const;
 962 proxy_settings const&amp; tracker_proxy() const;
 963 proxy_settings const&amp; dht_proxy() const;
 964 </pre>
 965 </blockquote>
 966 <p>These functions returns references to their respective current settings.</p>
 967 <p>The <tt class="docutils literal"><span class="pre">dht_proxy</span></tt> is not available when DHT is disabled.</p>
 968 </div>
 969 <div class="section">
 970 <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>
 971 <blockquote>
 972 <pre class="literal-block">
 973 void start_dht(entry const&amp; startup_state);
 974 void stop_dht();
 975 void set_dht_settings(dht_settings const&amp; settings);
 976 entry dht_state() const;
 977 </pre>
 978 </blockquote>
 979 <p>These functions are not available in case <tt class="docutils literal"><span class="pre">TORRENT_DISABLE_DHT</span></tt> is
 980 defined. <tt class="docutils literal"><span class="pre">start_dht</span></tt> starts the dht node and makes the trackerless service
 981 available to torrents. The startup state is optional and can contain nodes
 982 and the node id from the previous session. The dht node state is a bencoded
 983 dictionary with the following entries:</p>
 984 <dl class="docutils">
 985 <dt><tt class="docutils literal"><span class="pre">nodes</span></tt></dt>
 986 <dd>A list of strings, where each string is a node endpoint encoded in binary. If
 987 the string is 6 bytes long, it is an IPv4 address of 4 bytes, encoded in
 988 network byte order (big endian), followed by a 2 byte port number (also
 989 network byte order). If the string is 18 bytes long, it is 16 bytes of IPv6
 990 address followed by a 2 bytes port number (also network byte order).</dd>
 991 <dt><tt class="docutils literal"><span class="pre">node-id</span></tt></dt>
 992 <dd>The node id written as a readable string as a hexadecimal number.</dd>
 993 </dl>
 994 <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
 995 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
 996 idea to save this to disk when the session is closed, and read it up again
 997 when starting.</p>
 998 <p>If the port the DHT is supposed to listen on is already in use, and exception
 999 is thrown, <tt class="docutils literal"><span class="pre">asio::error</span></tt>.</p>
1000 <p><tt class="docutils literal"><span class="pre">stop_dht</span></tt> stops the dht node.</p>
1001 <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
1002 client has its own source of bootstrapping nodes.</p>
1003 <p><tt class="docutils literal"><span class="pre">set_dht_settings</span></tt> sets some parameters availavle to the dht node. The
1004 struct has the following members:</p>
1005 <pre class="literal-block">
1006 struct dht_settings
1007 {
1008         int max_peers_reply;
1009         int search_branching;
1010         int service_port;
1011         int max_fail_count;
1012 };
1013 </pre>
1014 <p><tt class="docutils literal"><span class="pre">max_peers_reply</span></tt> is the maximum number of peers the node will send in
1015 response to a <tt class="docutils literal"><span class="pre">get_peers</span></tt> message from another node.</p>
1016 <p><tt class="docutils literal"><span class="pre">search_branching</span></tt> is the number of concurrent search request the node will
1017 send when announcing and refreshing the routing table. This parameter is
1018 called alpha in the kademlia paper.</p>
1019 <p><tt class="docutils literal"><span class="pre">service_port</span></tt> is the udp port the node will listen to. This will default
1020 to 0, which means the udp listen port will be the same as the tcp listen
1021 port. This is in general a good idea, since some NAT implementations
1022 reserves the udp port for any mapped tcp port, and vice versa. NAT-PMP
1023 guarantees this for example.</p>
1024 <p><tt class="docutils literal"><span class="pre">max_fail_count</span></tt> is the maximum number of failed tries to contact a node
1025 before it is removed from the routing table. If there are known working nodes
1026 that are ready to replace a failing node, it will be replaced immediately,
1027 this limit is only used to clear out nodes that don't have any node that can
1028 replace them.</p>
1029 </div>
1030 <div class="section">
1031 <h2><a id="add-dht-node-add-dht-router" name="add-dht-node-add-dht-router">add_dht_node() add_dht_router()</a></h2>
1032 <blockquote>
1033 <pre class="literal-block">
1034 void add_dht_node(std::pair&lt;std::string, int&gt; const&amp; node);
1035 void add_dht_router(std::pair&lt;std::string, int&gt; const&amp; node);
1036 </pre>
1037 </blockquote>
1038 <p><tt class="docutils literal"><span class="pre">add_dht_node</span></tt> takes a host name and port pair. That endpoint will be
1039 pinged, and if a valid DHT reply is received, the node will be added to
1040 the routing table.</p>
1041 <p><tt class="docutils literal"><span class="pre">add_dht_router</span></tt> adds the given endpoint to a list of DHT router nodes.
1042 If a search is ever made while the routing table is empty, those nodes will
1043 be used as backups. Nodes in the router node list will also never be added
1044 to the regular routing table, which effectively means they are only used
1045 for bootstrapping, to keep the load off them.</p>
1046 <p>An example routing node that you could typically add is
1047 <tt class="docutils literal"><span class="pre">router.bittorrent.com</span></tt>.</p>
1048 </div>
1049 <div class="section">
1050 <h2><a id="start-lsd-stop-lsd" name="start-lsd-stop-lsd">start_lsd() stop_lsd()</a></h2>
1051 <blockquote>
1052 <pre class="literal-block">
1053 void start_lsd();
1054 void stop_lsd();
1055 </pre>
1056 </blockquote>
1057 <p>Starts and stops Local Service Discovery. This service will broadcast
1058 the infohashes of all the non-private torrents on the local network to
1059 look for peers on the same swarm within multicast reach.</p>
1060 <p>It is turned off by default.</p>
1061 </div>
1062 <div class="section">
1063 <h2><a id="start-upnp-stop-upnp" name="start-upnp-stop-upnp">start_upnp() stop_upnp()</a></h2>
1064 <blockquote>
1065 <pre class="literal-block">
1066 upnp* start_upnp();
1067 void stop_upnp();
1068 </pre>
1069 </blockquote>
1070 <p>Starts and stops the UPnP service. When started, the listen port and the DHT
1071 port are attempted to be forwarded on local UPnP router devices.</p>
1072 <p>The upnp object returned by <tt class="docutils literal"><span class="pre">start_upnp()</span></tt> can be used to add and remove
1073 arbitrary port mappings. Mapping status is returned through the
1074 <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
1075 <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>
1076 <p>It is off by default.</p>
1077 </div>
1078 <div class="section">
1079 <h2><a id="start-natpmp-stop-natpmp" name="start-natpmp-stop-natpmp">start_natpmp() stop_natpmp()</a></h2>
1080 <blockquote>
1081 <pre class="literal-block">
1082 natpmp* start_natpmp();
1083 void stop_natpmp();
1084 </pre>
1085 </blockquote>
1086 <p>Starts and stops the NAT-PMP service. When started, the listen port and the DHT
1087 port are attempted to be forwarded on the router through NAT-PMP.</p>
1088 <p>The natpmp object returned by <tt class="docutils literal"><span class="pre">start_natpmp()</span></tt> can be used to add and remove
1089 arbitrary port mappings. Mapping status is returned through the
1090 <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
1091 <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>
1092 <p>It is off by default.</p>
1093 </div>
1094 </div>
1095 <div class="section">
1096 <h1><a id="entry" name="entry">entry</a></h1>
1097 <p>The <tt class="docutils literal"><span class="pre">entry</span></tt> class represents one node in a bencoded hierarchy. It works as a
1098 variant type, it can be either a list, a dictionary (<tt class="docutils literal"><span class="pre">std::map</span></tt>), an integer
1099 or a string. This is its synopsis:</p>
1100 <pre class="literal-block">
1101 class entry
1102 {
1103 public:
1104
1105         typedef std::map&lt;std::string, entry&gt; dictionary_type;
1106         typedef std::string string_type;
1107         typedef std::list&lt;entry&gt; list_type;
1108         typedef size_type integer_type;
1109
1110         enum data_type
1111         {
1112                 int_t,
1113                 string_t,
1114                 list_t,
1115                 dictionary_t,
1116                 undefined_t
1117         };
1118
1119         data_type type() const;
1120
1121         entry(dictionary_type const&amp;);
1122         entry(string_type const&amp;);
1123         entry(list_type const&amp;);
1124         entry(integer_type const&amp;);
1125
1126         entry();
1127         entry(data_type t);
1128         entry(entry const&amp; e);
1129         ~entry();
1130
1131         void operator=(entry const&amp; e);
1132         void operator=(dictionary_type const&amp;);
1133         void operator=(string_type const&amp;);
1134         void operator=(list_type const&amp;);
1135         void operator=(integer_type const&amp;);
1136
1137         integer_type&amp; integer();
1138         integer_type const&amp; integer() const;
1139         string_type&amp; string();
1140         string_type const&amp; string() const;
1141         list_type&amp; list();
1142         list_type const&amp; list() const;
1143         dictionary_type&amp; dict();
1144         dictionary_type const&amp; dict() const;
1145
1146         // these functions requires that the entry
1147         // is a dictionary, otherwise they will throw
1148         entry&amp; operator[](char const* key);
1149         entry&amp; operator[](std::string const&amp; key);
1150         entry const&amp; operator[](char const* key) const;
1151         entry const&amp; operator[](std::string const&amp; key) const;
1152         entry* find_key(char const* key);
1153         entry const* find_key(char const* key) const;
1154
1155         void print(std::ostream&amp; os, int indent = 0) const;
1156 };
1157 </pre>
1158 <p><em>TODO: finish documentation of entry.</em></p>
1159 <div class="section">
1160 <h2><a id="integer-string-list-dict-type" name="integer-string-list-dict-type">integer() string() list() dict() type()</a></h2>
1161 <blockquote>
1162 <pre class="literal-block">
1163 integer_type&amp; integer();
1164 integer_type const&amp; integer() const;
1165 string_type&amp; string();
1166 string_type const&amp; string() const;
1167 list_type&amp; list();
1168 list_type const&amp; list() const;
1169 dictionary_type&amp; dict();
1170 dictionary_type const&amp; dict() const;
1171 </pre>
1172 </blockquote>
1173 <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
1174 are accessors that return the respective type. If the <tt class="docutils literal"><span class="pre">entry</span></tt> object isn't of the
1175 type you request, the accessor will throw <a class="reference" href="#type-error">type_error</a> (which derives from
1176 <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
1177 <tt class="docutils literal"><span class="pre">type()</span></tt> function.</p>
1178 <p>The <tt class="docutils literal"><span class="pre">print()</span></tt> function is there for debug purposes only.</p>
1179 <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
1180 constructor, and then use one of the non-const accessors to get a reference which you then
1181 can assign the value you want it to have.</p>
1182 <p>The typical code to get info from a torrent file will then look like this:</p>
1183 <pre class="literal-block">
1184 entry torrent_file;
1185 // ...
1186
1187 // throws if this is not a dictionary
1188 entry::dictionary_type const&amp; dict = torrent_file.dict();
1189 entry::dictionary_type::const_iterator i;
1190 i = dict.find(&quot;announce&quot;);
1191 if (i != dict.end())
1192 {
1193         std::string tracker_url = i-&gt;second.string();
1194         std::cout &lt;&lt; tracker_url &lt;&lt; &quot;\n&quot;;
1195 }
1196 </pre>
1197 <p>The following code is equivalent, but a little bit shorter:</p>
1198 <pre class="literal-block">
1199 entry torrent_file;
1200 // ...
1201
1202 // throws if this is not a dictionary
1203 if (entry* i = torrent_file.find_key(&quot;announce&quot;))
1204 {
1205         std::string tracker_url = i-&gt;string();
1206         std::cout &lt;&lt; tracker_url &lt;&lt; &quot;\n&quot;;
1207 }
1208 </pre>
1209 <p>To make it easier to extract information from a torrent file, the class <a class="reference" href="#torrent-info">torrent_info</a>
1210 exists.</p>
1211 </div>
1212 <div class="section">
1213 <h2><a id="operator" name="operator">operator[]</a></h2>
1214 <blockquote>
1215 <pre class="literal-block">
1216 entry&amp; operator[](char const* key);
1217 entry&amp; operator[](std::string const&amp; key);
1218 entry const&amp; operator[](char const* key) const;
1219 entry const&amp; operator[](std::string const&amp; key) const;
1220 </pre>
1221 </blockquote>
1222 <p>All of these functions requires the entry to be a dictionary, if it isn't they
1223 will throw <tt class="docutils literal"><span class="pre">libtorrent::type_error</span></tt>.</p>
1224 <p>The non-const versions of the <tt class="docutils literal"><span class="pre">operator[]</span></tt> will return a reference to either
1225 the existing element at the given key or, if there is no element with the
1226 given key, a reference to a newly inserted element at that key.</p>
1227 <p>The const version of <tt class="docutils literal"><span class="pre">operator[]</span></tt> will only return a reference to an
1228 existing element at the given key. If the key is not found, it will throw
1229 <tt class="docutils literal"><span class="pre">libtorrent::type_error</span></tt>.</p>
1230 </div>
1231 <div class="section">
1232 <h2><a id="find-key" name="find-key">find_key()</a></h2>
1233 <blockquote>
1234 <pre class="literal-block">
1235 entry* find_key(char const* key);
1236 entry const* find_key(char const* key) const;
1237 </pre>
1238 </blockquote>
1239 <p>These functions requires the entry to be a dictionary, if it isn't they
1240 will throw <tt class="docutils literal"><span class="pre">libtorrent::type_error</span></tt>.</p>
1241 <p>They will look for an element at the given key in the dictionary, if the
1242 element cannot be found, they will return 0. If an element with the given
1243 key is found, the return a pointer to it.</p>
1244 </div>
1245 </div>
1246 <div class="section">
1247 <h1><a id="torrent-info" name="torrent-info">torrent_info</a></h1>
1248 <p>In previous versions of libtorrent, this class was also used for creating
1249 torrent files. This functionality has been moved to <tt class="docutils literal"><span class="pre">create_torrent</span></tt>, see
1250 <a class="reference" href="make_torrent.html">make_torrent</a>.</p>
1251 <p>The <tt class="docutils literal"><span class="pre">torrent_info</span></tt> has the following synopsis:</p>
1252 <pre class="literal-block">
1253 class torrent_info
1254 {
1255 public:
1256
1257         torrent_info(sha1_hash const&amp; info_hash);
1258         torrent_info(lazy_entry const&amp; torrent_file);
1259         torrent_info(char const* buffer, int size);
1260         torrent_info(boost::filesystem::path const&amp; filename);
1261
1262         void add_tracker(std::string const&amp; url, int tier = 0);
1263         std::vector&lt;announce_entry&gt; const&amp; trackers() const;
1264
1265         file_storage const&amp; files() const;
1266
1267         typedef file_storage::iterator file_iterator;
1268         typedef file_storage::reverse_iterator reverse_file_iterator;
1269
1270         file_iterator begin_files() const;
1271         file_iterator end_files() const;
1272         reverse_file_iterator rbegin_files() const;
1273         reverse_file_iterator rend_files() const;
1274
1275         int num_files() const;
1276         file_entry const&amp; file_at(int index) const;
1277
1278         std::vector&lt;file_slice&gt; map_block(int piece, size_type offset
1279                 , int size) const;
1280         peer_request map_file(int file_index, size_type file_offset
1281                 , int size) const;
1282
1283         bool priv() const;
1284
1285         std::vector&lt;std::string&gt; const&amp; url_seeds() const;
1286
1287         size_type total_size() const;
1288         int piece_length() const;
1289         int num_pieces() const;
1290         sha1_hash const&amp; info_hash() const;
1291         std::string const&amp; name() const;
1292         std::string const&amp; comment() const;
1293         std::string const&amp; creator() const;
1294
1295         std::vector&lt;std::pair&lt;std::string, int&gt; &gt; const&amp; nodes() const;
1296         void add_node(std::pair&lt;std::string, int&gt; const&amp; node);
1297
1298         boost::optional&lt;boost::posix_time::ptime&gt;
1299         creation_date() const;
1300
1301         int piece_size(unsigned int index) const;
1302         sha1_hash const&amp; hash_for_piece(unsigned int index) const;
1303         char const* hash_for_piece_ptr(unsigned int index) const;
1304
1305         boost::shared_array&lt;char&gt; metadata() const;
1306         int metadata_size() const;
1307 };
1308 </pre>
1309 <div class="section">
1310 <h2><a id="id3" name="id3">torrent_info()</a></h2>
1311 <blockquote>
1312 <pre class="literal-block">
1313 torrent_info(sha1_hash const&amp; info_hash);
1314 torrent_info(lazy_entry const&amp; torrent_file);
1315 torrent_info(char const* buffer, int size);
1316 torrent_info(boost::filesystem::path const&amp; filename);
1317 </pre>
1318 </blockquote>
1319 <p>The constructor that takes an info-hash  will initialize the info-hash to the given value,
1320 but leave all other fields empty. This is used internally when downloading torrents without
1321 the metadata. The metadata will be created by libtorrent as soon as it has been downloaded
1322 from the swarm.</p>
1323 <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
1324 information found in the given torrent_file. The <tt class="docutils literal"><span class="pre">lazy_entry</span></tt> represents a tree node in
1325 an bencoded file. To load an ordinary .torrent file
1326 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>
1327 <p>The version that takes a buffer pointer and a size will decode it as a .torrent file and
1328 initialize the torrent_info object for you.</p>
1329 <p>The version that takes a filename will simply load the torrent file and decode it inside
1330 the constructor, for convenience. This might not be the most suitable for applications that
1331 want to be able to report detailed errors on what might go wrong.</p>
1332 </div>
1333 <div class="section">
1334 <h2><a id="add-tracker" name="add-tracker">add_tracker()</a></h2>
1335 <blockquote>
1336 <pre class="literal-block">
1337 void add_tracker(std::string const&amp; url, int tier = 0);
1338 </pre>
1339 </blockquote>
1340 <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
1341 which the trackers are to be tried. For more information see <a class="reference" href="#trackers">trackers()</a>.</p>
1342 </div>
1343 <div class="section">
1344 <h2><a id="files" name="files">files()</a></h2>
1345 <blockquote>
1346 <pre class="literal-block">
1347 file_storage const&amp; file() const;
1348 </pre>
1349 </blockquote>
1350 <p>The <tt class="docutils literal"><span class="pre">file_storage</span></tt> object contains the information on how to map the pieces to
1351 files. It is separated from the <tt class="docutils literal"><span class="pre">torrent_info</span></tt> object because when creating torrents
1352 a storage object needs to be created without having a torrent file. When renaming files
1353 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
1354 to make its mapping differ from the one in the torrent file.</p>
1355 <p>For more information on the <tt class="docutils literal"><span class="pre">file_storage</span></tt> object, see the separate document on how
1356 to create torrents.</p>
1357 </div>
1358 <div class="section">
1359 <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>
1360 <blockquote>
1361 <pre class="literal-block">
1362 file_iterator begin_files() const;
1363 file_iterator end_files() const;
1364 reverse_file_iterator rbegin_files() const;
1365 reverse_file_iterator rend_files() const;
1366 </pre>
1367 </blockquote>
1368 <p>This class will need some explanation. First of all, to get a list of all files
1369 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>,
1370 <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
1371 iterators with the type <tt class="docutils literal"><span class="pre">file_entry</span></tt>.</p>
1372 <pre class="literal-block">
1373 struct file_entry
1374 {
1375         boost::filesystem::path path;
1376         size_type offset;
1377         size_type size;
1378         size_type file_base;
1379         boost::shared_ptr&lt;const boost::filesystem::path&gt; orig_path;
1380 };
1381 </pre>
1382 <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
1383 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>.
1384 The filenames are encoded with UTF-8.</p>
1385 <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
1386 of the file within the torrent. i.e. the sum of all the sizes of the files
1387 before it in the list.</p>
1388 <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
1389 case is to have this set to 0, so that the storage starts saving data at the start
1390 if the file. In cases where multiple files are mapped into the same file though,
1391 the <tt class="docutils literal"><span class="pre">file_base</span></tt> should be set to an offset so that the different regions do
1392 not overlap. This is used when mapping &quot;unselected&quot; files into a so-called part
1393 file.</p>
1394 <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
1395 found in the metadata. In case the path in the original metadata was
1396 incorrectly encoded, and had to be fixed in order to be acceptable utf-8,
1397 the original string is preserved in <tt class="docutils literal"><span class="pre">orig_path</span></tt>. The reason to keep it
1398 is to be able to reproduce the info-section exactly, with the correct
1399 info-hash.</p>
1400 </div>
1401 <div class="section">
1402 <h2><a id="num-files-file-at" name="num-files-file-at">num_files() file_at()</a></h2>
1403 <blockquote>
1404 <pre class="literal-block">
1405 int num_files() const;
1406 file_entry const&amp; file_at(int index) const;
1407 </pre>
1408 </blockquote>
1409 <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>
1410 to access files using indices.</p>
1411 </div>
1412 <div class="section">
1413 <h2><a id="map-block" name="map-block">map_block()</a></h2>
1414 <blockquote>
1415 <pre class="literal-block">
1416 std::vector&lt;file_slice&gt; map_block(int piece, size_type offset
1417         , int size) const;
1418 </pre>
1419 </blockquote>
1420 <p>This function will map a piece index, a byte offset within that piece and
1421 a size (in bytes) into the corresponding files with offsets where that data
1422 for that piece is supposed to be stored.</p>
1423 <p>The file slice struct looks like this:</p>
1424 <pre class="literal-block">
1425 struct file_slice
1426 {
1427         int file_index;
1428         size_type offset;
1429         size_type size;
1430 };
1431 </pre>
1432 <p>The <tt class="docutils literal"><span class="pre">file_index</span></tt> refers to the index of the file (in the torrent_info).
1433 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>
1434 as argument. The <tt class="docutils literal"><span class="pre">offset</span></tt> is the byte offset in the file where the range
1435 starts, and <tt class="docutils literal"><span class="pre">size</span></tt> is the number of bytes this range is. The size + offset
1436 will never be greater than the file size.</p>
1437 </div>
1438 <div class="section">
1439 <h2><a id="map-file" name="map-file">map_file()</a></h2>
1440 <blockquote>
1441 <pre class="literal-block">
1442 peer_request map_file(int file_index, size_type file_offset
1443         , int size) const;
1444 </pre>
1445 </blockquote>
1446 <p>This function will map a range in a specific file into a range in the torrent.
1447 The <tt class="docutils literal"><span class="pre">file_offset</span></tt> parameter is the offset in the file, given in bytes, where
1448 0 is the start of the file.
1449 The <tt class="docutils literal"><span class="pre">peer_request</span></tt> structure looks like this:</p>
1450 <pre class="literal-block">
1451 struct peer_request
1452 {
1453         int piece;
1454         int start;
1455         int length;
1456         bool operator==(peer_request const&amp; r) const;
1457 };
1458 </pre>
1459 <p><tt class="docutils literal"><span class="pre">piece</span></tt> is the index of the piece in which the range starts.
1460 <tt class="docutils literal"><span class="pre">start</span></tt> is the offset within that piece where the range starts.
1461 <tt class="docutils literal"><span class="pre">length</span></tt> is the size of the range, in bytes.</p>
1462 <p>The input range is assumed to be valid within the torrent. <tt class="docutils literal"><span class="pre">file_offset</span></tt>
1463 + <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>
1464 must refer to a valid file, i.e. it cannot be &gt;= <tt class="docutils literal"><span class="pre">num_files()</span></tt>.</p>
1465 </div>
1466 <div class="section">
1467 <h2><a id="url-seeds-add-url-seed" name="url-seeds-add-url-seed">url_seeds() add_url_seed()</a></h2>
1468 <blockquote>
1469 <pre class="literal-block">
1470 std::vector&lt;std::string&gt; const&amp; url_seeds() const;
1471 void add_url_seed(std::string const&amp; url);
1472 </pre>
1473 </blockquote>
1474 <p>If there are any url-seeds in this torrent, <tt class="docutils literal"><span class="pre">url_seeds()</span></tt> will return a
1475 vector of those urls. If you're creating a torrent file, <tt class="docutils literal"><span class="pre">add_url_seed()</span></tt>
1476 adds one url to the list of url-seeds. Currently, the only transport protocol
1477 supported for the url is http.</p>
1478 <p>See <a class="reference" href="#http-seeding">HTTP seeding</a> for more information.</p>
1479 </div>
1480 <div class="section">
1481 <h2><a id="trackers" name="trackers">trackers()</a></h2>
1482 <blockquote>
1483 <pre class="literal-block">
1484 std::vector&lt;announce_entry&gt; const&amp; trackers() const;
1485 </pre>
1486 </blockquote>
1487 <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>.
1488 Each announce entry contains a string, which is the tracker url, and a tier index. The
1489 tier index is the high-level priority. No matter which trackers that works or not, the
1490 ones with lower tier will always be tried before the one with higher tier number.</p>
1491 <pre class="literal-block">
1492 struct announce_entry
1493 {
1494         announce_entry(std::string const&amp; url);
1495         std::string url;
1496         int tier;
1497 };
1498 </pre>
1499 </div>
1500 <div class="section">
1501 <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>
1502 <blockquote>
1503 <pre class="literal-block">
1504 size_type total_size() const;
1505 int piece_length() const;
1506 int piece_size(unsigned int index) const;
1507 int num_pieces() const;
1508 </pre>
1509 </blockquote>
1510 <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
1511 number of bytes the torrent-file represents (all the files in it), the number of byte for
1512 each piece and the total number of pieces, respectively. The difference between
1513 <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
1514 the piece index as argument and gives you the exact size of that piece. It will always
1515 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
1516 be smaller.</p>
1517 </div>
1518 <div class="section">
1519 <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>
1520 <blockquote>
1521 <pre class="literal-block">
1522 size_type piece_size(unsigned int index) const;
1523 sha1_hash const&amp; hash_for_piece(unsigned int index) const;
1524 char const* hash_for_piece_ptr(unsigned int index) const;
1525 </pre>
1526 </blockquote>
1527 <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
1528 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
1529 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.
1530 <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.
1531 Note that the string is not null-terminated.</p>
1532 </div>
1533 <div class="section">
1534 <h2><a id="name-comment-creation-date-creator" name="name-comment-creation-date-creator">name() comment() creation_date() creator()</a></h2>
1535 <blockquote>
1536 <pre class="literal-block">
1537 std::string const&amp; name() const;
1538 std::string const&amp; comment() const;
1539 boost::optional&lt;boost::posix_time::ptime&gt; creation_date() const;
1540 </pre>
1541 </blockquote>
1542 <p><tt class="docutils literal"><span class="pre">name()</span></tt> returns the name of the torrent.</p>
1543 <p><tt class="docutils literal"><span class="pre">comment()</span></tt> returns the comment associated with the torrent. If there's no comment,
1544 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>
1545 object, representing the time when this torrent file was created. If there's no time stamp
1546 in the torrent file, this will return a date of January 1:st 1970.</p>
1547 <p>Both the name and the comment is UTF-8 encoded strings.</p>
1548 <p><tt class="docutils literal"><span class="pre">creator()</span></tt> returns the creator string in the torrent. If there is no creator string
1549 it will return an empty string.</p>
1550 </div>
1551 <div class="section">
1552 <h2><a id="priv" name="priv">priv()</a></h2>
1553 <blockquote>
1554 <pre class="literal-block">
1555 bool priv() const;
1556 </pre>
1557 </blockquote>
1558 <p><tt class="docutils literal"><span class="pre">priv()</span></tt> returns true if this torrent is private. i.e., it should not be
1559 distributed on the trackerless network (the kademlia DHT).</p>
1560 </div>
1561 <div class="section">
1562 <h2><a id="nodes" name="nodes">nodes()</a></h2>
1563 <blockquote>
1564 <pre class="literal-block">
1565 std::vector&lt;std::pair&lt;std::string, int&gt; &gt; const&amp; nodes() const;
1566 </pre>
1567 </blockquote>
1568 <p>If this torrent contains any DHT nodes, they are put in this vector in their original
1569 form (host name and port number).</p>
1570 </div>
1571 <div class="section">
1572 <h2><a id="add-node" name="add-node">add_node()</a></h2>
1573 <blockquote>
1574 <pre class="literal-block">
1575 void add_node(std::pair&lt;std::string, int&gt; const&amp; node);
1576 </pre>
1577 </blockquote>
1578 <p>This is used when creating torrent. Use this to add a known DHT node. It may
1579 be used, by the client, to bootstrap into the DHT network.</p>
1580 </div>
1581 <div class="section">
1582 <h2><a id="metadata-metadata-size" name="metadata-metadata-size">metadata() metadata_size()</a></h2>
1583 <blockquote>
1584 <pre class="literal-block">
1585 boost::shared_array&lt;char&gt; metadata() const;
1586 int metadata_size() const;
1587 </pre>
1588 </blockquote>
1589 <p><tt class="docutils literal"><span class="pre">metadata()</span></tt> returns a the raw info section of the torrent file. The size
1590 of the metadata is returned by <tt class="docutils literal"><span class="pre">metadata_size()</span></tt>.</p>
1591 </div>
1592 </div>
1593 <div class="section">
1594 <h1><a id="torrent-handle" name="torrent-handle">torrent_handle</a></h1>
1595 <p>You will usually have to store your torrent handles somewhere, since it's the
1596 object through which you retrieve information about the torrent and aborts the torrent.
1597 Its declaration looks like this:</p>
1598 <pre class="literal-block">
1599 struct torrent_handle
1600 {
1601         torrent_handle();
1602
1603         torrent_status status();
1604         void file_progress(std::vector&lt;size_type&gt;&amp; fp);
1605         void get_download_queue(std::vector&lt;partial_piece_info&gt;&amp; queue) const;
1606         void get_peer_info(std::vector&lt;peer_info&gt;&amp; v) const;
1607         torrent_info const&amp; get_torrent_info() const;
1608         bool is_valid() const;
1609
1610         std::string name() const;
1611
1612         void save_resume_data() const;
1613         void force_reannounce() const;
1614         void force_reannounce(boost::posix_time::time_duration) const;
1615         void scrape_tracker() const;
1616         void connect_peer(asio::ip::tcp::endpoint const&amp; adr, int source = 0) const;
1617
1618         void set_tracker_login(std::string const&amp; username
1619                 , std::string const&amp; password) const;
1620
1621         std::vector&lt;announce_entry&gt; const&amp; trackers() const;
1622         void replace_trackers(std::vector&lt;announce_entry&gt; const&amp;);
1623
1624         void add_url_seed(std::string const&amp; url);
1625         void remove_url_seed(std::string const&amp; url);
1626         std::set&lt;std::string&gt; url_seeds() const;
1627
1628         void set_ratio(float ratio) const;
1629         void set_max_uploads(int max_uploads) const;
1630         void set_max_connections(int max_connections) const;
1631         void set_upload_limit(int limit) const;
1632         int upload_limit() const;
1633         void set_download_limit(int limit) const;
1634         int download_limit() const;
1635         void set_sequential_download(bool sd) const;
1636         bool is_sequential_download() const;
1637
1638         void set_peer_upload_limit(asio::ip::tcp::endpoint ip, int limit) const;
1639         void set_peer_download_limit(asio::ip::tcp::endpoint ip, int limit) const;
1640
1641         int queue_position() const;
1642         void queue_position_up() const;
1643         void queue_position_down() const;
1644         void queue_position_top() const;
1645         void queue_position_bottom() const;
1646
1647         void use_interface(char const* net_interface) const;
1648
1649         void pause() const;
1650         void resume() const;
1651         bool is_paused() const;
1652         bool is_seed() const;
1653         void force_recheck() const;
1654         void clear_error() const;
1655
1656         void resolve_countries(bool r);
1657         bool resolve_countries() const;
1658
1659         void piece_priority(int index, int priority) const;
1660         int piece_priority(int index) const;
1661
1662         void prioritize_pieces(std::vector&lt;int&gt; const&amp; pieces) const;
1663         std::vector&lt;int&gt; piece_priorities() const;
1664
1665         void prioritize_files(std::vector&lt;int&gt; const&amp; files) const;
1666
1667         bool is_auto_managed() const;
1668         void auto_managed(bool m) const;
1669
1670         bool has_metadata() const;
1671
1672         boost::filesystem::path save_path() const;
1673         void move_storage(boost::filesystem::path const&amp; save_path) const;
1674
1675         sha1_hash info_hash() const;
1676
1677         bool operator==(torrent_handle const&amp;) const;
1678         bool operator!=(torrent_handle const&amp;) const;
1679         bool operator&lt;(torrent_handle const&amp;) const;
1680 };
1681 </pre>
1682 <p>The default constructor will initialize the handle to an invalid state. Which
1683 means you cannot perform any operation on it, unless you first assign it a
1684 valid handle. If you try to perform any operation on an uninitialized handle,
1685 it will throw <tt class="docutils literal"><span class="pre">invalid_handle</span></tt>.</p>
1686 <div class="warning">
1687 <p class="first admonition-title">Warning</p>
1688 <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>
1689 exception, in case the handle is no longer refering to a torrent. There is
1690 one exception <tt class="docutils literal"><span class="pre">is_valid()</span></tt> will never throw.
1691 Since the torrents are processed by a background thread, there is no
1692 guarantee that a handle will remain valid between two calls.</p>
1693 </div>
1694 <div class="section">
1695 <h2><a id="piece-priority-prioritize-pieces-piece-priorities-prioritize-files" name="piece-priority-prioritize-pieces-piece-priorities-prioritize-files">piece_priority() prioritize_pieces() piece_priorities() prioritize_files()</a></h2>
1696 <blockquote>
1697 <pre class="literal-block">
1698 void piece_priority(int index, int priority) const;
1699 int piece_priority(int index) const;
1700 void prioritize_pieces(std::vector&lt;int&gt; const&amp; pieces) const;
1701 std::vector&lt;int&gt; piece_priorities() const;
1702 void prioritize_files(std::vector&lt;int&gt; const&amp; files) const;
1703 </pre>
1704 </blockquote>
1705 <p>These functions are used to set and get the prioritiy of individual pieces.
1706 By default all pieces have priority 1. That means that the random rarest
1707 first algorithm is effectively active for all pieces. You may however
1708 change the priority of individual pieces. There are 8 different priority
1709 levels:</p>
1710 <blockquote>
1711 <ol class="arabic simple" start="0">
1712 <li>piece is not downloaded at all</li>
1713 <li>normal priority. Download order is dependent on availability</li>
1714 <li>higher than normal priority. Pieces are preferred over pieces with
1715 the same availability, but not over pieces with lower availability</li>
1716 <li>pieces are as likely to be picked as partial pieces.</li>
1717 <li>pieces are preferred over partial pieces, but not over pieces with
1718 lower availability</li>
1719 <li><em>currently the same as 4</em></li>
1720 <li>piece is as likely to be picked as any piece with availability 1</li>
1721 <li>maximum priority, availability is disregarded, the piece is preferred
1722 over any other piece with lower priority</li>
1723 </ol>
1724 </blockquote>
1725 <p>The exact definitions of these priorities are implementation details, and
1726 subject to change. The interface guarantees that higher number means higher
1727 priority, and that 0 means do not download.</p>
1728 <p><tt class="docutils literal"><span class="pre">piece_priority</span></tt> sets or gets the priority for an individual piece,
1729 specified by <tt class="docutils literal"><span class="pre">index</span></tt>.</p>
1730 <p><tt class="docutils literal"><span class="pre">prioritize_pieces</span></tt> takes a vector of integers, one integer per piece in
1731 the torrent. All the piece priorities will be updated with the priorities
1732 in the vector.</p>
1733 <p><tt class="docutils literal"><span class="pre">piece_priorities</span></tt> returns a vector with one element for each piece in the
1734 torrent. Each element is the current priority of that piece.</p>
1735 <p><tt class="docutils literal"><span class="pre">prioritize_files</span></tt> takes a vector that has at as many elements as there are
1736 files in the torrent. Each entry is the priority of that file. The function
1737 sets the priorities of all the pieces in the torrent based on the vector.</p>
1738 </div>
1739 <div class="section">
1740 <h2><a id="file-progress" name="file-progress">file_progress()</a></h2>
1741 <blockquote>
1742 <pre class="literal-block">
1743 void file_progress(std::vector&lt;size_type&gt;&amp; fp);
1744 </pre>
1745 </blockquote>
1746 <p>This function fills in the supplied vector with the the number of bytes downloaded
1747 of each file in this torrent. The progress values are ordered the same as the files
1748 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>.
1749 Where <em>n</em> is the number of files, <em>m</em> is the number of downloading pieces and <em>j</em>
1750 is the number of blocks in a piece.</p>
1751 </div>
1752 <div class="section">
1753 <h2><a id="save-path" name="save-path">save_path()</a></h2>
1754 <blockquote>
1755 <pre class="literal-block">
1756 boost::filesystem::path save_path() const;
1757 </pre>
1758 </blockquote>
1759 <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
1760 was started.</p>
1761 </div>
1762 <div class="section">
1763 <h2><a id="move-storage" name="move-storage">move_storage()</a></h2>
1764 <blockquote>
1765 <pre class="literal-block">
1766 void move_storage(boost::filesystem::path const&amp; save_path) const;
1767 </pre>
1768 </blockquote>
1769 <p>Moves the file(s) that this torrent are currently seeding from or downloading to. This
1770 operation will only have the desired effect if the given <tt class="docutils literal"><span class="pre">save_path</span></tt> is located on
1771 the same drive as the original save path. Since disk IO is performed in a separate
1772 thread, this operation is also asynchronous. Once the operation completes, the
1773 <tt class="docutils literal"><span class="pre">storage_moved_alert</span></tt> is generated, with the new path as the message.</p>
1774 </div>
1775 <div class="section">
1776 <h2><a id="force-reannounce" name="force-reannounce">force_reannounce()</a></h2>
1777 <blockquote>
1778 <pre class="literal-block">
1779 void force_reannounce() const;
1780 void force_reannounce(boost::posix_time::time_duration) const;
1781 </pre>
1782 </blockquote>
1783 <p><tt class="docutils literal"><span class="pre">force_reannounce()</span></tt> will force this torrent to do another tracker request, to receive new
1784 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
1785 argument will schedule a reannounce in that amount of time from now.</p>
1786 </div>
1787 <div class="section">
1788 <h2><a id="scrape-tracker" name="scrape-tracker">scrape_tracker()</a></h2>
1789 <blockquote>
1790 <pre class="literal-block">
1791 void scrape_tracker() const;
1792 </pre>
1793 </blockquote>
1794 <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
1795 tracker for statistics such as total number of incomplete peers, complete peers, number of
1796 downloads etc.</p>
1797 <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
1798 the <a class="reference" href="#torrent-status">torrent_status</a> struct once it completes. When it completes, it will generate a
1799 <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>
1800 </div>
1801 <div class="section">
1802 <h2><a id="connect-peer" name="connect-peer">connect_peer()</a></h2>
1803 <blockquote>
1804 <pre class="literal-block">
1805 void connect_peer(asio::ip::tcp::endpoint const&amp; adr, int source = 0) const;
1806 </pre>
1807 </blockquote>
1808 <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
1809 torrent. If the peer does not respond, or is not a member of this torrent, it will simply
1810 be disconnected. No harm can be done by using this other than an unnecessary connection
1811 attempt is made. If the torrent is uninitialized or in queued or checking mode, this
1812 will throw <a class="reference" href="#invalid-handle">invalid_handle</a>. The second (optional) argument will be bitwised ORed into
1813 the source mask of this peer. Typically this is one of the source flags in <a class="reference" href="#peer-info">peer_info</a>.
1814 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>
1815 </div>
1816 <div class="section">
1817 <h2><a id="name" name="name">name()</a></h2>
1818 <blockquote>
1819 <pre class="literal-block">
1820 std::string name() const;
1821 </pre>
1822 </blockquote>
1823 <p>Returns the name of the torrent. i.e. the name from the metadata associated with it. In
1824 case the torrent was started without metadata, and hasn't completely received it yet,
1825 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>
1826 </div>
1827 <div class="section">
1828 <h2><a id="set-ratio" name="set-ratio">set_ratio()</a></h2>
1829 <blockquote>
1830 <pre class="literal-block">
1831 void set_ratio(float ratio) const;
1832 </pre>
1833 </blockquote>
1834 <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
1835 infinite. i.e. the client will always upload as much as it can, no matter how much it gets back
1836 in return. With this setting it will work much like the standard clients.</p>
1837 <p>Besides 0, the ratio can be set to any number greater than or equal to 1. It means how much to
1838 attempt to upload in return for each download. e.g. if set to 2, the client will try to upload
1839 2 bytes for every byte received. The default setting for this is 0, which will make it work
1840 as a standard client.</p>
1841 </div>
1842 <div class="section">
1843 <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>
1844 <blockquote>
1845 <pre class="literal-block">
1846 void set_upload_limit(int limit) const;
1847 void set_download_limit(int limit) const;
1848 int upload_limit() const;
1849 int download_limit() const;
1850 </pre>
1851 </blockquote>
1852 <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
1853 limit you set. It is given as the number of bytes per second the torrent is allowed to upload.
1854 <tt class="docutils literal"><span class="pre">set_download_limit</span></tt> works the same way but for download bandwidth instead of upload bandwidth.
1855 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>)
1856 will not override the global rate limit. The torrent can never upload more than the global rate
1857 limit.</p>
1858 <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
1859 download, respectively.</p>
1860 </div>
1861 <div class="section">
1862 <h2><a id="set-sequential-download-is-sequential-download" name="set-sequential-download-is-sequential-download">set_sequential_download() is_sequential_download()</a></h2>
1863 <blockquote>
1864 <pre class="literal-block">
1865 void set_sequential_download(bool sd);
1866 bool is_sequential_download() const;
1867 </pre>
1868 </blockquote>
1869 <p><tt class="docutils literal"><span class="pre">set_sequential_download()</span></tt> enables or disables <em>sequential download</em>. When enabled, the piece
1870 picker will pick pieces in sequence instead of rarest first.</p>
1871 <p>Enabling sequential download will affect the piece distribution negatively in the swarm. It should be
1872 used sparingly.</p>
1873 <p><tt class="docutils literal"><span class="pre">is_sequential_download()</span></tt> returns true if this torrent is downloading in sequence, and false
1874 otherwise.</p>
1875 </div>
1876 <div class="section">
1877 <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>
1878 <blockquote>
1879 <pre class="literal-block">
1880 void set_peer_upload_limit(asio::ip::tcp::endpoint ip, int limit) const;
1881 void set_peer_download_limit(asio::ip::tcp::endpoint ip, int limit) const;
1882 </pre>
1883 </blockquote>
1884 <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
1885 peer instead of the whole torrent.</p>
1886 </div>
1887 <div class="section">
1888 <h2><a id="id5" name="id5">pause() resume() is_paused()</a></h2>
1889 <blockquote>
1890 <pre class="literal-block">
1891 void pause() const;
1892 void resume() const;
1893 bool is_paused() const;
1894 </pre>
1895 </blockquote>
1896 <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.
1897 When a torrent is paused, it will however remember all share ratios to all peers and remember
1898 all potential (not connected) peers. You can use <tt class="docutils literal"><span class="pre">is_paused()</span></tt> to determine if a torrent
1899 is currently paused. Torrents may be paused automatically if there is a file error (e.g. disk full)
1900 or something similar. See <a class="reference" href="#file-error-alert">file_error_alert</a>.</p>
1901 </div>
1902 <div class="section">
1903 <h2><a id="force-recheck" name="force-recheck">force_recheck()</a></h2>
1904 <blockquote>
1905 <pre class="literal-block">
1906 void force_recheck() const;
1907 </pre>
1908 </blockquote>
1909 <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.
1910 All peers will be disconnected and the torrent will stop announcing to the tracker. The torrent
1911 will be added to the checking queue, and will be checked (all the files will be read and
1912 compared to the piece hashes). Once the check is complete, the torrent will start connecting
1913 to peers again, as normal.</p>
1914 </div>
1915 <div class="section">
1916 <h2><a id="clear-error" name="clear-error">clear_error()</a></h2>
1917 <blockquote>
1918 <pre class="literal-block">
1919 void clear_error() const;
1920 </pre>
1921 </blockquote>
1922 <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
1923 will clear the error and start the torrent again.</p>
1924 </div>
1925 <div class="section">
1926 <h2><a id="resolve-countries" name="resolve-countries">resolve_countries()</a></h2>
1927 <blockquote>
1928 <pre class="literal-block">
1929 void resolve_countries(bool r);
1930 bool resolve_countries() const;
1931 </pre>
1932 </blockquote>
1933 <p>Sets or gets the flag that derermines if countries should be resolved for the peers of this
1934 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
1935 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
1936 on how to interpret this field.</p>
1937 </div>
1938 <div class="section">
1939 <h2><a id="is-seed" name="is-seed">is_seed()</a></h2>
1940 <blockquote>
1941 <pre class="literal-block">
1942 bool is_seed() const;
1943 </pre>
1944 </blockquote>
1945 <p>Returns true if the torrent is in seed mode (i.e. if it has finished downloading).</p>
1946 </div>
1947 <div class="section">
1948 <h2><a id="is-auto-managed-auto-managed" name="is-auto-managed-auto-managed">is_auto_managed() auto_managed()</a></h2>
1949 <blockquote>
1950 <pre class="literal-block">
1951 bool is_auto_managed() const;
1952 void auto_managed(bool m) const;
1953 </pre>
1954 </blockquote>
1955 <p><tt class="docutils literal"><span class="pre">is_auto_managed()</span></tt> returns true if this torrent is currently <em>auto managed</em>.
1956 <tt class="docutils literal"><span class="pre">auto_managed()</span></tt> changes whether the torrent is auto managed or not. For more info,
1957 see <a class="reference" href="#queuing">queuing</a>.</p>
1958 </div>
1959 <div class="section">
1960 <h2><a id="has-metadata" name="has-metadata">has_metadata()</a></h2>
1961 <blockquote>
1962 <pre class="literal-block">
1963 bool has_metadata() const;
1964 </pre>
1965 </blockquote>
1966 <p>Returns true if this torrent has metadata (either it was started from a .torrent file or the
1967 metadata has been downloaded). The only scenario where this can return false is when the torrent
1968 was started torrent-less (i.e. with just an info-hash and tracker ip). Note that if the torrent
1969 doesn't have metadata, the member <a class="reference" href="#get-torrent-info">get_torrent_info()</a> will throw.</p>
1970 </div>
1971 <div class="section">
1972 <h2><a id="set-tracker-login" name="set-tracker-login">set_tracker_login()</a></h2>
1973 <blockquote>
1974 <pre class="literal-block">
1975 void set_tracker_login(std::string const&amp; username
1976         , std::string const&amp; password) const;
1977 </pre>
1978 </blockquote>
1979 <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
1980 of the tracker announce. Set this if the tracker requires authorization.</p>
1981 </div>
1982 <div class="section">
1983 <h2><a id="trackers-replace-trackers" name="trackers-replace-trackers">trackers() replace_trackers()</a></h2>
1984 <blockquote>
1985 <pre class="literal-block">
1986 std::vector&lt;announce_entry&gt; const&amp; trackers() const;
1987 void replace_trackers(std::vector&lt;announce_entry&gt; const&amp;) const;
1988 </pre>
1989 </blockquote>
1990 <p><tt class="docutils literal"><span class="pre">trackers()</span></tt> will return the list of trackers for this torrent. The
1991 announce entry contains both a string <tt class="docutils literal"><span class="pre">url</span></tt> which specify the announce url
1992 for the tracker as well as an int <tt class="docutils literal"><span class="pre">tier</span></tt>, which is specifies the order in
1993 which this tracker is tried. If you want libtorrent to use another list of
1994 trackers for this torrent, you can use <tt class="docutils literal"><span class="pre">replace_trackers()</span></tt> which takes
1995 a list of the same form as the one returned from <tt class="docutils literal"><span class="pre">trackers()</span></tt> and will
1996 replace it. If you want an immediate effect, you have to call
1997 <a class="reference" href="#force-reannounce">force_reannounce()</a>.</p>
1998 </div>
1999 <div class="section">
2000 <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>
2001 <blockquote>
2002 <pre class="literal-block">
2003 void add_url_seed(std::string const&amp; url);
2004 void remove_url_seed(std::string const&amp; url);
2005 std::set&lt;std::string&gt; url_seeds() const;
2006 </pre>
2007 </blockquote>
2008 <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
2009 given url already exists in that list, the call has no effect. The torrent
2010 will connect to the server and try to download pieces from it, unless it's
2011 paused, queued, checking or seeding. <tt class="docutils literal"><span class="pre">remove_url_seed()</span></tt> removes the given
2012 url if it exists already. <tt class="docutils literal"><span class="pre">url_seeds()</span></tt> return a set of the url seeds
2013 currently in this torrent. Note that urls that fails may be removed
2014 automatically from the list.</p>
2015 <p>See <a class="reference" href="#http-seeding">HTTP seeding</a> for more information.</p>
2016 </div>
2017 <div class="section">
2018 <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>
2019 <blockquote>
2020 <pre class="literal-block">
2021 int queue_position() const;
2022 void queue_position_up() const;
2023 void queue_position_down() const;
2024 void queue_position_top() const;
2025 void queue_position_bottom() const;
2026 </pre>
2027 </blockquote>
2028 <p>Every torrent that is added is assigned a queue position exactly one greater than
2029 the greatest queue position of all existing torrents. Torrents that are being
2030 seeded have -1 as their queue position, since they're no longer in line to be downloaded.</p>
2031 <p>When a torrent is removed or turns into a seed, all torrents with greater queue positions
2032 have their positions decreased to fill in the space in the sequence.</p>
2033 <p><tt class="docutils literal"><span class="pre">queue_position()</span></tt> returns the torrent's position in the download queue. The torrents
2034 with the smallest numbers are the ones that are being downloaded. The smaller number,
2035 the closer the torrent is to the front of the line to be started.</p>
2036 <p>The <tt class="docutils literal"><span class="pre">queue_position_*()</span></tt> functions adjust the torrents position in the queue. Up means
2037 closer to the front and down means closer to the back of the queue. Top and bottom refers
2038 to the front and the back of the queue respectively.</p>
2039 </div>
2040 <div class="section">
2041 <h2><a id="use-interface" name="use-interface">use_interface()</a></h2>
2042 <blockquote>
2043 <pre class="literal-block">
2044 void use_interface(char const* net_interface) const;
2045 </pre>
2046 </blockquote>
2047 <p><tt class="docutils literal"><span class="pre">use_interface()</span></tt> sets the network interface this torrent will use when it opens outgoing
2048 connections. By default, it uses the same interface as the <a class="reference" href="#session">session</a> uses to listen on. The
2049 parameter must be a string containing an ip-address (either an IPv4 or IPv6 address). If
2050 the string does not conform to this format and exception is thrown.</p>
2051 </div>
2052 <div class="section">
2053 <h2><a id="info-hash" name="info-hash">info_hash()</a></h2>
2054 <blockquote>
2055 <pre class="literal-block">
2056 sha1_hash info_hash() const;
2057 </pre>
2058 </blockquote>
2059 <p><tt class="docutils literal"><span class="pre">info_hash()</span></tt> returns the info-hash for the torrent.</p>
2060 </div>
2061 <div class="section">
2062 <h2><a id="id6" name="id6">set_max_uploads() set_max_connections()</a></h2>
2063 <blockquote>
2064 <pre class="literal-block">
2065 void set_max_uploads(int max_uploads) const;
2066 void set_max_connections(int max_connections) const;
2067 </pre>
2068 </blockquote>
2069 <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
2070 torrent. If you set this to -1, there will be no limit.</p>
2071 <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
2072 connections are used up, incoming connections may be refused or poor connections may be closed.
2073 This must be at least 2. The default is unlimited number of connections. If -1 is given to the
2074 function, it means unlimited.</p>
2075 </div>
2076 <div class="section">
2077 <h2><a id="save-resume-data" name="save-resume-data">save_resume_data()</a></h2>
2078 <blockquote>
2079 <pre class="literal-block">
2080 void save_resume_data() const;
2081 </pre>
2082 </blockquote>
2083 <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>
2084 is suitable for being bencoded. For more information about how fast-resume works, see <a class="reference" href="#fast-resume">fast resume</a>.</p>
2085 <p>This operation is asynchronous, <tt class="docutils literal"><span class="pre">save_resume_data</span></tt> will return immediately. The resume data
2086 is delivered when it's done through an <a class="reference" href="#save-resume-data-alert">save_resume_data_alert</a>.</p>
2087 <p>The fast resume data will be empty in the following cases:</p>
2088 <blockquote>
2089 <ol class="arabic simple">
2090 <li>The torrent handle is invalid.</li>
2091 <li>The torrent is checking (or is queued for checking) its storage, it will obviously
2092 not be ready to write resume data.</li>
2093 <li>The torrent hasn't received valid metadata and was started without metadata
2094 (see libtorrent's <a class="reference" href="#metadata-from-peers">metadata from peers</a> extension)</li>
2095 </ol>
2096 </blockquote>
2097 <p>Note that by the time you receive the fast resume data, it may already be invalid if the torrent
2098 is still downloading! The recommended practice is to first pause the torrent, then generate the
2099 fast resume data, and then close it down. Make sure to not <a class="reference" href="#remove-torrent">remove_torrent()</a> before you receive
2100 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
2101 if you will remove the torrent afterwards. There's no need to pause when saving intermittent
2102 resume data.</p>
2103 <p>In full allocation mode the reume data is never invalidated by subsequent
2104 writes to the files, since pieces won't move around. This means that you don't need to
2105 pause before writing resume data in full or sparse mode. If you don't, however, any data written to
2106 disk after you saved resume data and before the <a class="reference" href="#session">session</a> closed is lost.</p>
2107 <p>It also means that if the resume data is out dated, libtorrent will not re-check the files, but assume
2108 that it is fairly recent. The assumption is that it's better to loose a little bit than to re-check
2109 the entire file.</p>
2110 <p>It is still a good idea to save resume data periodically during download as well as when
2111 closing down.</p>
2112 <p>Example code to pause and save resume data for all torrents and wait for the alerts:</p>
2113 <pre class="literal-block">
2114 int num_resume_data = 0;
2115 std::vector&lt;torrent_handle&gt; handles = ses.get_torrents();
2116 for (std::vector&lt;torrent_handle&gt;::iterator i = handles.begin();
2117         i != handles.end(); ++i)
2118 {
2119         torrent_handle&amp; h = *i;
2120         if (!h.has_metadata()) continue;
2121
2122         h.pause();
2123         h.save_resume_data();
2124         ++num_resume_data;
2125 }
2126
2127 while (num_resume_data &gt; 0)
2128 {
2129         alert const* a = ses.wait_for_alert(seconds(10));
2130
2131         // if we don't get an alert within 10 seconds, abort
2132         if (a == 0) break;
2133
2134         std::auto_ptr&lt;alert&gt; holder = ses.pop_alert();
2135         save_resume_data_alert const* rd = dynamic_cast&lt;save_resume_data_alert const*&gt;(a);
2136         if (rd == 0)
2137         {
2138                 process_alert(a);
2139                 continue;
2140         }
2141
2142         torrent_handle h = rd-&gt;handle;
2143         boost::filesystem::ofstream out(h.save_path()
2144                 / (h.get_torrent_info().name() + &quot;.fastresume&quot;), std::ios_base::binary);
2145         out.unsetf(std::ios_base::skipws);
2146         bencode(std::ostream_iterator&lt;char&gt;(out), *rd-&gt;resume_data);
2147         --num_resume_data;
2148 }
2149 </pre>
2150 </div>
2151 <div class="section">
2152 <h2><a id="id7" name="id7">status()</a></h2>
2153 <blockquote>
2154 <pre class="literal-block">
2155 torrent_status status() const;
2156 </pre>
2157 </blockquote>
2158 <p><tt class="docutils literal"><span class="pre">status()</span></tt> will return a structure with information about the status of this
2159 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.
2160 See <a class="reference" href="#torrent-status">torrent_status</a>.</p>
2161 </div>
2162 <div class="section">
2163 <h2><a id="get-download-queue" name="get-download-queue">get_download_queue()</a></h2>
2164 <blockquote>
2165 <pre class="literal-block">
2166 void get_download_queue(std::vector&lt;partial_piece_info&gt;&amp; queue) const;
2167 </pre>
2168 </blockquote>
2169 <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
2170 information about pieces that are partially downloaded or not downloaded at all but partially
2171 requested. The entry in the vector (<tt class="docutils literal"><span class="pre">partial_piece_info</span></tt>) looks like this:</p>
2172 <pre class="literal-block">
2173 struct partial_piece_info
2174 {
2175         int piece_index;
2176         int blocks_in_piece;
2177         block_info blocks[256];
2178         enum state_t { none, slow, medium, fast };
2179         state_t piece_state;
2180 };
2181 </pre>
2182 <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
2183 number of blocks in this particular piece. This number will be the same for most pieces, but
2184 the last piece may have fewer blocks than the standard pieces.</p>
2185 <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
2186 download rate category the peers downloading this piece falls into. <tt class="docutils literal"><span class="pre">none</span></tt> means that no
2187 peer is currently downloading any part of the piece. Peers prefer picking pieces from
2188 the same category as themselves. The reason for this is to keep the number of partially
2189 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>,
2190 <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>
2191 <pre class="literal-block">
2192 struct block_info
2193 {
2194         enum block_state_t
2195         { none, requested, writing, finished };
2196
2197         tcp::endpoint peer;
2198         unsigned state:2;
2199         unsigned num_peers:14;
2200 };
2201 </pre>
2202 <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
2203 a state (<tt class="docutils literal"><span class="pre">state</span></tt>) which is any of:</p>
2204 <ul class="simple">
2205 <li><tt class="docutils literal"><span class="pre">none</span></tt> - This block has not been downloaded or requested form any peer.</li>
2206 <li><tt class="docutils literal"><span class="pre">requested</span></tt> - The block has been requested, but not completely downloaded yet.</li>
2207 <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>
2208 <li><tt class="docutils literal"><span class="pre">finished</span></tt> - The block has been written to disk.</li>
2209 </ul>
2210 <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.
2211 <tt class="docutils literal"><span class="pre">num_peers</span></tt> is the number of peers that is currently requesting this block. Typically this
2212 is 0 or 1, but at the end of the torrent blocks may be requested by more peers in parallel to
2213 speed things up.</p>
2214 </div>
2215 <div class="section">
2216 <h2><a id="get-peer-info" name="get-peer-info">get_peer_info()</a></h2>
2217 <blockquote>
2218 <pre class="literal-block">
2219 void get_peer_info(std::vector&lt;peer_info&gt;&amp;) const;
2220 </pre>
2221 </blockquote>
2222 <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
2223 with one entry for each peer connected to this torrent, given the handle is valid. If the
2224 <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
2225 the vector contains information about that particular peer. See <a class="reference" href="#peer-info">peer_info</a>.</p>
2226 </div>
2227 <div class="section">
2228 <h2><a id="get-torrent-info" name="get-torrent-info">get_torrent_info()</a></h2>
2229 <blockquote>
2230 <pre class="literal-block">
2231 torrent_info const&amp; get_torrent_info() const;
2232 </pre>
2233 </blockquote>
2234 <p>Returns a const reference to the <a class="reference" href="#torrent-info">torrent_info</a> object associated with this torrent.
2235 This reference is valid as long as the <a class="reference" href="#torrent-handle">torrent_handle</a> is valid, no longer. If the
2236 <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>
2237 exception will be thrown. The torrent may be in a state without metadata only if
2238 it was started without a .torrent file, i.e. by using the libtorrent extension of
2239 just supplying a tracker and info-hash.</p>
2240 </div>
2241 <div class="section">
2242 <h2><a id="is-valid" name="is-valid">is_valid()</a></h2>
2243 <blockquote>
2244 <pre class="literal-block">
2245 bool is_valid() const;
2246 </pre>
2247 </blockquote>
2248 <p>Returns true if this handle refers to a valid torrent and false if it hasn't been initialized
2249 or if the torrent it refers to has been aborted. Note that a handle may become invalid after
2250 it has been added to the session. Usually this is because the storage for the torrent is
2251 somehow invalid or if the filenames are not allowed (and hence cannot be opened/created) on
2252 your filesystem. If such an error occurs, a <a class="reference" href="#file-error-alert">file_error_alert</a> is generated and all handles
2253 that refers to that torrent will become invalid.</p>
2254 </div>
2255 </div>
2256 <div class="section">
2257 <h1><a id="torrent-status" name="torrent-status">torrent_status</a></h1>
2258 <p>It contains the following fields:</p>
2259 <pre class="literal-block">
2260 struct torrent_status
2261 {
2262         enum state_t
2263         {
2264                 queued_for_checking,
2265                 checking_files,
2266                 connecting_to_tracker,
2267                 downloading_metadata,
2268                 downloading,
2269                 finished,
2270                 seeding,
2271                 allocating
2272         };
2273
2274         state_t state;
2275         bool paused;
2276         float progress;
2277         std::string error;
2278
2279         boost::posix_time::time_duration next_announce;
2280         boost::posix_time::time_duration announce_interval;
2281
2282         std::string current_tracker;
2283
2284         size_type total_download;
2285         size_type total_upload;
2286
2287         size_type total_payload_download;
2288         size_type total_payload_upload;
2289
2290         size_type total_failed_bytes;
2291         size_type total_redundant_bytes;
2292
2293         float download_rate;
2294         float upload_rate;
2295
2296         float download_payload_rate;
2297         float upload_payload_rate;
2298
2299         int num_peers;
2300
2301         int num_complete;
2302         int num_incomplete;
2303
2304         int list_seeds;
2305         int list_peers;
2306
2307         int connect_candidates;
2308
2309         bitfield pieces;
2310         int num_pieces;
2311
2312         size_type total_done;
2313         size_type total_wanted_done;
2314         size_type total_wanted;
2315
2316         int num_seeds;
2317         float distributed_copies;
2318
2319         int block_size;
2320
2321         int num_uploads;
2322         int num_connections;
2323         int uploads_limit;
2324         int connections_limit;
2325
2326         storage_mode_t storage_mode;
2327
2328         int up_bandwidth_queue;
2329         int down_bandwidth_queue;
2330
2331         size_type all_time_upload;
2332         size_type all_time_download;
2333
2334         int active_time;
2335         int seeding_time;
2336
2337         int seed_rank;
2338
2339         int last_scrape;
2340
2341         bool has_incoming;
2342 };
2343 </pre>
2344 <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
2345 torrent's current task. It may be checking files or downloading. The torrent's
2346 current task is in the <tt class="docutils literal"><span class="pre">state</span></tt> member, it will be one of the following:</p>
2347 <table border="1" class="docutils">
2348 <colgroup>
2349 <col width="31%" />
2350 <col width="69%" />
2351 </colgroup>
2352 <tbody valign="top">
2353 <tr><td><tt class="docutils literal"><span class="pre">queued_for_checking</span></tt></td>
2354 <td>The torrent is in the queue for being checked. But there
2355 currently is another torrent that are being checked.
2356 This torrent will wait for its turn.</td>
2357 </tr>
2358 <tr><td><tt class="docutils literal"><span class="pre">checking_files</span></tt></td>
2359 <td>The torrent has not started its download yet, and is
2360 currently checking existing files.</td>
2361 </tr>
2362 <tr><td><tt class="docutils literal"><span class="pre">connecting_to_tracker</span></tt></td>
2363 <td>The torrent has sent a request to the tracker and is
2364 currently waiting for a response</td>
2365 </tr>
2366 <tr><td><tt class="docutils literal"><span class="pre">downloading_metadata</span></tt></td>
2367 <td>The torrent is trying to download metadata from peers.
2368 This assumes the metadata_transfer extension is in use.</td>
2369 </tr>
2370 <tr><td><tt class="docutils literal"><span class="pre">downloading</span></tt></td>
2371 <td>The torrent is being downloaded. This is the state
2372 most torrents will be in most of the time. The progress
2373 meter will tell how much of the files that has been
2374 downloaded.</td>
2375 </tr>
2376 <tr><td><tt class="docutils literal"><span class="pre">finished</span></tt></td>
2377 <td>In this state the torrent has finished downloading but
2378 still doesn't have the entire torrent. i.e. some pieces
2379 are filtered and won't get downloaded.</td>
2380 </tr>
2381 <tr><td><tt class="docutils literal"><span class="pre">seeding</span></tt></td>
2382 <td>In this state the torrent has finished downloading and
2383 is a pure seeder.</td>
2384 </tr>
2385 <tr><td><tt class="docutils literal"><span class="pre">allocating</span></tt></td>
2386 <td>If the torrent was started in full allocation mode, this
2387 indicates that the (disk) storage for the torrent is
2388 allocated.</td>
2389 </tr>
2390 </tbody>
2391 </table>
2392 <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>
2393 <p><tt class="docutils literal"><span class="pre">paused</span></tt> is set to true if the torrent is paused and false otherwise.</p>
2394 <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
2395 case it was paused by an error. If the torrent is not paused or if it's paused but
2396 not because of an error, this string is empty.</p>
2397 <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
2398 <tt class="docutils literal"><span class="pre">announce_interval</span></tt> is the time the tracker want us to wait until we announce ourself
2399 again the next time.</p>
2400 <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
2401 been successful yet, it's set to an empty string.</p>
2402 <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
2403 uploaded to all peers, accumulated, <em>this session</em> only.</p>
2404 <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
2405 send and received this session, but only the actual payload data (i.e the interesting
2406 data), these counters ignore any protocol overhead.</p>
2407 <p><tt class="docutils literal"><span class="pre">total_failed_bytes</span></tt> is the number of bytes that has been downloaded and that
2408 has failed the piece hash test. In other words, this is just how much crap that
2409 has been downloaded.</p>
2410 <p><tt class="docutils literal"><span class="pre">total_redundant_bytes</span></tt> is the number of bytes that has been downloaded even
2411 though that data already was downloaded. The reason for this is that in some
2412 situations the same data can be downloaded by mistake. When libtorrent sends
2413 requests to a peer, and the peer doesn't send a response within a certain
2414 timeout, libtorrent will re-request that block. Another situation when
2415 libtorrent may re-request blocks is when the requests it sends out are not
2416 replied in FIFO-order (it will re-request blocks that are skipped by an out of
2417 order block). This is supposed to be as low as possible.</p>
2418 <p><tt class="docutils literal"><span class="pre">pieces</span></tt> is the bitmask that represents which pieces we have (set to true) and
2419 the pieces we don't have. It's a pointer and may be set to 0 if the torrent isn't
2420 downloading or seeding.</p>
2421 <p><tt class="docutils literal"><span class="pre">num_pieces</span></tt> is the number of pieces that has been downloaded. It is equivalent
2422 to: <tt class="docutils literal"><span class="pre">std::accumulate(pieces-&gt;begin(),</span> <span class="pre">pieces-&gt;end())</span></tt>. So you don't have to
2423 count yourself. This can be used to see if anything has updated since last time
2424 if you want to keep a graph of the pieces up to date.</p>
2425 <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
2426 torrent. These will usually have better precision than summing the rates from
2427 all peers. The rates are given as the number of bytes per second. The
2428 <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
2429 total transfer rate of payload only, not counting protocol chatter. This might
2430 be slightly smaller than the other rates, but if projected over a long time
2431 (e.g. when calculating ETA:s) the difference may be noticeable.</p>
2432 <p><tt class="docutils literal"><span class="pre">num_peers</span></tt> is the number of peers this torrent currently is connected to.
2433 Peer connections that are in the half-open state (is attempting to connect)
2434 or are queued for later connection attempt do not count. Although they are
2435 visible in the peer list when you call <a class="reference" href="#get-peer-info">get_peer_info()</a>.</p>
2436 <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
2437 send any scrape data in its announce reply. This data is optional and may
2438 not be available from all trackers. If these are not -1, they are the total
2439 number of peers that are seeding (complete) and the total number of peers
2440 that are still downloading (incomplete) this torrent.</p>
2441 <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
2442 and the total number of peers (including seeds) respectively. We are not
2443 necessarily connected to all the peers in our peer list. This is the number
2444 of peers we know of in total, including banned peers and peers that we have
2445 failed to connect to.</p>
2446 <p><tt class="docutils literal"><span class="pre">connect_candidates</span></tt> is the number of peers in this torrent's peer list
2447 that is a candidate to be connected to. i.e. It has fewer connect attempts
2448 than the max fail count, it is not a seed if we are a seed, it is not banned
2449 etc. If this is 0, it means we don't know of any more peers that we can try.</p>
2450 <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
2451 this does not necessarily has to be downloaded during this session (that's
2452 <tt class="docutils literal"><span class="pre">total_payload_download</span></tt>).</p>
2453 <p><tt class="docutils literal"><span class="pre">total_wanted_done</span></tt> is the number of bytes we have downloaded, only counting the
2454 pieces that we actually want to download. i.e. excluding any pieces that we have but
2455 are filtered as not wanted.</p>
2456 <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
2457 excluding pieces that have been filtered.</p>
2458 <p><tt class="docutils literal"><span class="pre">num_seeds</span></tt> is the number of peers that are seeding that this client is
2459 currently connected to.</p>
2460 <p><tt class="docutils literal"><span class="pre">distributed_copies</span></tt> is the number of distributed copies of the torrent.
2461 Note that one copy may be spread out among many peers. The integer part
2462 tells how many copies there are currently of the rarest piece(s) among the
2463 peers this client is connected to. The fractional part tells the share of
2464 pieces that have more copies than the rarest piece(s). For example: 2.5 would
2465 mean that the rarest pieces have only 2 copies among the peers this torrent is
2466 connected to, and that 50% of all the pieces have more than two copies.</p>
2467 <p>If we are a seed, the piece picker is deallocated as an optimization, and
2468 piece availability is no longer tracked. In this case the distributed
2469 copies is set to -1.</p>
2470 <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
2471 is the number of bytes that each piece request asks for and the number of
2472 bytes that each bit in the <tt class="docutils literal"><span class="pre">partial_piece_info</span></tt>'s bitset represents
2473 (see <a class="reference" href="#get-download-queue">get_download_queue()</a>). This is typically 16 kB, but it may be
2474 larger if the pieces are larger.</p>
2475 <p><tt class="docutils literal"><span class="pre">num_uploads</span></tt> is the number of unchoked peers in this torrent.</p>
2476 <p><tt class="docutils literal"><span class="pre">num_connections</span></tt> is the number of peer connections this torrent has, including
2477 half-open connections that hasn't completed the bittorrent handshake yet. This is
2478 always &lt;= <tt class="docutils literal"><span class="pre">num_peers</span></tt>.</p>
2479 <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>
2480 <p><tt class="docutils literal"><span class="pre">connections_limit</span></tt> is the set limit of number of connections for this torrent.</p>
2481 <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
2482 <tt class="docutils literal"><span class="pre">storage_mode_compact</span></tt>. Identifies which storage mode this torrent is being saved
2483 with. See <a class="reference" href="#storage-allocation">Storage allocation</a>.</p>
2484 <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
2485 torrent that are waiting for more bandwidth quota from the torrent rate limiter.
2486 This can determine if the rate you get from this torrent is bound by the torrents
2487 limit or not. If there is no limit set on this torrent, the peers might still be
2488 waiting for bandwidth quota from the global limiter, but then they are counted in
2489 the <tt class="docutils literal"><span class="pre">session_status</span></tt> object.</p>
2490 <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
2491 byte counters. They are saved in and restored from resume data to keep totals
2492 across sessions.</p>
2493 <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
2494 number of seconds this torrent has been active (not paused) and the number of
2495 seconds it has been active while being a seed. <tt class="docutils literal"><span class="pre">seeding_time</span></tt> should be &gt;=
2496 <tt class="docutils literal"><span class="pre">active_time</span></tt> They are saved in and restored from resume data, to keep totals
2497 across sessions.</p>
2498 <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
2499 to determine which torrents to seed and which to queue. It is based on the peer
2500 to seed ratio from the tracker scrape. For more information, see <a class="reference" href="#queuing">queuing</a>.</p>
2501 <p><tt class="docutils literal"><span class="pre">last_scrape</span></tt> is the number of seconds since this torrent acquired scrape data.
2502 If it has never done that, this value is -1.</p>
2503 <p><tt class="docutils literal"><span class="pre">has_incoming</span></tt> is true if there has ever been an incoming connection attempt
2504 to this torrent.'</p>
2505 </div>
2506 <div class="section">
2507 <h1><a id="peer-info" name="peer-info">peer_info</a></h1>
2508 <p>It contains the following fields:</p>
2509 <pre class="literal-block">
2510 struct peer_info
2511 {
2512         enum
2513         {
2514                 interesting = 0x1,
2515                 choked = 0x2,
2516                 remote_interested = 0x4,
2517                 remote_choked = 0x8,
2518                 supports_extensions = 0x10,
2519                 local_connection = 0x20,
2520                 handshake = 0x40,
2521                 connecting = 0x80,
2522                 queued = 0x100,
2523                 on_parole = 0x200,
2524                 seed = 0x400,
2525                 optimistic_unchoke = 0x800,
2526                 snubbed = 0x1000,
2527                 upload_only = 0x2000,
2528                 rc4_encrypted = 0x100000,
2529                 plaintext_encrypted = 0x200000
2530         };
2531
2532         unsigned int flags;
2533
2534         enum peer_source_flags
2535         {
2536                 tracker = 0x1,
2537                 dht = 0x2,
2538                 pex = 0x4,
2539                 lsd = 0x8
2540         };
2541
2542         int source;
2543
2544         enum bw_state { bw_idle, bw_torrent, bw_global, bw_network };
2545
2546         char read_state;
2547         char write_state;
2548
2549         asio::ip::tcp::endpoint ip;
2550         float up_speed;
2551         float down_speed;
2552         float payload_up_speed;
2553         float payload_down_speed;
2554         size_type total_download;
2555         size_type total_upload;
2556         peer_id pid;
2557         bitfield pieces;
2558         int upload_limit;
2559         int download_limit;
2560
2561         time_duration last_request;
2562         time_duration last_active;
2563         int request_timeout;
2564
2565         int send_buffer_size;
2566         int used_send_buffer;
2567
2568         int receive_buffer_size;
2569         int used_receive_buffer;
2570
2571         int num_hashfails;
2572
2573         char country[2];
2574
2575         std::string inet_as_name;
2576         int inet_as;
2577
2578         size_type load_balancing;
2579
2580         int requests_in_buffer;
2581         int download_queue_length;
2582         int upload_queue_length;
2583
2584         int failcount;
2585
2586         int downloading_piece_index;
2587         int downloading_block_index;
2588         int downloading_progress;
2589         int downloading_total;
2590
2591         std::string client;
2592
2593         enum
2594         {
2595                 standard_bittorrent = 0,
2596                 web_seed = 1
2597         };
2598         int connection_type;
2599
2600         int remote_dl_rate;
2601
2602         int pending_disk_bytes;
2603
2604         int send_quota;
2605         int receive_quota;
2606
2607         int rtt;
2608
2609         int download_rate_peak;
2610         int upload_rate_peak;
2611
2612 };
2613 </pre>
2614 <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
2615 any combination of the enums above. The following table describes each flag:</p>
2616 <table border="1" class="docutils">
2617 <colgroup>
2618 <col width="31%" />
2619 <col width="69%" />
2620 </colgroup>
2621 <tbody valign="top">
2622 <tr><td><tt class="docutils literal"><span class="pre">interesting</span></tt></td>
2623 <td><strong>we</strong> are interested in pieces from this peer.</td>
2624 </tr>
2625 <tr><td><tt class="docutils literal"><span class="pre">choked</span></tt></td>
2626 <td><strong>we</strong> have choked this peer.</td>
2627 </tr>
2628 <tr><td><tt class="docutils literal"><span class="pre">remote_interested</span></tt></td>
2629 <td>the peer is interested in <strong>us</strong></td>
2630 </tr>
2631 <tr><td><tt class="docutils literal"><span class="pre">remote_choked</span></tt></td>
2632 <td>the peer has choked <strong>us</strong>.</td>
2633 </tr>
2634 <tr><td><tt class="docutils literal"><span class="pre">support_extensions</span></tt></td>
2635 <td>means that this peer supports the
2636 <a class="reference" href="extension_protocol.html">extension protocol</a>.</td>
2637 </tr>
2638 <tr><td><tt class="docutils literal"><span class="pre">local_connection</span></tt></td>
2639 <td>The connection was initiated by us, the peer has a
2640 listen port open, and that port is the same as in the
2641 address of this peer. If this flag is not set, this
2642 peer connection was opened by this peer connecting to
2643 us.</td>
2644 </tr>
2645 <tr><td><tt class="docutils literal"><span class="pre">handshake</span></tt></td>
2646 <td>The connection is opened, and waiting for the
2647 handshake. Until the handshake is done, the peer
2648 cannot be identified.</td>
2649 </tr>
2650 <tr><td><tt class="docutils literal"><span class="pre">connecting</span></tt></td>
2651 <td>The connection is in a half-open state (i.e. it is
2652 being connected).</td>
2653 </tr>
2654 <tr><td><tt class="docutils literal"><span class="pre">queued</span></tt></td>
2655 <td>The connection is currently queued for a connection
2656 attempt. This may happen if there is a limit set on
2657 the number of half-open TCP connections.</td>
2658 </tr>
2659 <tr><td><tt class="docutils literal"><span class="pre">on_parole</span></tt></td>
2660 <td>The peer has participated in a piece that failed the
2661 hash check, and is now &quot;on parole&quot;, which means we're
2662 only requesting whole pieces from this peer until
2663 it either fails that piece or proves that it doesn't
2664 send bad data.</td>
2665 </tr>
2666 <tr><td><tt class="docutils literal"><span class="pre">seed</span></tt></td>
2667 <td>This peer is a seed (it has all the pieces).</td>
2668 </tr>
2669 <tr><td><tt class="docutils literal"><span class="pre">optimistic_unchoke</span></tt></td>
2670 <td>This peer is subject to an optimistic unchoke. It has
2671 been unchoked for a while to see if it might unchoke
2672 us in return an earn an upload/unchoke slot. If it
2673 doesn't within some period of time, it will be choked
2674 and another peer will be optimistically unchoked.</td>
2675 </tr>
2676 <tr><td><tt class="docutils literal"><span class="pre">snubbed</span></tt></td>
2677 <td>This peer has recently failed to send a block within
2678 the request timeout from when the request was sent.
2679 We're currently picking one block at a time from this
2680 peer.</td>
2681 </tr>
2682 <tr><td><tt class="docutils literal"><span class="pre">upload_only</span></tt></td>
2683 <td>This peer has either explicitly (with an extension)
2684 or implicitly (by becoming a seed) told us that it
2685 will not downloading anything more, regardless of
2686 which pieces we have.</td>
2687 </tr>
2688 </tbody>
2689 </table>
2690 <p><tt class="docutils literal"><span class="pre">source</span></tt> is a combination of flags describing from which sources this peer
2691 was received. The flags are:</p>
2692 <table border="1" class="docutils">
2693 <colgroup>
2694 <col width="30%" />
2695 <col width="70%" />
2696 </colgroup>
2697 <tbody valign="top">
2698 <tr><td><tt class="docutils literal"><span class="pre">tracker</span></tt></td>
2699 <td>The peer was received from the tracker.</td>
2700 </tr>
2701 <tr><td><tt class="docutils literal"><span class="pre">dht</span></tt></td>
2702 <td>The peer was received from the kademlia DHT.</td>
2703 </tr>
2704 <tr><td><tt class="docutils literal"><span class="pre">pex</span></tt></td>
2705 <td>The peer was received from the peer exchange
2706 extension.</td>
2707 </tr>
2708 <tr><td><tt class="docutils literal"><span class="pre">lsd</span></tt></td>
2709 <td>The peer was received from the local service
2710 discovery (The peer is on the local network).</td>
2711 </tr>
2712 <tr><td><tt class="docutils literal"><span class="pre">resume_data</span></tt></td>
2713 <td>The peer was added from the fast resume data.</td>
2714 </tr>
2715 </tbody>
2716 </table>
2717 <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
2718 to sending and receiving data. The states are declared in the <tt class="docutils literal"><span class="pre">bw_state</span></tt> enum and
2719 defines as follows:</p>
2720 <table border="1" class="docutils">
2721 <colgroup>
2722 <col width="30%" />
2723 <col width="70%" />
2724 </colgroup>
2725 <tbody valign="top">
2726 <tr><td><tt class="docutils literal"><span class="pre">bw_idle</span></tt></td>
2727 <td>The peer is not waiting for any external events to
2728 send or receive data.</td>
2729 </tr>
2730 <tr><td><tt class="docutils literal"><span class="pre">bw_torrent</span></tt></td>
2731 <td>The peer is waiting for the torrent to receive
2732 bandwidth quota in order to forward the bandwidth
2733 request to the global manager.</td>
2734 </tr>
2735 <tr><td><tt class="docutils literal"><span class="pre">bw_global</span></tt></td>
2736 <td>The peer is waiting for the global bandwidth manager
2737 to receive more quota in order to handle the request.</td>
2738 </tr>
2739 <tr><td><tt class="docutils literal"><span class="pre">bw_network</span></tt></td>
2740 <td>The peer has quota and is currently waiting for a
2741 network read or write operation to complete. This is
2742 the state all peers are in if there are no bandwidth
2743 limits.</td>
2744 </tr>
2745 </tbody>
2746 </table>
2747 <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
2748 more info, see the <a class="reference" href="http://asio.sf.net">asio</a> documentation.</p>
2749 <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
2750 we have to and from this peer (including any protocol messages). The transfer rates
2751 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>.
2752 These figures are updated approximately once every second.</p>
2753 <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
2754 from and uploaded to this peer. These numbers do not include the protocol chatter, but only
2755 the payload data.</p>
2756 <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
2757 extract 'fingerprints' from the peer. Sometimes it can tell you which client the peer
2758 is using. See identify_client()_</p>
2759 <p><tt class="docutils literal"><span class="pre">pieces</span></tt> is a bitfield, with one bit per piece in the torrent.
2760 Each bit tells you if the peer has that piece (if it's set to 1)
2761 or if the peer miss that piece (set to 0).</p>
2762 <p><tt class="docutils literal"><span class="pre">seed</span></tt> is true if this peer is a seed.</p>
2763 <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
2764 peer every second. It may be -1 if there's no local limit on the peer. The global
2765 limit and the torrent limit is always enforced anyway.</p>
2766 <p><tt class="docutils literal"><span class="pre">download_limit</span></tt> is the number of bytes per second this peer is allowed to
2767 receive. -1 means it's unlimited.</p>
2768 <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
2769 to this peer and since any transfer occurred with this peer, respectively.</p>
2770 <p><tt class="docutils literal"><span class="pre">request_timeout</span></tt> is the number of seconds until the current front piece request
2771 will time out. This timeout can be adjusted through <tt class="docutils literal"><span class="pre">session_settings::request_timeout</span></tt>.
2772 -1 means that there is not outstanding request.</p>
2773 <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
2774 and used for the peer's send buffer, respectively.</p>
2775 <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
2776 allocated and used as receive buffer, respectively.</p>
2777 <p><tt class="docutils literal"><span class="pre">num_hashfails</span></tt> is the number of pieces this peer has participated in
2778 sending us that turned out to fail the hash check.</p>
2779 <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
2780 is connected from. If the country hasn't been resolved yet, both chars are set
2781 to 0. If the resolution failed for some reason, the field is set to &quot;--&quot;. If the
2782 resolution service returns an invalid country code, it is set to &quot;!!&quot;.
2783 The <tt class="docutils literal"><span class="pre">countries.nerd.dk</span></tt> service is used to look up countries. This field will
2784 remain set to 0 unless the torrent is set to resolve countries, see <a class="reference" href="#resolve-countries">resolve_countries()</a>.</p>
2785 <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
2786 an empty string if there is no name in the geo ip database.</p>
2787 <p><tt class="docutils literal"><span class="pre">inet_as</span></tt> is the AS number the peer is located in.</p>
2788 <p><tt class="docutils literal"><span class="pre">load_balancing</span></tt> is a measurement of the balancing of free download (that we get)
2789 and free upload that we give. Every peer gets a certain amount of free upload, but
2790 this member says how much <em>extra</em> free upload this peer has got. If it is a negative
2791 number it means that this was a peer from which we have got this amount of free
2792 download.</p>
2793 <p><tt class="docutils literal"><span class="pre">requests_in_buffer</span></tt> is the number of requests messages that are currently in the
2794 send buffer waiting to be sent.</p>
2795 <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
2796 that hasn't been answered with a piece yet.</p>
2797 <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
2798 that we haven't answered with a piece yet.</p>
2799 <p><tt class="docutils literal"><span class="pre">failcount</span></tt> is the number of times this peer has &quot;failed&quot;. i.e. failed to connect
2800 or disconnected us. The failcount is decremented when we see this peer in a tracker
2801 response or peer exchange message.</p>
2802 <p>You can know which piece, and which part of that piece, that is currently being
2803 downloaded from a specific peer by looking at the next four members.
2804 <tt class="docutils literal"><span class="pre">downloading_piece_index</span></tt> is the index of the piece that is currently being downloaded.
2805 This may be set to -1 if there's currently no piece downloading from this peer. If it is
2806 &gt;= 0, the other three members are valid. <tt class="docutils literal"><span class="pre">downloading_block_index</span></tt> is the index of the
2807 block (or sub-piece) that is being downloaded. <tt class="docutils literal"><span class="pre">downloading_progress</span></tt> is the number
2808 of bytes of this block we have received from the peer, and <tt class="docutils literal"><span class="pre">downloading_total</span></tt> is
2809 the total number of bytes in this block.</p>
2810 <p><tt class="docutils literal"><span class="pre">client</span></tt> is a string describing the software at the other end of the connection.
2811 In some cases this information is not available, then it will contain a string
2812 that may give away something about which software is running in the other end.
2813 In the case of a web seed, the server type and version will be a part of this
2814 string.</p>
2815 <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
2816 <tt class="docutils literal"><span class="pre">web_seed</span></tt>. These are currently the only implemented protocols.</p>
2817 <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
2818 bytes per second.</p>
2819 <p><tt class="docutils literal"><span class="pre">pending_disk_bytes</span></tt> is the number of bytes this peer has pending in the
2820 disk-io thread. Downloaded and waiting to be written to disk. This is what
2821 is capped by <tt class="docutils literal"><span class="pre">session_settings::max_outstanding_disk_bytes_per_connection</span></tt>.</p>
2822 <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
2823 assigned to be allowed to send and receive until it has to request more quota
2824 from the bandwidth manager.</p>
2825 <p><tt class="docutils literal"><span class="pre">rtt</span></tt> is an estimated round trip time to this peer, in milliseconds. It is
2826 estimated by timing the the tcp <tt class="docutils literal"><span class="pre">connect()</span></tt>. It may be 0 for incoming connections.</p>
2827 <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
2828 rates seen on this connection. They are given in bytes per second. This number is
2829 reset to 0 on reconnect.</p>
2830 </div>
2831 <div class="section">
2832 <h1><a id="session-settings" name="session-settings">session_settings</a></h1>
2833 <p>You have some control over tracker requests through the <tt class="docutils literal"><span class="pre">session_settings</span></tt> object. You
2834 create it and fill it with your settings and then use <tt class="docutils literal"><span class="pre">session::set_settings()</span></tt>
2835 to apply them. You have control over proxy and authorization settings and also the user-agent
2836 that will be sent to the tracker. The user-agent is a good way to identify your client.</p>
2837 <pre class="literal-block">
2838 struct session_settings
2839 {
2840         session_settings();
2841         std::string user_agent;
2842         int tracker_completion_timeout;
2843         int tracker_receive_timeout;
2844         int stop_tracker_timeout;
2845         int tracker_maximum_response_length;
2846
2847         int piece_timeout;
2848         float request_queue_time;
2849         int max_allowed_in_request_queue;
2850         int max_out_request_queue;
2851         int whole_pieces_threshold;
2852         int peer_timeout;
2853         int urlseed_timeout;
2854         int urlseed_pipeline_size;
2855         int file_pool_size;
2856         bool allow_multiple_connections_per_ip;
2857         int max_failcount;
2858         int min_reconnect_time;
2859         int peer_connect_timeout;
2860         bool ignore_limits_on_local_network;
2861         int connection_speed;
2862         bool send_redundant_have;
2863         bool lazy_bitfields;
2864         int inactivity_timeout;
2865         int unchoke_interval;
2866         int optimistic_unchoke_multiplier;
2867         address announce_ip;
2868         int num_want;
2869         int initial_picker_threshold;
2870         int allowed_fast_set_size;
2871         int max_outstanding_disk_bytes_per_connection;
2872         int handshake_timeout;
2873         bool use_dht_as_fallback;
2874         bool free_torrent_hashes;
2875         bool upnp_ignore_nonrouters;
2876         int send_buffer_watermark;
2877         bool auto_upload_slots;
2878         bool use_parole_mode;
2879         int cache_size;
2880         int cache_expiry;
2881         std::pair&lt;int, int&gt; outgoing_ports;
2882         char peer_tos;
2883
2884         int active_downloads;
2885         int active_seeds;
2886         int active_limit;
2887         bool dont_count_slow_torrents;
2888         int auto_manage_interval;
2889         float share_ratio_limit;
2890         float seed_time_ratio_limit;
2891         int seed_time_limit;
2892         bool close_redundant_connections;
2893
2894         int auto_scrape_interval;
2895         int auto_scrape_min_interval;
2896
2897         int max_peerlist_size;
2898 };
2899 </pre>
2900 <p><tt class="docutils literal"><span class="pre">user_agent</span></tt> this is the client identification to the tracker.
2901 The recommended format of this string is:
2902 &quot;ClientName/ClientVersion libtorrent/libtorrentVersion&quot;.
2903 This name will not only be used when making HTTP requests, but also when
2904 sending extended headers to peers that support that extension.</p>
2905 <p><tt class="docutils literal"><span class="pre">tracker_completion_timeout</span></tt> is the number of seconds the tracker
2906 connection will wait from when it sent the request until it considers the
2907 tracker to have timed-out. Default value is 60 seconds.</p>
2908 <p><tt class="docutils literal"><span class="pre">tracker_receive_timeout</span></tt> is the number of seconds to wait to receive
2909 any data from the tracker. If no data is received for this number of
2910 seconds, the tracker will be considered as having timed out. If a tracker
2911 is down, this is the kind of timeout that will occur. The default value
2912 is 20 seconds.</p>
2913 <p><tt class="docutils literal"><span class="pre">stop_tracker_timeout</span></tt> is the time to wait for tracker responses when
2914 shutting down the session object. This is given in seconds. Default is
2915 10 seconds.</p>
2916 <p><tt class="docutils literal"><span class="pre">tracker_maximum_response_length</span></tt> is the maximum number of bytes in a
2917 tracker response. If a response size passes this number it will be rejected
2918 and the connection will be closed. On gzipped responses this size is measured
2919 on the uncompressed data. So, if you get 20 bytes of gzip response that'll
2920 expand to 2 megs, it will be interrupted before the entire response has been
2921 uncompressed (given your limit is lower than 2 megs). Default limit is
2922 1 megabyte.</p>
2923 <p><tt class="docutils literal"><span class="pre">piece_timeout</span></tt> controls the number of seconds from a request is sent until
2924 it times out if no piece response is returned.</p>
2925 <p><tt class="docutils literal"><span class="pre">request_queue_time</span></tt> is the length of the request queue given in the number
2926 of seconds it should take for the other end to send all the pieces. i.e. the
2927 actual number of requests depends on the download rate and this number.</p>
2928 <p><tt class="docutils literal"><span class="pre">max_allowed_in_request_queue</span></tt> is the number of outstanding block requests
2929 a peer is allowed to queue up in the client. If a peer sends more requests
2930 than this (before the first one has been handled) the last request will be
2931 dropped. The higher this is, the faster upload speeds the client can get to a
2932 single peer.</p>
2933 <p><tt class="docutils literal"><span class="pre">max_out_request_queue</span></tt> is the maximum number of outstanding requests to
2934 send to a peer. This limit takes precedence over <tt class="docutils literal"><span class="pre">request_queue_time</span></tt>. i.e.
2935 no matter the download speed, the number of outstanding requests will never
2936 exceed this limit.</p>
2937 <p><tt class="docutils literal"><span class="pre">whole_pieces_threshold</span></tt> is a limit in seconds. if a whole piece can be
2938 downloaded in at least this number of seconds from a specific peer, the
2939 peer_connection will prefer requesting whole pieces at a time from this peer.
2940 The benefit of this is to better utilize disk caches by doing localized
2941 accesses and also to make it easier to identify bad peers if a piece fails
2942 the hash check.</p>
2943 <p><tt class="docutils literal"><span class="pre">peer_timeout</span></tt> is the number of seconds the peer connection should
2944 wait (for any activity on the peer connection) before closing it due
2945 to time out. This defaults to 120 seconds, since that's what's specified
2946 in the protocol specification. After half the time out, a keep alive message
2947 is sent.</p>
2948 <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
2949 url seeds. This value defaults to 20 seconds.</p>
2950 <p><tt class="docutils literal"><span class="pre">urlseed_pipeline_size</span></tt> controls the pipelining with the web server. When
2951 using persistent connections to HTTP 1.1 servers, the client is allowed to
2952 send more requests before the first response is received. This number controls
2953 the number of outstanding requests to use with url-seeds. Default is 5.</p>
2954 <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
2955 session will keep open. The reason why files are left open at all is that
2956 some anti virus software hooks on every file close, and scans the file for
2957 viruses. deferring the closing of the files will be the difference between
2958 a usable system and a completely hogged down system. Most operating systems
2959 also has a limit on the total number of file descriptors a process may have
2960 open. It is usually a good idea to find this limit and set the number of
2961 connections and the number of files limits so their sum is slightly below it.</p>
2962 <p><tt class="docutils literal"><span class="pre">allow_multiple_connections_per_ip</span></tt> determines if connections from the
2963 same IP address as existing connections should be rejected or not. Multiple
2964 connections from the same IP address is not allowed by default, to prevent
2965 abusive behavior by peers. It may be useful to allow such connections in
2966 cases where simulations are run on the same machie, and all peers in a
2967 swarm has the same IP address.</p>
2968 <p><tt class="docutils literal"><span class="pre">max_failcount</span></tt> is the maximum times we try to connect to a peer before
2969 stop connecting again. If a peer succeeds, the failcounter is reset. If
2970 a peer is retrieved from a peer source (other than DHT) the failcount is
2971 decremented by one, allowing another try.</p>
2972 <p><tt class="docutils literal"><span class="pre">min_reconnect_time</span></tt> is the time to wait between connection attempts. If
2973 the peer fails, the time is multiplied by fail counter.</p>
2974 <p><tt class="docutils literal"><span class="pre">peer_connect_timeout</span></tt> the number of seconds to wait after a connection
2975 attempt is initiated to a peer until it is considered as having timed out.
2976 The default is 10 seconds. This setting is especially important in case
2977 the number of half-open connections are limited, since stale half-open
2978 connection may delay the connection of other peers considerably.</p>
2979 <p><tt class="docutils literal"><span class="pre">ignore_limits_on_local_network</span></tt>, if set to true, upload, download and
2980 unchoke limits are ignored for peers on the local network.</p>
2981 <p><tt class="docutils literal"><span class="pre">connection_speed</span></tt> is the number of connection attempts that
2982 are made per second. If a number &lt;= 0 is specified, it will default to
2983 200 connections per second.</p>
2984 <p><tt class="docutils literal"><span class="pre">send_redundant_have</span></tt> controls if have messages will be sent
2985 to peers that already have the piece. This is typically not necessary,
2986 but it might be necessary for collecting statistics in some cases.
2987 Default is false.</p>
2988 <p><tt class="docutils literal"><span class="pre">lazy_bitfields</span></tt> prevents outgoing bitfields from being full. If the
2989 client is seed, a few bits will be set to 0, and later filled in with
2990 have-messages. This is to prevent certain ISPs from stopping people
2991 from seeding.</p>
2992 <p><tt class="docutils literal"><span class="pre">inactivity_timeout</span></tt>, if a peer is uninteresting and uninterested
2993 for longer than this number of seconds, it will be disconnected.
2994 Default is 10 minutes</p>
2995 <p><tt class="docutils literal"><span class="pre">unchoke_interval</span></tt> is the number of seconds between chokes/unchokes.
2996 On this interval, peers are re-evaluated for being choked/unchoked. This
2997 is defined as 30 seconds in the protocol, and it should be significantly
2998 longer than what it takes for TCP to ramp up to it's max rate.</p>
2999 <p><tt class="docutils literal"><span class="pre">optimistic_unchoke_multiplier</span></tt> is the number of unchoke intervals between
3000 each <em>optimistic</em> unchoke interval. On this timer, the currently optimistically
3001 unchoked peer will change.</p>
3002 <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">&amp;ip=</span></tt> parameter.
3003 If left as the default (default constructed), that parameter is ommited.</p>
3004 <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
3005 what is sent as the <tt class="docutils literal"><span class="pre">&amp;num_want=</span></tt> parameter to the tracker.</p>
3006 <p><tt class="docutils literal"><span class="pre">initial_picker_threshold</span></tt> specifies the number of pieces we need before we
3007 switch to rarest first picking. This defaults to 4, which means the 4 first
3008 pieces in any torrent are picked at random, the following pieces are picked
3009 in rarest first order.</p>
3010 <p><tt class="docutils literal"><span class="pre">allowed_fast_set_size</span></tt> is the number of pieces we allow peers to download
3011 from us without being unchoked.</p>
3012 <p><tt class="docutils literal"><span class="pre">max_outstanding_disk_bytes_per_connection</span></tt> is the number of bytes each
3013 connection is allowed to have waiting in the disk I/O queue before it is
3014 throttled back. This limit is meant to stop fast internet connections to
3015 queue up bufferes indefinitely on slow hard-drives or storage.</p>
3016 <p><tt class="docutils literal"><span class="pre">handshake_timeout</span></tt> specifies the number of seconds we allow a peer to
3017 delay responding to a protocol handshake. If no response is received within
3018 this time, the connection is closed.</p>
3019 <p><tt class="docutils literal"><span class="pre">use_dht_as_fallback</span></tt> determines how the DHT is used. If this is true
3020 (which it is by default), the DHT will only be used for torrents where
3021 all trackers in its tracker list has failed. Either by an explicit error
3022 message or a time out.</p>
3023 <p><tt class="docutils literal"><span class="pre">free_torrent_hashes</span></tt> determines whether or not the torrent's piece hashes
3024 are kept in memory after the torrent becomes a seed or not. If it is set to
3025 <tt class="docutils literal"><span class="pre">true</span></tt> the hashes are freed once the torrent is a seed (they're not
3026 needed anymore since the torrent won't download anything more). If it's set
3027 to false they are not freed. If they are freed, the <a class="reference" href="#torrent-info">torrent_info</a> returned
3028 by get_torrent_info() will return an object that may be incomplete, that
3029 cannot be passed back to <a class="reference" href="#add-torrent">add_torrent()</a> for instance.</p>
3030 <p><tt class="docutils literal"><span class="pre">upnp_ignore_nonrouters</span></tt> indicates whether or not the UPnP implementation
3031 should ignore any broadcast response from a device whose address is not the
3032 configured router for this machine. i.e. it's a way to not talk to other
3033 people's routers by mistake.</p>
3034 <p><tt class="docutils literal"><span class="pre">send_buffer_waterbark</span></tt> is the upper limit of the send buffer low-watermark.
3035 if the send buffer has fewer bytes than this, we'll read another 16kB block
3036 onto it. If set too small, upload rate capacity will suffer. If set too high,
3037 memory will be wasted. The actual watermark may be lower than this in case
3038 the upload rate is low, this is the upper limit.</p>
3039 <p><tt class="docutils literal"><span class="pre">auto_upload_slots</span></tt> defaults to true. When true, if there is a global upload
3040 limit set and the current upload rate is less than 90% of that, another upload
3041 slot is opened. If the upload rate has been saturated for an extended period
3042 of time, on upload slot is closed. The number of upload slots will never be
3043 less than what has been set by <tt class="docutils literal"><span class="pre">session::set_max_uploads()</span></tt>. To query the
3044 current number of upload slots, see <tt class="docutils literal"><span class="pre">session_status::allowed_upload_slots</span></tt>.</p>
3045 <p><tt class="docutils literal"><span class="pre">use_parole_mode</span></tt> specifies if parole mode should be used. Parole mode means
3046 that peers that participate in pieces that fail the hash check are put in a mode
3047 where they are only allowed to download whole pieces. If the whole piece a peer
3048 in parole mode fails the hash check, it is banned. If a peer participates in a
3049 piece that passes the hash check, it is taken out of parole mode.</p>
3050 <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.
3051 It defaults to 512 (= 8 MB).</p>
3052 <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
3053 in the write cache, to when it's forcefully flushed to disk. Default is 60 second.</p>
3054 <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
3055 used to bind outgoing sockets to. This may be useful for users whose router
3056 allows them to assign QoS classes to traffic based on its local port. It is
3057 a range instead of a single port because of the problems with failing to reconnect
3058 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>
3059 <p><tt class="docutils literal"><span class="pre">peer_tos</span></tt> determines the TOS byte set in the IP header of every packet
3060 sent to peers (including web seeds). The default value for this is <tt class="docutils literal"><span class="pre">0x0</span></tt>
3061 (no marking). One potentially useful TOS mark is <tt class="docutils literal"><span class="pre">0x20</span></tt>, this represents
3062 the <em>QBone scavenger service</em>. For more details, see <a class="reference" href="http://qbone.internet2.edu/qbss/">QBSS</a>.</p>
3063 <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
3064 downloading torrents the queuing mechanism allows. The target number of active
3065 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
3066 <tt class="docutils literal"><span class="pre">active_seeds</span></tt> are upper limits on the number of downloading torrents and
3067 seeding torrents respectively. Setting the value to -1 will mean unlimited.</p>
3068 <p>For example if there are 10 seeding torrents and 10 downloading torrents, and
3069 <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
3070 active, but 4 downloading torrents. If the settings are <tt class="docutils literal"><span class="pre">active_downloads</span></tt> = 2
3071 and <tt class="docutils literal"><span class="pre">active_seeds</span></tt> = 4, then there will be 2 downloading torrenst and 2 seeding
3072 torrents active. Torrents that are not auto managed are also counted against these
3073 limits. If there are non-auto managed torrents that use up all the slots, no
3074 auto managed torrent will be activated.</p>
3075 <p>if <tt class="docutils literal"><span class="pre">dont_count_slow_torrents</span></tt> is true, torrents without any payload transfers are
3076 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
3077 to make it more likely to utilize all available bandwidth, and avoid having torrents
3078 that don't transfer anything block the active slots.</p>
3079 <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
3080 slow torrents.</p>
3081 <p><tt class="docutils literal"><span class="pre">auto_manage_interval</span></tt> is the number of seconds between the torrent queue
3082 is updated, and rotated.</p>
3083 <p><tt class="docutils literal"><span class="pre">share_ratio_limit</span></tt> is the upload / download ratio limit for considering a
3084 seeding torrent have met the seed limit criteria. See <a class="reference" href="#queuing">queuing</a>.</p>
3085 <p><tt class="docutils literal"><span class="pre">seed_time_ratio_limit</span></tt> is the seeding time / downloading time ratio limit
3086 for considering a seeding torrent to have met the seed limit criteria. See <a class="reference" href="#queuing">queuing</a>.</p>
3087 <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
3088 (specified in seconds) before it is considered having met the seed limit criteria.
3089 See <a class="reference" href="#queuing">queuing</a>.</p>
3090 <p><tt class="docutils literal"><span class="pre">close_redundant_connections</span></tt> specifies whether libtorrent should close
3091 connections where both ends have no utility in keeping the connection open.
3092 For instance if both ends have completed their downloads, there's no point
3093 in keeping it open. This defaults to <tt class="docutils literal"><span class="pre">true</span></tt>.</p>
3094 <p><tt class="docutils literal"><span class="pre">auto_scrape_interval</span></tt> is the number of seconds between scrapes of
3095 queued torrents (auto managed and paused torrents). Auto managed
3096 torrents that are paused, are scraped regularly in order to keep
3097 track of their downloader/seed ratio. This ratio is used to determine
3098 which torrents to seed and which to pause.</p>
3099 <p><tt class="docutils literal"><span class="pre">auto_scrape_min_interval</span></tt> is the minimum number of seconds between any
3100 automatic scrape (regardless of torrent). In case there are a large number
3101 of paused auto managed torrents, this puts a limit on how often a scrape
3102 request is sent.</p>
3103 <p><tt class="docutils literal"><span class="pre">max_peerlist_size</span></tt> is the maximum number of peers in the list of
3104 known peers. These peers are not necessarily connected, so this number
3105 should be much greater than the maximum number of connected peers.
3106 Peers are evicted from the cache when the list grows passed 90% of
3107 this limit, and once the size hits the limit, peers are no longer
3108 added to the list.</p>
3109 </div>
3110 <div class="section">
3111 <h1><a id="pe-settings" name="pe-settings">pe_settings</a></h1>
3112 <p>The <tt class="docutils literal"><span class="pre">pe_settings</span></tt> structure is used to control the settings related
3113 to peer protocol encryption:</p>
3114 <pre class="literal-block">
3115 struct pe_settings
3116 {
3117         pe_settings();
3118
3119         enum enc_policy
3120         {
3121                 forced,
3122                 enabled,
3123                 disabled
3124         };
3125
3126         enum enc_level
3127         {
3128                 plaintext,
3129                 rc4,
3130                 both
3131         };
3132
3133         enc_policy out_enc_policy;
3134         enc_policy in_enc_policy;
3135         enc_level allowed_enc_level;
3136         bool prefer_rc4;
3137 };
3138 </pre>
3139 <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
3140 and outgoing connections respectively. The settings for these are:</p>
3141 <blockquote>
3142 <ul class="simple">
3143 <li><tt class="docutils literal"><span class="pre">forced</span></tt> - Only encrypted connections are allowed. Incoming connections
3144 that are not encrypted are closed and if the encrypted outgoing connection
3145 fails, a non-encrypted retry will not be made.</li>
3146 <li><tt class="docutils literal"><span class="pre">enabled</span></tt> - encrypted connections are enabled, but non-encrypted
3147 connections are allowed. An incoming non-encrypted connection will
3148 be accepted, and if an outgoing encrypted connection fails, a non-
3149 encrypted connection will be tried.</li>
3150 <li><tt class="docutils literal"><span class="pre">disabled</span></tt> - only non-encrypted connections are allowed.</li>
3151 </ul>
3152 </blockquote>
3153 <p><tt class="docutils literal"><span class="pre">allowed_enc_level</span></tt> determines the encryption level of the
3154 connections.  This setting will adjust which encryption scheme is
3155 offered to the other peer, as well as which encryption scheme is
3156 selected by the client. The settings are:</p>
3157 <blockquote>
3158 <ul class="simple">
3159 <li><tt class="docutils literal"><span class="pre">plaintext</span></tt> - only the handshake is encrypted, the bulk of the traffic
3160 remains unchanged.</li>
3161 <li><tt class="docutils literal"><span class="pre">rc4</span></tt> - the entire stream is encrypted with RC4</li>
3162 <li><tt class="docutils literal"><span class="pre">both</span></tt> - both RC4 and plaintext connections are allowed.</li>
3163 </ul>
3164 </blockquote>
3165 <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>
3166 </div>
3167 <div class="section">
3168 <h1><a id="proxy-settings" name="proxy-settings">proxy_settings</a></h1>
3169 <p>The <tt class="docutils literal"><span class="pre">proxy_settings</span></tt> structs contains the information needed to
3170 direct certain traffic to a proxy.</p>
3171 <blockquote>
3172 <pre class="literal-block">
3173 struct proxy_settings
3174 {
3175         proxy_settings();
3176
3177         std::string hostname;
3178         int port;
3179
3180         std::string username;
3181         std::string password;
3182
3183         enum proxy_type
3184         {
3185                 none,
3186                 socks4,
3187                 socks5,
3188                 socks5_pw,
3189                 http,
3190                 http_pw
3191         };
3192
3193         proxy_type type;
3194 };
3195 </pre>
3196 </blockquote>
3197 <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
3198 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>
3199 can be set to authenticate with the proxy.</p>
3200 <p>The <tt class="docutils literal"><span class="pre">type</span></tt> tells libtorrent what kind of proxy server it is. The following
3201 options are available:</p>
3202 <blockquote>
3203 <ul class="simple">
3204 <li><tt class="docutils literal"><span class="pre">none</span></tt> - This is the default, no proxy server is used, all other fields
3205 are ignored.</li>
3206 <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
3207 requires a username.</li>
3208 <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
3209 does not require any authentication. The username and password are ignored.</li>
3210 <li><tt class="docutils literal"><span class="pre">socks5_pw</span></tt> - The server is assumed to be a SOCKS5 server that supports
3211 plain text username and password authentication (<a class="reference" href="http://www.faqs.org/rfcs/rfc1929.html">RFC 1929</a>). The username
3212 and password specified may be sent to the proxy if it requires.</li>
3213 <li><tt class="docutils literal"><span class="pre">http</span></tt> - The server is assumed to be an HTTP proxy. If the transport used
3214 for the connection is non-HTTP, the server is assumed to support the
3215 <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
3216 suffice. The proxy is assumed to not require authorization. The username
3217 and password will not be used.</li>
3218 <li><tt class="docutils literal"><span class="pre">http_pw</span></tt> - The server is assumed to be an HTTP proxy that requires
3219 user authorization. The username and password will be sent to the proxy.</li>
3220 </ul>
3221 </blockquote>
3222 </div>
3223 <div class="section">
3224 <h1><a id="ip-filter" name="ip-filter">ip_filter</a></h1>
3225 <p>The <tt class="docutils literal"><span class="pre">ip_filter</span></tt> class is a set of rules that uniquely categorizes all
3226 ip addresses as allowed or disallowed. The default constructor creates
3227 a single rule that allows all addresses (0.0.0.0 - 255.255.255.255 for
3228 the IPv4 range, and the equivalent range covering all addresses for the
3229 IPv6 range).</p>
3230 <blockquote>
3231 <pre class="literal-block">
3232 template &lt;class Addr&gt;
3233 struct ip_range
3234 {
3235         Addr first;
3236         Addr last;
3237         int flags;
3238 };
3239
3240 class ip_filter
3241 {
3242 public:
3243         enum access_flags { blocked = 1 };
3244
3245         ip_filter();
3246         void add_rule(address first, address last, int flags);
3247         int access(address const&amp; addr) const;
3248
3249         typedef boost::tuple&lt;std::vector&lt;ip_range&lt;address_v4&gt; &gt;
3250                 , std::vector&lt;ip_range&lt;address_v6&gt; &gt; &gt; filter_tuple_t;
3251
3252         filter_tuple_t export_filter() const;
3253 };
3254 </pre>
3255 </blockquote>
3256 <div class="section">
3257 <h2><a id="id10" name="id10">ip_filter()</a></h2>
3258 <blockquote>
3259 <pre class="literal-block">
3260 ip_filter()
3261 </pre>
3262 </blockquote>
3263 <p>Creates a default filter that doesn't filter any address.</p>
3264 <p>postcondition:
3265 <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>
3266 </div>
3267 <div class="section">
3268 <h2><a id="add-rule" name="add-rule">add_rule()</a></h2>
3269 <blockquote>
3270 <pre class="literal-block">
3271 void add_rule(address first, address last, int flags);
3272 </pre>
3273 </blockquote>
3274 <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
3275 ip addresses that will be marked with the given flags. The <tt class="docutils literal"><span class="pre">flags</span></tt>
3276 can currently be 0, which means allowed, or <tt class="docutils literal"><span class="pre">ip_filter::blocked</span></tt>, which
3277 means disallowed.</p>
3278 <p>precondition:
3279 <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">&amp;&amp;</span> <span class="pre">first.is_v6()</span> <span class="pre">==</span> <span class="pre">last.is_v6()</span></tt></p>
3280 <p>postcondition:
3281 <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>
3282 <p>This means that in a case of overlapping ranges, the last one applied takes
3283 precedence.</p>
3284 </div>
3285 <div class="section">
3286 <h2><a id="access" name="access">access()</a></h2>
3287 <blockquote>
3288 <pre class="literal-block">
3289 int access(address const&amp; addr) const;
3290 </pre>
3291 </blockquote>
3292 <p>Returns the access permissions for the given address (<tt class="docutils literal"><span class="pre">addr</span></tt>). The permission
3293 can currently be 0 or <tt class="docutils literal"><span class="pre">ip_filter::blocked</span></tt>. The complexity of this operation
3294 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
3295 the current filter.</p>
3296 </div>
3297 <div class="section">
3298 <h2><a id="export-filter" name="export-filter">export_filter()</a></h2>
3299 <blockquote>
3300 <pre class="literal-block">
3301 boost::tuple&lt;std::vector&lt;ip_range&lt;address_v4&gt; &gt;
3302         , std::vector&lt;ip_range&lt;address_v6&gt; &gt; &gt; export_filter() const;
3303 </pre>
3304 </blockquote>
3305 <p>This function will return the current state of the filter in the minimum number of
3306 ranges possible. They are sorted from ranges in low addresses to high addresses. Each
3307 entry in the returned vector is a range with the access control specified in its
3308 <tt class="docutils literal"><span class="pre">flags</span></tt> field.</p>
3309 <p>The return value is a tuple containing two range-lists. One for IPv4 addresses
3310 and one for IPv6 addresses.</p>
3311 </div>
3312 </div>
3313 <div class="section">
3314 <h1><a id="big-number" name="big-number">big_number</a></h1>
3315 <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
3316 <tt class="docutils literal"><span class="pre">big_number</span></tt>. It represents 20 bytes of data. Its synopsis follows:</p>
3317 <pre class="literal-block">
3318 class big_number
3319 {
3320 public:
3321         bool operator==(const big_number&amp; n) const;
3322         bool operator!=(const big_number&amp; n) const;
3323         bool operator&lt;(const big_number&amp; n) const;
3324
3325         const unsigned char* begin() const;
3326         const unsigned char* end() const;
3327
3328         unsigned char* begin();
3329         unsigned char* end();
3330 };
3331 </pre>
3332 <p>The iterators gives you access to individual bytes.</p>
3333 </div>
3334 <div class="section">
3335 <h1><a id="bitfield" name="bitfield">bitfield</a></h1>
3336 <p>The bitfiled type stores any number of bits as a bitfield in an array.</p>
3337 <pre class="literal-block">
3338 class bitfield
3339 {
3340         bitfield();
3341         bitfield(int bits);
3342         bitfield(int bits, bool val);
3343         bitfield(char const* bytes, int bits);
3344         bitfield(bitfield const&amp; rhs);
3345
3346         void borrow_bytes(char* bytes, int bits);
3347         ~bitfield();
3348
3349         void assign(char const* bytes, int bits);
3350
3351         bool operator[](int index) const;
3352
3353         bool get_bit(int index) const;
3354
3355         void clear_bit(int index);
3356         void set_bit(int index);
3357
3358         std::size_t size() const;
3359         bool empty() const;
3360
3361         char const* bytes() const;
3362
3363         bitfield&amp; operator=(bitfield const&amp; rhs);
3364
3365         int count() const;
3366
3367         typedef const_iterator;
3368         const_iterator begin() const;
3369         const_iterator end() const;
3370
3371         void resize(int bits, bool val);
3372         void set_all();
3373         void clear_all();
3374         void resize(int bits);
3375 };
3376 </pre>
3377 </div>
3378 <div class="section">
3379 <h1><a id="hasher" name="hasher">hasher</a></h1>
3380 <p>This class creates sha1-hashes. Its declaration looks like this:</p>
3381 <pre class="literal-block">
3382 class hasher
3383 {
3384 public:
3385         hasher();
3386         hasher(char const* data, unsigned int len);
3387
3388         void update(char const* data, unsigned int len);
3389         sha1_hash final();
3390         void reset();
3391 };
3392 </pre>
3393 <p>You use it by first instantiating it, then call <tt class="docutils literal"><span class="pre">update()</span></tt> to feed it
3394 with data. i.e. you don't have to keep the entire buffer of which you want to
3395 create the hash in memory. You can feed the hasher parts of it at a time. When
3396 You have fed the hasher with all the data, you call <tt class="docutils literal"><span class="pre">final()</span></tt> and it
3397 will return the sha1-hash of the data.</p>
3398 <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
3399 sha1 context and feed it the data passed in.</p>
3400 <p>If you want to reuse the hasher object once you have created a hash, you have to
3401 call <tt class="docutils literal"><span class="pre">reset()</span></tt> to reinitialize it.</p>
3402 <p>The sha1-algorithm used was implemented by Steve Reid and released as public domain.
3403 For more info, see <tt class="docutils literal"><span class="pre">src/sha1.cpp</span></tt>.</p>
3404 </div>
3405 <div class="section">
3406 <h1><a id="fingerprint" name="fingerprint">fingerprint</a></h1>
3407 <p>The fingerprint class represents information about a client and its version. It is used
3408 to encode this information into the client's peer id.</p>
3409 <p>This is the class declaration:</p>
3410 <pre class="literal-block">
3411 struct fingerprint
3412 {
3413         fingerprint(const char* id_string, int major, int minor
3414                 , int revision, int tag);
3415
3416         std::string to_string() const;
3417
3418         char name[2];
3419         char major_version;
3420         char minor_version;
3421         char revision_version;
3422         char tag_version;
3423
3424 };
3425 </pre>
3426 <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
3427 exactly two characters. These are the characters that should be unique for your client. Make
3428 sure not to clash with anybody else. Here are some taken id's:</p>
3429 <table border="1" class="docutils">
3430 <colgroup>
3431 <col width="30%" />
3432 <col width="70%" />
3433 </colgroup>
3434 <thead valign="bottom">
3435 <tr><th class="head">id chars</th>
3436 <th class="head">client</th>
3437 </tr>
3438 </thead>
3439 <tbody valign="top">
3440 <tr><td>'AZ'</td>
3441 <td>Azureus</td>
3442 </tr>
3443 <tr><td>'LT'</td>
3444 <td>libtorrent (default)</td>
3445 </tr>
3446 <tr><td>'BX'</td>
3447 <td>BittorrentX</td>
3448 </tr>
3449 <tr><td>'MT'</td>
3450 <td>Moonlight Torrent</td>
3451 </tr>
3452 <tr><td>'TS'</td>
3453 <td>Torrent Storm</td>
3454 </tr>
3455 <tr><td>'SS'</td>
3456 <td>Swarm Scope</td>
3457 </tr>
3458 <tr><td>'XT'</td>
3459 <td>Xan Torrent</td>
3460 </tr>
3461 </tbody>
3462 </table>
3463 <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>
3464 <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
3465 version of your client. All these numbers must be within the range [0, 9].</p>
3466 <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>
3467 </div>
3468 <div class="section">
3469 <h1><a id="upnp-and-nat-pmp" name="upnp-and-nat-pmp">UPnP and NAT-PMP</a></h1>
3470 <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,
3471 by default 1 or two mappings are made by libtorrent, one for the listen port and one
3472 for the DHT port (UDP).</p>
3473 <pre class="literal-block">
3474 class upnp
3475 {
3476 public:
3477
3478         enum protocol_type { none = 0, udp = 1, tcp = 2 };
3479         int add_mapping(protocol_type p, int external_port, int local_port);
3480         void delete_mapping(int mapping_index);
3481
3482         void discover_device();
3483         void close();
3484
3485         std::string router_model();
3486 };
3487
3488 class natpmp
3489 {
3490 public:
3491
3492         enum protocol_type { none = 0, udp = 1, tcp = 2 };
3493         int add_mapping(protocol_type p, int external_port, int local_port);
3494         void delete_mapping(int mapping_index);
3495
3496         void close();
3497         void rebind(address const&amp; listen_interface);
3498 };
3499 </pre>
3500 <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
3501 not be called directly by clients.</p>
3502 <div class="section">
3503 <h2><a id="add-mapping" name="add-mapping">add_mapping</a></h2>
3504 <blockquote>
3505 <pre class="literal-block">
3506 int add_mapping(protocol_type p, int external_port, int local_port);
3507 </pre>
3508 </blockquote>
3509 <p>Attempts to add a port mapping for the specified protocol. Valid protocols are
3510 <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
3511 <tt class="docutils literal"><span class="pre">natpmp::udp</span></tt> for the NAT-PMP class.</p>
3512 <p><tt class="docutils literal"><span class="pre">external_port</span></tt> is the port on the external address that will be mapped. This
3513 is a hint, you are not guaranteed that this port will be available, and it may
3514 end up being something else. In the <a class="reference" href="#portmap-alert">portmap_alert</a> notification, the actual
3515 external port is reported.</p>
3516 <p><tt class="docutils literal"><span class="pre">local_port</span></tt> is the port in the local machine that the mapping should forward
3517 to.</p>
3518 <p>The return value is an index that identifies this port mapping. This is used
3519 to refer to mappings that fails or succeeds in the <a class="reference" href="#portmap-error-alert">portmap_error_alert</a> and
3520 <a class="reference" href="#portmap-alert">portmap_alert</a> respectively. If The mapping fails immediately, the return value
3521 is -1, which means failure. There will not be any error alert notification for
3522 mappings that fail with a -1 return value.</p>
3523 </div>
3524 <div class="section">
3525 <h2><a id="delete-mapping" name="delete-mapping">delete_mapping</a></h2>
3526 <blockquote>
3527 <pre class="literal-block">
3528 void delete_mapping(int mapping_index);
3529 </pre>
3530 </blockquote>
3531 <p>This function removes a port mapping. <tt class="docutils literal"><span class="pre">mapping_index</span></tt> is the index that refers
3532 to the mapping you want to remove, which was returned from <a class="reference" href="#add-mapping">add_mapping</a>.</p>
3533 </div>
3534 <div class="section">
3535 <h2><a id="router-model" name="router-model">router_model()</a></h2>
3536 <blockquote>
3537 <pre class="literal-block">
3538 std::string router_model();
3539 </pre>
3540 </blockquote>
3541 <p>This is only available for UPnP routers. If the model is advertized by
3542 the router, it can be queried through this function.</p>
3543 </div>
3544 </div>
3545 <div class="section">
3546 <h1><a id="free-functions" name="free-functions">free functions</a></h1>
3547 <div class="section">
3548 <h2><a id="identify-client" name="identify-client">identify_client()</a></h2>
3549 <blockquote>
3550 <pre class="literal-block">
3551 std::string identify_client(peer_id const&amp; id);
3552 </pre>
3553 </blockquote>
3554 <p>This function is declared in the header <tt class="docutils literal"><span class="pre">&lt;libtorrent/identify_client.hpp&gt;</span></tt>. It can can be used
3555 to extract a string describing a client version from its peer-id. It will recognize most clients
3556 that have this kind of identification in the peer-id.</p>
3557 </div>
3558 <div class="section">
3559 <h2><a id="client-fingerprint" name="client-fingerprint">client_fingerprint()</a></h2>
3560 <blockquote>
3561 <pre class="literal-block">
3562 boost::optional&lt;fingerprint&gt; client_fingerprint(peer_id const&amp; p);
3563 </pre>
3564 </blockquote>
3565 <p>Returns an optional fingerprint if any can be identified from the peer id. This can be used
3566 to automate the identification of clients. It will not be able to identify peers with non-
3567 standard encodings. Only Azureus style, Shadow's style and Mainline style. This function is
3568 declared in the header <tt class="docutils literal"><span class="pre">&lt;libtorrent/identify_client.hpp&gt;</span></tt>.</p>
3569 </div>
3570 <div class="section">
3571 <h2><a id="bdecode-bencode" name="bdecode-bencode">bdecode() bencode()</a></h2>
3572 <blockquote>
3573 <pre class="literal-block">
3574 template&lt;class InIt&gt; entry bdecode(InIt start, InIt end);
3575 template&lt;class OutIt&gt; void bencode(OutIt out, const entry&amp; e);
3576 </pre>
3577 </blockquote>
3578 <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>
3579 <p>The <a class="reference" href="#entry">entry</a> class is the internal representation of the bencoded data
3580 and it can be used to retrieve information, an <a class="reference" href="#entry">entry</a> can also be build by
3581 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>
3582 iterator.</p>
3583 <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
3584 (<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
3585 are templates and are usually instantiated as <a class="reference" href="http://www.sgi.com/tech/stl/ostream_iterator.html">ostream_iterator</a>,
3586 <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
3587 functions will assume that the iterator refers to a character
3588 (<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
3589 in memory, you can do it like this:</p>
3590 <pre class="literal-block">
3591 std::vector&lt;char&gt; buffer;
3592 bencode(std::back_inserter(buf), e);
3593 </pre>
3594 <p>If you want to decode a torrent file from a buffer in memory, you can do it like this:</p>
3595 <pre class="literal-block">
3596 std::vector&lt;char&gt; buffer;
3597 // ...
3598 entry e = bdecode(buf.begin(), buf.end());
3599 </pre>
3600 <p>Or, if you have a raw char buffer:</p>
3601 <pre class="literal-block">
3602 const char* buf;
3603 // ...
3604 entry e = bdecode(buf, buf + data_size);
3605 </pre>
3606 <p>Now we just need to know how to retrieve information from the <a class="reference" href="#entry">entry</a>.</p>
3607 <p>If <tt class="docutils literal"><span class="pre">bdecode()</span></tt> encounters invalid encoded data in the range given to it
3608 it will throw <a class="reference" href="#invalid-encoding">invalid_encoding</a>.</p>
3609 </div>
3610 </div>
3611 <div class="section">
3612 <h1><a id="alerts" name="alerts">alerts</a></h1>
3613 <p>The <tt class="docutils literal"><span class="pre">pop_alert()</span></tt> function on session is the interface for retrieving
3614 alerts, warnings, messages and errors from libtorrent. If no alerts have
3615 been posted by libtorrent <tt class="docutils literal"><span class="pre">pop_alert()</span></tt> will return a default initialized
3616 <tt class="docutils literal"><span class="pre">auto_ptr</span></tt> object. If there is an alert in libtorrent's queue, the alert
3617 from the front of the queue is popped and returned.
3618 You can then use the alert object and query</p>
3619 <p>By default, only errors are reported. <tt class="docutils literal"><span class="pre">session::set_alert_mask()</span></tt> can be
3620 used to specify which kinds of events should be reported. The alert mask
3621 is a bitmask with the following bits:</p>
3622 <table border="1" class="docutils">
3623 <colgroup>
3624 <col width="32%" />
3625 <col width="68%" />
3626 </colgroup>
3627 <tbody valign="top">
3628 <tr><td><tt class="docutils literal"><span class="pre">error_notification</span></tt></td>
3629 <td><p class="first">Enables alerts that report an error. This includes:</p>
3630 <ul class="last simple">
3631 <li>tracker errors</li>
3632 <li>tracker warnings</li>
3633 <li>file errors</li>
3634 <li>resume data failures</li>
3635 <li>web seed errors</li>
3636 <li>.torrent files errors</li>
3637 <li>listen socket errors</li>
3638 <li>port mapping errors</li>
3639 </ul>
3640 </td>
3641 </tr>
3642 <tr><td><tt class="docutils literal"><span class="pre">peer_notification</span></tt></td>
3643 <td>Enables alerts when peers send invalid requests, get banned or
3644 snubbed.</td>
3645 </tr>
3646 <tr><td><tt class="docutils literal"><span class="pre">port_mapping_notification</span></tt></td>
3647 <td>Enables alerts for port mapping events. For NAT-PMP and UPnP.</td>
3648 </tr>
3649 <tr><td><tt class="docutils literal"><span class="pre">storage_notification</span></tt></td>
3650 <td>Enables alerts for events related to the storage. File errors and
3651 synchronization events for moving the storage, renaming files etc.</td>
3652 </tr>
3653 <tr><td><tt class="docutils literal"><span class="pre">tracker_notification</span></tt></td>
3654 <td>Enables all tracker events. Includes announcing to trackers,
3655 receiving responses, warnings and errors.</td>
3656 </tr>
3657 <tr><td><tt class="docutils literal"><span class="pre">debug_notification</span></tt></td>
3658 <td>Low level alerts for when peers are connected and disconnected.</td>
3659 </tr>
3660 <tr><td><tt class="docutils literal"><span class="pre">status_notification</span></tt></td>
3661 <td>Enables alerts for when a torrent or the session changes state.</td>
3662 </tr>
3663 <tr><td><tt class="docutils literal"><span class="pre">progress_notification</span></tt></td>
3664 <td>Alerts for when blocks are requested and completed. Also when
3665 pieces are completed.</td>
3666 </tr>
3667 <tr><td><tt class="docutils literal"><span class="pre">ip_block_notification</span></tt></td>
3668 <td>Alerts when a peer is blocked by the ip blocker or port blocker.</td>
3669 </tr>
3670 <tr><td><tt class="docutils literal"><span class="pre">all_categories</span></tt></td>
3671 <td>The full bitmask, representing all available categories.</td>
3672 </tr>
3673 </tbody>
3674 </table>
3675 <p>Every alert belongs to one or more category. There is a small cost involved in posting alerts. Only
3676 alerts that belong to an enabled category are posted. Setting the alert bitmask to 0 will disable
3677 all alerts</p>
3678 <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&lt;&gt;</span></tt> to get more detailed
3679 information on exactly which type it is. i.e. what kind of error it is. You can also use a
3680 <a class="reference" href="#dispatcher">dispatcher</a> mechanism that's available in libtorrent.</p>
3681 <p>All alert types are defined in the <tt class="docutils literal"><span class="pre">&lt;libtorrent/alert_types.hpp&gt;</span></tt> header file.</p>
3682 <p>The <tt class="docutils literal"><span class="pre">alert</span></tt> class is the base class that specific messages are derived from. This
3683 is its synopsis:</p>
3684 <pre class="literal-block">
3685 class alert
3686 {
3687 public:
3688
3689         enum category_t
3690         {
3691                 error_notification = <em>implementation defined</em>,
3692                 peer_notification = <em>implementation defined</em>,
3693                 port_mapping_notification = <em>implementation defined</em>,
3694                 storage_notification = <em>implementation defined</em>,
3695                 tracker_notification = <em>implementation defined</em>,
3696                 debug_notification = <em>implementation defined</em>,
3697                 status_notification = <em>implementation defined</em>,
3698                 progress_notification = <em>implementation defined</em>,
3699                 ip_block_notification = <em>implementation defined</em>,
3700
3701                 all_categories = <em>implementation defined</em>
3702         };
3703
3704         ptime timestamp() const;
3705
3706         virtual ~alert();
3707
3708         virtual std::string message() const = 0;
3709         virtual char const* what() const = 0;
3710         virtual int category() const = 0;
3711         virtual std::auto_ptr&lt;alert&gt; clone() const = 0;
3712 };
3713 </pre>
3714 <p><tt class="docutils literal"><span class="pre">what()</span></tt> returns a string literal describing the type of the alert. It does
3715 not include any information that might be bundled with the alert.</p>
3716 <p><tt class="docutils literal"><span class="pre">category()</span></tt> returns a bitmask specifying which categories this alert belong to.</p>
3717 <p><tt class="docutils literal"><span class="pre">clone()</span></tt> returns a pointer to a copy of the alert.</p>
3718 <p><tt class="docutils literal"><span class="pre">message()</span></tt> generate a string describing the alert and the information bundled
3719 with it. This is mainly intended for debug and development use. It is not suitable
3720 to use this for applications that may be localized. Instead, handle each alert
3721 type individually and extract and render the information from the alert depending
3722 on the locale.</p>
3723 <p>There's another alert base class that most alerts derives from, all the
3724 alerts that are generated for a specific torrent are derived from:</p>
3725 <pre class="literal-block">
3726 struct torrent_alert: alert
3727 {
3728         // ...
3729         torrent_handle handle;
3730 };
3731 </pre>
3732 <p>There's also a base class for all alerts referring to tracker events:</p>
3733 <pre class="literal-block">
3734 struct tracker_alert: torrent_alert
3735 {
3736         // ...
3737         std::string url;
3738 };
3739 </pre>
3740 <p>The specific alerts are:</p>
3741 <div class="section">
3742 <h2><a id="external-ip-alert" name="external-ip-alert">external_ip_alert</a></h2>
3743 <p>Whenever libtorrent learns about the machines external IP, this alert is
3744 generated. The external IP address can be acquired from the tracker (if it
3745 supports that) or from peers that supports the extension protocol.
3746 The address can be accessed through the <tt class="docutils literal"><span class="pre">external_address</span></tt> member.</p>
3747 <pre class="literal-block">
3748 struct external_ip_alert: alert
3749 {
3750         // ...
3751         address external_address;
3752 };
3753 </pre>
3754 </div>
3755 <div class="section">
3756 <h2><a id="listen-failed-alert" name="listen-failed-alert">listen_failed_alert</a></h2>
3757 <p>This alert is generated when none of the ports, given in the port range, to
3758 <a class="reference" href="#session">session</a> can be opened for listening. This alert doesn't have any extra
3759 data members.</p>
3760 </div>
3761 <div class="section">
3762 <h2><a id="portmap-error-alert" name="portmap-error-alert">portmap_error_alert</a></h2>
3763 <p>This alert is generated when a NAT router was successfully found but some
3764 part of the port mapping request failed. It contains a text message that
3765 may help the user figure out what is wrong. This alert is not generated in
3766 case it appears the client is not running on a NAT:ed network or if it
3767 appears there is no NAT router that can be remote controlled to add port
3768 mappings.</p>
3769 <p><tt class="docutils literal"><span class="pre">mapping</span></tt> refers to the mapping index of the port map that failed, i.e.
3770 the index returned from <a class="reference" href="#add-mapping">add_mapping</a>.</p>
3771 <p><tt class="docutils literal"><span class="pre">type</span></tt> is 0 for NAT-PMP and 1 for UPnP.</p>
3772 <pre class="literal-block">
3773 struct portmap_error_alert: alert
3774 {
3775         // ...
3776         int mapping;
3777         int type;
3778 };
3779 </pre>
3780 </div>
3781 <div class="section">
3782 <h2><a id="portmap-alert" name="portmap-alert">portmap_alert</a></h2>
3783 <p>This alert is generated when a NAT router was successfully found and
3784 a port was successfully mapped on it. On a NAT:ed network with a NAT-PMP
3785 capable router, this is typically generated once when mapping the TCP
3786 port and, if DHT is enabled, when the UDP port is mapped.</p>
3787 <p><tt class="docutils literal"><span class="pre">mapping</span></tt> refers to the mapping index of the port map that failed, i.e.
3788 the index returned from <a class="reference" href="#add-mapping">add_mapping</a>.</p>
3789 <p><tt class="docutils literal"><span class="pre">external_port</span></tt> is the external port allocated for the mapping.</p>
3790 <p><tt class="docutils literal"><span class="pre">type</span></tt> is 0 for NAT-PMP and 1 for UPnP.</p>
3791 <pre class="literal-block">
3792 struct portmap_alert: alert
3793 {
3794         // ...
3795         int mapping;
3796         int external_port;
3797         int type;
3798 };
3799 </pre>
3800 </div>
3801 <div class="section">
3802 <h2><a id="file-error-alert" name="file-error-alert">file_error_alert</a></h2>
3803 <p>If the storage fails to read or write files that it needs access to, this alert is
3804 generated and the torrent is paused.</p>
3805 <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>
3806 <p><tt class="docutils literal"><span class="pre">msg</span></tt> is the error message received from the OS.</p>
3807 <pre class="literal-block">
3808 struct file_error_alert: torrent_alert
3809 {
3810         // ...
3811         std::string file;
3812         std::string msg;
3813 };
3814 </pre>
3815 </div>
3816 <div class="section">
3817 <h2><a id="tracker-announce-alert" name="tracker-announce-alert">tracker_announce_alert</a></h2>
3818 <p>This alert is generated each time a tracker announce is sent (or attempted to be sent).
3819 There are no extra data members in this alert. The url can be found in the base class
3820 however.</p>
3821 <pre class="literal-block">
3822 struct tracker_announce_alert: tracker_alert
3823 {
3824         // ...
3825         int event;
3826 };
3827 </pre>
3828 <p>Event specifies what event was sent to the tracker. It is defined as:</p>
3829 <ol class="arabic simple" start="0">
3830 <li>None</li>
3831 <li>Completed</li>
3832 <li>Started</li>
3833 <li>Stopped</li>
3834 </ol>
3835 </div>
3836 <div class="section">
3837 <h2><a id="tracker-error-alert" name="tracker-error-alert">tracker_error_alert</a></h2>
3838 <p>This alert is generated on tracker time outs, premature disconnects, invalid response or
3839 a HTTP response other than &quot;200 OK&quot;. From the alert you can get the handle to the torrent
3840 the tracker belongs to.</p>
3841 <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.
3842 <tt class="docutils literal"><span class="pre">status_code</span></tt> is the code returned from the HTTP server. 401 means the tracker needs
3843 authentication, 404 means not found etc. If the tracker timed out, the code will be set
3844 to 0.</p>
3845 <pre class="literal-block">
3846 struct tracker_error_alert: tracker_alert
3847 {
3848         // ...
3849         int times_in_row;
3850         int status_code;
3851 };
3852 </pre>
3853 </div>
3854 <div class="section">
3855 <h2><a id="tracker-reply-alert" name="tracker-reply-alert">tracker_reply_alert</a></h2>
3856 <p>This alert is only for informational purpose. It is generated when a tracker announce
3857 succeeds. It is generated regardless what kind of tracker was used, be it UDP, HTTP or
3858 the DHT.</p>
3859 <pre class="literal-block">
3860 struct tracker_reply_alert: tracker_alert
3861 {
3862         // ...
3863         int num_peers;
3864 };
3865 </pre>
3866 <p>The <tt class="docutils literal"><span class="pre">num_peers</span></tt> tells how many peers were returned from the tracker. This is
3867 not necessarily all new peers, some of them may already be connected.</p>
3868 </div>
3869 <div class="section">
3870 <h2><a id="dht-reply-alert" name="dht-reply-alert">dht_reply_alert</a></h2>
3871 <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>
3872 is the number of peers we received in this packet. Typically these packets are
3873 received from multiple DHT nodes, and so the alerts are typically generated
3874 a few at a time.</p>
3875 <pre class="literal-block">
3876 struct dht_reply_alert: tracker_alert
3877 {
3878         // ...
3879         int num_peers;
3880 };
3881 </pre>
3882 </div>
3883 <div class="section">
3884 <h2><a id="tracker-warning-alert" name="tracker-warning-alert">tracker_warning_alert</a></h2>
3885 <p>This alert is triggered if the tracker reply contains a warning field. Usually this
3886 means that the tracker announce was successful, but the tracker has a message to
3887 the client. The <tt class="docutils literal"><span class="pre">msg</span></tt> string in the alert contains the warning message from
3888 the tracker.</p>
3889 <pre class="literal-block">
3890 struct tracker_warning_alert: tracker_alert
3891 {
3892         // ...
3893         std::string msg;
3894 };
3895 </pre>
3896 </div>
3897 <div class="section">
3898 <h2><a id="scrape-reply-alert" name="scrape-reply-alert">scrape_reply_alert</a></h2>
3899 <p>This alert is generated when a scrape request succeeds. <tt class="docutils literal"><span class="pre">incomplete</span></tt>
3900 and <tt class="docutils literal"><span class="pre">complete</span></tt> is the data returned in the scrape response. These numbers
3901 may be -1 if the reponse was malformed.</p>
3902 <pre class="literal-block">
3903 struct scrape_reply_alert: tracker_alert
3904 {
3905         // ...
3906         int incomplete;
3907         int complete;
3908 };
3909 </pre>
3910 </div>
3911 <div class="section">
3912 <h2><a id="scrape-failed-alert" name="scrape-failed-alert">scrape_failed_alert</a></h2>
3913 <p>If a scrape request fails, this alert is generated. This might be due
3914 to the tracker timing out, refusing connection or returning an http response
3915 code indicating an error. <tt class="docutils literal"><span class="pre">msg</span></tt> contains a message describing the error.</p>
3916 <pre class="literal-block">
3917 struct scrape_failed_alert: tracker_alert
3918 {
3919         // ...
3920         std::string msg;
3921 };
3922 </pre>
3923 </div>
3924 <div class="section">
3925 <h2><a id="url-seed-alert" name="url-seed-alert">url_seed_alert</a></h2>
3926 <p>This alert is generated when a HTTP seed name lookup fails.</p>
3927 <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>
3928 <pre class="literal-block">
3929 struct url_seed_alert: torrent_alert
3930 {
3931         // ...
3932         std::string url;
3933 };
3934 </pre>
3935 </div>
3936 <div class="section">
3937 <h2><a id="hash-failed-alert" name="hash-failed-alert">hash_failed_alert</a></h2>
3938 <p>This alert is generated when a finished piece fails its hash check. You can get the handle
3939 to the torrent which got the failed piece and the index of the piece itself from the alert.</p>
3940 <pre class="literal-block">
3941 struct hash_failed_alert: torrent_alert
3942 {
3943         // ...
3944         int piece_index;
3945 };
3946 </pre>
3947 </div>
3948 <div class="section">
3949 <h2><a id="peer-ban-alert" name="peer-ban-alert">peer_ban_alert</a></h2>
3950 <p>This alert is generated when a peer is banned because it has sent too many corrupt pieces
3951 to us. <tt class="docutils literal"><span class="pre">ip</span></tt> is the endpoint to the peer that was banned.</p>
3952 <pre class="literal-block">
3953 struct peer_ban_alert: torrent_alert
3954 {
3955         // ...
3956         asio::ip::tcp::endpoint ip;
3957 };
3958 </pre>
3959 </div>
3960 <div class="section">
3961 <h2><a id="peer-error-alert" name="peer-error-alert">peer_error_alert</a></h2>
3962 <p>This alert is generated when a peer sends invalid data over the peer-peer protocol. The peer
3963 will be disconnected, but you get its ip address from the alert, to identify it.</p>
3964 <pre class="literal-block">
3965 struct peer_error_alert: torrent_alert
3966 {
3967         // ...
3968         asio::ip::tcp::endpoint ip;
3969         peer_id id;
3970 };
3971 </pre>
3972 </div>
3973 <div class="section">
3974 <h2><a id="invalid-request-alert" name="invalid-request-alert">invalid_request_alert</a></h2>
3975 <p>This is a debug alert that is generated by an incoming invalid piece request.
3976 <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
3977 request from the peer.</p>
3978 <pre class="literal-block">
3979 struct invalid_request_alert: torrent_alert
3980 {
3981         invalid_request_alert(
3982                 peer_request const&amp; r
3983                 , torrent_handle const&amp; h
3984                 , asio::ip::tcp::endpoint const&amp; send
3985                 , peer_id const&amp; pid
3986                 , std::string const&amp; msg);
3987
3988         virtual std::auto_ptr&lt;alert&gt; clone() const;
3989
3990         asio::ip::tcp::endpoint ip;
3991         peer_request request;
3992         peer_id id;
3993 };
3994
3995
3996 struct peer_request
3997 {
3998         int piece;
3999         int start;
4000         int length;
4001         bool operator==(peer_request const&amp; r) const;
4002 };
4003 </pre>
4004 <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
4005 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
4006 should be read, and <tt class="docutils literal"><span class="pre">length</span></tt> is the amount of data it wants.</p>
4007 </div>
4008 <div class="section">
4009 <h2><a id="torrent-finished-alert" name="torrent-finished-alert">torrent_finished_alert</a></h2>
4010 <p>This alert is generated when a torrent switches from being a downloader to a seed.
4011 It will only be generated once per torrent. It contains a torrent_handle to the
4012 torrent in question.</p>
4013 <p>There are no additional data members in this alert.</p>
4014 </div>
4015 <div class="section">
4016 <h2><a id="metadata-failed-alert" name="metadata-failed-alert">metadata_failed_alert</a></h2>
4017 <p>This alert is generated when the metadata has been completely received and the info-hash
4018 failed to match it. i.e. the metadata that was received was corrupt. libtorrent will
4019 automatically retry to fetch it in this case. This is only relevant when running a
4020 torrent-less download, with the metadata extension provided by libtorrent.</p>
4021 <p>There are no additional data members in this alert.</p>
4022 </div>
4023 <div class="section">
4024 <h2><a id="metadata-received-alert" name="metadata-received-alert">metadata_received_alert</a></h2>
4025 <p>This alert is generated when the metadata has been completely received and the torrent
4026 can start downloading. It is not generated on torrents that are started with metadata, but
4027 only those that needs to download it from peers (when utilizing the libtorrent extension).</p>
4028 <p>There are no additional data members in this alert.</p>
4029 </div>
4030 <div class="section">
4031 <h2><a id="fastresume-rejected-alert" name="fastresume-rejected-alert">fastresume_rejected_alert</a></h2>
4032 <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
4033 files on disk did not match the fastresume file. The string explains the reason why the
4034 resume file was rejected.</p>
4035 <pre class="literal-block">
4036 struct fastresume_rejected_alert: torrent_alert
4037 {
4038         // ...
4039         std::string msg;
4040 };
4041 </pre>
4042 </div>
4043 <div class="section">
4044 <h2><a id="peer-blocked-alert" name="peer-blocked-alert">peer_blocked_alert</a></h2>
4045 <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
4046 address that was blocked.</p>
4047 <pre class="literal-block">
4048 struct peer_blocked_alert: alert
4049 {
4050         // ...
4051         address ip;
4052 };
4053 </pre>
4054 </div>
4055 <div class="section">
4056 <h2><a id="storage-moved-alert" name="storage-moved-alert">storage_moved_alert</a></h2>
4057 <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
4058 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
4059 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
4060 the storage.</p>
4061 <pre class="literal-block">
4062 struct storage_moved_alert: torrent_alert
4063 {
4064         // ...
4065         std::string path;
4066 };
4067 </pre>
4068 </div>
4069 <div class="section">
4070 <h2><a id="torrent-paused-alert" name="torrent-paused-alert">torrent_paused_alert</a></h2>
4071 <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
4072 generated once all disk IO is complete and the files in the torrent have been closed.
4073 This is useful for synchronizing with the disk.</p>
4074 <p>There are no additional data members in this alert.</p>
4075 </div>
4076 <div class="section">
4077 <h2><a id="torrent-resumed-alert" name="torrent-resumed-alert">torrent_resumed_alert</a></h2>
4078 <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
4079 generated when a torrent goes from a paused state to an active state.</p>
4080 <p>There are no additional data members in this alert.</p>
4081 </div>
4082 <div class="section">
4083 <h2><a id="save-resume-data-alert" name="save-resume-data-alert">save_resume_data_alert</a></h2>
4084 <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.
4085 It is generated once the disk IO thread is done writing the state for this torrent.
4086 The <tt class="docutils literal"><span class="pre">resume_data</span></tt> member points to the resume data.</p>
4087 <pre class="literal-block">
4088 struct save_resume_data_alert: torrent_alert
4089 {
4090         // ...
4091         boost::shared_ptr&lt;entry&gt; resume_data;
4092 };
4093 </pre>
4094 </div>
4095 <div class="section">
4096 <h2><a id="save-resume-data-failed-alert" name="save-resume-data-failed-alert">save_resume_data_failed_alert</a></h2>
4097 <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
4098 generating the resume data. <tt class="docutils literal"><span class="pre">msg</span></tt> describes what went wrong.</p>
4099 <pre class="literal-block">
4100 struct save_resume_data_failed_alert: torrent_alert
4101 {
4102         // ...
4103         std::string msg;
4104 };
4105 </pre>
4106 </div>
4107 <div class="section">
4108 <h2><a id="dispatcher" name="dispatcher">dispatcher</a></h2>
4109 <p>The <tt class="docutils literal"><span class="pre">handle_alert</span></tt> class is defined in <tt class="docutils literal"><span class="pre">&lt;libtorrent/alert.hpp&gt;</span></tt>.</p>
4110 <p>Examples usage:</p>
4111 <pre class="literal-block">
4112 struct my_handler
4113 {
4114         void operator()(portmap_error_alert const&amp; a)
4115         {
4116                 std::cout &lt;&lt; &quot;Portmapper: &quot; &lt;&lt; a.msg &lt;&lt; std::endl;
4117         }
4118
4119         void operator()(tracker_warning_alert const&amp; a)
4120         {
4121                 std::cout &lt;&lt; &quot;Tracker warning: &quot; &lt;&lt; a.msg &lt;&lt; std::endl;
4122         }
4123
4124         void operator()(torrent_finished_alert const&amp; a)
4125         {
4126                 // write fast resume data
4127                 // ...
4128
4129                 std::cout &lt;&lt; a.handle.get_torrent_info().name() &lt;&lt; &quot;completed&quot;
4130                         &lt;&lt; std::endl;
4131         }
4132 };
4133 </pre>
4134 <pre class="literal-block">
4135 std::auto_ptr&lt;alert&gt; a;
4136 a = ses.pop_alert();
4137 my_handler h;
4138 while (a.get())
4139 {
4140         handle_alert&lt;portmap_error_alert
4141                 , tracker_warning_alert
4142                 , torrent_finished_alert
4143         &gt;::handle_alert(h, a);
4144         a = ses.pop_alert();
4145 }
4146 </pre>
4147 <p>In this example 3 alert types are used. You can use any number of template
4148 parameters to select between more types. If the number of types are more than
4149 15, you can define <tt class="docutils literal"><span class="pre">TORRENT_MAX_ALERT_TYPES</span></tt> to a greater number before
4150 including <tt class="docutils literal"><span class="pre">&lt;libtorrent/alert.hpp&gt;</span></tt>.</p>
4151 </div>
4152 </div>
4153 <div class="section">
4154 <h1><a id="exceptions" name="exceptions">exceptions</a></h1>
4155 <p>There are a number of exceptions that can be thrown from different places in libtorrent,
4156 here's a complete list with description.</p>
4157 <div class="section">
4158 <h2><a id="invalid-handle" name="invalid-handle">invalid_handle</a></h2>
4159 <p>This exception is thrown when querying information from a <a class="reference" href="#torrent-handle">torrent_handle</a> that hasn't
4160 been initialized or that has become invalid.</p>
4161 <pre class="literal-block">
4162 struct invalid_handle: std::exception
4163 {
4164         const char* what() const throw();
4165 };
4166 </pre>
4167 </div>
4168 <div class="section">
4169 <h2><a id="duplicate-torrent" name="duplicate-torrent">duplicate_torrent</a></h2>
4170 <p>This is thrown by <a class="reference" href="#add-torrent">add_torrent()</a> if the torrent already has been added to
4171 the session. Since <a class="reference" href="#remove-torrent">remove_torrent()</a> is asynchronous, this exception may
4172 be thrown if the torrent is removed and then immediately added again.</p>
4173 <pre class="literal-block">
4174 struct duplicate_torrent: std::exception
4175 {
4176         const char* what() const throw();
4177 };
4178 </pre>
4179 </div>
4180 <div class="section">
4181 <h2><a id="invalid-encoding" name="invalid-encoding">invalid_encoding</a></h2>
4182 <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>
4183 <pre class="literal-block">
4184 struct invalid_encoding: std::exception
4185 {
4186         const char* what() const throw();
4187 };
4188 </pre>
4189 </div>
4190 <div class="section">
4191 <h2><a id="type-error" name="type-error">type_error</a></h2>
4192 <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
4193 match the type you want to extract from it.</p>
4194 <pre class="literal-block">
4195 struct type_error: std::runtime_error
4196 {
4197         type_error(const char* error);
4198 };
4199 </pre>
4200 </div>
4201 <div class="section">
4202 <h2><a id="invalid-torrent-file" name="invalid-torrent-file">invalid_torrent_file</a></h2>
4203 <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
4204 doesn't meet the requirements on what information has to be present in a torrent file.</p>
4205 <pre class="literal-block">
4206 struct invalid_torrent_file: std::exception
4207 {
4208         const char* what() const throw();
4209 };
4210 </pre>
4211 </div>
4212 </div>
4213 <div class="section">
4214 <h1><a id="storage-interface" name="storage-interface">storage_interface</a></h1>
4215 <p>The storage interface is a pure virtual class that can be implemented to
4216 change the behavior of the actual file storage. The interface looks like
4217 this:</p>
4218 <pre class="literal-block">
4219 struct storage_interface
4220 {
4221         virtual void initialize(bool allocate_files) = 0;
4222         virtual size_type read(char* buf, int slot, int offset, int size) = 0;
4223         virtual void write(const char* buf, int slot, int offset, int size) = 0;
4224         virtual bool move_storage(fs::path save_path) = 0;
4225         virtual bool verify_resume_data(lazy_entry&amp; rd, std::string&amp; error) = 0;
4226         virtual void write_resume_data(entry&amp; rd) const = 0;
4227         virtual void move_slot(int src_slot, int dst_slot) = 0;
4228         virtual void swap_slots(int slot1, int slot2) = 0;
4229         virtual void swap_slots3(int slot1, int slot2, int slot3) = 0;
4230         virtual sha1_hash hash_for_slot(int slot, partial_hash&amp; h, int piece_size) = 0;
4231         virtual void release_files() = 0;
4232         virtual void delete_files() = 0;
4233         virtual ~storage_interface() {}
4234 };
4235 </pre>
4236 <div class="section">
4237 <h2><a id="initialize" name="initialize">initialize()</a></h2>
4238 <blockquote>
4239 <pre class="literal-block">
4240 void initialize(bool allocate_files) = 0;
4241 </pre>
4242 </blockquote>
4243 <p>This function is called when the storage is to be initialized. The default storage
4244 will create directories and empty files at this point. If <tt class="docutils literal"><span class="pre">allocate_files</span></tt> is true,
4245 it will also <tt class="docutils literal"><span class="pre">ftruncate</span></tt> all files to their target size.</p>
4246 </div>
4247 <div class="section">
4248 <h2><a id="read" name="read">read()</a></h2>
4249 <blockquote>
4250 <pre class="literal-block">
4251 size_type read(char* buf, int slot, int offset, int size) = 0;
4252 </pre>
4253 </blockquote>
4254 <p>This function should read the data in the given slot and at the given offset
4255 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>
4256 <p>The return value is the number of bytes actually read.</p>
4257 </div>
4258 <div class="section">
4259 <h2><a id="write" name="write">write()</a></h2>
4260 <blockquote>
4261 <pre class="literal-block">
4262 void write(const char* buf, int slot, int offset, int size) = 0;
4263 </pre>
4264 </blockquote>
4265 <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
4266 <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>
4267 </div>
4268 <div class="section">
4269 <h2><a id="id12" name="id12">move_storage()</a></h2>
4270 <blockquote>
4271 <pre class="literal-block">
4272 bool move_storage(fs::path save_path) = 0;
4273 </pre>
4274 </blockquote>
4275 <p>This function should move all the files belonging to the storage to the new save_path.
4276 The default storage moves the single file or the directory of the torrent.</p>
4277 <p>Before moving the files, any open file handles may have to be closed, like
4278 <tt class="docutils literal"><span class="pre">release_files()</span></tt>.</p>
4279 </div>
4280 <div class="section">
4281 <h2><a id="verify-resume-data" name="verify-resume-data">verify_resume_data()</a></h2>
4282 <blockquote>
4283 <pre class="literal-block">
4284 bool verify_resume_data(entry&amp; rd, std::string&amp; error) = 0;
4285 </pre>
4286 </blockquote>
4287 <p>This function should verify the resume data <tt class="docutils literal"><span class="pre">rd</span></tt> with the files
4288 on disk. If the resume data seems to be up-to-date, return true. If
4289 not, set <tt class="docutils literal"><span class="pre">error</span></tt> to a description of what mismatched and return false.</p>
4290 <p>The default storage may compare file sizes and time stamps of the files.</p>
4291 </div>
4292 <div class="section">
4293 <h2><a id="write-resume-data" name="write-resume-data">write_resume_data()</a></h2>
4294 <blockquote>
4295 <pre class="literal-block">
4296 void write_resume_data(entry&amp; rd) const = 0;
4297 </pre>
4298 </blockquote>
4299 <p>This function should fill in resume data, the current state of the
4300 storage, in <tt class="docutils literal"><span class="pre">rd</span></tt>. The default storage adds file timestamps and
4301 sizes.</p>
4302 </div>
4303 <div class="section">
4304 <h2><a id="move-slot" name="move-slot">move_slot()</a></h2>
4305 <blockquote>
4306 <pre class="literal-block">
4307 void move_slot(int src_slot, int dst_slot) = 0;
4308 </pre>
4309 </blockquote>
4310 <p>This function should copy or move the data in slot <tt class="docutils literal"><span class="pre">src_slot</span></tt> to
4311 the slot <tt class="docutils literal"><span class="pre">dst_slot</span></tt>. This is only used in compact mode.</p>
4312 <p>If the storage caches slots, this could be implemented more
4313 efficient than reading and writing the data.</p>
4314 </div>
4315 <div class="section">
4316 <h2><a id="swap-slots" name="swap-slots">swap_slots()</a></h2>
4317 <blockquote>
4318 <pre class="literal-block">
4319 void swap_slots(int slot1, int slot2) = 0;
4320 </pre>
4321 </blockquote>
4322 <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
4323 storage uses a scratch buffer to read the data into, then moving the other
4324 slot and finally writing back the temporary slot's data</p>
4325 <p>This is only used in compact mode.</p>
4326 </div>
4327 <div class="section">
4328 <h2><a id="swap-slots3" name="swap-slots3">swap_slots3()</a></h2>
4329 <blockquote>
4330 <pre class="literal-block">
4331 void swap_slots3(int slot1, int slot2, int slot3) = 0;
4332 </pre>
4333 </blockquote>
4334 <p>This function should do a 3-way swap, or shift of the slots. <tt class="docutils literal"><span class="pre">slot1</span></tt>
4335 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
4336 should be moved to <tt class="docutils literal"><span class="pre">slot1</span></tt>.</p>
4337 <p>This is only used in compact mode.</p>
4338 </div>
4339 <div class="section">
4340 <h2><a id="hash-for-slot" name="hash-for-slot">hash_for_slot()</a></h2>
4341 <blockquote>
4342 <pre class="literal-block">
4343 sha1_hash hash_for_slot(int slot, partial_hash&amp; h, int piece_size) = 0;
4344 </pre>
4345 </blockquote>
4346 <p>The function should read the remaining bytes of the slot and hash it with the
4347 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>
4348 <pre class="literal-block">
4349 struct partial_hash
4350 {
4351         partial_hash();
4352         int offset;
4353         hasher h;
4354 };
4355 </pre>
4356 <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
4357 <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
4358 that is stored in the given slot.</p>
4359 <p>The function should return the hash of the piece stored in the slot.</p>
4360 </div>
4361 <div class="section">
4362 <h2><a id="release-files" name="release-files">release_files()</a></h2>
4363 <blockquote>
4364 <pre class="literal-block">
4365 void release_files() = 0;
4366 </pre>
4367 </blockquote>
4368 <p>This function should release all the file handles that it keeps open to files
4369 belonging to this storage. The default implementation just calls
4370 <tt class="docutils literal"><span class="pre">file_pool::release_files(this)</span></tt>.</p>
4371 </div>
4372 <div class="section">
4373 <h2><a id="delete-files" name="delete-files">delete_files()</a></h2>
4374 <blockquote>
4375 <pre class="literal-block">
4376 void delete_files() = 0;
4377 </pre>
4378 </blockquote>
4379 <p>This function should delete all files and directories belonging to this storage.</p>
4380 </div>
4381 </div>
4382 <div class="section">
4383 <h1><a id="queuing" name="queuing">queuing</a></h1>
4384 <p>libtorrent supports <em>queuing</em>. Which means it makes sure that a limited number of
4385 torrents are being downloaded at any given time, and once a torrent is completely
4386 downloaded, the next in line is started.</p>
4387 <p>Torrents that are <em>auto managed</em> are subject to the queuing and the active torrents
4388 limits. To make a torrent auto managed, set <tt class="docutils literal"><span class="pre">auto_managed</span></tt> to true when adding the
4389 torrent (see <a class="reference" href="#add-torrent">add_torrent()</a>).</p>
4390 <p>The limits of the number of downloading and seeding torrents are controlled via
4391 <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>.
4392 These limits takes non auto managed torrents into account as well. If there are
4393 more non-auto managed torrents being downloaded than the <tt class="docutils literal"><span class="pre">active_downloads</span></tt>
4394 setting, any auto managed torrents will be queued until torrents are removed so
4395 that the number drops below the limit.</p>
4396 <p>The default values are 8 active downloads and 5 active seeds.</p>
4397 <p>At a regular interval, torrents are checked if there needs to be any re-ordering of
4398 which torrents are active and which are queued. This interval can be controlled via
4399 <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>
4400 <p>For queuing to work, resume data needs to be saved and restored for all torrents.
4401 See <a class="reference" href="#save-resume-data">save_resume_data()</a>.</p>
4402 <div class="section">
4403 <h2><a id="downloading" name="downloading">downloading</a></h2>
4404 <p>Torrents that are currently being downloaded or incomplete (with bytes still to download)
4405 are queued. The torrents in the front of the queue are started to be actively downloaded
4406 and the rest are ordered with regards to their queue position. Any newly added torrent
4407 is placed at the end of the queue. Once a torrent is removed or turns into a seed, its
4408 queue position is -1 and all torrents that used to be after it in the queue, decreases their
4409 position in order to fill the gap.</p>
4410 <p>The queue positions are always in a sequence without any gaps.</p>
4411 <p>Lower queue position means closer to the front of the queue, and will be started sooner than
4412 torrents with higher queue positions.</p>
4413 <p>To query a torrent for its position in the queue, or change its position, see:
4414 <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>
4415 </div>
4416 <div class="section">
4417 <h2><a id="seeding" name="seeding">seeding</a></h2>
4418 <p>Auto managed seeding torrents are rotated, so that all of them are allocated a fair
4419 amount of seeding. Torrents with fewer completed <em>seed cycles</em> are prioritized for
4420 seeding. A seed cycle is completed when a torrent meets either the share ratio limit
4421 (uploaded bytes / downloaded bytes), the share time ratio (time seeding / time
4422 downloaing) or seed time limit (time seeded).</p>
4423 <p>The relevant settings to control these limits are <tt class="docutils literal"><span class="pre">share_ratio_limit</span></tt>,
4424 <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>
4425 </div>
4426 </div>
4427 <div class="section">
4428 <h1><a id="fast-resume" name="fast-resume">fast resume</a></h1>
4429 <p>The fast resume mechanism is a way to remember which pieces are downloaded
4430 and where they are put between sessions. You can generate fast resume data by
4431 calling <a class="reference" href="#save-resume-data">save_resume_data()</a> on <a class="reference" href="#torrent-handle">torrent_handle</a>. You can
4432 then save this data to disk and use it when resuming the torrent. libtorrent
4433 will not check the piece hashes then, and rely on the information given in the
4434 fast-resume data. The fast-resume data also contains information about which
4435 blocks, in the unfinished pieces, were downloaded, so it will not have to
4436 start from scratch on the partially downloaded pieces.</p>
4437 <p>To use the fast-resume data you simply give it to <a class="reference" href="#add-torrent">add_torrent()</a>, and it
4438 will skip the time consuming checks. It may have to do the checking anyway, if
4439 the fast-resume data is corrupt or doesn't fit the storage for that torrent,
4440 then it will not trust the fast-resume data and just do the checking.</p>
4441 <div class="section">
4442 <h2><a id="file-format" name="file-format">file format</a></h2>
4443 <p>The file format is a bencoded dictionary containing the following fields:</p>
4444 <table border="1" class="docutils">
4445 <colgroup>
4446 <col width="26%" />
4447 <col width="74%" />
4448 </colgroup>
4449 <tbody valign="top">
4450 <tr><td><tt class="docutils literal"><span class="pre">file-format</span></tt></td>
4451 <td>string: &quot;libtorrent resume file&quot;</td>
4452 </tr>
4453 <tr><td><tt class="docutils literal"><span class="pre">file-version</span></tt></td>
4454 <td>integer: 1</td>
4455 </tr>
4456 <tr><td><tt class="docutils literal"><span class="pre">info-hash</span></tt></td>
4457 <td>string, the info hash of the torrent this data is saved for.</td>
4458 </tr>
4459 <tr><td><tt class="docutils literal"><span class="pre">blocks</span> <span class="pre">per</span> <span class="pre">piece</span></tt></td>
4460 <td>integer, the number of blocks per piece. Must be: piece_size
4461 / (16 * 1024). Clamped to be within the range [1, 256]. It
4462 is the number of blocks per (normal sized) piece. Usually
4463 each block is 16 * 1024 bytes in size. But if piece size is
4464 greater than 4 megabytes, the block size will increase.</td>
4465 </tr>
4466 <tr><td><tt class="docutils literal"><span class="pre">pieces</span></tt></td>
4467 <td>A string with piece flags, one character per piece.
4468 Bit 1 means we have that piece.</td>
4469 </tr>
4470 <tr><td><tt class="docutils literal"><span class="pre">slots</span></tt></td>
4471 <td><p class="first">list of integers. The list maps slots to piece indices. It
4472 tells which piece is on which slot. If piece index is -2 it
4473 means it is free, that there's no piece there. If it is -1,
4474 means the slot isn't allocated on disk yet. The pieces have
4475 to meet the following requirement:</p>
4476 <p class="last">If there's a slot at the position of the piece index,
4477 the piece must be located in that slot.</p>
4478 </td>
4479 </tr>
4480 <tr><td><tt class="docutils literal"><span class="pre">peers</span></tt></td>
4481 <td><p class="first">list of dictionaries. Each dictionary has the following
4482 layout:</p>
4483 <table border="1" class="docutils">
4484 <colgroup>
4485 <col width="18%" />
4486 <col width="82%" />
4487 </colgroup>
4488 <tbody valign="top">
4489 <tr><td><tt class="docutils literal"><span class="pre">ip</span></tt></td>
4490 <td>string, the ip address of the peer. This is
4491 not a binary representation of the ip
4492 address, but the string representation. It
4493 may be an IPv6 string or an IPv4 string.</td>
4494 </tr>
4495 <tr><td><tt class="docutils literal"><span class="pre">port</span></tt></td>
4496 <td>integer, the listen port of the peer</td>
4497 </tr>
4498 </tbody>
4499 </table>
4500 <p class="last">These are the local peers we were connected to when this
4501 fast-resume data was saved.</p>
4502 </td>
4503 </tr>
4504 <tr><td><tt class="docutils literal"><span class="pre">unfinished</span></tt></td>
4505 <td><p class="first">list of dictionaries. Each dictionary represents an
4506 piece, and has the following layout:</p>
4507 <table border="1" class="last docutils">
4508 <colgroup>
4509 <col width="23%" />
4510 <col width="77%" />
4511 </colgroup>
4512 <tbody valign="top">
4513 <tr><td><tt class="docutils literal"><span class="pre">piece</span></tt></td>
4514 <td>integer, the index of the piece this entry
4515 refers to.</td>
4516 </tr>
4517 <tr><td><tt class="docutils literal"><span class="pre">bitmask</span></tt></td>
4518 <td>string, a binary bitmask representing the
4519 blocks that have been downloaded in this
4520 piece.</td>
4521 </tr>
4522 <tr><td><tt class="docutils literal"><span class="pre">adler32</span></tt></td>
4523 <td>The adler32 checksum of the data in the
4524 blocks specified by <tt class="docutils literal"><span class="pre">bitmask</span></tt>.</td>
4525 </tr>
4526 </tbody>
4527 </table>
4528 </td>
4529 </tr>
4530 <tr><td><tt class="docutils literal"><span class="pre">file</span> <span class="pre">sizes</span></tt></td>
4531 <td>list where each entry corresponds to a file in the file list
4532 in the metadata. Each entry has a list of two values, the
4533 first value is the size of the file in bytes, the second
4534 is the time stamp when the last time someone wrote to it.
4535 This information is used to compare with the files on disk.
4536 All the files must match exactly this information in order
4537 to consider the resume data as current. Otherwise a full
4538 re-check is issued.</td>
4539 </tr>
4540 <tr><td><tt class="docutils literal"><span class="pre">allocation</span></tt></td>
4541 <td>The allocation mode for the storage. Can be either <tt class="docutils literal"><span class="pre">full</span></tt>
4542 or <tt class="docutils literal"><span class="pre">compact</span></tt>. If this is full, the file sizes and
4543 timestamps are disregarded. Pieces are assumed not to have
4544 moved around even if the files have been modified after the
4545 last resume data checkpoint.</td>
4546 </tr>
4547 </tbody>
4548 </table>
4549 </div>
4550 </div>
4551 <div class="section">
4552 <h1><a id="threads" name="threads">threads</a></h1>
4553 <p>libtorrent starts 2 or 3 threads.</p>
4554 <blockquote>
4555 <ul class="simple">
4556 <li>The first thread is the main thread that will sit
4557 idle in a <tt class="docutils literal"><span class="pre">select()</span></tt> call most of the time. This thread runs the main loop
4558 that will send and receive data on all connections.</li>
4559 <li>The second thread is a hash-check thread. Whenever a torrent is added it will
4560 first be passed to this thread for checking the files that may already have been
4561 downloaded. If there is any resume data this thread will make sure it is valid
4562 and matches the files. Once the torrent has been checked, it is passed on to the
4563 main thread that will start it. The hash-check thread has a queue of torrents,
4564 it will only check one torrent at a time.</li>
4565 <li>The third thread is spawned by asio on systems that don't support
4566 non-blocking host name resolution to simulate non-blocking behavior.</li>
4567 </ul>
4568 </blockquote>
4569 </div>
4570 <div class="section">
4571 <h1><a id="storage-allocation" name="storage-allocation">storage allocation</a></h1>
4572 <p>There are three modes in which storage (files on disk) are allocated in libtorrent.</p>
4573 <ol class="arabic simple">
4574 <li>The traditional <em>full allocation</em> mode, where the entire files are filled up with
4575 zeros before anything is downloaded. libtorrent will look for sparse files support
4576 in the filesystem that is used for storage, and use sparse files or file system
4577 zero fill support if present. This means that on NTFS, full allocation mode will
4578 only allocate storage for the downloaded pieces.</li>
4579 <li>The <em>compact allocation</em> mode, where only files are allocated for actual
4580 pieces that have been downloaded. This is the default allocation mode in libtorrent.</li>
4581 <li>The <em>sparce allocation</em>, sparse files are used, and pieces are downloaded directly
4582 to where they belong. This is the recommended (and default) mode.</li>
4583 </ol>
4584 <p>The allocation mode is selected when a torrent is started. It is passed as an
4585 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>
4586 <p>The decision to use full allocation or compact allocation typically depends on whether
4587 any files are filtered and if the filesystem supports sparse files.</p>
4588 <div class="section">
4589 <h2><a id="sparse-allocation" name="sparse-allocation">sparse allocation</a></h2>
4590 <p>On filesystems that supports sparse files, this allocation mode will only use
4591 as much space as has been downloaded.</p>
4592 <blockquote>
4593 <ul class="simple">
4594 <li>It does not require an allocation pass on startup.</li>
4595 <li>It supports skipping files (setting prioirty to 0 to not download).</li>
4596 <li>Fast resume data will remain valid even when file time stamps are out of date.</li>
4597 </ul>
4598 </blockquote>
4599 </div>
4600 <div class="section">
4601 <h2><a id="full-allocation" name="full-allocation">full allocation</a></h2>
4602 <p>When a torrent is started in full allocation mode, the checker thread (see <a class="reference" href="#threads">threads</a>)
4603 will make sure that the entire storage is allocated, and fill any gaps with zeros.
4604 This will be skipped if the filesystem supports sparse files or automatic zero filling.
4605 It will of course still check for existing pieces and fast resume data. The main
4606 drawbacks of this mode are:</p>
4607 <blockquote>
4608 <ul class="simple">
4609 <li>It may take longer to start the torrent, since it will need to fill the files
4610 with zeros on some systems. This delay is linearly dependent on the size of
4611 the download.</li>
4612 <li>The download may occupy unnecessary disk space between download sessions. In case
4613 sparse files are not supported.</li>
4614 <li>Disk caches usually perform extremely poorly with random access to large files
4615 and may slow down a download considerably.</li>
4616 </ul>
4617 </blockquote>
4618 <p>The benefits of this mode are:</p>
4619 <blockquote>
4620 <ul class="simple">
4621 <li>Downloaded pieces are written directly to their final place in the files and the
4622 total number of disk operations will be fewer and may also play nicer to
4623 filesystems' file allocation, and reduce fragmentation.</li>
4624 <li>No risk of a download failing because of a full disk during download. Unless
4625 sparse files are being used.</li>
4626 <li>The fast resume data will be more likely to be usable, regardless of crashes or
4627 out of date data, since pieces won't move around.</li>
4628 <li>Can be used with the filter files feature.</li>
4629 </ul>
4630 </blockquote>
4631 </div>
4632 <div class="section">
4633 <h2><a id="compact-allocation" name="compact-allocation">compact allocation</a></h2>
4634 <p>The compact allocation will only allocate as much storage as it needs to keep the
4635 pieces downloaded so far. This means that pieces will be moved around to be placed
4636 at their final position in the files while downloading (to make sure the completed
4637 download has all its pieces in the correct place). So, the main drawbacks are:</p>
4638 <blockquote>
4639 <ul class="simple">
4640 <li>More disk operations while downloading since pieces are moved around.</li>
4641 <li>Potentially more fragmentation in the filesystem.</li>
4642 <li>Cannot be used while filtering files.</li>
4643 </ul>
4644 </blockquote>
4645 <p>The benefits though, are:</p>
4646 <blockquote>
4647 <ul class="simple">
4648 <li>No startup delay, since the files doesn't need allocating.</li>
4649 <li>The download will not use unnecessary disk space.</li>
4650 <li>Disk caches perform much better than in full allocation and raises the download
4651 speed limit imposed by the disk.</li>
4652 <li>Works well on filesystems that doesn't support sparse files.</li>
4653 </ul>
4654 </blockquote>
4655 <p>The algorithm that is used when allocating pieces and slots isn't very complicated.
4656 For the interested, a description follows.</p>
4657 <p>storing a piece:</p>
4658 <ol class="arabic simple">
4659 <li>let <strong>A</strong> be a newly downloaded piece, with index <strong>n</strong>.</li>
4660 <li>let <strong>s</strong> be the number of slots allocated in the file we're
4661 downloading to. (the number of pieces it has room for).</li>
4662 <li>if <strong>n</strong> &gt;= <strong>s</strong> then allocate a new slot and put the piece there.</li>
4663 <li>if <strong>n</strong> &lt; <strong>s</strong> then allocate a new slot, move the data at
4664 slot <strong>n</strong> to the new slot and put <strong>A</strong> in slot <strong>n</strong>.</li>
4665 </ol>
4666 <p>allocating a new slot:</p>
4667 <ol class="arabic simple">
4668 <li>if there's an unassigned slot (a slot that doesn't
4669 contain any piece), return that slot index.</li>
4670 <li>append the new slot at the end of the file (or find an unused slot).</li>
4671 <li>let <strong>i</strong> be the index of newly allocated slot</li>
4672 <li>if we have downloaded piece index <strong>i</strong> already (to slot <strong>j</strong>) then<ol class="arabic">
4673 <li>move the data at slot <strong>j</strong> to slot <strong>i</strong>.</li>
4674 <li>return slot index <strong>j</strong> as the newly allocated free slot.</li>
4675 </ol>
4676 </li>
4677 <li>return <strong>i</strong> as the newly allocated slot.</li>
4678 </ol>
4679 </div>
4680 </div>
4681 <div class="section">
4682 <h1><a id="extensions" name="extensions">extensions</a></h1>
4683 <p>These extensions all operates within the <a class="reference" href="extension_protocol.html">extension protocol</a>. The
4684 name of the extension is the name used in the extension-list packets,
4685 and the payload is the data in the extended message (not counting the
4686 length-prefix, message-id nor extension-id).</p>
4687 <p>Note that since this protocol relies on one of the reserved bits in the
4688 handshake, it may be incompatible with future versions of the mainline
4689 bittorrent client.</p>
4690 <p>These are the extensions that are currently implemented.</p>
4691 <div class="section">
4692 <h2><a id="metadata-from-peers" name="metadata-from-peers">metadata from peers</a></h2>
4693 <p>Extension name: &quot;LT_metadata&quot;</p>
4694 <p>The point with this extension is that you don't have to distribute the
4695 metadata (.torrent-file) separately. The metadata can be distributed
4696 through the bittorrent swarm. The only thing you need to download such
4697 a torrent is the tracker url and the info-hash of the torrent.</p>
4698 <p>It works by assuming that the initial seeder has the metadata and that
4699 the metadata will propagate through the network as more peers join.</p>
4700 <p>There are three kinds of messages in the metadata extension. These packets
4701 are put as payload to the extension message. The three packets are:</p>
4702 <blockquote>
4703 <ul class="simple">
4704 <li>request metadata</li>
4705 <li>metadata</li>
4706 <li>don't have metadata</li>
4707 </ul>
4708 </blockquote>
4709 <p>request metadata:</p>
4710 <table border="1" class="docutils">
4711 <colgroup>
4712 <col width="17%" />
4713 <col width="23%" />
4714 <col width="61%" />
4715 </colgroup>
4716 <thead valign="bottom">
4717 <tr><th class="head">size</th>
4718 <th class="head">name</th>
4719 <th class="head">description</th>
4720 </tr>
4721 </thead>
4722 <tbody valign="top">
4723 <tr><td>uint8_t</td>
4724 <td>msg_type</td>
4725 <td>Determines the kind of message this is
4726 0 means 'request metadata'</td>
4727 </tr>
4728 <tr><td>uint8_t</td>
4729 <td>start</td>
4730 <td>The start of the metadata block that
4731 is requested. It is given in 256:ths
4732 of the total size of the metadata,
4733 since the requesting client don't know
4734 the size of the metadata.</td>
4735 </tr>
4736 <tr><td>uint8_t</td>
4737 <td>size</td>
4738 <td>The size of the metadata block that is
4739 requested. This is also given in
4740 256:ths of the total size of the
4741 metadata. The size is given as size-1.
4742 That means that if this field is set
4743 0, the request wants one 256:th of the
4744 metadata.</td>
4745 </tr>
4746 </tbody>
4747 </table>
4748 <p>metadata:</p>
4749 <table border="1" class="docutils">
4750 <colgroup>
4751 <col width="17%" />
4752 <col width="23%" />
4753 <col width="61%" />
4754 </colgroup>
4755 <thead valign="bottom">
4756 <tr><th class="head">size</th>
4757 <th class="head">name</th>
4758 <th class="head">description</th>
4759 </tr>
4760 </thead>
4761 <tbody valign="top">
4762 <tr><td>uint8_t</td>
4763 <td>msg_type</td>
4764 <td>1 means 'metadata'</td>
4765 </tr>
4766 <tr><td>int32_t</td>
4767 <td>total_size</td>
4768 <td>The total size of the metadata, given
4769 in number of bytes.</td>
4770 </tr>
4771 <tr><td>int32_t</td>
4772 <td>offset</td>
4773 <td>The offset of where the metadata block
4774 in this message belongs in the final
4775 metadata. This is given in bytes.</td>
4776 </tr>
4777 <tr><td>uint8_t[]</td>
4778 <td>metadata</td>
4779 <td>The actual metadata block. The size of
4780 this part is given implicit by the
4781 length prefix in the bittorrent
4782 protocol packet.</td>
4783 </tr>
4784 </tbody>
4785 </table>
4786 <p>Don't have metadata:</p>
4787 <table border="1" class="docutils">
4788 <colgroup>
4789 <col width="17%" />
4790 <col width="23%" />
4791 <col width="61%" />
4792 </colgroup>
4793 <thead valign="bottom">
4794 <tr><th class="head">size</th>
4795 <th class="head">name</th>
4796 <th class="head">description</th>
4797 </tr>
4798 </thead>
4799 <tbody valign="top">
4800 <tr><td>uint8_t</td>
4801 <td>msg_type</td>
4802 <td>2 means 'I don't have metadata'.
4803 This message is sent as a reply to a
4804 metadata request if the the client
4805 doesn't have any metadata.</td>
4806 </tr>
4807 </tbody>
4808 </table>
4809 </div>
4810 <div class="section">
4811 <h2><a id="http-seeding" name="http-seeding">HTTP seeding</a></h2>
4812 <p>The HTTP seed extension implements <a class="reference" href="http://www.getright.com/seedtorrent.html">this specification</a>.</p>
4813 <p>The libtorrent implementation assumes that, if the URL ends with a slash
4814 ('/'), the filename should be appended to it in order to request pieces from
4815 that file. The way this works is that if the torrent is a single-file torrent,
4816 only that filename is appended. If the torrent is a multi-file torrent, the
4817 torrent's name '/' the file name is appended. This is the same directory
4818 structure that libtorrent will download torrents into.</p>
4819 </div>
4820 </div>
4821 <div class="section">
4822 <h1><a id="filename-checks" name="filename-checks">filename checks</a></h1>
4823 <p>Boost.Filesystem will by default check all its paths to make sure they conform
4824 to filename requirements on many platforms. If you don't want this check, you can
4825 set it to either only check for native filesystem requirements or turn it off
4826 altogether. You can use:</p>
4827 <pre class="literal-block">
4828 boost::filesystem::path::default_name_check(boost::filesystem::native);
4829 </pre>
4830 <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>
4831 </div>
4832 <div class="section">
4833 <h1><a id="acknowledgments" name="acknowledgments">acknowledgments</a></h1>
4834 <p>Written by Arvid Norberg. Copyright © 2003-2006</p>
4835 <p>Contributions by Magnus Jonsson, Daniel Wallin and Cory Nelson</p>
4836 <p>Lots of testing, suggestions and contributions by Massaroddel and Tianhao Qiu.</p>
4837 <p>Big thanks to Michael Wojciechowski and Peter Koeleman for making the autotools
4838 scripts.</p>
4839 <p>Thanks to Reimond Retz for bugfixes, suggestions and testing</p>
4840 <p>Thanks to <a class="reference" href="http://www.cs.umu.se">University of Umeå</a> for providing development and test hardware.</p>
4841 <p>Project is hosted by sourceforge.</p>
4842 <p><a class="reference" href="http://sourceforge.net"><img alt="sf_logo" src="http://sourceforge.net/sflogo.php?group_id=7994" /></a></p>
4843 </div>
4844 </div>
4845 </body>
4846 </html>