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