| blob | f23744f2b3c977ed9d69e9ae0ef1e58e768295fe |
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
4 <head>
10 </head>
11 <body>
19 <td>Arvid Norberg, <a class="last reference" href="mailto:arvid@rasterbar.com">arvid@rasterbar.com</a></td></tr>
22 </tbody>
23 </table>
28 <li><a class="reference" href="#primitive-network-types" id="id17">primitive network types</a></li>
34 <li><a class="reference" href="#remove-torrent-find-torrent-get-torrents" id="id23">remove_torrent() find_torrent() get_torrents()</a></li>
35 <li><a class="reference" href="#set-upload-rate-limit-set-download-rate-limit-upload-rate-limit-download-rate-limit" id="id24">set_upload_rate_limit() set_download_rate_limit() upload_rate_limit() download_rate_limit()</a></li>
36 <li><a class="reference" href="#set-max-uploads-set-max-connections" id="id25">set_max_uploads() set_max_connections()</a></li>
37 <li><a class="reference" href="#num-uploads-num-connections" id="id26">num_uploads() num_connections()</a></li>
38 <li><a class="reference" href="#set-max-half-open-connections" id="id27">set_max_half_open_connections()</a></li>
41 <li><a class="reference" href="#is-listening-listen-port-listen-on" id="id30">is_listening() listen_port() listen_on()</a></li>
42 <li><a class="reference" href="#pop-alert-set-severity-level" id="id31">pop_alert() set_severity_level()</a></li>
44 <li><a class="reference" href="#set-peer-proxy-set-web-seed-proxy-set-tracker-proxy-set-dht-proxy" id="id33">set_peer_proxy() set_web_seed_proxy() set_tracker_proxy() set_dht_proxy()</a></li>
45 <li><a class="reference" href="#peer-proxy-web-seed-proxy-tracker-proxy-dht-proxy" id="id34">peer_proxy() web_seed_proxy() tracker_proxy() dht_proxy()</a></li>
46 <li><a class="reference" href="#start-dht-stop-dht-set-dht-settings-dht-state" id="id35">start_dht() stop_dht() set_dht_settings() dht_state()</a></li>
47 <li><a class="reference" href="#add-dht-node-add-dht-router" id="id36">add_dht_node() add_dht_router()</a></li>
48 </ul>
49 </li>
51 <li><a class="reference" href="#integer-string-list-dict-type" id="id38">integer() string() list() dict() type()</a></li>
54 </ul>
55 </li>
58 <li><a class="reference" href="#set-comment-set-piece-size-set-creator-set-hash-add-tracker-add-file" id="id43">set_comment() set_piece_size() set_creator() set_hash() add_tracker() add_file()</a></li>
60 <li><a class="reference" href="#begin-files-end-files-rbegin-files-rend-files" id="id45">begin_files() end_files() rbegin_files() rend_files()</a></li>
67 <li><a class="reference" href="#total-size-piece-length-piece-size-num-pieces" id="id52">total_size() piece_length() piece_size() num_pieces()</a></li>
68 <li><a class="reference" href="#hash-for-piece-info-hash" id="id53">hash_for_piece() info_hash()</a></li>
69 <li><a class="reference" href="#name-comment-creation-date-creator" id="id54">name() comment() creation_date() creator()</a></li>
73 </ul>
74 </li>
76 <li><a class="reference" href="#piece-priority-prioritize-pieces-piece-priorities-prioritize-files" id="id59">piece_priority() prioritize_pieces() piece_priorities() prioritize_files()</a></li>
84 <li><a class="reference" href="#set-upload-limit-set-download-limit-upload-limit-download-limit" id="id67">set_upload_limit() set_download_limit() upload_limit() download_limit()</a></li>
85 <li><a class="reference" href="#set-sequenced-download-threshold" id="id68">set_sequenced_download_threshold()</a></li>
86 <li><a class="reference" href="#set-peer-upload-limit-set-peer-download-limit" id="id69">set_peer_upload_limit() set_peer_download_limit()</a></li>
87 <li><a class="reference" href="#pause-resume-is-paused" id="id70">pause() resume() is_paused()</a></li>
92 <li><a class="reference" href="#trackers-replace-trackers" id="id75">trackers() replace_trackers()</a></li>
103 </ul>
104 </li>
114 </ul>
115 </li>
123 <li><a class="reference" href="#supports-sparse-files" id="id102">supports_sparse_files()</a></li>
124 </ul>
125 </li>
131 <li><a class="reference" href="#tracker-announce-alert" id="id108">tracker_announce_alert</a></li>
134 <li><a class="reference" href="#tracker-warning-alert" id="id111">tracker_warning_alert</a></li>
139 <li><a class="reference" href="#invalid-request-alert" id="id116">invalid_request_alert</a></li>
140 <li><a class="reference" href="#torrent-finished-alert" id="id117">torrent_finished_alert</a></li>
141 <li><a class="reference" href="#metadata-failed-alert" id="id118">metadata_failed_alert</a></li>
142 <li><a class="reference" href="#metadata-received-alert" id="id119">metadata_received_alert</a></li>
143 <li><a class="reference" href="#fastresume-rejected-alert" id="id120">fastresume_rejected_alert</a></li>
146 </ul>
147 </li>
154 </ul>
155 </li>
158 </ul>
159 </li>
164 </ul>
165 </li>
169 </ul>
170 </li>
173 </ul>
174 </div>
177 <p>The interface of libtorrent consists of a few classes. The main class is
178 the <tt class="docutils literal"><span class="pre">session</span></tt>, it contains the main loop that serves all torrents.</p>
180 <ul>
182 </li>
183 <li><p class="first">parse .torrent-files and add them to the session (see <a class="reference" href="#bdecode-bencode">bdecode() bencode()</a>)</p>
184 </li>
186 <blockquote>
188 <li>query the torrent_handles for progress (see <a class="reference" href="#torrent-handle">torrent_handle</a>)</li>
191 </ul>
192 </blockquote>
193 </li>
196 </li>
198 </li>
199 </ul>
201 </div>
204 <p>There are a few typedefs in the <tt class="docutils literal"><span class="pre">libtorrent</span></tt> namespace which pulls
205 in network types from the <tt class="docutils literal"><span class="pre">asio</span></tt> namespace. These are:</p>
207 typedef asio::ip::address address;
208 typedef asio::ip::address_v4 address_v4;
209 typedef asio::ip::address_v6 address_v6;
210 using asio::ip::tcp;
211 using asio::ip::udp;
212 </pre>
213 <p>These are declared in the <tt class="docutils literal"><span class="pre"><libtorrent/socket.hpp></span></tt> header.</p>
214 <p>The <tt class="docutils literal"><span class="pre">using</span></tt> statements will give easy access to:</p>
216 tcp::endpoint
217 udp::endpoint
218 </pre>
219 <p>Which are the endpoint types used in libtorrent. An endpoint is an address
220 with an associated port.</p>
221 </div>
224 <p>The <tt class="docutils literal"><span class="pre">session</span></tt> class has the following synopsis:</p>
226 class session: public boost::noncopyable
227 {
229 session(fingerprint const& print
230 = libtorrent::fingerprint(
233 session(
234 fingerprint const& print
236 , char const* listen_interface = 0);
238 torrent_handle add_torrent(
239 torrent_info const& ti
240 , boost::filesystem::path const& save_path
241 , entry const& resume_data = entry()
242 , bool compact_mode = true
245 torrent_handle add_torrent(
246 char const* tracker_url
247 , sha1_hash const& info_hash
248 , char const* name
249 , boost::filesystem::path const& save_path
250 , entry const& resume_data = entry()
251 , bool compact_mode = true
254 session_proxy abort();
256 void remove_torrent(torrent_handle const& h);
257 torrent_handle find_torrent(sha_hash const& ih);
260 void set_settings(
261 session_settings const& settings);
263 void set_upload_rate_limit(int bytes_per_second);
264 int upload_rate_limit() const;
265 void set_download_rate_limit(int bytes_per_second);
266 int download_rate_limit() const;
267 void set_max_uploads(int limit);
268 void set_max_connections(int limit);
269 void set_max_half_open_connections(int limit);
271 void set_peer_proxy(proxy_settings const& s);
272 void set_web_seed_proxy(proxy_settings const& s);
273 void set_tracker_proxy(proxy_settings const& s);
275 proxy_settings const& peer_proxy() const;
276 proxy_settings const& web_seed_proxy() const;
277 proxy_settings const& tracker_proxy() const;
279 int num_uploads() const;
280 int num_connections() const;
282 void set_ip_filter(ip_filter const& f);
284 session_status status() const;
286 bool is_listening() const;
287 unsigned short listen_port() const;
288 bool listen_on(
290 , char const* interface = 0);
293 void set_severity_level(alert::severity_t s);
295 void add_extension(boost::function<
298 void start_dht();
299 void stop_dht();
300 void set_dht_settings(
301 dht_settings const& settings);
302 entry dht_state() const;
303 void add_dht_node(std::pair<std::string
305 void add_dht_router(std::pair<std::string
307 };
308 </pre>
309 <p>Once it's created, the session object will spawn the main thread that will do all the work.
310 The main thread will be idle as long it doesn't have any torrents to participate in.</p>
313 <blockquote>
315 session(fingerprint const& print
317 session(fingerprint const& print
319 , char const* listen_interface = 0);
320 </pre>
321 </blockquote>
322 <p>If the fingerprint in the first overload is omited, the client will get a default
323 fingerprint stating the version of libtorrent. The fingerprint is a short string that will be
324 used in the peer-id to identify the client and the client's version. For more details see the
325 <a class="reference" href="#fingerprint">fingerprint</a> class. The constructor that only takes a fingerprint will not open a
326 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>.
327 The other constructor, that takes a port range and an interface as well as the fingerprint
328 will automatically try to listen on a port on the given interface. For more information about
329 the parameters, see <tt class="docutils literal"><span class="pre">listen_on()</span></tt> function.</p>
330 </div>
333 <p>The destructor of session will notify all trackers that our torrents have been shut down.
334 If some trackers are down, they will time out. All this before the destructor of session
335 returns. So, it's advised that any kind of interface (such as windows) are closed before
336 destructing the session object. Because it can take a few second for it to finish. The
337 timeout can be set with <tt class="docutils literal"><span class="pre">set_settings()</span></tt>.</p>
338 </div>
342 session_proxy abort();
343 </pre>
344 <p>In case you want to destruct the session asynchrounously, you can request a session
345 destruction proxy. If you don't do this, the destructor of the session object will
346 block while the trackers are contacted. If you keep one <tt class="docutils literal"><span class="pre">session_proxy</span></tt> to the
347 session when destructing it, the destructor will not block, but start to close down
348 the session, the destructor of the proxy will then synchronize the threads. So, the
349 destruction of the session is performed from the <tt class="docutils literal"><span class="pre">session</span></tt> destructor call until the
350 <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
351 on it (since the session is being closed down, no operations are allowed on it). The
352 only valid operation is calling the destructor:</p>
354 class session_proxy
355 {
356 public:
357 session_proxy();
358 ~session_proxy()
359 };
360 </pre>
361 </div>
364 <blockquote>
366 torrent_handle add_torrent(
367 torrent_info const& ti
368 , boost::filesystem::path const& save_path
369 , entry const& resume_data = entry()
370 , bool compact_mode = true
373 torrent_handle add_torrent(
374 char const* tracker_url
375 , sha1_hash const& info_hash
376 , char const* name
377 , boost::filesystem::path const& save_path
378 , entry const& resume_data = entry()
379 , bool compact_mode = true
381 </pre>
382 </blockquote>
383 <p>You add torrents through the <tt class="docutils literal"><span class="pre">add_torrent()</span></tt> function where you give an
384 object representing the information found in the torrent file and the path where you
385 want to save the files. The <tt class="docutils literal"><span class="pre">save_path</span></tt> will be prepended to the directory
386 structure in the torrent-file.</p>
387 <p>If the torrent you are trying to add already exists in the session (is either queued
388 for checking, being checked or downloading) <tt class="docutils literal"><span class="pre">add_torrent()</span></tt> will throw
389 <a class="reference" href="#duplicate-torrent">duplicate_torrent</a> which derives from <tt class="docutils literal"><span class="pre">std::exception</span></tt>.</p>
390 <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
391 is available. The fast-resume data can be acquired from a running torrent by calling
392 <tt class="docutils literal"><span class="pre">torrent_handle::write_resume_data()</span></tt>. See <a class="reference" href="#fast-resume">fast resume</a>.</p>
393 <p>The <tt class="docutils literal"><span class="pre">compact_mode</span></tt> parameter refers to the layout of the storage for this torrent. If
394 set to true (default), the storage will grow as more pieces are downloaded, and pieces
395 are rearranged to finally be in their correct places once the entire torrent has been
396 downloaded. If it is false, the entire storage is allocated before download begins. I.e.
397 the files contained in the torrent are filled with zeros, and each downloaded piece
398 is put in its final place directly when downloaded. For more info, see <a class="reference" href="#storage-allocation">storage allocation</a>.</p>
399 <p><tt class="docutils literal"><span class="pre">block_size</span></tt> sets the preferred request size, i.e. the number of bytes to request from
400 a peer at a time. This block size must be a divisor of the piece size, and since the piece
401 size is an even power of 2, so must the block size be. If the block size given here turns
402 out to be greater than the piece size, it will simply be clamped to the piece size.</p>
403 <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
404 about the torrent's progress, its peers etc. It is also used to abort a torrent.</p>
405 <p>The second overload that takes a tracker url and an info-hash instead of metadata
406 (<tt class="docutils literal"><span class="pre">torrent_info</span></tt>) can be used with torrents where (at least some) peers support
407 the metadata extension. For the overload to be available, libtorrent must be built
408 with extensions enabled (<tt class="docutils literal"><span class="pre">TORRENT_ENABLE_EXTENSIONS</span></tt> defined). It also takes an
409 optional <tt class="docutils literal"><span class="pre">name</span></tt> argument. This may be 0 in case no name should be assigned to the
410 torrent. In case it's not 0, the name is used for the torrent as long as it doesn't
411 have metadata. See <tt class="docutils literal"><span class="pre">torrent_handle::name</span></tt>.</p>
412 </div>
415 <blockquote>
417 void remove_torrent(torrent_handle const& h);
418 torrent_handle find_torrent(sha_hash const& ih);
420 </pre>
421 </blockquote>
422 <p><tt class="docutils literal"><span class="pre">remove_torrent()</span></tt> will close all peer connections associated with the torrent and tell
423 the tracker that we've stopped participating in the swarm.</p>
424 <p><tt class="docutils literal"><span class="pre">find_torrent()</span></tt> looks for a torrent with the given info-hash. In case there
425 is such a torrent in the session, a torrent_handle to that torrent is returned.
426 In case the torrent cannot be found, an invalid torrent_handle is returned.</p>
427 <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>
428 <p><tt class="docutils literal"><span class="pre">get_torrents()</span></tt> returns a vector of torrent_handles to all the torrents
429 currently in the session.</p>
430 </div>
431 <div class="section" id="set-upload-rate-limit-set-download-rate-limit-upload-rate-limit-download-rate-limit">
432 <h2>set_upload_rate_limit() set_download_rate_limit() upload_rate_limit() download_rate_limit()</h2>
433 <blockquote>
435 void set_upload_rate_limit(int bytes_per_second);
436 void set_download_rate_limit(int bytes_per_second);
437 int upload_rate_limit() const;
438 int download_rate_limit() const;
439 </pre>
440 </blockquote>
441 <p><tt class="docutils literal"><span class="pre">set_upload_rate_limit()</span></tt> set the maximum number of bytes allowed to be
442 sent to peers per second. This bandwidth is distributed among all the peers. If
443 you don't want to limit upload rate, you can set this to -1 (the default).
444 <tt class="docutils literal"><span class="pre">set_download_rate_limit()</span></tt> works the same way but for download rate instead
445 of upload rate.
446 <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
447 set limits.</p>
448 </div>
451 <blockquote>
453 void set_max_uploads(int limit);
454 void set_max_connections(int limit);
455 </pre>
456 </blockquote>
457 <p>These functions will set a global limit on the number of unchoked peers (uploads)
458 and the number of connections opened. The number of connections is set to a hard
459 minimum of at least two connections per torrent, so if you set a too low
460 connections limit, and open too many torrents, the limit will not be met. The
461 number of uploads is at least one per torrent.</p>
462 </div>
465 <blockquote>
467 int num_uploads() const;
468 int num_connections() const;
469 </pre>
470 </blockquote>
471 <p>Returns the number of currently unchoked peers and the number of connections
472 (including half-open ones) respectively.</p>
473 </div>
476 <blockquote>
478 void set_max_half_open_connections(int limit);
479 </pre>
480 </blockquote>
481 <p>Sets the maximum number of half-open connections libtorrent will have when
482 connecting to peers. A half-open connection is one where connect() has been
483 called, but the connection still hasn't been established (nor failed). Windows
484 XP Service Pack 2 sets a default, system wide, limit of the number of half-open
485 connections to 10. So, this limit can be used to work nicer together with
486 other network applications on that system. The default is to have no limit,
487 and passing -1 as the limit, means to have no limit. When limiting the number
488 of simultaneous connection attempts, peers will be put in a queue waiting for
489 their turn to get connected.</p>
490 </div>
493 <blockquote>
495 void set_ip_filter(ip_filter const& filter);
496 </pre>
497 </blockquote>
498 <p>Sets a filter that will be used to reject and accept incoming as well as outgoing
499 connections based on their originating ip address. The default filter will allow
500 connections to any ip address. To build a set of rules for which addresses are
502 <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
503 generated.</p>
504 </div>
507 <blockquote>
509 session_status status() const;
510 </pre>
511 </blockquote>
512 <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>
513 struct has the following members:</p>
515 struct session_status
516 {
517 bool has_incoming_connections;
519 float upload_rate;
520 float download_rate;
522 float payload_upload_rate;
523 float payload_download_rate;
525 size_type total_download;
526 size_type total_upload;
528 size_type total_payload_download;
529 size_type total_payload_upload;
531 int num_peers;
533 int dht_nodes;
534 int dht_cache_nodes;
535 int dht_torrents;
536 int dht_global_nodes;
537 };
538 </pre>
539 <p><tt class="docutils literal"><span class="pre">has_incoming_connections</span></tt> is false as long as no incoming connections have been
540 established on the listening socket. Every time you change the listen port, this will
541 be reset to false.</p>
542 <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>
543 are the total download and upload rates accumulated from all torrents. The payload
544 versions is the payload download only.</p>
545 <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
546 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>
547 are the same thing but where only the payload is considered.</p>
548 <p><tt class="docutils literal"><span class="pre">num_peers</span></tt> is the total number of peer connections this session have.</p>
549 <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
550 built with DHT support. They are all set to 0 if the DHT isn't running. When
551 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
553 <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
554 are used to replace the regular nodes in the routing table in case any of them
555 becomes unresponsive.</p>
556 <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>
557 <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
558 network.</p>
559 </div>
562 <blockquote>
564 bool is_listening() const;
565 unsigned short listen_port() const;
566 bool listen_on(
568 , char const* interface = 0);
569 </pre>
570 </blockquote>
571 <p><tt class="docutils literal"><span class="pre">is_listening()</span></tt> will tell you whether or not the session has successfully
572 opened a listening port. If it hasn't, this function will return false, and
573 then you can use <tt class="docutils literal"><span class="pre">listen_on()</span></tt> to make another try.</p>
574 <p><tt class="docutils literal"><span class="pre">listen_port()</span></tt> returns the port we ended up listening on. Since you just pass
575 a port-range to the constructor and to <tt class="docutils literal"><span class="pre">listen_on()</span></tt>, to know which port it
576 ended up using, you have to ask the session using this function.</p>
577 <p><tt class="docutils literal"><span class="pre">listen_on()</span></tt> will change the listen port and/or the listen interface. If the
578 session is already listening on a port, this socket will be closed and a new socket
579 will be opened with these new settings. The port range is the ports it will try
580 to listen on, if the first port fails, it will continue trying the next port within
581 the range and so on. The interface parameter can be left as 0, in that case the
582 os will decide which interface to listen on, otherwise it should be the ip-address
583 of the interface you want the listener socket bound to. <tt class="docutils literal"><span class="pre">listen_on()</span></tt> returns true
584 if it managed to open the socket, and false if it failed. If it fails, it will also
585 generate an appropriate alert (<a class="reference" href="#listen-failed-alert">listen_failed_alert</a>).</p>
586 <p>The interface parameter can also be a hostname that will resolve to the device you
587 want to listen on.</p>
588 <p>If you're also starting the DHT, it is a good idea to do that after you've called
589 <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
590 listen socket. If you start the DHT first, it will assume the tcp port is free and
591 open the udp socket on that port, then later, when <tt class="docutils literal"><span class="pre">listen_on()</span></tt> is called, it
592 may turn out that the tcp port is in use. That results in the DHT and the bittorrent
593 socket listening on different ports. If the DHT is active when <tt class="docutils literal"><span class="pre">listen_on</span></tt> is
594 called, the udp port will be rebound to the new port, if it was configured to use
595 the same port as the tcp socket, and if the listen_on call failed to bind to the
596 same port that the udp uses.</p>
597 <p>The reason why it's a good idea to run the DHT and the bittorrent socket on the same
598 port is because that is an assumption that may be used to increase performance. One
599 way to accelerate the connecting of peers on windows may be to first ping all peers
600 with a DHT ping packet, and connect to those that responds first. On windows one
601 can only connect to a few peers at a time because of a built in limitation (in XP
603 </div>
606 <blockquote>
609 void set_severity_level(alert::severity_t s);
610 </pre>
611 </blockquote>
612 <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
613 <tt class="docutils literal"><span class="pre">set_severity_level()</span></tt> you can filter how serious the event has to be for you to
614 receive it through <tt class="docutils literal"><span class="pre">pop_alert()</span></tt>. For information, see <a class="reference" href="#alerts">alerts</a>.</p>
615 </div>
618 <blockquote>
620 void add_extension(boost::function<
622 </pre>
623 </blockquote>
624 <p>This function adds an extension to this session. The argument is a function
625 object that is called with a <tt class="docutils literal"><span class="pre">torrent*</span></tt> and which should return a
626 <tt class="docutils literal"><span class="pre">boost::shared_ptr<torrent_plugin></span></tt>. To write custom plugins, see
627 <a class="reference" href="libtorrent_plugins.html">libtorrent plugins</a>. The main plugins implemented in libtorrent are:</p>
630 <dd>Allows peers to download the metadata (.torren files) from the swarm
631 directly. Makes it possible to join a swarm with just a tracker and
632 info-hash.</dd>
635 </dl>
636 <p>To use these, imclude <tt class="docutils literal"><span class="pre"><libtorrent/extensions/metadata_transfer.hpp></span></tt>
637 or <tt class="docutils literal"><span class="pre"><libtorrent/extensions/ut_pex.hpp></span></tt>. The functions to pass in to
638 <tt class="docutils literal"><span class="pre">add_extension()</span></tt> are <tt class="docutils literal"><span class="pre">libtorrent::create_metadata_plugin</span></tt> and
639 <tt class="docutils literal"><span class="pre">libtorrent::create_ut_pex_plugin</span></tt> respectively.</p>
642 ses.add_extension(&libtorrent::create_metadata_plugin);
643 ses.add_extension(&libtorrent::create_ut_pex_plugin);
644 </pre>
645 </div>
648 <blockquote>
650 void set_peer_proxy(proxy_settings const& s);
651 void set_web_seed_proxy(proxy_settings const& s);
652 void set_tracker_proxy(proxy_settings const& s);
653 void set_dht_proxy(proxy_settings const& s);
654 </pre>
655 </blockquote>
656 <p>The <tt class="docutils literal"><span class="pre">set_dht_proxy</span></tt> is not available when DHT is disabled. These functions
657 sets the proxy settings for different kinds of connections, bittorrent peers,
658 web seeds, trackers and the DHT traffic.</p>
659 <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>
661 <p><tt class="docutils literal"><span class="pre">set_tracker_proxy</span></tt> only affects HTTP tracker connections (UDP tracker
662 connections are affected if the given proxy supports UDP, e.g. SOCKS5).</p>
663 <p><tt class="docutils literal"><span class="pre">set_dht_proxy</span></tt> affects the DHT messages. Since they are sent over UDP,
664 it only has any effect if the proxy supports UDP.</p>
665 <p>For more information on what settings are available for proxies, see
667 </div>
670 <blockquote>
672 proxy_settings const& peer_proxy() const;
673 proxy_settings const& web_seed_proxy() const;
674 proxy_settings const& tracker_proxy() const;
675 proxy_settings const& dht_proxy() const;
676 </pre>
677 </blockquote>
679 <p>The <tt class="docutils literal"><span class="pre">dht_proxy</span></tt> is not available when DHT is disabled.</p>
680 </div>
683 <blockquote>
685 void start_dht(entry const& startup_state);
686 void stop_dht();
687 void set_dht_settings(dht_settings const& settings);
688 entry dht_state() const;
689 </pre>
690 </blockquote>
691 <p>These functions are not available in case <tt class="docutils literal"><span class="pre">TORRENT_DISABLE_DHT</span></tt> is
692 defined. <tt class="docutils literal"><span class="pre">start_dht</span></tt> starts the dht node and makes the trackerless service
693 available to torrents. The startup state is optional and can contain nodes
694 and the node id from the previous session. The dht node state is a bencoded
695 dictionary with the following entries:</p>
698 <dd>A list of strings, where each string is a node endpoint encoded in binary. If
700 network byte order (big endian), followed by a 2 byte port number (also
705 </dl>
706 <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
707 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
708 idea to save this to disk when the session is closed, and read it up again
709 when starting.</p>
710 <p>If the port the DHT is supposed to listen on is already in use, and exception
713 <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
714 client has its own source of bootstrapping nodes.</p>
715 <p><tt class="docutils literal"><span class="pre">set_dht_settings</span></tt> sets some parameters availavle to the dht node. The
716 struct has the following members:</p>
718 struct dht_settings
719 {
720 int max_peers_reply;
721 int search_branching;
722 int service_port;
723 int max_fail_count;
724 };
725 </pre>
726 <p><tt class="docutils literal"><span class="pre">max_peers_reply</span></tt> is the maximum number of peers the node will send in
727 response to a <tt class="docutils literal"><span class="pre">get_peers</span></tt> message from another node.</p>
728 <p><tt class="docutils literal"><span class="pre">search_branching</span></tt> is the number of concurrent search request the node will
729 send when announcing and refreshing the routing table. This parameter is
730 called alpha in the kademlia paper.</p>
731 <p><tt class="docutils literal"><span class="pre">service_port</span></tt> is the udp port the node will listen to. This will default
732 to 0, which means the udp listen port will be the same as the tcp listen
733 port. This is in general a good idea, since some NAT implementations
734 reserves the udp port for any mapped tcp port, and vice versa. NAT-PMP
735 guarantees this for example.</p>
736 <p><tt class="docutils literal"><span class="pre">max_fail_count</span></tt> is the maximum number of failed tries to contact a node
737 before it is removed from the routing table. If there are known working nodes
738 that are ready to replace a failing node, it will be replaced immediately,
739 this limit is only used to clear out nodes that don't have any node that can
740 replace them.</p>
741 </div>
744 <blockquote>
748 </pre>
749 </blockquote>
750 <p><tt class="docutils literal"><span class="pre">add_dht_node</span></tt> takes a host name and port pair. That endpoint will be
751 pinged, and if a valid DHT reply is received, the node will be added to
752 the routing table.</p>
753 <p><tt class="docutils literal"><span class="pre">add_dht_router</span></tt> adds the given endpoint to a list of DHT router nodes.
754 If a search is ever made while the routing table is empty, those nodes will
755 be used as backups. Nodes in the router node list will also never be added
756 to the regular routing table, which effectively means they are only used
757 for bootstrapping, to keep the load off them.</p>
758 <p>An example routing node that you could typically add is
760 </div>
761 </div>
764 <p>The <tt class="docutils literal"><span class="pre">entry</span></tt> class represents one node in a bencoded hierarchy. It works as a
765 variant type, it can be either a list, a dictionary (<tt class="docutils literal"><span class="pre">std::map</span></tt>), an integer
766 or a string. This is its synopsis:</p>
768 class entry
769 {
770 public:
773 typedef std::string string_type;
775 typedef size_type integer_type;
777 enum data_type
778 {
779 int_t,
780 string_t,
781 list_t,
782 dictionary_t,
783 undefined_t
784 };
786 data_type type() const;
788 entry(dictionary_type const&);
789 entry(string_type const&);
790 entry(list_type const&);
791 entry(integer_type const&);
793 entry();
794 entry(data_type t);
795 entry(entry const& e);
796 ~entry();
798 void operator=(entry const& e);
799 void operator=(dictionary_type const&);
800 void operator=(string_type const&);
801 void operator=(list_type const&);
802 void operator=(integer_type const&);
804 integer_type& integer();
805 integer_type const& integer() const;
806 string_type& string();
807 string_type const& string() const;
808 list_type& list();
809 list_type const& list() const;
810 dictionary_type& dict();
811 dictionary_type const& dict() const;
813 // these functions requires that the entry
814 // is a dictionary, otherwise they will throw
815 entry& operator[](char const* key);
817 entry const& operator[](char const* key) const;
819 entry* find_key(char const* key);
820 entry const* find_key(char const* key) const;
823 };
824 </pre>
828 <blockquote>
830 integer_type& integer();
831 integer_type const& integer() const;
832 string_type& string();
833 string_type const& string() const;
834 list_type& list();
835 list_type const& list() const;
836 dictionary_type& dict();
837 dictionary_type const& dict() const;
838 </pre>
839 </blockquote>
840 <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
841 are accessors that return the respective type. If the <tt class="docutils literal"><span class="pre">entry</span></tt> object isn't of the
842 type you request, the accessor will throw <a class="reference" href="#type-error">type_error</a> (which derives from
843 <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
845 <p>The <tt class="docutils literal"><span class="pre">print()</span></tt> function is there for debug purposes only.</p>
846 <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
847 constructor, and then use one of the non-const accessors to get a reference which you then
848 can assign the value you want it to have.</p>
851 entry torrent_file;
852 // ...
854 // throws if this is not a dictionary
855 entry::dictionary_type const& dict = torrent_file.dict();
856 entry::dictionary_type::const_iterator i;
858 if (i != dict.end())
859 {
860 std::string tracker_url = i->second.string();
862 }
863 </pre>
866 entry torrent_file;
867 // ...
869 // throws if this is not a dictionary
871 {
872 std::string tracker_url = i->string();
874 }
875 </pre>
876 <p>To make it easier to extract information from a torrent file, the class <a class="reference" href="#torrent-info">torrent_info</a>
877 exists.</p>
878 </div>
881 <blockquote>
883 entry& operator[](char const* key);
885 entry const& operator[](char const* key) const;
887 </pre>
888 </blockquote>
889 <p>All of these functions requires the entry to be a dictionary, if it isn't they
890 will throw <tt class="docutils literal"><span class="pre">libtorrent::type_error</span></tt>.</p>
891 <p>The non-const versions of the <tt class="docutils literal"><span class="pre">operator[]</span></tt> will return a reference to either
892 the existing element at the given key or, if there is no element with the
893 given key, a reference to a newly inserted element at that key.</p>
894 <p>The const version of <tt class="docutils literal"><span class="pre">operator[]</span></tt> will only return a reference to an
895 existing element at the given key. If the key is not found, it will throw
897 </div>
900 <blockquote>
902 entry* find_key(char const* key);
903 entry const* find_key(char const* key) const;
904 </pre>
905 </blockquote>
906 <p>These functions requires the entry to be a dictionary, if it isn't they
907 will throw <tt class="docutils literal"><span class="pre">libtorrent::type_error</span></tt>.</p>
908 <p>They will look for an element at the given key in the dictionary, if the
909 element cannot be found, they will return 0. If an element with the given
910 key is found, the return a pointer to it.</p>
911 </div>
912 </div>
915 <p>The <tt class="docutils literal"><span class="pre">torrent_info</span></tt> has the following synopsis:</p>
917 class torrent_info
918 {
919 public:
921 torrent_info();
922 torrent_info(sha1_hash const& info_hash);
923 torrent_info(entry const& torrent_file);
925 entry create_torrent() const;
926 void set_comment(char const* str);
927 void set_piece_size(int size);
928 void set_creator(char const* str);
929 void set_hash(int index, sha1_hash const& h);
931 void add_file(boost::filesystem::path file, size_type size);
932 void add_url_seed(std::string const& url);
936 reverse_file_iterator;
938 file_iterator begin_files() const;
939 file_iterator end_files() const;
940 reverse_file_iterator rbegin_files() const;
941 reverse_file_iterator rend_files() const;
943 int num_files() const;
944 file_entry const& file_at(int index) const;
947 , int size) const;
948 peer_request map_file(int file_index, size_type file_offset
949 , int size) const;
953 bool priv() const;
954 void set_priv(bool v);
958 size_type total_size() const;
959 size_type piece_length() const;
960 int num_pieces() const;
961 sha1_hash const& info_hash() const;
962 std::string const& name() const;
963 std::string const& comment() const;
964 std::string const& creator() const;
970 creation_date() const;
972 void print(std::ostream& os) const;
974 size_type piece_size(unsigned int index) const;
975 sha1_hash const& hash_for_piece(unsigned int index) const;
976 };
977 </pre>
980 <blockquote>
982 torrent_info();
983 torrent_info(sha1_hash const& info_hash);
984 torrent_info(entry const& torrent_file);
985 </pre>
986 </blockquote>
987 <p>The default constructor of <tt class="docutils literal"><span class="pre">torrent_info</span></tt> is used when creating torrent files. It will
988 initialize the object to an empty torrent, containing no files. The info hash will be set
989 to 0 when this constructor is used. To use the empty <tt class="docutils literal"><span class="pre">torrent_info</span></tt> object, add files
990 and piece hashes, announce URLs and optionally a creator tag and comment. To do this you
991 use the members <tt class="docutils literal"><span class="pre">set_comment()</span></tt>, <tt class="docutils literal"><span class="pre">set_piece_size()</span></tt>, <tt class="docutils literal"><span class="pre">set_creator()</span></tt>, <tt class="docutils literal"><span class="pre">set_hash()</span></tt>
992 etc.</p>
993 <p>The constructor that takes an info-hash is identical to the default constructor with the
994 exception that it will initialize the info-hash to the given value. This is used internally
995 when downloading torrents without the metadata. The metadata will be created by libtorrent
996 as soon as it has been downloaded from the swarm.</p>
997 <p>The last constructor is the one that is used in most cases. It will create a <tt class="docutils literal"><span class="pre">torrent_info</span></tt>
998 object from the information found in the given torrent_file. The <tt class="docutils literal"><span class="pre">entry</span></tt> represents a tree
999 node in an bencoded file. To load an ordinary .torrent file into an <tt class="docutils literal"><span class="pre">entry</span></tt>, use bdecode(),
1001 </div>
1002 <div class="section" id="set-comment-set-piece-size-set-creator-set-hash-add-tracker-add-file">
1004 <blockquote>
1006 void set_comment(char const* str);
1007 void set_piece_size(int size);
1008 void set_creator(char const* str);
1009 void set_hash(int index, sha1_hash const& h);
1011 void add_file(boost::filesystem::path file, size_type size);
1012 </pre>
1013 </blockquote>
1014 <p>These files are used when creating a torrent file. <tt class="docutils literal"><span class="pre">set_comment()</span></tt> will simply set
1015 the comment that belongs to this torrent. The comment can be retrieved with the
1016 <tt class="docutils literal"><span class="pre">comment()</span></tt> member. The string should be UTF-8 encoded.</p>
1017 <p><tt class="docutils literal"><span class="pre">set_piece_size()</span></tt> will set the size of each piece in this torrent. The piece size must
1019 size is given in number of bytes.</p>
1020 <p><tt class="docutils literal"><span class="pre">set_creator()</span></tt> is an optional attribute that can be used to identify your application
1022 <p><tt class="docutils literal"><span class="pre">set_hash()</span></tt> writes the hash for the piece with the given piece-index. You have to call
1023 this function for every piece in the torrent. Usually the <a class="reference" href="#hasher">hasher</a> is used to calculate
1024 the sha1-hash for a piece.</p>
1025 <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
1026 which the trackers are to be tried. For more information see <a class="reference" href="#trackers">trackers()</a>.</p>
1027 <p><tt class="docutils literal"><span class="pre">add_file()</span></tt> adds a file to the torrent. The order in which you add files will determine
1028 the order in which they are placed in the torrent file. You have to add at least one file
1029 to the torrent. The <tt class="docutils literal"><span class="pre">path</span></tt> you give has to be a relative path from the root directory
1030 of the torrent. The <tt class="docutils literal"><span class="pre">size</span></tt> is given in bytes.</p>
1031 <p>When you have added all the files and hashes to your torrent, you can generate an <tt class="docutils literal"><span class="pre">entry</span></tt>
1032 which then can be encoded as a .torrent file. You do this by calling <a class="reference" href="#create-torrent">create_torrent()</a>.</p>
1033 <p>For a complete example of how to create a torrent from a file structure, see <a class="reference" href="examples.html#make_torrent">make_torrent</a>.</p>
1034 </div>
1037 <blockquote>
1039 entry create_torrent();
1040 </pre>
1041 </blockquote>
1042 <p>Returns an <tt class="docutils literal"><span class="pre">entry</span></tt> representing the bencoded tree of data that makes up a .torrent file.
1043 You can save this data as a torrent file with bencode() (see <a class="reference" href="#bdecode-bencode">bdecode() bencode()</a>), for a
1044 complete example, see <a class="reference" href="examples.html#make_torrent">make_torrent</a>.</p>
1045 <p>This function is not const because it will also set the info-hash of the <tt class="docutils literal"><span class="pre">torrent_info</span></tt>
1046 object.</p>
1047 <p>Note that a torrent file must include at least one file, and it must have at
1048 least one tracker url or at least one DHT node.</p>
1049 </div>
1052 <blockquote>
1054 file_iterator begin_files() const;
1055 file_iterator end_files() const;
1056 reverse_file_iterator rbegin_files() const;
1057 reverse_file_iterator rend_files() const;
1058 </pre>
1059 </blockquote>
1060 <p>This class will need some explanation. First of all, to get a list of all files
1061 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>,
1062 <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
1063 iterators with the type <tt class="docutils literal"><span class="pre">file_entry</span></tt>.</p>
1064 <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
1065 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>.
1067 <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
1068 of the file within the torrent. i.e. the sum of all the sizes of the files
1069 before this one in the file list this one in the file list.</p>
1070 <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
1071 found in the metadata. In case the path in the original metadata was
1072 incorrectly encoded, and had to be fixed in order to be acceptable utf-8,
1073 the original string is preserved in <tt class="docutils literal"><span class="pre">orig_path</span></tt>. The reason to keep it
1074 is to be able to reproduce the info-section exactly, with the correct
1075 info-hash.</p>
1077 struct file_entry
1078 {
1079 boost::filesystem::path path;
1080 size_type offset;
1081 size_type size;
1083 };
1084 </pre>
1085 </div>
1088 <blockquote>
1090 int num_files() const;
1091 file_entry const& file_at(int index) const;
1092 </pre>
1093 </blockquote>
1094 <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>
1095 to access files using indices.</p>
1096 </div>
1099 <blockquote>
1102 , int size) const;
1103 </pre>
1104 </blockquote>
1105 <p>This function will map a piece index, a byte offset within that piece and
1106 a size (in bytes) into the corresponding files with offsets where that data
1107 for that piece is supposed to be stored.</p>
1110 struct file_slice
1111 {
1112 int file_index;
1113 size_type offset;
1114 size_type size;
1115 };
1116 </pre>
1117 <p>The <tt class="docutils literal"><span class="pre">file_index</span></tt> refers to the index of the file (in the torrent_info).
1118 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>
1119 as argument. The <tt class="docutils literal"><span class="pre">offset</span></tt> is the byte offset in the file where the range
1120 starts, and <tt class="docutils literal"><span class="pre">size</span></tt> is the number of bytes this range is. The size + offset
1121 will never be greater than the file size.</p>
1122 </div>
1125 <blockquote>
1127 peer_request map_file(int file_index, size_type file_offset
1128 , int size) const;
1129 </pre>
1130 </blockquote>
1131 <p>This function will map a range in a specific file into a range in the torrent.
1132 The <tt class="docutils literal"><span class="pre">file_offset</span></tt> parameter is the offset in the file, given in bytes, where
1133 0 is the start of the file.
1134 The <tt class="docutils literal"><span class="pre">peer_request</span></tt> structure looks like this:</p>
1136 struct peer_request
1137 {
1138 int piece;
1139 int start;
1140 int length;
1141 bool operator==(peer_request const& r) const;
1142 };
1143 </pre>
1144 <p><tt class="docutils literal"><span class="pre">piece</span></tt> is the index of the piece in which the range starts.
1145 <tt class="docutils literal"><span class="pre">start</span></tt> is the offset within that piece where the range starts.
1146 <tt class="docutils literal"><span class="pre">length</span></tt> is the size of the range, in bytes.</p>
1147 <p>The input range is assumed to be valid within the torrent. <tt class="docutils literal"><span class="pre">file_offset</span></tt>
1148 + <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>
1149 must refer to a valid file, i.e. it cannot be >= <tt class="docutils literal"><span class="pre">num_files()</span></tt>.</p>
1150 </div>
1153 <blockquote>
1156 void add_url_seed(std::string const& url);
1157 </pre>
1158 </blockquote>
1159 <p>If there are any url-seeds in this torrent, <tt class="docutils literal"><span class="pre">url_seeds()</span></tt> will return a
1160 vector of those urls. If you're creating a torrent file, <tt class="docutils literal"><span class="pre">add_url_seed()</span></tt>
1161 adds one url to the list of url-seeds. Currently, the only transport protocol
1162 supported for the url is http.</p>
1164 </div>
1167 <blockquote>
1169 void print(std::ostream& os) const;
1170 </pre>
1171 </blockquote>
1172 <p>The <tt class="docutils literal"><span class="pre">print()</span></tt> function is there for debug purposes only. It will print the info from
1173 the torrent file to the given outstream. This function has been deprecated and will
1174 be removed from future releases.</p>
1175 </div>
1178 <blockquote>
1181 </pre>
1182 </blockquote>
1183 <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>.
1184 Each announce entry contains a string, which is the tracker url, and a tier index. The
1185 tier index is the high-level priority. No matter which trackers that works or not, the
1186 ones with lower tier will always be tried before the one with higher tier number.</p>
1188 struct announce_entry
1189 {
1190 announce_entry(std::string const& url);
1191 std::string url;
1192 int tier;
1193 };
1194 </pre>
1195 </div>
1198 <blockquote>
1200 size_type total_size() const;
1201 size_type piece_length() const;
1202 size_type piece_size(unsigned int index) const;
1203 int num_pieces() const;
1204 </pre>
1205 </blockquote>
1206 <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
1207 number of bytes the torrent-file represents (all the files in it), the number of byte for
1208 each piece and the total number of pieces, respectively. The difference between
1209 <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
1210 the piece index as argument and gives you the exact size of that piece. It will always
1211 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
1212 be smaller.</p>
1213 </div>
1216 <blockquote>
1218 size_type piece_size(unsigned int index) const;
1219 sha1_hash const& hash_for_piece(unsigned int index) const;
1220 </pre>
1221 </blockquote>
1222 <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
1223 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
1224 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.
1225 <tt class="docutils literal"><span class="pre">info_hash()</span></tt> will only return a valid hash if the torrent_info was read from a
1226 <tt class="docutils literal"><span class="pre">.torrent</span></tt> file or if an <tt class="docutils literal"><span class="pre">entry</span></tt> was created from it (through <tt class="docutils literal"><span class="pre">create_torrent</span></tt>).</p>
1227 </div>
1230 <blockquote>
1232 std::string const& name() const;
1233 std::string const& comment() const;
1235 </pre>
1236 </blockquote>
1237 <p><tt class="docutils literal"><span class="pre">name()</span></tt> returns the name of the torrent.</p>
1238 <p><tt class="docutils literal"><span class="pre">comment()</span></tt> returns the comment associated with the torrent. If there's no comment,
1239 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>
1240 object, representing the time when this torrent file was created. If there's no time stamp
1243 <p><tt class="docutils literal"><span class="pre">creator()</span></tt> returns the creator string in the torrent. If there is no creator string
1244 it will return an empty string.</p>
1245 </div>
1248 <blockquote>
1250 bool priv() const;
1251 void set_priv(bool v);
1252 </pre>
1253 </blockquote>
1254 <p><tt class="docutils literal"><span class="pre">priv()</span></tt> returns true if this torrent is private. i.e., it should not be
1255 distributed on the trackerless network (the kademlia DHT).</p>
1256 <p><tt class="docutils literal"><span class="pre">set_priv()</span></tt> sets or clears the private flag on this torrent.</p>
1257 </div>
1260 <blockquote>
1263 </pre>
1264 </blockquote>
1265 <p>If this torrent contains any DHT nodes, they are put in this vector in their original
1266 form (host name and port number).</p>
1267 </div>
1270 <blockquote>
1273 </pre>
1274 </blockquote>
1275 <p>This is used when creating torrent. Use this to add a known DHT node. It may
1276 be used, by the client, to bootstrap into the DHT network.</p>
1277 </div>
1278 </div>
1281 <p>You will usually have to store your torrent handles somewhere, since it's the
1282 object through which you retrieve information about the torrent and aborts the torrent.
1283 Its declaration looks like this:</p>
1285 struct torrent_handle
1286 {
1287 torrent_handle();
1289 torrent_status status();
1293 torrent_info const& get_torrent_info() const;
1294 bool is_valid() const;
1296 std::string name() const;
1298 entry write_resume_data() const;
1299 void force_reannounce() const;
1302 void set_tracker_login(std::string const& username
1303 , std::string const& password) const;
1308 void add_url_seed(std::string const& url);
1310 void set_ratio(float ratio) const;
1311 void set_max_uploads(int max_uploads) const;
1312 void set_max_connections(int max_connections) const;
1313 void set_upload_limit(int limit) const;
1314 int upload_limit() const;
1315 void set_download_limit(int limit) const;
1316 int download_limit() const;
1317 void set_sequenced_download_threshold(int threshold) const;
1319 void set_peer_upload_limit(asio::ip::tcp::endpoint ip, int limit) const;
1320 void set_peer_download_limit(asio::ip::tcp::endpoint ip, int limit) const;
1322 void use_interface(char const* net_interface) const;
1324 void pause() const;
1325 void resume() const;
1326 bool is_paused() const;
1327 bool is_seed() const;
1329 void resolve_countries(bool r);
1330 bool resolve_countries() const;
1332 void piece_priority(int index, int priority) const;
1333 int piece_priority(int index) const;
1340 // these functions are deprecated
1341 void filter_piece(int index, bool filter) const;
1343 bool is_piece_filtered(int index) const;
1347 bool has_metadata() const;
1349 boost::filesystem::path save_path() const;
1350 bool move_storage(boost::filesystem::path const& save_path) const;
1352 sha1_hash info_hash() const;
1354 bool operator==(torrent_handle const&) const;
1355 bool operator!=(torrent_handle const&) const;
1357 };
1358 </pre>
1359 <p>The default constructor will initialize the handle to an invalid state. Which
1360 means you cannot perform any operation on it, unless you first assign it a
1361 valid handle. If you try to perform any operation on an uninitialized handle,
1365 <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>
1366 exception, in case the handle is no longer refering to a torrent. There are
1367 two exceptions, <tt class="docutils literal"><span class="pre">info_hash()</span></tt> and <tt class="docutils literal"><span class="pre">is_valid()</span></tt> will never throw.
1368 Since the torrents are processed by a background thread, there is no
1369 guarantee that a handle will remain valid between two calls.</p>
1370 </div>
1373 <blockquote>
1375 void piece_priority(int index, int priority) const;
1376 int piece_priority(int index) const;
1380 </pre>
1381 </blockquote>
1382 <p>These functions are used to set and get the prioritiy of individual pieces.
1383 By default all pieces have priority 1. That means that the random rarest
1384 first algorithm is effectively active for all pieces. You may however
1385 change the priority of individual pieces. There are 8 different priority
1386 levels:</p>
1387 <blockquote>
1391 <li>higher than normal priority. Pieces are preferred over pieces with
1392 the same availability, but not over pieces with lower availability</li>
1394 <li>pieces are preferred over partial pieces, but not over pieces with
1395 lower availability</li>
1398 <li>maximum priority, availability is disregarded, the piece is preferred
1399 over any other piece with lower priority</li>
1400 </ol>
1401 </blockquote>
1402 <p>The exact definitions of these priorities are implementation details, and
1403 subject to change. The interface guarantees that higher number means higher
1405 <p><tt class="docutils literal"><span class="pre">piece_priority</span></tt> sets or gets the priority for an individual piece,
1407 <p><tt class="docutils literal"><span class="pre">prioritize_pieces</span></tt> takes a vector of integers, one integer per piece in
1408 the torrent. All the piece priorities will be updated with the priorities
1409 in the vector.</p>
1410 <p><tt class="docutils literal"><span class="pre">piece_priorities</span></tt> returns a vector with one element for each piece in the
1411 torrent. Each element is the current priority of that piece.</p>
1412 <p><tt class="docutils literal"><span class="pre">prioritize_files</span></tt> takes a vector that has at as many elements as there are
1413 files in the torrent. Each entry is the priority of that file. The function
1414 sets the priorities of all the pieces in the torrent based on the vector.</p>
1415 </div>
1418 <blockquote>
1421 </pre>
1422 </blockquote>
1423 <p>This function fills in the supplied vector with the progress (a value in the
1425 The progress values are ordered the same as the files in the <a class="reference" href="#torrent-info">torrent_info</a>.
1426 This operation is not very cheap.</p>
1427 </div>
1430 <blockquote>
1432 boost::filesystem::path save_path() const;
1433 </pre>
1434 </blockquote>
1435 <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
1436 was started.</p>
1437 </div>
1440 <blockquote>
1442 bool move_storage(boost::filesystem::path const& save_path) const;
1443 </pre>
1444 </blockquote>
1445 <p>Moves the file(s) that this torrent are currently seeding from or downloading to. This
1446 operation will only have the desired effect if the given <tt class="docutils literal"><span class="pre">save_path</span></tt> is located on
1447 the same drive as the original save path. If the move operation fails, this function
1448 returns false, otherwise true. Post condition for successful operation is:
1449 <tt class="docutils literal"><span class="pre">save_path()</span> <span class="pre">==</span> <span class="pre">save_path</span></tt>.</p>
1450 </div>
1453 <blockquote>
1455 void force_reannounce() const;
1456 </pre>
1457 </blockquote>
1458 <p><tt class="docutils literal"><span class="pre">force_reannounce()</span></tt> will force this torrent to do another tracker request, to receive new
1459 peers. If the torrent is invalid, queued or in checking mode, this functions will throw
1461 </div>
1464 <blockquote>
1467 </pre>
1468 </blockquote>
1469 <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
1470 torrent. If the peer does not respond, or is not a member of this torrent, it will simply
1471 be disconnected. No harm can be done by using this other than an unnecessary connection
1472 attempt is made. If the torrent is uninitialized or in queued or checking mode, this
1473 will throw <a class="reference" href="#invalid-handle">invalid_handle</a>. The second (optional) argument will be bitwised ORed into
1474 the source mask of this peer. Typically this is one of the source flags in <a class="reference" href="#peer-info">peer_info</a>.
1475 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>
1476 </div>
1479 <blockquote>
1481 std::string name() const;
1482 </pre>
1483 </blockquote>
1484 <p>Returns the name of the torrent. i.e. the name from the metadata associated with it. In
1485 case the torrent was started without metadata, and hasn't completely received it yet,
1486 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>
1487 </div>
1490 <blockquote>
1492 void set_ratio(float ratio) const;
1493 </pre>
1494 </blockquote>
1495 <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
1496 infinite. i.e. the client will always upload as much as it can, no matter how much it gets back
1497 in return. With this setting it will work much like the standard clients.</p>
1498 <p>Besides 0, the ratio can be set to any number greater than or equal to 1. It means how much to
1499 attempt to upload in return for each download. e.g. if set to 2, the client will try to upload
1501 as a standard client.</p>
1502 </div>
1505 <blockquote>
1507 void set_upload_limit(int limit) const;
1508 void set_download_limit(int limit) const;
1509 int upload_limit() const;
1510 int download_limit() const;
1511 </pre>
1512 </blockquote>
1513 <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
1514 limit you set. It is given as the number of bytes per second the torrent is allowed to upload.
1515 <tt class="docutils literal"><span class="pre">set_download_limit</span></tt> works the same way but for download bandwidth instead of upload bandwidth.
1516 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>)
1517 will not override the global rate limit. The torrent can never upload more than the global rate
1518 limit.</p>
1519 <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
1520 download, respectively.</p>
1521 </div>
1524 <blockquote>
1526 void set_sequenced_download_threshold(int threshold);
1527 </pre>
1528 </blockquote>
1529 <p>sequenced-download threshold is the limit on how popular a piece has to be
1530 (popular == inverse of rarity) to be downloaded in sequence instead of in
1531 random (rarest first) order. It can be used to tweak disk performance in
1532 settings where the random download property is less necessary. For example, if
1534 in index order. This setting defaults to 100, which means that it is disabled
1535 in practice.</p>
1536 <p>Setting this threshold to a very small value will affect the piece distribution
1537 negatively in the swarm. It should basically only be used in situations where
1538 the random seeks on the disk is the download bottleneck.</p>
1539 </div>
1542 <blockquote>
1544 void set_peer_upload_limit(asio::ip::tcp::endpoint ip, int limit) const;
1545 void set_peer_download_limit(asio::ip::tcp::endpoint ip, int limit) const;
1546 </pre>
1547 </blockquote>
1548 <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
1549 peer instead of the whole torrent.</p>
1550 </div>
1553 <blockquote>
1555 void pause() const;
1556 void resume() const;
1557 bool is_paused() const;
1558 </pre>
1559 </blockquote>
1560 <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.
1561 When a torrent is paused, it will however remember all share ratios to all peers and remember
1562 all potential (not connected) peers. You can use <tt class="docutils literal"><span class="pre">is_paused()</span></tt> to determine if a torrent
1563 is currently paused. Torrents may be paused automatically if there is a file error (e.g. disk full)
1564 or something similar. See <a class="reference" href="#file-error-alert">file_error_alert</a>.</p>
1565 </div>
1568 <blockquote>
1570 void resolve_countries(bool r);
1571 bool resolve_countries() const;
1572 </pre>
1573 </blockquote>
1574 <p>Sets or gets the flag that derermines if countries should be resolved for the peers of this
1575 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
1576 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
1577 on how to interpret this field.</p>
1578 </div>
1581 <blockquote>
1583 bool is_seed() const;
1584 </pre>
1585 </blockquote>
1587 </div>
1590 <blockquote>
1592 bool has_metadata() const;
1593 </pre>
1594 </blockquote>
1595 <p>Returns true if this torrent has metadata (either it was started from a .torrent file or the
1596 metadata has been downloaded). The only scenario where this can return false is when the torrent
1597 was started torrent-less (i.e. with just an info-hash and tracker ip). Note that if the torrent
1598 doesn't have metadata, the member <a class="reference" href="#get-torrent-info">get_torrent_info()</a> will throw.</p>
1599 </div>
1602 <blockquote>
1604 void set_tracker_login(std::string const& username
1605 , std::string const& password) const;
1606 </pre>
1607 </blockquote>
1608 <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
1609 of the tracker announce. Set this if the tracker requires authorization.</p>
1610 </div>
1613 <blockquote>
1617 </pre>
1618 </blockquote>
1619 <p><tt class="docutils literal"><span class="pre">trackers()</span></tt> will return the list of trackers for this torrent. The
1620 announce entry contains both a string <tt class="docutils literal"><span class="pre">url</span></tt> which specify the announce url
1621 for the tracker as well as an int <tt class="docutils literal"><span class="pre">tier</span></tt>, which is specifies the order in
1622 which this tracker is tried. If you want libtorrent to use another list of
1623 trackers for this torrent, you can use <tt class="docutils literal"><span class="pre">replace_trackers()</span></tt> which takes
1624 a list of the same form as the one returned from <tt class="docutils literal"><span class="pre">trackers()</span></tt> and will
1625 replace it. If you want an immediate effect, you have to call
1627 </div>
1630 <blockquote>
1632 void add_url_seed(std::string const& url);
1633 </pre>
1634 </blockquote>
1635 <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
1636 given url already exists in that list, the call has no effect. The torrent
1637 will connect to the server and try to download pieces from it, unless it's
1638 paused, queued, checking or seeding.</p>
1640 </div>
1643 <blockquote>
1645 void use_interface(char const* net_interface) const;
1646 </pre>
1647 </blockquote>
1648 <p><tt class="docutils literal"><span class="pre">use_interface()</span></tt> sets the network interface this torrent will use when it opens outgoing
1649 connections. By default, it uses the same interface as the <a class="reference" href="#session">session</a> uses to listen on. The
1650 parameter must be a string containing an ip-address (either an IPv4 or IPv6 address). If
1651 the string does not conform to this format and exception is thrown.</p>
1652 </div>
1655 <blockquote>
1657 sha1_hash info_hash() const;
1658 </pre>
1659 </blockquote>
1660 <p><tt class="docutils literal"><span class="pre">info_hash()</span></tt> returns the info-hash for the torrent.</p>
1661 </div>
1664 <blockquote>
1666 void set_max_uploads(int max_uploads) const;
1667 void set_max_connections(int max_connections) const;
1668 </pre>
1669 </blockquote>
1670 <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
1672 <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
1673 connections are used up, incoming connections may be refused or poor connections may be closed.
1675 function, it means unlimited.</p>
1676 </div>
1679 <blockquote>
1681 entry write_resume_data() const;
1682 </pre>
1683 </blockquote>
1684 <p><tt class="docutils literal"><span class="pre">write_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>
1685 is suitable for being bencoded. For more information about how fast-resume works, see <a class="reference" href="#fast-resume">fast resume</a>.</p>
1686 <p>There are three cases where this function will just return an empty <tt class="docutils literal"><span class="pre">entry</span></tt>:</p>
1687 <blockquote>
1690 <li>The torrent is checking (or is queued for checking) its storage, it will obviously
1691 not be ready to write resume data.</li>
1692 <li>The torrent hasn't received valid metadata and was started without metadata
1693 (see libtorrent's <a class="reference" href="#metadata-from-peers">metadata from peers</a> extension)</li>
1694 </ol>
1695 </blockquote>
1696 <p>Note that by the time this function returns, the resume data may already be invalid if the torrent
1697 is still downloading! The recommended practice is to first pause the torrent, then generate the
1698 fast resume data, and then close it down.</p>
1699 <p>It is still a good idea to save resume data periodically during download as well as when
1700 closing down. In full allocation mode the reume data is never invalidated by subsequent
1701 writes to the files, since pieces won't move around.</p>
1702 </div>
1705 <blockquote>
1707 torrent_status status() const;
1708 </pre>
1709 </blockquote>
1710 <p><tt class="docutils literal"><span class="pre">status()</span></tt> will return a structure with information about the status of this
1711 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.
1713 </div>
1716 <blockquote>
1719 </pre>
1720 </blockquote>
1721 <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
1722 information about pieces that are partially downloaded or not downloaded at all but partially
1723 requested. The entry in the vector (<tt class="docutils literal"><span class="pre">partial_piece_info</span></tt>) looks like this:</p>
1725 struct partial_piece_info
1726 {
1727 enum { max_blocks_per_piece };
1728 int piece_index;
1729 int blocks_in_piece;
1732 address peer[max_blocks_per_piece];
1733 int num_downloads[max_blocks_per_piece];
1734 enum state_t { none, slow. medium, fast };
1735 state_t piece_state;
1736 };
1737 </pre>
1738 <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
1739 number of blocks in this particular piece. This number will be the same for most pieces, but
1740 the last piece may have fewer blocks than the standard pieces.</p>
1741 <p><tt class="docutils literal"><span class="pre">requested_blocks</span></tt> is a bitset with one bit per block in the piece. If a bit is set, it
1742 means that that block has been requested, but not necessarily fully downloaded yet. To know
1743 from whom the block has been requested, have a look in the <tt class="docutils literal"><span class="pre">peer</span></tt> array. The bit-index
1744 in the <tt class="docutils literal"><span class="pre">requested_blocks</span></tt> and <tt class="docutils literal"><span class="pre">finished_blocks</span></tt> corresponds to the array-index into
1745 <tt class="docutils literal"><span class="pre">peers</span></tt> and <tt class="docutils literal"><span class="pre">num_downloads</span></tt>. The array of peers is contains the address of the
1746 peer the piece was requested from. If a piece hasn't been requested (the bit in
1747 <tt class="docutils literal"><span class="pre">requested_blocks</span></tt> is not set) the peer array entry will be undefined.</p>
1748 <p>The <tt class="docutils literal"><span class="pre">finished_blocks</span></tt> is a bitset where each bit says if the block is fully downloaded
1749 or not. And the <tt class="docutils literal"><span class="pre">num_downloads</span></tt> array says how many times that block has been downloaded.
1750 When a piece fails a hash verification, single blocks may be re-downloaded to
1751 see if the hash test may pass then.</p>
1752 <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
1753 download rate category the peers downloading this piece falls into. <tt class="docutils literal"><span class="pre">none</span></tt> means that no
1754 peer is currently downloading any part of the piece. Peers prefer picking pieces from
1755 the same category as themselves. The reason for this is to keep the number of partially
1756 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>,
1757 <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>
1758 </div>
1761 <blockquote>
1764 </pre>
1765 </blockquote>
1766 <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
1767 with one entry for each peer connected to this torrent, given the handle is valid. If the
1768 <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
1769 the vector contains information about that particular peer. See <a class="reference" href="#peer-info">peer_info</a>.</p>
1770 </div>
1773 <blockquote>
1775 torrent_info const& get_torrent_info() const;
1776 </pre>
1777 </blockquote>
1778 <p>Returns a const reference to the <a class="reference" href="#torrent-info">torrent_info</a> object associated with this torrent.
1779 This reference is valid as long as the <a class="reference" href="#torrent-handle">torrent_handle</a> is valid, no longer. If the
1780 <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>
1781 exception will be thrown. The torrent may be in a state without metadata only if
1782 it was started without a .torrent file, i.e. by using the libtorrent extension of
1783 just supplying a tracker and info-hash.</p>
1784 </div>
1787 <blockquote>
1789 bool is_valid() const;
1790 </pre>
1791 </blockquote>
1792 <p>Returns true if this handle refers to a valid torrent and false if it hasn't been initialized
1793 or if the torrent it refers to has been aborted. Note that a handle may become invalid after
1794 it has been added to the session. Usually this is because the storage for the torrent is
1795 somehow invalid or if the filenames are not allowed (and hence cannot be opened/created) on
1796 your filesystem. If such an error occurs, a <a class="reference" href="#file-error-alert">file_error_alert</a> is generated and all handles
1797 that refers to that torrent will become invalid.</p>
1799 </div>
1800 </div>
1805 struct torrent_status
1806 {
1807 enum state_t
1808 {
1809 queued_for_checking,
1810 checking_files,
1811 connecting_to_tracker,
1812 downloading,
1813 finished,
1814 seeding,
1815 allocating
1816 };
1818 state_t state;
1819 bool paused;
1820 float progress;
1821 boost::posix_time::time_duration next_announce;
1822 boost::posix_time::time_duration announce_interval;
1824 std::string current_tracker;
1826 size_type total_download;
1827 size_type total_upload;
1829 size_type total_payload_download;
1830 size_type total_payload_upload;
1832 size_type total_failed_bytes;
1833 size_type total_redundant_bytes;
1835 float download_rate;
1836 float upload_rate;
1838 float download_payload_rate;
1839 float upload_payload_rate;
1841 int num_peers;
1843 int num_complete;
1844 int num_incomplete;
1847 int num_pieces;
1849 size_type total_done;
1850 size_type total_wanted_done;
1851 size_type total_wanted;
1853 int num_seeds;
1854 float distributed_copies;
1856 int block_size;
1857 };
1858 </pre>
1859 <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
1860 torrent's current task. It may be checking files or downloading. The torrent's
1861 current task is in the <tt class="docutils literal"><span class="pre">state</span></tt> member, it will be one of the following:</p>
1863 <colgroup>
1866 </colgroup>
1869 <td>The torrent is in the queue for being checked. But there
1870 currently is another torrent that are being checked.
1871 This torrent will wait for its turn.</td>
1872 </tr>
1874 <td>The torrent has not started its download yet, and is
1875 currently checking existing files.</td>
1876 </tr>
1878 <td>The torrent has sent a request to the tracker and is
1879 currently waiting for a response</td>
1880 </tr>
1882 <td>The torrent is being downloaded. This is the state
1883 most torrents will be in most of the time. The progress
1884 meter will tell how much of the files that has been
1885 downloaded.</td>
1886 </tr>
1888 <td>In this state the torrent has finished downloading but
1889 still doesn't have the entire torrent. i.e. some pieces
1890 are filtered and won't get downloaded.</td>
1891 </tr>
1893 <td>In this state the torrent has finished downloading and
1894 is a pure seeder.</td>
1895 </tr>
1897 <td>If the torrent was started in full allocation mode, this
1898 indicates that the (disk) storage for the torrent is
1899 allocated.</td>
1900 </tr>
1901 </tbody>
1902 </table>
1903 <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>
1904 <p><tt class="docutils literal"><span class="pre">paused</span></tt> is set to true if the torrent is paused and false otherwise.</p>
1905 <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
1906 <tt class="docutils literal"><span class="pre">announce_interval</span></tt> is the time the tracker want us to wait until we announce ourself
1907 again the next time.</p>
1908 <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
1909 been successful yet, it's set to an empty string.</p>
1910 <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
1912 <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
1913 send and received this session, but only the actual payload data (i.e the interesting
1914 data), these counters ignore any protocol overhead.</p>
1915 <p><tt class="docutils literal"><span class="pre">total_failed_bytes</span></tt> is the number of bytes that has been downloaded and that
1916 has failed the piece hash test. In other words, this is just how much crap that
1917 has been downloaded.</p>
1918 <p><tt class="docutils literal"><span class="pre">total_redundant_bytes</span></tt> is the number of bytes that has been downloaded even
1919 though that data already was downloaded. The reason for this is that in some
1920 situations the same data can be downloaded by mistake. When libtorrent sends
1921 requests to a peer, and the peer doesn't send a response within a certain
1922 timeout, libtorrent will re-request that block. Another situation when
1923 libtorrent may re-request blocks is when the requests it sends out are not
1924 replied in FIFO-order (it will re-request blocks that are skipped by an out of
1925 order block). This is supposed to be as low as possible.</p>
1926 <p><tt class="docutils literal"><span class="pre">pieces</span></tt> is the bitmask that represents which pieces we have (set to true) and
1927 the pieces we don't have. It's a pointer and may be set to 0 if the torrent isn't
1928 downloading or seeding.</p>
1929 <p><tt class="docutils literal"><span class="pre">num_pieces</span></tt> is the number of pieces that has been downloaded. It is equivalent
1930 to: <tt class="docutils literal"><span class="pre">std::accumulate(pieces->begin(),</span> <span class="pre">pieces->end())</span></tt>. So you don't have to
1931 count yourself. This can be used to see if anything has updated since last time
1932 if you want to keep a graph of the pieces up to date.</p>
1933 <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
1934 torrent. These will usually have better precision than summing the rates from
1935 all peers. The rates are given as the number of bytes per second. The
1936 <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
1937 total transfer rate of payload only, not counting protocol chatter. This might
1938 be slightly smaller than the other rates, but if projected over a long time
1939 (e.g. when calculating ETA:s) the difference may be noticeable.</p>
1940 <p><tt class="docutils literal"><span class="pre">num_peers</span></tt> is the number of peers this torrent currently is connected to.
1941 Peer connections that are in the half-open state (is attempting to connect)
1942 or are queued for later connection attempt do not count. Although they are
1943 visible in the peer list when you call <a class="reference" href="#get-peer-info">get_peer_info()</a>.</p>
1944 <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
1945 send any scrape data in its announce reply. This data is optional and may
1946 not be available from all trackers. If these are not -1, they are the total
1947 number of peers that are seeding (complete) and the total number of peers
1948 that are still downloading (incomplete) this torrent.</p>
1949 <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
1950 this does not necessarily has to be downloaded during this session (that's
1952 <p><tt class="docutils literal"><span class="pre">total_wanted_done</span></tt> is the number of bytes we have downloaded, only counting the
1953 pieces that we actually want to download. i.e. excluding any pieces that we have but
1954 are filtered as not wanted.</p>
1955 <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
1956 excluding pieces that have been filtered.</p>
1957 <p><tt class="docutils literal"><span class="pre">num_seeds</span></tt> is the number of peers that are seeding that this client is
1958 currently connected to.</p>
1959 <p><tt class="docutils literal"><span class="pre">distributed_copies</span></tt> is the number of distributed copies of the torrent.
1960 Note that one copy may be spread out among many peers. The integer part
1961 tells how many copies there are currently of the rarest piece(s) among the
1962 peers this client is connected to. The fractional part tells the share of
1963 pieces that have more copies than the rarest piece(s). For example: 2.5 would
1964 mean that the rarest pieces have only 2 copies among the peers this torrent is
1966 <p>If we are a seed, the piece picker is deallocated as an optimization, and
1967 piece availability is no longer tracked. In this case the distributed
1969 <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
1970 is the number of bytes that each piece request asks for and the number of
1971 bytes that each bit in the <tt class="docutils literal"><span class="pre">partial_piece_info</span></tt>'s bitset represents
1972 (see <a class="reference" href="#get-download-queue">get_download_queue()</a>). This is typically 16 kB, but it may be
1973 larger if the pieces are larger.</p>
1974 </div>
1979 struct peer_info
1980 {
1981 enum
1982 {
1983 interesting = 0x1,
1984 choked = 0x2,
1985 remote_interested = 0x4,
1986 remote_choked = 0x8,
1987 supports_extensions = 0x10,
1988 local_connection = 0x20,
1989 handshake = 0x40,
1990 connecting = 0x80,
1991 queued = 0x100
1992 };
1994 unsigned int flags;
1996 enum peer_source_flags
1997 {
1998 tracker = 0x1,
1999 dht = 0x2,
2000 pex = 0x4,
2001 lsd = 0x8
2002 };
2004 int source;
2006 asio::ip::tcp::endpoint ip;
2007 float up_speed;
2008 float down_speed;
2009 float payload_up_speed;
2010 float payload_down_speed;
2011 size_type total_download;
2012 size_type total_upload;
2013 peer_id pid;
2015 bool seed;
2016 int upload_limit;
2017 int download_limit;
2019 char country[2];
2021 size_type load_balancing;
2023 int download_queue_length;
2024 int upload_queue_length;
2026 int downloading_piece_index;
2027 int downloading_block_index;
2028 int downloading_progress;
2029 int downloading_total;
2031 std::string client;
2033 enum
2034 {
2035 standard_bittorrent = 0,
2036 web_seed = 1
2037 };
2038 int connection_type;
2039 };
2040 </pre>
2041 <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
2042 any combination of the enums above. The following table describes each flag:</p>
2044 <colgroup>
2047 </colgroup>
2051 </tr>
2054 </tr>
2057 </tr>
2060 </tr>
2062 <td>means that this peer supports the
2064 </tr>
2066 <td>The connection was initiated by us, the peer has a
2067 listen port open, and that port is the same as in the
2068 address of this peer. If this flag is not set, this
2069 peer connection was opened by this peer connecting to
2070 us.</td>
2071 </tr>
2073 <td>The connection is opened, and waiting for the
2074 handshake. Until the handshake is done, the peer
2075 cannot be identified.</td>
2076 </tr>
2078 <td>The connection is in a half-open state (i.e. it is
2079 being connected).</td>
2080 </tr>
2082 <td>The connection is currently queued for a connection
2083 attempt. This may happen if there is a limit set on
2084 the number of half-open TCP connections.</td>
2085 </tr>
2086 </tbody>
2087 </table>
2088 <p><tt class="docutils literal"><span class="pre">source</span></tt> is a combination of flags describing from which sources this peer
2089 was received. The flags are:</p>
2091 <colgroup>
2094 </colgroup>
2098 </tr>
2101 </tr>
2103 <td>The peer was received from the peer exchange
2104 extension.</td>
2105 </tr>
2107 <td>The peer was received from the local service
2108 discovery (The peer is on the local network).</td>
2109 </tr>
2112 </tr>
2113 </tbody>
2114 </table>
2115 <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
2117 <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
2118 we have to and from this peer (including any protocol messages). The transfer rates
2119 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>.
2120 These figures are updated approximately once every second.</p>
2121 <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
2122 from and uploaded to this peer. These numbers do not include the protocol chatter, but only
2123 the payload data.</p>
2124 <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
2125 extract 'fingerprints' from the peer. Sometimes it can tell you which client the peer
2126 is using. See identify_client()_</p>
2127 <p><tt class="docutils literal"><span class="pre">pieces</span></tt> is a vector of booleans that has as many entries as there are pieces
2128 in the torrent. Each boolean tells you if the peer has that piece (if it's set to true)
2129 or if the peer miss that piece (set to false).</p>
2130 <p><tt class="docutils literal"><span class="pre">seed</span></tt> is true if this peer is a seed.</p>
2131 <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
2132 peer every second. It may be -1 if there's no local limit on the peer. The global
2133 limit and the torrent limit is always enforced anyway.</p>
2134 <p><tt class="docutils literal"><span class="pre">download_limit</span></tt> is the number of bytes per second this peer is allowed to
2136 <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
2137 is connected from. If the country hasn't been resolved yet, both chars are set
2140 The <tt class="docutils literal"><span class="pre">countries.nerd.dk</span></tt> service is used to look up countries. This field will
2141 remain set to 0 unless the torrent is set to resolve countries, see <a class="reference" href="#resolve-countries">resolve_countries()</a>.</p>
2142 <p><tt class="docutils literal"><span class="pre">load_balancing</span></tt> is a measurement of the balancing of free download (that we get)
2143 and free upload that we give. Every peer gets a certain amount of free upload, but
2145 number it means that this was a peer from which we have got this amount of free
2146 download.</p>
2147 <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
2148 that hasn't been answered with a piece yet.</p>
2149 <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
2150 that we haven't answered with a piece yet.</p>
2151 <p>You can know which piece, and which part of that piece, that is currently being
2152 downloaded from a specific peer by looking at the next four members.
2153 <tt class="docutils literal"><span class="pre">downloading_piece_index</span></tt> is the index of the piece that is currently being downloaded.
2154 This may be set to -1 if there's currently no piece downloading from this peer. If it is
2155 >= 0, the other three members are valid. <tt class="docutils literal"><span class="pre">downloading_block_index</span></tt> is the index of the
2156 block (or sub-piece) that is being downloaded. <tt class="docutils literal"><span class="pre">downloading_progress</span></tt> is the number
2157 of bytes of this block we have received from the peer, and <tt class="docutils literal"><span class="pre">downloading_total</span></tt> is
2158 the total number of bytes in this block.</p>
2159 <p><tt class="docutils literal"><span class="pre">client</span></tt> is a string describing the software at the other end of the connection.
2160 In some cases this information is not available, then it will contain a string
2161 that may give away something about which software is running in the other end.
2162 In the case of a web seed, the server type and version will be a part of this
2163 string.</p>
2164 <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
2165 <tt class="docutils literal"><span class="pre">web_seed</span></tt>. These are currently the only implemented protocols.</p>
2166 </div>
2169 <p>You have some control over tracker requests through the <tt class="docutils literal"><span class="pre">session_settings</span></tt> object. You
2170 create it and fill it with your settings and then use <tt class="docutils literal"><span class="pre">session::set_settings()</span></tt>
2171 to apply them. You have control over proxy and authorization settings and also the user-agent
2172 that will be sent to the tracker. The user-agent is a good way to identify your client.</p>
2174 struct session_settings
2175 {
2176 session_settings();
2177 std::string user_agent;
2178 int tracker_completion_timeout;
2179 int tracker_receive_timeout;
2180 int tracker_maximum_response_length;
2182 int piece_timeout;
2183 float request_queue_time;
2184 int max_allowed_in_request_queue;
2185 int max_out_request_queue;
2186 int whole_pieces_threshold;
2187 int peer_timeout;
2188 int urlseed_timeout;
2189 int urlseed_pipeline_size;
2190 int file_pool_size;
2191 bool allow_multiple_connections_per_ip;
2192 int max_failcount;
2193 int min_reconnect_time;
2194 int peer_connect_timeout;
2195 bool use_dht_as_fallback;
2196 };
2197 </pre>
2198 <p><tt class="docutils literal"><span class="pre">user_agent</span></tt> this is the client identification to the tracker.
2199 The recommended format of this string is:
2201 This name will not only be used when making HTTP requests, but also when
2202 sending extended headers to peers that support that extension.</p>
2203 <p><tt class="docutils literal"><span class="pre">tracker_completion_timeout</span></tt> is the number of seconds the tracker
2204 connection will wait from when it sent the request until it considers the
2206 <p><tt class="docutils literal"><span class="pre">tracker_receive_timeout</span></tt> is the number of seconds to wait to receive
2207 any data from the tracker. If no data is received for this number of
2208 seconds, the tracker will be considered as having timed out. If a tracker
2209 is down, this is the kind of timeout that will occur. The default value
2211 <p><tt class="docutils literal"><span class="pre">tracker_maximum_response_length</span></tt> is the maximum number of bytes in a
2212 tracker response. If a response size passes this number it will be rejected
2213 and the connection will be closed. On gzipped responses this size is measured
2214 on the uncompressed data. So, if you get 20 bytes of gzip response that'll
2215 expand to 2 megs, it will be interrupted before the entire response has been
2216 uncompressed (given your limit is lower than 2 megs). Default limit is
2218 <p><tt class="docutils literal"><span class="pre">piece_timeout</span></tt> controls the number of seconds from a request is sent until
2219 it times out if no piece response is returned.</p>
2220 <p><tt class="docutils literal"><span class="pre">request_queue_time</span></tt> is the length of the request queue given in the number
2221 of seconds it should take for the other end to send all the pieces. i.e. the
2222 actual number of requests depends on the download rate and this number.</p>
2223 <p><tt class="docutils literal"><span class="pre">max_allowed_in_request_queue</span></tt> is the number of outstanding block requests
2224 a peer is allowed to queue up in the client. If a peer sends more requests
2225 than this (before the first one has been handled) the last request will be
2226 dropped. The higher this is, the faster upload speeds the client can get to a
2227 single peer.</p>
2228 <p><tt class="docutils literal"><span class="pre">max_out_request_queue</span></tt> is the maximum number of outstanding requests to
2229 send to a peer. This limit takes precedence over <tt class="docutils literal"><span class="pre">request_queue_time</span></tt>. i.e.
2230 no matter the download speed, the number of outstanding requests will never
2231 exceed this limit.</p>
2232 <p><tt class="docutils literal"><span class="pre">whole_pieces_threshold</span></tt> is a limit in seconds. if a whole piece can be
2233 downloaded in at least this number of seconds from a specific peer, the
2234 peer_connection will prefer requesting whole pieces at a time from this peer.
2235 The benefit of this is to better utilize disk caches by doing localized
2236 accesses and also to make it easier to identify bad peers if a piece fails
2237 the hash check.</p>
2238 <p><tt class="docutils literal"><span class="pre">peer_timeout</span></tt> is the number of seconds the peer connection should
2239 wait (for any activity on the peer connection) before closing it due
2240 to time out. This defaults to 120 seconds, since that's what's specified
2241 in the protocol specification. After half the time out, a keep alive message
2242 is sent.</p>
2243 <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
2245 <p><tt class="docutils literal"><span class="pre">urlseed_pipeline_size</span></tt> controls the pipelining with the web server. When
2246 using persistent connections to HTTP 1.1 servers, the client is allowed to
2247 send more requests before the first response is received. This number controls
2249 <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
2250 session will keep open. The reason why files are left open at all is that
2251 some anti virus software hooks on every file close, and scans the file for
2252 viruses. deferring the closing of the files will be the difference between
2253 a usable system and a completely hogged down system. Most operating systems
2254 also has a limit on the total number of file descriptors a process may have
2255 open. It is usually a good idea to find this limit and set the number of
2256 connections and the number of files limits so their sum is slightly below it.</p>
2257 <p><tt class="docutils literal"><span class="pre">allow_multiple_connections_per_ip</span></tt> determines if connections from the
2258 same IP address as existing connections should be rejected or not. Multiple
2259 connections from the same IP address is not allowed by default, to prevent
2260 abusive behavior by peers. It may be useful to allow such connections in
2261 cases where simulations are run on the same machie, and all peers in a
2262 swarm has the same IP address.</p>
2263 <p><tt class="docutils literal"><span class="pre">max_failcount</span></tt> is the maximum times we try to connect to a peer before
2264 stop connecting again. If a peer succeeds, the failcounter is reset. If
2265 a peer is retrieved from a peer source (other than DHT) the failcount is
2266 decremented by one, allowing another try.</p>
2267 <p><tt class="docutils literal"><span class="pre">min_reconnect_time</span></tt> is the time to wait between connection attempts. If
2268 the peer fails, the time is multiplied by fail counter.</p>
2269 <p><tt class="docutils literal"><span class="pre">peer_connect_timeout</span></tt> the number of seconds to wait after a connection
2270 attempt is initiated to a peer until it is considered as having timed out.
2271 The default is 10 seconds. This setting is especially important in case
2272 the number of half-open connections are limited, since stale half-open
2273 connection may delay the connection of other peers considerably.</p>
2274 <p><tt class="docutils literal"><span class="pre">use_dht_as_fallback</span></tt> determines how the DHT is used. If this is true
2275 (which it is by default), the DHT will only be used for torrents where
2276 all trackers in its tracker list has failed. Either by an explicit error
2277 message or a time out.</p>
2278 </div>
2281 <p>The <tt class="docutils literal"><span class="pre">proxy_settings</span></tt> structs contains the information needed to
2282 direct certain traffic to a proxy.</p>
2283 <blockquote>
2285 struct proxy_settings
2286 {
2287 proxy_settings();
2289 std::string hostname;
2290 int port;
2292 std::string username;
2293 std::string password;
2295 enum proxy_type
2296 {
2297 none,
2298 socks5,
2299 socks5_pw,
2300 http,
2301 http_pw
2302 };
2304 proxy_type type;
2305 };
2306 </pre>
2307 </blockquote>
2308 <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
2309 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>
2310 can be set to authenticate with the proxy.</p>
2311 <p>The <tt class="docutils literal"><span class="pre">type</span></tt> tells libtorrent what kind of proxy server it is. The following
2312 options are available:</p>
2313 <blockquote>
2315 <li><tt class="docutils literal"><span class="pre">none</span></tt> - This is the default, no proxy server is used, all other fields
2316 are ignored.</li>
2317 <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
2318 does not require any authentication. The username and password are ignored.</li>
2319 <li><tt class="docutils literal"><span class="pre">socks5_pw</span></tt> - The server is assumed to be a SOCKS5 server that supports
2320 plain text username and password authentication (<a class="reference" href="http://www.faqs.org/rfcs/rfc1929.html">RFC 1929</a>). The username
2321 and password specified may be sent to the proxy if it requires.</li>
2322 <li><tt class="docutils literal"><span class="pre">http</span></tt> - The server is assumed to be an HTTP proxy. If the transport used
2323 for the connection is non-HTTP, the server is assumed to support the
2324 <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
2325 suffice. The proxy is assumed to not require authorization. The username
2326 and password will not be used.</li>
2327 <li><tt class="docutils literal"><span class="pre">http_pw</span></tt> - The server is assumed to be an HTTP proxy that requires
2328 user authorization. The username and password will be sent to the proxy.</li>
2329 </ul>
2330 </blockquote>
2331 </div>
2334 <p>The <tt class="docutils literal"><span class="pre">ip_filter</span></tt> class is a set of rules that uniquely categorizes all
2335 ip addresses as allowed or disallowed. The default constructor creates
2337 the IPv4 range, and the equivalent range covering all addresses for the
2338 IPv6 range).</p>
2339 <blockquote>
2342 struct ip_range
2343 {
2344 Addr first;
2345 Addr last;
2346 int flags;
2347 };
2349 class ip_filter
2350 {
2351 public:
2352 enum access_flags { blocked = 1 };
2354 ip_filter();
2355 void add_rule(address first, address last, int flags);
2356 int access(address const& addr) const;
2361 filter_tuple_t export_filter() const;
2362 };
2363 </pre>
2364 </blockquote>
2367 <blockquote>
2369 ip_filter()
2370 </pre>
2371 </blockquote>
2373 <p>postcondition:
2374 <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>
2375 </div>
2378 <blockquote>
2380 void add_rule(address first, address last, int flags);
2381 </pre>
2382 </blockquote>
2383 <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
2384 ip addresses that will be marked with the given flags. The <tt class="docutils literal"><span class="pre">flags</span></tt>
2385 can currently be 0, which means allowed, or <tt class="docutils literal"><span class="pre">ip_filter::blocked</span></tt>, which
2386 means disallowed.</p>
2387 <p>precondition:
2388 <tt class="docutils literal"><span class="pre">first.is_v4()</span> <span class="pre">==</span> <span class="pre">last.is_v4()</span> <span class="pre">&&</span> <span class="pre">first.is_v6()</span> <span class="pre">==</span> <span class="pre">last.is_v6()</span></tt></p>
2389 <p>postcondition:
2390 <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>
2391 <p>This means that in a case of overlapping ranges, the last one applied takes
2392 precedence.</p>
2393 </div>
2396 <blockquote>
2398 int access(address const& addr) const;
2399 </pre>
2400 </blockquote>
2401 <p>Returns the access permissions for the given address (<tt class="docutils literal"><span class="pre">addr</span></tt>). The permission
2402 can currently be 0 or <tt class="docutils literal"><span class="pre">ip_filter::blocked</span></tt>. The complexity of this operation
2403 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
2404 the current filter.</p>
2405 </div>
2408 <blockquote>
2412 </pre>
2413 </blockquote>
2414 <p>This function will return the current state of the filter in the minimum number of
2415 ranges possible. They are sorted from ranges in low addresses to high addresses. Each
2416 entry in the returned vector is a range with the access control specified in its
2418 <p>The return value is a tuple containing two range-lists. One for IPv4 addresses
2419 and one for IPv6 addresses.</p>
2420 </div>
2421 </div>
2424 <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
2425 <tt class="docutils literal"><span class="pre">big_number</span></tt>. It represents 20 bytes of data. Its synopsis follows:</p>
2427 class big_number
2428 {
2429 public:
2430 bool operator==(const big_number& n) const;
2431 bool operator!=(const big_number& n) const;
2434 const unsigned char* begin() const;
2435 const unsigned char* end() const;
2437 unsigned char* begin();
2438 unsigned char* end();
2439 };
2440 </pre>
2442 </div>
2447 class hasher
2448 {
2449 public:
2450 hasher();
2451 hasher(char const* data, unsigned int len);
2453 void update(char const* data, unsigned int len);
2454 sha1_hash final();
2455 void reset();
2456 };
2457 </pre>
2458 <p>You use it by first instantiating it, then call <tt class="docutils literal"><span class="pre">update()</span></tt> to feed it
2459 with data. i.e. you don't have to keep the entire buffer of which you want to
2460 create the hash in memory. You can feed the hasher parts of it at a time. When
2461 You have fed the hasher with all the data, you call <tt class="docutils literal"><span class="pre">final()</span></tt> and it
2462 will return the sha1-hash of the data.</p>
2463 <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
2464 sha1 context and feed it the data passed in.</p>
2465 <p>If you want to reuse the hasher object once you have created a hash, you have to
2466 call <tt class="docutils literal"><span class="pre">reset()</span></tt> to reinitialize it.</p>
2467 <p>The sha1-algorithm used was implemented by Steve Reid and released as public domain.
2468 For more info, see <tt class="docutils literal"><span class="pre">src/sha1.cpp</span></tt>.</p>
2469 </div>
2472 <p>The fingerprint class represents information about a client and its version. It is used
2473 to encode this information into the client's peer id.</p>
2476 struct fingerprint
2477 {
2478 fingerprint(const char* id_string, int major, int minor
2479 , int revision, int tag);
2481 std::string to_string() const;
2483 char name[2];
2484 char major_version;
2485 char minor_version;
2486 char revision_version;
2487 char tag_version;
2489 };
2490 </pre>
2491 <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
2492 exactly two characters. These are the characters that should be unique for your client. Make
2493 sure not to clash with anybody else. Here are some taken id's:</p>
2495 <colgroup>
2498 </colgroup>
2502 </tr>
2503 </thead>
2507 </tr>
2510 </tr>
2513 </tr>
2516 </tr>
2519 </tr>
2522 </tr>
2525 </tr>
2526 </tbody>
2527 </table>
2528 <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>
2529 <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
2531 <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>
2532 </div>
2537 <blockquote>
2539 std::string identify_client(peer_id const& id);
2540 </pre>
2541 </blockquote>
2542 <p>This function is declared in the header <tt class="docutils literal"><span class="pre"><libtorrent/identify_client.hpp></span></tt>. It can can be used
2543 to extract a string describing a client version from its peer-id. It will recognize most clients
2544 that have this kind of identification in the peer-id.</p>
2545 </div>
2548 <blockquote>
2551 </pre>
2552 </blockquote>
2553 <p>Returns an optional fingerprint if any can be identified from the peer id. This can be used
2554 to automate the identification of clients. It will not be able to identify peers with non-
2555 standard encodings. Only Azureus style, Shadow's style and Mainline style. This function is
2556 declared in the header <tt class="docutils literal"><span class="pre"><libtorrent/identify_client.hpp></span></tt>.</p>
2557 </div>
2560 <blockquote>
2564 </pre>
2565 </blockquote>
2566 <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>
2567 <p>The <a class="reference" href="#entry">entry</a> class is the internal representation of the bencoded data
2568 and it can be used to retrieve information, an <a class="reference" href="#entry">entry</a> can also be build by
2569 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>
2570 iterator.</p>
2571 <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
2572 (<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
2573 are templates and are usually instantiated as <a class="reference" href="http://www.sgi.com/tech/stl/ostream_iterator.html">ostream_iterator</a>,
2574 <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
2575 functions will assume that the iterator refers to a character
2576 (<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
2577 in memory, you can do it like this:</p>
2580 bencode(std::back_inserter(buf), e);
2581 </pre>
2585 // ...
2586 entry e = bdecode(buf.begin(), buf.end());
2587 </pre>
2590 const char* buf;
2591 // ...
2592 entry e = bdecode(buf, buf + data_size);
2593 </pre>
2594 <p>Now we just need to know how to retrieve information from the <a class="reference" href="#entry">entry</a>.</p>
2595 <p>If <tt class="docutils literal"><span class="pre">bdecode()</span></tt> encounters invalid encoded data in the range given to it
2597 </div>
2600 <blockquote>
2602 bool supports_sparse_files(boost::filesystem::path const&);
2603 </pre>
2604 </blockquote>
2605 <p>The path is expected to be the path to the directory where you will want to
2606 store sparse files. The return value is true if the file system supports
2607 sparse files or if it supports automatic zero filling of files. The main
2608 characteristics that is tested by this function is not the storage aspects
2609 of sparse files, but rather the support for seeking passed end of file and
2610 write data there, with expected behavior.</p>
2611 </div>
2612 </div>
2615 <p>The <tt class="docutils literal"><span class="pre">pop_alert()</span></tt> function on session is the interface for retrieving
2616 alerts, warnings, messages and errors from libtorrent. If there hasn't
2617 occurred any errors (matching your severity level) <tt class="docutils literal"><span class="pre">pop_alert()</span></tt> will
2618 return a zero pointer. If there has been some error, it will return a pointer
2619 to an alert object describing it. You can then use the alert object and query
2620 it for information about the error or message. To retrieve any alerts, you have
2621 to select a severity level using <tt class="docutils literal"><span class="pre">session::set_severity_level()</span></tt>. It defaults to
2622 <tt class="docutils literal"><span class="pre">alert::none</span></tt>, which means that you don't get any messages at all, ever.
2623 You have the following levels to select among:</p>
2625 <colgroup>
2628 </colgroup>
2631 <td>No alert will ever have this severity level, which
2632 effectively filters all messages.</td>
2633 </tr>
2635 <td>Fatal errors will have this severity level. Examples can
2636 be disk full or something else that will make it
2637 impossible to continue normal execution.</td>
2638 </tr>
2640 <td>Signals errors that requires user interaction or
2641 messages that almost never should be ignored. For
2642 example, a chat message received from another peer is
2643 announced as severity <tt class="docutils literal"><span class="pre">critical</span></tt>.</td>
2644 </tr>
2646 <td>Messages with the warning severity can be a tracker that
2647 times out or responds with invalid data. It will be
2648 retried automatically, and the possible next tracker in
2649 a multitracker sequence will be tried. It does not
2650 require any user interaction.</td>
2651 </tr>
2653 <td>Events that can be considered normal, but still deserves
2654 an event. This could be a piece hash that fails.</td>
2655 </tr>
2657 <td>This will include a lot of debug events that can be used
2658 both for debugging libtorrent but also when debugging
2659 other clients that are connected to libtorrent. It will
2660 report strange behaviors among the connected peers.</td>
2661 </tr>
2662 </tbody>
2663 </table>
2664 <p>When setting a severity level, you will receive messages of that severity and all
2665 messages that are more sever. If you set <tt class="docutils literal"><span class="pre">alert::none</span></tt> (the default) you will not receive
2666 any events at all.</p>
2667 <p>When you set a severity level other than <tt class="docutils literal"><span class="pre">none</span></tt>, you have the responsibility to call
2668 <tt class="docutils literal"><span class="pre">pop_alert()</span></tt> from time to time. If you don't do that, the alert queue will just grow.</p>
2669 <p>When you get an alert, you can use <tt class="docutils literal"><span class="pre">typeid()</span></tt> or <tt class="docutils literal"><span class="pre">dynamic_cast<></span></tt> to get more detailed
2670 information on exactly which type it is. i.e. what kind of error it is. You can also use a
2671 <a class="reference" href="#dispatcher">dispatcher</a> mechanism that's available in libtorrent.</p>
2672 <p>All alert types are defined in the <tt class="docutils literal"><span class="pre"><libtorrent/alert_types.hpp></span></tt> header file.</p>
2673 <p>The <tt class="docutils literal"><span class="pre">alert</span></tt> class is the base class that specific messages are derived from. This
2674 is its synopsis:</p>
2676 class alert
2677 {
2678 public:
2680 enum severity_t { debug, info, warning, critical, fatal, none };
2682 alert(severity_t severity, std::string const& msg);
2683 virtual ~alert();
2685 std::string const& msg() const;
2686 severity_t severity() const;
2689 };
2690 </pre>
2691 <p>This means that all alerts have at least a string describing it. They also
2692 have a severity level that can be used to sort them or present them to the
2693 user in different ways.</p>
2694 <p>There's another alert base class that all most alerts derives from, all the
2695 alerts that are generated for a specific torrent are derived from:</p>
2697 struct torrent_alert: alert
2698 {
2701 torrent_handle handle;
2702 };
2703 </pre>
2704 <p>The specific alerts, that all derives from <tt class="docutils literal"><span class="pre">alert</span></tt>, are:</p>
2707 <p>This alert is generated when none of the ports, given in the port range, to
2708 <a class="reference" href="#session">session</a> can be opened for listening. This alert is generated as severity
2711 struct listen_failed_alert: alert
2712 {
2713 listen_failed_alert(const std::string& msg);
2715 };
2716 </pre>
2717 </div>
2720 <p>This alert is generated when a NAT router was successfully found but some
2721 part of the port mapping request failed. It contains a text message that
2722 may help the user figure out what is wrong. This alert is not generated in
2723 case it appears the client is not running on a NAT:ed network or if it
2724 appears there is no NAT router that can be remote controlled to add port
2725 mappings.</p>
2726 <p>The alert is generated as severity <tt class="docutils literal"><span class="pre">warning</span></tt>, since it should be displayed
2727 to the user somehow, and could mean reduced preformance.</p>
2729 struct portmap_error_alert: alert
2730 {
2731 portmap_error_alert(const std::string& msg);
2733 };
2734 </pre>
2735 </div>
2738 <p>This alert is generated when a NAT router was successfully found and
2739 a port was successfully mapped on it. On a NAT:ed network with a NAT-PMP
2740 capable router, this is typically generated once when mapping the TCP
2741 port and, if DHT is enabled, when the UDP port is mapped. This is merely
2742 an informational alert, and is generated at severity level <tt class="docutils literal"><span class="pre">info</span></tt>.</p>
2744 struct portmap_alert: alert
2745 {
2746 portmap_alert(const std::string& msg);
2748 };
2749 </pre>
2750 </div>
2753 <p>If the storage fails to read or write files that it needs access to, this alert is
2754 generated and the torrent is paused. It is generated as severity level <tt class="docutils literal"><span class="pre">fatal</span></tt>.</p>
2756 struct file_error_alert: torrent_alert
2757 {
2758 file_error_alert(
2759 const torrent_handle& h
2760 , const std::string& msg);
2763 };
2764 </pre>
2765 </div>
2768 <p>This alert is generated each time a tracker announce is sent (or attempted to be sent).
2769 It is generated at severity level <tt class="docutils literal"><span class="pre">info</span></tt>.</p>
2771 struct tracker_announce_alert: torrent_alert
2772 {
2773 tracker_announce_alert(
2774 const torrent_handle& h
2775 , const std::string& msg);
2778 };
2779 </pre>
2780 </div>
2783 <p>This alert is generated on tracker time outs, premature disconnects, invalid response or
2784 a HTTP response other than "200 OK". From the alert you can get the handle to the torrent
2785 the tracker belongs to. This alert is generated as severity level <tt class="docutils literal"><span class="pre">warning</span></tt>.</p>
2786 <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.
2787 <tt class="docutils literal"><span class="pre">status_code</span></tt> is the code returned from the HTTP server. 401 means the tracker needs
2788 authentication, 404 means not found etc. If the tracker timed out, the code will be set
2791 struct tracker_alert: torrent_alert
2792 {
2793 tracker_alert(torrent_handle const& h, int times, int status
2794 , const std::string& msg);
2797 int times_in_row;
2798 int status_code;
2799 };
2800 </pre>
2801 </div>
2804 <p>This alert is only for informational purpose. It is generated when a tracker announce
2805 succeeds. It is generated regardless what kind of tracker was used, be it UDP, HTTP or
2806 the DHT. It is generated with severity level <tt class="docutils literal"><span class="pre">info</span></tt>.</p>
2808 struct tracker_reply_alert: torrent_alert
2809 {
2810 tracker_reply_alert(const torrent_handle& h
2811 , int num_peers
2812 , const std::string& msg);
2814 int num_peers;
2817 };
2818 </pre>
2819 <p>The <tt class="docutils literal"><span class="pre">num_peers</span></tt> tells how many peers were returned from the tracker. This is
2820 not necessarily all new peers, some of them may already be connected.</p>
2821 </div>
2824 <p>This alert is triggered if the tracker reply contains a warning field. Usually this
2825 means that the tracker announce was successful, but the tracker has a message to
2826 the client. The message string in the alert will contain the warning message from
2827 the tracker. It is generated with severity level <tt class="docutils literal"><span class="pre">warning</span></tt>.</p>
2829 struct tracker_warning_alert: torrent_alert
2830 {
2831 tracker_warning_alert(torrent_handle const& h
2832 , std::string const& msg);
2835 };
2836 </pre>
2837 </div>
2840 <p>This alert is generated when a HTTP seed name lookup fails. This alert is
2841 generated as severity level <tt class="docutils literal"><span class="pre">warning</span></tt>.</p>
2842 <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>
2844 struct url_seed_alert: torrent_alert
2845 {
2847 , const std::string& msg);
2850 std::string url;
2851 };
2852 </pre>
2853 </div>
2856 <p>This alert is generated when a finished piece fails its hash check. You can get the handle
2857 to the torrent which got the failed piece and the index of the piece itself from the alert.
2858 This alert is generated as severity level <tt class="docutils literal"><span class="pre">info</span></tt>.</p>
2860 struct hash_failed_alert: torrent_alert
2861 {
2862 hash_failed_alert(
2863 torrent_handle const& h
2864 , int index
2865 , const std::string& msg);
2869 int piece_index;
2870 };
2871 </pre>
2872 </div>
2875 <p>This alert is generated when a peer is banned because it has sent too many corrupt pieces
2876 to us. It is generated at severity level <tt class="docutils literal"><span class="pre">info</span></tt>. The <tt class="docutils literal"><span class="pre">handle</span></tt> member is a <a class="reference" href="#torrent-handle">torrent_handle</a>
2877 to the torrent that this peer was a member of.</p>
2879 struct peer_ban_alert: torrent_alert
2880 {
2881 peer_ban_alert(
2882 asio::ip::tcp::endpoint const& pip
2883 , torrent_handle h
2884 , const std::string& msg);
2888 asio::ip::tcp::endpoint ip;
2889 };
2890 </pre>
2891 </div>
2894 <p>This alert is generated when a peer sends invalid data over the peer-peer protocol. The peer
2895 will be disconnected, but you get its ip address from the alert, to identify it. This alert
2896 is generated as severity level <tt class="docutils literal"><span class="pre">debug</span></tt>.</p>
2898 struct peer_error_alert: alert
2899 {
2900 peer_error_alert(
2901 asio::ip::tcp::endpoint const& pip
2902 , peer_id const& pid
2903 , const std::string& msg);
2906 asio::ip::tcp::endpoint ip;
2907 peer_id id;
2908 };
2909 </pre>
2910 </div>
2913 <p>This is a debug alert that is generated by an incoming invalid piece request. The <tt class="docutils literal"><span class="pre">handle</span></tt>
2914 is a handle to the torrent the peer is a member of. <tt class="docutils literal"><span class="pre">Ïp</span></tt> is the address of the peer and the
2915 <tt class="docutils literal"><span class="pre">request</span></tt> is the actual incoming request from the peer. The alert is generated as severity level
2918 struct invalid_request_alert: torrent_alert
2919 {
2920 invalid_request_alert(
2921 peer_request const& r
2922 , torrent_handle const& h
2923 , asio::ip::tcp::endpoint const& send
2924 , peer_id const& pid
2925 , std::string const& msg);
2929 asio::ip::tcp::endpoint ip;
2930 peer_request request;
2931 peer_id id;
2932 };
2935 struct peer_request
2936 {
2937 int piece;
2938 int start;
2939 int length;
2940 bool operator==(peer_request const& r) const;
2941 };
2942 </pre>
2943 <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
2944 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
2945 should be read, and <tt class="docutils literal"><span class="pre">length</span></tt> is the amount of data it wants.</p>
2946 </div>
2949 <p>This alert is generated when a torrent switches from being a downloader to a seed.
2950 It will only be generated once per torrent. It contains a torrent_handle to the
2951 torrent in question. This alert is generated as severity level <tt class="docutils literal"><span class="pre">info</span></tt>.</p>
2953 struct torrent_finished_alert: torrent_alert
2954 {
2955 torrent_finished_alert(
2956 const torrent_handle& h
2957 , const std::string& msg);
2960 };
2961 </pre>
2962 </div>
2965 <p>This alert is generated when the metadata has been completely received and the info-hash
2966 failed to match it. i.e. the metadata that was received was corrupt. libtorrent will
2967 automatically retry to fetch it in this case. This is only relevant when running a
2968 torrent-less download, with the metadata extension provided by libtorrent.
2969 It is generated at severity level <tt class="docutils literal"><span class="pre">info</span></tt>.</p>
2971 struct metadata_failed_alert: torrent_alert
2972 {
2973 metadata_failed_alert(
2974 torrent_handle const& h
2975 , std::string const& msg);
2978 };
2979 </pre>
2980 </div>
2983 <p>This alert is generated when the metadata has been completely received and the torrent
2984 can start downloading. It is not generated on torrents that are started with metadata, but
2985 only those that needs to download it from peers (when utilizing the libtorrent extension).
2986 It is generated at severity level <tt class="docutils literal"><span class="pre">info</span></tt>.</p>
2988 struct metadata_received_alert: torrent_alert
2989 {
2990 metadata_received_alert(
2991 torrent_handle const_& h
2992 , std::string const& msg);
2995 };
2996 </pre>
2997 </div>
3000 <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
3001 files on disk did not match the fastresume file. The string explains the reason why the
3002 resume file was rejected. It is generated at severity level <tt class="docutils literal"><span class="pre">warning</span></tt>.</p>
3004 struct fastresume_rejected_alert: torrent_alert
3005 {
3006 fastresume_rejected_alert(torrent_handle const& h
3007 , std::string const& msg);
3010 };
3011 </pre>
3012 </div>
3015 <p>This alert is generated when a peer is blocked by the IP filter. It has the severity leve
3016 <tt class="docutils literal"><span class="pre">info</span></tt>. The <tt class="docutils literal"><span class="pre">ip</span></tt> member is the address that was blocked.</p>
3018 struct peer_blocked_alert: alert
3019 {
3020 peer_blocked_alert(address const& ip_
3021 , std::string const& msg);
3023 address ip;
3026 };
3027 </pre>
3028 </div>
3031 <p>The <tt class="docutils literal"><span class="pre">handle_alert</span></tt> class is defined in <tt class="docutils literal"><span class="pre"><libtorrent/alert.hpp></span></tt>.</p>
3034 struct my_handler
3035 {
3036 void operator()(portmap_error_alert const& a)
3037 {
3039 }
3041 void operator()(tracker_warning_alert const& a)
3042 {
3044 }
3046 void operator()(torrent_finished_alert const& a)
3047 {
3048 // write fast resume data
3049 // ...
3052 << std::endl;
3053 }
3054 };
3055 </pre>
3058 a = ses.pop_alert();
3059 my_handler h;
3060 while (a.get())
3061 {
3062 handle_alert<portmap_error_alert
3063 , tracker_warning_alert
3064 , torrent_finished_alert
3065 >::handle_alert(h, a);
3066 a = ses.pop_alert();
3067 }
3068 </pre>
3070 parameters to select between more types. If the number of types are more than
3071 15, you can define <tt class="docutils literal"><span class="pre">TORRENT_MAX_ALERT_TYPES</span></tt> to a greater number before
3072 including <tt class="docutils literal"><span class="pre"><libtorrent/alert.hpp></span></tt>.</p>
3073 </div>
3074 </div>
3077 <p>There are a number of exceptions that can be thrown from different places in libtorrent,
3078 here's a complete list with description.</p>
3081 <p>This exception is thrown when querying information from a <a class="reference" href="#torrent-handle">torrent_handle</a> that hasn't
3082 been initialized or that has become invalid.</p>
3084 struct invalid_handle: std::exception
3085 {
3086 const char* what() const throw();
3087 };
3088 </pre>
3089 </div>
3092 <p>This is thrown by <a class="reference" href="#add-torrent">add_torrent()</a> if the torrent already has been added to
3093 the session.</p>
3095 struct duplicate_torrent: std::exception
3096 {
3097 const char* what() const throw();
3098 };
3099 </pre>
3100 </div>
3103 <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>
3105 struct invalid_encoding: std::exception
3106 {
3107 const char* what() const throw();
3108 };
3109 </pre>
3110 </div>
3113 <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
3114 match the type you want to extract from it.</p>
3116 struct type_error: std::runtime_error
3117 {
3118 type_error(const char* error);
3119 };
3120 </pre>
3121 </div>
3124 <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
3125 doesn't meet the requirements on what information has to be present in a torrent file.</p>
3127 struct invalid_torrent_file: std::exception
3128 {
3129 const char* what() const throw();
3130 };
3131 </pre>
3132 </div>
3133 </div>
3136 <p>The fast resume mechanism is a way to remember which pieces are downloaded
3137 and where they are put between sessions. You can generate fast resume data by
3138 calling <tt class="docutils literal"><span class="pre">torrent_handle::write_resume_data()</span></tt> on <a class="reference" href="#torrent-handle">torrent_handle</a>. You can
3139 then save this data to disk and use it when resuming the torrent. libtorrent
3140 will not check the piece hashes then, and rely on the information given in the
3141 fast-resume data. The fast-resume data also contains information about which
3142 blocks, in the unfinished pieces, were downloaded, so it will not have to
3143 start from scratch on the partially downloaded pieces.</p>
3144 <p>To use the fast-resume data you simply give it to <a class="reference" href="#add-torrent">add_torrent()</a>, and it
3145 will skip the time consuming checks. It may have to do the checking anyway, if
3146 the fast-resume data is corrupt or doesn't fit the storage for that torrent,
3147 then it will not trust the fast-resume data and just do the checking.</p>
3152 <colgroup>
3155 </colgroup>
3159 </tr>
3162 </tr>
3165 </tr>
3166 <tr><td><tt class="docutils literal"><span class="pre">blocks</span> <span class="pre">per</span> <span class="pre">piece</span></tt></td>
3167 <td>integer, the number of blocks per piece. Must be: piece_size
3169 is the number of blocks per (normal sized) piece. Usually
3172 </tr>
3175 tells which piece is on which slot. If piece index is -2 it
3176 means it is free, that there's no piece there. If it is -1,
3177 means the slot isn't allocated on disk yet. The pieces have
3178 to meet the following requirement:</p>
3180 the piece must be located in that slot.</p>
3181 </td>
3182 </tr>
3185 layout:</p>
3187 <colgroup>
3190 </colgroup>
3193 <td>string, the ip address of the peer. This is
3194 not a binary representation of the ip
3195 address, but the string representation. It
3196 may be an IPv6 string or an IPv4 string.</td>
3197 </tr>
3200 </tr>
3201 </tbody>
3202 </table>
3204 fast-resume data was saved.</p>
3205 </td>
3206 </tr>
3209 piece, and has the following layout:</p>
3211 <colgroup>
3214 </colgroup>
3217 <td>integer, the index of the piece this entry
3218 refers to.</td>
3219 </tr>
3221 <td>string, a binary bitmask representing the
3222 blocks that have been downloaded in this
3223 piece.</td>
3224 </tr>
3226 <td>The adler32 checksum of the data in the
3228 </tr>
3229 </tbody>
3230 </table>
3231 </td>
3232 </tr>
3233 <tr><td><tt class="docutils literal"><span class="pre">file</span> <span class="pre">sizes</span></tt></td>
3234 <td>list where each entry corresponds to a file in the file list
3235 in the metadata. Each entry has a list of two values, the
3236 first value is the size of the file in bytes, the second
3237 is the time stamp when the last time someone wrote to it.
3238 This information is used to compare with the files on disk.
3239 All the files must match exactly this information in order
3240 to consider the resume data as current. Otherwise a full
3241 re-check is issued.</td>
3242 </tr>
3244 <td>The allocation mode for the storage. Can be either <tt class="docutils literal"><span class="pre">full</span></tt>
3245 or <tt class="docutils literal"><span class="pre">compact</span></tt>. If this is full, the file sizes and
3246 timestamps are disregarded. Pieces are assumed not to have
3247 moved around even if the files have been modified after the
3248 last resume data checkpoint.</td>
3249 </tr>
3250 </tbody>
3251 </table>
3252 </div>
3253 </div>
3257 <blockquote>
3259 <li>The first thread is the main thread that will sit
3260 idle in a <tt class="docutils literal"><span class="pre">select()</span></tt> call most of the time. This thread runs the main loop
3261 that will send and receive data on all connections.</li>
3262 <li>The second thread is a hash-check thread. Whenever a torrent is added it will
3263 first be passed to this thread for checking the files that may already have been
3264 downloaded. If there is any resume data this thread will make sure it is valid
3265 and matches the files. Once the torrent has been checked, it is passed on to the
3266 main thread that will start it. The hash-check thread has a queue of torrents,
3267 it will only check one torrent at a time.</li>
3268 <li>The third thread is spawned by asio on systems that don't support
3269 non-blocking host name resolution to simulate non-blocking behavior.</li>
3270 </ul>
3271 </blockquote>
3272 </div>
3276 <blockquote>
3279 zeros before anything is downloaded. libtorrent will look for sparse files support
3280 in the filesystem that is used for storage, and use sparse files or file system
3281 zero fill support if present. This means that on NTFS, full allocation mode will
3282 only allocate storage for the downloaded pieces.</li>
3284 pieces that have been downloaded. This is the default allocation mode in libtorrent.</li>
3285 </ul>
3286 </blockquote>
3287 <p>The allocation mode is selected when a torrent is started. It is passed as a boolean
3288 argument to <tt class="docutils literal"><span class="pre">session::add_torrent()</span></tt> (see <a class="reference" href="#add-torrent">add_torrent()</a>). These two modes have
3289 different drawbacks and benefits.</p>
3290 <p>The decision to use full allocation or compact allocation typically depends on whether
3291 any files are filtered and if the filesystem supports sparse files.</p>
3292 <p>To know if the filesystem supports sparse files (and to know if libtorrent believes the
3293 filesystem supports sparse files), see <a class="reference" href="#supports-sparse-files">supports_sparse_files()</a>.</p>
3296 <p>When a torrent is started in full allocation mode, the checker thread (see <a class="reference" href="#threads">threads</a>)
3297 will make sure that the entire storage is allocated, and fill any gaps with zeros.
3298 This will be skipped if the filesystem supports sparse files or automatic zero filling.
3299 It will of course still check for existing pieces and fast resume data. The main
3300 drawbacks of this mode are:</p>
3301 <blockquote>
3303 <li>It may take longer to start the torrent, since it will need to fill the files
3304 with zeros on some systems. This delay is linearly dependent on the size of
3305 the download.</li>
3306 <li>The download may occupy unnecessary disk space between download sessions. In case
3307 sparse files are not supported.</li>
3308 <li>Disk caches usually perform extremely poorly with random access to large files
3309 and may slow down a download considerably.</li>
3310 </ul>
3311 </blockquote>
3313 <blockquote>
3315 <li>Downloaded pieces are written directly to their final place in the files and the
3316 total number of disk operations will be fewer and may also play nicer to
3317 filesystems' file allocation, and reduce fragmentation.</li>
3318 <li>No risk of a download failing because of a full disk during download. Unless
3319 sparse files are being used.</li>
3320 <li>The fast resume data will be more likely to be usable, regardless of crashes or
3321 out of date data, since pieces won't move around.</li>
3323 </ul>
3324 </blockquote>
3325 </div>
3328 <p>The compact allocation will only allocate as much storage as it needs to keep the
3329 pieces downloaded so far. This means that pieces will be moved around to be placed
3330 at their final position in the files while downloading (to make sure the completed
3331 download has all its pieces in the correct place). So, the main drawbacks are:</p>
3332 <blockquote>
3337 </ul>
3338 </blockquote>
3340 <blockquote>
3344 <li>Disk caches perform much better than in full allocation and raises the download
3345 speed limit imposed by the disk.</li>
3347 </ul>
3348 </blockquote>
3349 <p>The algorithm that is used when allocating pieces and slots isn't very complicated.
3350 For the interested, a description follows.</p>
3355 downloading to. (the number of pieces it has room for).</li>
3356 <li>if <strong>n</strong> >= <strong>s</strong> then allocate a new slot and put the piece there.</li>
3358 slot <strong>n</strong> to the new slot and put <strong>A</strong> in slot <strong>n</strong>.</li>
3359 </ol>
3362 <li>if there's an unassigned slot (a slot that doesn't
3363 contain any piece), return that slot index.</li>
3366 <li>if we have downloaded piece index <strong>i</strong> already (to slot <strong>j</strong>) then<ol class="arabic">
3369 </ol>
3370 </li>
3372 </ol>
3373 </div>
3374 </div>
3377 <p>These extensions all operates within the <a class="reference" href="extension_protocol.html">extension protocol</a>. The
3378 name of the extension is the name used in the extension-list packets,
3379 and the payload is the data in the extended message (not counting the
3380 length-prefix, message-id nor extension-id).</p>
3381 <p>Note that since this protocol relies on one of the reserved bits in the
3382 handshake, it may be incompatible with future versions of the mainline
3383 bittorrent client.</p>
3388 <p>The point with this extension is that you don't have to distribute the
3389 metadata (.torrent-file) separately. The metadata can be distributed
3390 through the bittorrent swarm. The only thing you need to download such
3391 a torrent is the tracker url and the info-hash of the torrent.</p>
3392 <p>It works by assuming that the initial seeder has the metadata and that
3393 the metadata will propagate through the network as more peers join.</p>
3394 <p>There are three kinds of messages in the metadata extension. These packets
3395 are put as payload to the extension message. The three packets are:</p>
3396 <blockquote>
3401 </ul>
3402 </blockquote>
3405 <colgroup>
3409 </colgroup>
3414 </tr>
3415 </thead>
3419 <td>Determines the kind of message this is
3421 </tr>
3424 <td>The start of the metadata block that
3425 is requested. It is given in 256:ths
3426 of the total size of the metadata,
3427 since the requesting client don't know
3428 the size of the metadata.</td>
3429 </tr>
3432 <td>The size of the metadata block that is
3433 requested. This is also given in
3434 256:ths of the total size of the
3435 metadata. The size is given as size-1.
3436 That means that if this field is set
3438 metadata.</td>
3439 </tr>
3440 </tbody>
3441 </table>
3444 <colgroup>
3448 </colgroup>
3453 </tr>
3454 </thead>
3459 </tr>
3462 <td>The total size of the metadata, given
3463 in number of bytes.</td>
3464 </tr>
3467 <td>The offset of where the metadata block
3468 in this message belongs in the final
3469 metadata. This is given in bytes.</td>
3470 </tr>
3473 <td>The actual metadata block. The size of
3474 this part is given implicit by the
3475 length prefix in the bittorrent
3476 protocol packet.</td>
3477 </tr>
3478 </tbody>
3479 </table>
3482 <colgroup>
3486 </colgroup>
3491 </tr>
3492 </thead>
3497 This message is sent as a reply to a
3498 metadata request if the the client
3499 doesn't have any metadata.</td>
3500 </tr>
3501 </tbody>
3502 </table>
3503 </div>
3506 <p>The HTTP seed extension implements <a class="reference" href="http://www.getright.com/seedtorrent.html">this specification</a>.</p>
3507 <p>The libtorrent implementation assumes that, if the URL ends with a slash
3508 ('/'), the filename should be appended to it in order to request pieces from
3509 that file. The way this works is that if the torrent is a single-file torrent,
3510 only that filename is appended. If the torrent is a multi-file torrent, the
3511 torrent's name '/' the file name is appended. This is the same directory
3512 structure that libtorrent will download torrents into.</p>
3513 </div>
3514 </div>
3517 <p>Boost.Filesystem will by default check all its paths to make sure they conform
3518 to filename requirements on many platforms. If you don't want this check, you can
3519 set it to either only check for native filesystem requirements or turn it off
3520 altogether. You can use:</p>
3522 boost::filesystem::path::default_name_check(boost::filesystem::native);
3523 </pre>
3524 <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>
3525 </div>
3531 <p>Big thanks to Michael Wojciechowski and Peter Koeleman for making the autotools
3532 scripts.</p>
3534 <p>Thanks to <a class="reference" href="http://www.cs.umu.se">University of UmeÂ</a> for providing development and test hardware.</p>
3536 <p><a class="reference" href="http://sourceforge.net"><img alt="sf_logo" src="http://sourceforge.net/sflogo.php?group_id=7994" /></a></p>
3537 </div>
3538 </div>
3539 </body>
3540 </html>