« back to all changes in this revision
Viewing changes to docs/manual.rst
- browse files at revision 20
- compare with another revision
- download diff
- download tarball
- view history from revision 20
- Committer: Bazaar Package Importer
- Author(s): Christophe Sauthier
- Date: 2010-08-10 12:59:37 UTC
- mfrom: (1.3.7 upstream)
- Revision ID: james.westby@ubuntu.com-20100810125937-jbcmmf17y8yo9hgz
Tags: 0.15.0-0ubuntu1
* New upstream version.
* debian/patches/100_fix_html_docs.patch: refreshed.
* debian/control: bump up standards-version to 3.9.1 (no changes).
* debian/patches/100_fix_html_docs.patch: refreshed.
* debian/control: bump up standards-version to 3.9.1 (no changes).
- files added:
- CMakeLists.txt
- build-aux
- files removed:
- .pc/debian-changes-0.14.10-2
- .pc/debian-changes-0.14.10-2/docs
- include/libtorrent/asio
- include/libtorrent/asio/detail
- include/libtorrent/asio/impl
- include/libtorrent/asio/ip
- include/libtorrent/asio/ip/detail
- include/libtorrent/asio/local
- include/libtorrent/asio/posix
- include/libtorrent/asio/ssl
- include/libtorrent/asio/ssl/detail
- include/libtorrent/asio/windows
- files modified:
- .pc/100_fix_html_docs.patch/docs/index.rst
added
removed
docs/manual.rst
3
3
============================
4
4
5
5
:Author: Arvid Norberg, arvid@rasterbar.com
6
:Version: 0.14.10
6
:Version: 0.15.0
7
7
8
8
.. contents:: Table of contents
9
9
:depth: 2
18
18
The basic usage is as follows:
19
19
20
20
* construct a session
21
* load session state from settings file (see `load_state() save_state()`_)
21
22
* start extensions (see `add_extension()`_).
22
* start DHT, LSD, UPnP, NAT-PMP etc (see `start_dht() stop_dht() set_dht_settings() dht_state()`_
23
* start DHT, LSD, UPnP, NAT-PMP etc (see `start_dht() stop_dht() set_dht_settings() dht_state() is_dht_running()`_)
23
24
`start_lsd() stop_lsd()`_, `start_upnp() stop_upnp()`_ and `start_natpmp() stop_natpmp()`_)
24
25
* parse .torrent-files and add them to the session (see `bdecode() bencode()`_ and `add_torrent()`_)
25
26
* main loop (see session_)
30
31
31
32
* save resume data for all torrent_handles (optional, see
32
33
`save_resume_data()`_)
34
* save session state (see `load_state() save_state()`_)
33
35
* destruct session object
34
36
35
37
Each class and function is described in this manual.
38
40
39
41
.. _make_torrent: make_torrent.html
40
42
43
things to keep in mind
44
======================
45
46
A common problem developers are facing is torrents stopping without explanation.
47
Here is a description on which conditions libtorrent will stop your torrents,
48
how to find out about it and what to do about it.
49
50
Make sure to keep track of the paused state, the error state and the upload
51
mode of your torrents. By default, torrents are auto-managed, which means
52
libtorrent will pause them, unpause them, scrape them and take them out
53
of upload-mode automatically.
54
55
Whenever a torrent encounters a fatal error, it will be stopped, and the
56
``torrent_status::error`` will describe the error that caused it. If a torrent
57
is auto managed, it is scraped periodically and paused or resumed based on
58
the number of downloaders per seed. This will effectively seed torrents that
59
are in the greatest need of seeds.
60
61
If a torrent hits a disk write error, it will be put into upload mode. This
62
means it will not download anything, but only upload. The assumption is that
63
the write error is caused by a full disk or write permission errors. If the
64
torrent is auto-managed, it will periodically be taken out of the upload
65
mode, trying to write things to the disk again. This means torrent will recover
66
from certain disk errors if the problem is resolved. If the torrent is not
67
auto managed, you have to call `set_upload_mode()`_ to turn
68
downloading back on again.
69
70
41
71
network primitives
42
72
==================
43
73
75
105
session(fingerprint const& print
76
106
= libtorrent::fingerprint(
77
107
"LT", 0, 1, 0, 0)
78
, int flags = start_default_features | add_default_plugins);
108
, int flags = start_default_features
109
| add_default_plugins
110
, int alert_mask = alert::error_notification);
79
111
80
112
session(
81
113
fingerprint const& print
82
114
, std::pair<int, int> listen_port_range
83
115
, char const* listen_interface = 0
84
, int flags = start_default_features | add_default_plugins);
85
86
torrent_handle add_torrent(add_torrent_params const& params);
116
, int flags = start_default_features
117
| add_default_plugins
118
, int alert_mask = alert::error_notification);
119
120
enum save_state_flags_t
121
{
122
save_settings = 0x001,
123
save_dht_settings = 0x002,
124
save_dht_proxy = 0x004,
125
save_dht_state = 0x008,
126
save_i2p_proxy = 0x010,
127
save_encryption_settings = 0x020,
128
save_peer_proxy = 0x040,
129
save_web_proxy = 0x080,
130
save_tracker_proxy = 0x100,
131
save_as_map = 0x200,
132
};
133
134
void load_state(lazy_entry const& e);
135
void save_state(entry& e, boost::uint32_t flags) const;
136
137
torrent_handle add_torrent(
138
add_torrent_params const& params);
139
torrent_handle add_torrent(
140
add_torrent_params const& params
141
, error_code& ec);
87
142
88
143
void pause();
89
144
void resume();
103
158
start_default_features = 2
104
159
};
105
160
106
void remove_torrent(torrent_handle const& h, int options = none);
161
void remove_torrent(torrent_handle const& h
162
, int options = none);
107
163
torrent_handle find_torrent(sha_hash const& ih);
108
164
std::vector<torrent_handle> get_torrents() const;
109
165
114
170
int upload_rate_limit() const;
115
171
void set_download_rate_limit(int bytes_per_second);
116
172
int download_rate_limit() const;
173
174
void set_local_upload_rate_limit(int bytes_per_second);
175
int local_upload_rate_limit() const;
176
void set_local_download_rate_limit(int bytes_per_second);
177
int local_download_rate_limit() const;
178
117
179
void set_max_uploads(int limit);
118
180
void set_max_connections(int limit);
181
int max_connections() const;
119
182
void set_max_half_open_connections(int limit);
120
183
int max_half_open_connections() const;
121
184
131
194
int num_connections() const;
132
195
133
196
bool load_asnum_db(char const* file);
197
bool load_asnum_db(wchar_t const* file);
134
198
bool load_country_db(char const* file);
199
bool load_country_db(wchar_t const* file);
135
200
int as_for_ip(address const& adr);
136
201
137
void load_state(entry const& ses_state);
138
entry state() const;
139
140
202
void set_ip_filter(ip_filter const& f);
141
203
ip_filter const& get_ip_filter() const;
142
204
143
205
session_status status() const;
144
206
cache_status get_cache_status() const;
145
207
152
214
std::auto_ptr<alert> pop_alert();
153
215
alert const* wait_for_alert(time_duration max_wait);
154
216
void set_alert_mask(int m);
155
size_t set_alert_queue_size_limit(size_t queue_size_limit_);
217
size_t set_alert_queue_size_limit(
218
size_t queue_size_limit_);
156
219
157
220
void add_extension(boost::function<
158
221
boost::shared_ptr<torrent_plugin>(torrent*)> ext);
166
229
, int> const& node);
167
230
void add_dht_router(std::pair<std::string
168
231
, int> const& node);
232
bool is_dht_running() const;
169
233
170
234
void start_lsd();
171
235
void stop_lsd();
187
251
188
252
session(fingerprint const& print
189
253
= libtorrent::fingerprint("LT", 0, 1, 0, 0)
190
, int flags = start_default_features | add_default_plugins);
254
, int flags = start_default_features
255
| add_default_plugins
256
, int alert_mask = alert::error_notification);
191
257
192
258
session(fingerprint const& print
193
259
, std::pair<int, int> listen_port_range
194
260
, char const* listen_interface = 0
195
, int flags = start_default_features | add_default_plugins);
261
, int flags = start_default_features
262
| add_default_plugins
263
, int alert_mask = alert::error_notification);
196
264
197
265
If the fingerprint in the first overload is omited, the client will get a default
198
266
fingerprint stating the version of libtorrent. The fingerprint is a short string that will be
207
275
(ut_metadata, ut_pex and smart_ban). The default is to start those things. If you do not want
208
276
them to start, pass 0 as the flags parameter.
209
277
278
The ``alert_mask`` is the same mask that you would send to `set_alert_mask()`_.
279
210
280
~session()
211
281
----------
212
282
216
286
destructing the session object. Because it can take a few second for it to finish. The
217
287
timeout can be set with ``set_settings()``.
218
288
289
load_state() save_state()
290
-------------------------
291
292
::
293
294
void load_state(lazy_entry const& e);
295
void save_state(entry& e, boost::uint32_t flags) const;
296
297
loads and saves all session settings, including dht_settings, encryption settings and proxy
298
settings. ``save_state`` writes all keys to the ``entry`` that's passed in, which needs to
299
either not be initialized, or initialized as a dictionary.
300
301
``load_state`` expects a ``lazy_entry`` which can be built from a bencoded buffer with
302
``lazy_bdecode``.
303
304
The ``flags`` arguments passed in to ``save_state`` can be used to filter which parts
305
of the session state to save. By default, all state is saved (except for the individual
306
torrents). These are the possible flags. A flag that's set, means those settings are saved::
307
308
enum save_state_flags_t
309
{
310
save_settings = 0x001,
311
save_dht_settings = 0x002,
312
save_dht_proxy = 0x004,
313
save_dht_state = 0x008,
314
save_i2p_proxy = 0x010,
315
save_encryption_settings = 0x020,
316
save_peer_proxy = 0x040,
317
save_web_proxy = 0x080,
318
save_tracker_proxy = 0x100,
319
save_as_map = 0x200,
320
};
321
322
219
323
pause() resume() is_paused()
220
324
----------------------------
221
325
280
384
bool duplicate_is_error;
281
385
storage_constructor_type storage;
282
386
void* userdata;
387
bool seed_mode;
388
bool override_resume_data;
389
bool upload_mode;
283
390
};
284
391
285
392
torrent_handle add_torrent(add_torrent_params const& params);
393
torrent_handle add_torrent(add_torrent_params const& params
394
, error_code& ec);
286
395
287
396
You add torrents through the ``add_torrent()`` function where you give an
288
397
object with all the parameters.
289
398
399
The overload that does not take an ``error_code`` throws an exception on
400
error and is not available when building without exception support.
401
290
402
The only mandatory parameter is ``save_path`` which is the directory where you
291
403
want the files to be saved. You also need to specify either the ``ti`` (the
292
404
torrent file) or ``info_hash`` (the info hash of the torrent). If you specify the
303
415
304
416
If the torrent you are trying to add already exists in the session (is either queued
305
417
for checking, being checked or downloading) ``add_torrent()`` will throw
306
duplicate_torrent_ which derives from ``std::exception`` unless ``duplicate_is_error``
418
libtorrent_exception_ which derives from ``std::exception`` unless ``duplicate_is_error``
307
419
is set to false. In that case, ``add_torrent`` will return the handle to the existing
308
420
torrent.
309
421
340
452
configuration options on torrents before starting them.
341
453
342
454
If you pass in resume data, the paused state of the torrent when the resume data
343
was saved will override the paused state you pass in here.
455
was saved will override the paused state you pass in here. You can override this
456
by setting ``override_resume_data``.
344
457
345
458
If ``auto_managed`` is true, this torrent will be queued, started and seeded
346
459
automatically by libtorrent. When this is set, the torrent should also be started
348
461
are all downloaded in that order. For more details, see queuing_.
349
462
350
463
If you pass in resume data, the auto_managed state of the torrent when the resume data
351
was saved will override the auto_managed state you pass in here.
464
was saved will override the auto_managed state you pass in here. You can override this
465
by setting ``override_resume_data``.
352
466
353
467
``storage`` can be used to customize how the data is stored. The default
354
468
storage will simply write the data to the files it belongs to, but it could be
359
473
The ``userdata`` parameter is optional and will be passed on to the extension
360
474
constructor functions, if any (see `add_extension()`_).
361
475
476
If ``seed_mode`` is set to true, libtorrent will assume that all files are present
477
for this torrent and that they all match the hashes in the torrent file. Each time
478
a peer requests to download a block, the piece is verified against the hash, unless
479
it has been verified already. If a hash fails, the torrent will automatically leave
480
the seed mode and recheck all the files. The use case for this mode is if a torrent
481
is created and seeded, or if the user already know that the files are complete, this
482
is a way to avoid the initial file checks, and significantly reduce the startup time.
483
484
Setting ``seed_mode`` on a torrent without metadata (a .torrent file) is a no-op
485
and will be ignored.
486
487
If resume data is passed in with this torrent, the seed mode saved in there will
488
override the seed mode you set here.
489
362
490
The torrent_handle_ returned by ``add_torrent()`` can be used to retrieve information
363
491
about the torrent's progress, its peers etc. It is also used to abort a torrent.
364
492
493
If ``override_resume_data`` is set to true, the ``paused`` and ``auto_managed``
494
state of the torrent are not loaded from the resume data, but the states requested
495
by this ``add_torrent_params`` will override it.
496
497
If ``upload_mode`` is set to true, the torrent will be initialized in upload-mode,
498
which means it will not make any piece requests. This state is typically entered
499
on disk I/O errors, and if the torrent is also auto managed, it will be taken out
500
of this state periodically. This mode can be used to avoid race conditions when
501
adjusting priorities of pieces before allowing the torrent to start downloading.
365
502
366
503
remove_torrent()
367
504
----------------
375
512
``options`` can be used to delete all the files downloaded by this torrent. To do this, pass
376
513
in the value ``session::delete_files``. The removal of the torrent is asyncronous, there is
377
514
no guarantee that adding the same torrent immediately after it was removed will not throw
378
a duplicate_torrent_ exception.
515
a libtorrent_exception_ exception. Once the torrent is deleted, a torrent_deleted_alert_
516
is posted.
379
517
380
518
find_torrent() get_torrents()
381
519
-----------------------------
407
545
408
546
``set_upload_rate_limit()`` set the maximum number of bytes allowed to be
409
547
sent to peers per second. This bandwidth is distributed among all the peers. If
410
you don't want to limit upload rate, you can set this to -1 (the default).
548
you don't want to limit upload rate, you can set this to 0 (the default).
411
549
``set_download_rate_limit()`` works the same way but for download rate instead
412
550
of upload rate.
413
551
``download_rate_limit()`` and ``upload_rate_limit()`` returns the previously
414
552
set limits.
415
553
554
A rate limit of 0 means infinite.
555
416
556
Upload and download rate limits are not applied to peers on the local network
417
557
by default. To change that, see ``session_settings::ignore_limits_on_local_network``.
418
419
420
set_max_uploads() set_max_connections()
421
---------------------------------------
558
559
560
set_local_upload_rate_limit() set_local_download_rate_limit() local_upload_rate_limit() local_download_rate_limit()
561
-------------------------------------------------------------------------------------------------------------------
562
563
::
564
565
void set_local_upload_rate_limit(int bytes_per_second);
566
void set_local_download_rate_limit(int bytes_per_second);
567
int local_upload_rate_limit() const;
568
int local_download_rate_limit() const;
569
570
These rate limits are only used for local peers (peers within the same subnet as
571
the client itself) and it is only used when ``session_settings::ignore_limits_on_local_network``
572
is set to true (which it is by default). These rate limits default to unthrottled,
573
but can be useful in case you want to treat local peers preferentially, but not
574
quite unthrottled.
575
576
A rate limit of 0 means infinite.
577
578
579
set_max_uploads() set_max_connections() max_uploads() max_connections()
580
-----------------------------------------------------------------------
422
581
423
582
::
424
583
425
584
void set_max_uploads(int limit);
426
585
void set_max_connections(int limit);
586
int max_uploads() const;
587
int max_connections() const;
427
588
428
589
These functions will set a global limit on the number of unchoked peers (uploads)
429
590
and the number of connections opened. The number of connections is set to a hard
431
592
connections limit, and open too many torrents, the limit will not be met. The
432
593
number of uploads is at least one per torrent.
433
594
595
``max_uploads()`` and ``max_connections()`` returns the current settings.
596
597
The number of unchoke slots may be ignored. In order to make this setting
598
take effect, disable ``session_settings::auto_upload_slots_rate_based``.
599
434
600
435
601
num_uploads() num_connections()
436
602
-------------------------------
471
637
::
472
638
473
639
bool load_asnum_db(char const* file);
640
bool load_asnum_db(wchar_t const* file);
474
641
bool load_country_db(char const* file);
642
bool load_country_db(wchar_t const* file);
475
643
int as_for_ip(address const& adr);
476
644
477
645
These functions are not available if ``TORRENT_DISABLE_GEO_IP`` is defined. They
481
649
``as_for_ip`` returns the AS number for the IP address specified. If the IP is not
482
650
in the database or the ASN database is not loaded, 0 is returned.
483
651
652
The ``wchar_t`` overloads are for wide character paths.
653
484
654
.. _`MaxMind ASN database`: http://www.maxmind.com/app/asnum
485
655
.. _`MaxMind GeoIP database`: http://www.maxmind.com/app/geolitecountry
486
656
487
load_state() state()
488
--------------------
489
490
::
491
492
void load_state(entry const& ses_state);
493
entry state() const;
494
495
These functions loads and save session state. Currently, the only state
496
that's stored is peak download rates for ASes. This map is used to
497
determine which order to connect to peers.
498
499
657
set_ip_filter()
500
658
---------------
501
659
530
688
``status()`` returns session wide-statistics and status. The ``session_status``
531
689
struct has the following members::
532
690
691
struct dht_lookup
692
{
693
char const* type;
694
int outstanding_requests;
695
int timeouts;
696
int responses;
697
int branch_factor;
698
};
699
533
700
struct session_status
534
701
{
535
702
bool has_incoming_connections;
536
703
537
float upload_rate;
538
float download_rate;
539
540
float payload_upload_rate;
541
float payload_download_rate;
542
704
int upload_rate;
705
int download_rate;
543
706
size_type total_download;
544
707
size_type total_upload;
545
708
709
int payload_upload_rate;
710
int payload_download_rate;
711
size_type total_payload_download;
712
size_type total_payload_upload;
713
714
int ip_overhead_upload_rate;
715
int ip_overhead_download_rate;
716
size_type total_ip_overhead_download;
717
size_type total_ip_overhead_upload;
718
719
int dht_upload_rate;
720
int dht_download_rate;
721
size_type total_dht_download;
722
size_type total_dht_upload;
723
724
int tracker_upload_rate;
725
int tracker_download_rate;
726
size_type total_tracker_download;
727
size_type total_tracker_upload;
728
546
729
size_type total_redundant_bytes;
547
730
size_type total_failed_bytes;
548
731
549
size_type total_payload_download;
550
size_type total_payload_upload;
551
552
732
int num_peers;
553
733
int num_unchoked;
554
734
int allowed_upload_slots;
555
735
736
int optimistic_unchoke_counter;
737
int unchoke_counter;
738
556
739
int dht_nodes;
557
740
int dht_node_cache;
558
741
int dht_torrents;
559
742
int dht_global_nodes;
743
std::vector<dht_lookup> active_requests;
560
744
};
561
745
562
746
``has_incoming_connections`` is false as long as no incoming connections have been
563
747
established on the listening socket. Every time you change the listen port, this will
564
748
be reset to false.
565
749
566
``upload_rate``, ``download_rate``, ``payload_download_rate`` and ``payload_upload_rate``
567
are the total download and upload rates accumulated from all torrents. The payload
568
versions is the payload download only.
750
``upload_rate``, ``download_rate`` are the total download and upload rates accumulated
751
from all torrents. This includes bittorrent protocol, DHT and an estimated TCP/IP
752
protocol overhead.
569
753
570
754
``total_download`` and ``total_upload`` are the total number of bytes downloaded and
571
uploaded to and from all torrents. ``total_payload_download`` and ``total_payload_upload``
572
are the same thing but where only the payload is considered.
755
uploaded to and from all torrents. This also includes all the protocol overhead.
756
757
``payload_download_rate`` and ``payload_upload_rate`` is the rate of the payload
758
down- and upload only.
759
760
``total_payload_download`` and ``total_payload_upload`` is the total transfers of payload
761
only. The payload does not include the bittorrent protocol overhead, but only parts of the
762
actual files to be downloaded.
763
764
``ip_overhead_upload_rate``, ``ip_overhead_download_rate``, ``total_ip_overhead_download``
765
and ``total_ip_overhead_upload`` is the estimated TCP/IP overhead in each direction.
766
767
``dht_upload_rate``, ``dht_download_rate``, ``total_dht_download`` and ``total_dht_upload``
768
is the DHT bandwidth usage.
573
769
574
770
``total_redundant_bytes`` is the number of bytes that has been received more than once.
575
771
This can happen if a request from a peer times out and is requested from a different
588
784
``num_unchoked`` is the current number of unchoked peers.
589
785
``allowed_upload_slots`` is the current allowed number of unchoked peers.
590
786
787
``optimistic_unchoke_counter`` and ``unchoke_counter`` tells the number of
788
seconds until the next optimistic unchoke change and the start of the next
789
unchoke interval. These numbers may be reset prematurely if a peer that is
790
unchoked disconnects or becomes notinterested.
791
591
792
``dht_nodes``, ``dht_node_cache`` and ``dht_torrents`` are only available when
592
793
built with DHT support. They are all set to 0 if the DHT isn't running. When
593
794
the DHT is running, ``dht_nodes`` is set to the number of nodes in the routing
601
802
``dht_global_nodes`` is an estimation of the total number of nodes in the DHT
602
803
network.
603
804
805
``active_requests`` is a vector of the currently running DHT lookups.
806
807
604
808
get_cache_status()
605
809
------------------
606
810
621
825
size_type reads;
622
826
int cache_size;
623
827
int read_cache_size;
828
int total_used_buffers;
624
829
};
625
830
626
831
``blocks_written`` is the total number of 16 KiB blocks written to disk
646
851
647
852
``read_cache_size`` is the number of 16KiB blocks in the read cache.
648
853
854
``total_used_buffers`` is the total number of buffers currently in use.
855
This includes the read/write disk cache as well as send and receive buffers
856
used in peer connections.
857
649
858
get_cache_info()
650
859
----------------
651
860
734
943
can only connect to a few peers at a time because of a built in limitation (in XP
735
944
Service pack 2).
736
945
737
pop_alert() set_alert_mask() wait_for_alert() set_alert_queue_size_limit()
738
--------------------------------------------------------------------------
946
set_alert_mask()
947
----------------
948
949
::
950
951
void set_alert_mask(int m);
952
953
Changes the mask of which alerts to receive. By default only errors are reported.
954
``m`` is a bitmask where each bit represents a category of alerts.
955
956
See alerts_ for mor information on the alert categories.
957
958
pop_alert() wait_for_alert() set_alert_queue_size_limit()
959
---------------------------------------------------------
739
960
740
961
::
741
962
742
963
std::auto_ptr<alert> pop_alert();
743
964
alert const* wait_for_alert(time_duration max_wait);
744
void set_alert_mask(int m);
745
965
size_t set_alert_queue_size_limit(size_t queue_size_limit_);
746
966
747
967
``pop_alert()`` is used to ask the session if any errors or events has occurred. With
748
``set_alert_mask()`` you can filter which alerts to receive through ``pop_alert()``.
968
`set_alert_mask()`_ you can filter which alerts to receive through ``pop_alert()``.
749
969
For information about the alert categories, see alerts_.
750
970
751
971
``wait_for_alert`` blocks until an alert is available, or for no more than ``max_wait``
873
1093
The ``dht_proxy`` is not available when DHT is disabled.
874
1094
875
1095
876
start_dht() stop_dht() set_dht_settings() dht_state()
877
-----------------------------------------------------
1096
start_dht() stop_dht() set_dht_settings() dht_state() is_dht_running()
1097
----------------------------------------------------------------------
878
1098
879
1099
::
880
1100
882
1102
void stop_dht();
883
1103
void set_dht_settings(dht_settings const& settings);
884
1104
entry dht_state() const;
1105
bool is_dht_running() const;
885
1106
886
1107
These functions are not available in case ``TORRENT_DISABLE_DHT`` is
887
1108
defined. ``start_dht`` starts the dht node and makes the trackerless service
942
1163
this limit is only used to clear out nodes that don't have any node that can
943
1164
replace them.
944
1165
1166
``is_dht_running`` returns true if the DHT support has been started and false
1167
otherwise.
1168
945
1169
946
1170
add_dht_node() add_dht_router()
947
1171
-------------------------------
1098
1322
1099
1323
The ``integer()``, ``string()``, ``list()`` and ``dict()`` functions
1100
1324
are accessors that return the respective type. If the ``entry`` object isn't of the
1101
type you request, the accessor will throw type_error_ (which derives from
1325
type you request, the accessor will throw libtorrent_exception_ (which derives from
1102
1326
``std::runtime_error``). You can ask an ``entry`` for its type through the
1103
1327
``type()`` function.
1104
1328
1192
1416
{
1193
1417
public:
1194
1418
1419
// these constructors throws exceptions on error
1195
1420
torrent_info(sha1_hash const& info_hash);
1196
1421
torrent_info(lazy_entry const& torrent_file);
1197
1422
torrent_info(char const* buffer, int size);
1198
1423
torrent_info(boost::filesystem::path const& filename);
1424
torrent_info(boost::filesystem::wpath const& filename);
1425
1426
// these constructors sets the error code on error
1427
torrent_info(sha1_hash const& info_hash, error_code& ec);
1428
torrent_info(lazy_entry const& torrent_file, error_code& ec);
1429
torrent_info(char const* buffer, int size, error_code& ec);
1430
torrent_info(fs::path const& filename, error_code& ec);
1431
torrent_info(fs::wpath const& filename, error_code& ec);
1199
1432
1200
1433
void add_tracker(std::string const& url, int tier = 0);
1201
1434
std::vector<announce_entry> const& trackers() const;
1203
1436
file_storage const& files() const;
1204
1437
file_storage const& orig_files() const;
1205
1438
1439
void remap_files(file_storage const& f);
1440
1206
1441
void rename_file(int index, std::string const& new_filename);
1207
1442
void rename_file(int index, std::wstring const& new_filename);
1208
1443
1225
1460
bool priv() const;
1226
1461
1227
1462
std::vector<std::string> const& url_seeds() const;
1463
void add_url_seed(std::string const& url);
1464
std::vector<std::string> const& http_seeds() const;
1465
void add_http_seed(std::string const& url);
1228
1466
1229
1467
size_type total_size() const;
1230
1468
int piece_length() const;
1257
1495
torrent_info(lazy_entry const& torrent_file);
1258
1496
torrent_info(char const* buffer, int size);
1259
1497
torrent_info(boost::filesystem::path const& filename);
1498
torrent_info(boost::filesystem::wpath const& filename);
1499
1500
torrent_info(sha1_hash const& info_hash, error_code& ec);
1501
torrent_info(lazy_entry const& torrent_file, error_code& ec);
1502
torrent_info(char const* buffer, int size, error_code& ec);
1503
torrent_info(fs::path const& filename, error_code& ec);
1504
torrent_info(fs::wpath const& filename, error_code& ec);
1260
1505
1261
1506
The constructor that takes an info-hash will initialize the info-hash to the given value,
1262
1507
but leave all other fields empty. This is used internally when downloading torrents without
1275
1520
the constructor, for convenience. This might not be the most suitable for applications that
1276
1521
want to be able to report detailed errors on what might go wrong.
1277
1522
1523
The overloads that takes an ``error_code const&`` never throws if an error occur, they
1524
will simply set the error code to describe what went wrong and not fully initialize the
1525
torrent_info object. The overloads that do not take the extra error_code_ parameter will
1526
always throw if an error occurs. These overloads are not available when building without
1527
exception support.
1528
1278
1529
1279
1530
add_tracker()
1280
1531
-------------
1307
1558
For more information on the ``file_storage`` object, see the separate document on how
1308
1559
to create torrents.
1309
1560
1561
remap_files()
1562
-------------
1563
1564
::
1565
1566
void remap_files(file_storage const& f);
1567
1568
Remaps the file storage to a new file layout. This can be used to, for instance,
1569
download all data in a torrent to a single file, or to a number of fixed size
1570
sector aligned files, regardless of the number and sizes of the files in the torrent.
1571
1572
The new specified ``file_storage`` must have the exact same size as the current one.
1573
1310
1574
rename_file()
1311
1575
-------------
1312
1576
1343
1607
size_type offset;
1344
1608
size_type size;
1345
1609
size_type file_base;
1346
boost::shared_ptr<const boost::filesystem::path> orig_path;
1610
bool pad_file:1;
1611
bool hidden_attribute:1;
1612
bool executable_attribute:1;
1347
1613
};
1348
1614
1349
1615
The ``path`` is the full (relative) path of each file. i.e. if it is a multi-file
1361
1627
not overlap. This is used when mapping "unselected" files into a so-called part
1362
1628
file.
1363
1629
1364
``orig_path`` is set to 0 in case the path element is an exact copy of that
1365
found in the metadata. In case the path in the original metadata was
1366
incorrectly encoded, and had to be fixed in order to be acceptable utf-8,
1367
the original string is preserved in ``orig_path``. The reason to keep it
1368
is to be able to reproduce the info-section exactly, with the correct
1369
info-hash.
1370
1630
``pad_file`` is set to true for files that are not part of the data of the torrent.
1631
They are just there to make sure the next file is aligned to a particular byte offset
1632
or piece boundry. These files should typically be hidden from an end user. They are
1633
not written to disk.
1371
1634
1372
1635
1373
1636
num_files() file_at()
1441
1704
must refer to a valid file, i.e. it cannot be >= ``num_files()``.
1442
1705
1443
1706
1444
url_seeds() add_url_seed()
1445
--------------------------
1707
url_seeds() add_url_seed() http_seeds() add_http_seed()
1708
-------------------------------------------------------
1446
1709
1447
1710
::
1448
1711
1449
1712
std::vector<std::string> const& url_seeds() const;
1450
1713
void add_url_seed(std::string const& url);
1714
std::vector<std::string> const& http_seeds() const;
1715
void add_http_seed(std::string const& url);
1451
1716
1452
If there are any url-seeds in this torrent, ``url_seeds()`` will return a
1453
vector of those urls. If you're creating a torrent file, ``add_url_seed()``
1454
adds one url to the list of url-seeds. Currently, the only transport protocol
1717
If there are any url-seeds or http seeds in this torrent, ``url_seeds()``
1718
and ``http_seeds()`` will return a vector of those urls.
1719
``add_url_seed()`` and ``add_http_seed()`` adds one url to the list of
1720
url/http seeds. Currently, the only transport protocol
1455
1721
supported for the url is http.
1456
1722
1457
1723
See `HTTP seeding`_ for more information.
1475
1741
{
1476
1742
announce_entry(std::string const& url);
1477
1743
std::string url;
1478
int tier;
1744
1745
int next_announce_in() const;
1746
int min_announce_in() const;
1747
1748
boost::uint8_t tier;
1749
boost::uint8_t fail_limit;
1750
boost::uint8_t fails;
1751
1752
enum tracker_source
1753
{
1754
source_torrent = 1,
1755
source_client = 2,
1756
source_magnet_link = 4,
1757
source_tex = 8
1758
};
1759
boost::uint8_t source;
1760
1761
bool verified:1;
1762
bool updating:1;
1763
bool start_sent:1;
1764
bool complete_sent:1;
1479
1765
};
1480
1766
1767
``next_announce_in()`` returns the number of seconds to the next announce on
1768
this tracker. ``min_announce_in()`` returns the number of seconds until we are
1769
allowed to force another tracker update with this tracker.
1770
1771
``fail_limit`` is the max number of failures to announce to this tracker in
1772
a row, before this tracker is not used anymore.
1773
1774
``fails`` is the number of times in a row we have failed to announce to this
1775
tracker.
1776
1777
``source`` is a bitmask specifying which sources we got this tracker from.
1778
1779
``verified`` is set to true the first time we receive a valid response
1780
from this tracker.
1781
1782
``updating`` is true while we're waiting for a response from the tracker.
1783
1784
``start_sent`` is set to true when we get a valid response from an announce
1785
with event=started. If it is set, we won't send start in the subsequent
1786
announces.
1787
1788
``complete_sent`` is set to true when we send a event=completed.
1789
1481
1790
1482
1791
total_size() piece_length() piece_size() num_pieces()
1483
1792
-----------------------------------------------------
1595
1904
torrent_handle();
1596
1905
1597
1906
torrent_status status();
1598
void file_progress(std::vector<size_type>& fp);
1907
void file_progress(std::vector<size_type>& fp, int flags = 0);
1599
1908
void get_download_queue(std::vector<partial_piece_info>& queue) const;
1600
1909
void get_peer_info(std::vector<peer_info>& v) const;
1601
1910
torrent_info const& get_torrent_info() const;
1605
1914
1606
1915
void save_resume_data() const;
1607
1916
void force_reannounce() const;
1917
void force_dht_announce() const;
1608
1918
void force_reannounce(boost::posix_time::time_duration) const;
1609
1919
void scrape_tracker() const;
1610
1920
void connect_peer(asio::ip::tcp::endpoint const& adr, int source = 0) const;
1612
1922
void set_tracker_login(std::string const& username
1613
1923
, std::string const& password) const;
1614
1924
1615
std::vector<announce_entry> const& trackers() const;
1925
std::vector<announce_entry> trackers() const;
1616
1926
void replace_trackers(std::vector<announce_entry> const&);
1927
void add_tracker(announce_entry const& url);
1617
1928
1618
1929
void add_url_seed(std::string const& url);
1619
1930
void remove_url_seed(std::string const& url);
1620
1931
std::set<std::string> url_seeds() const;
1621
1932
1933
void add_http_seed(std::string const& url);
1934
void remove_http_seed(std::string const& url);
1935
std::set<std::string> http_seeds() const;
1936
1622
1937
void set_ratio(float ratio) const;
1938
int max_uploads() const;
1623
1939
void set_max_uploads(int max_uploads) const;
1624
1940
void set_max_connections(int max_connections) const;
1941
int max_connections() const;
1625
1942
void set_upload_limit(int limit) const;
1626
1943
int upload_limit() const;
1627
1944
void set_download_limit(int limit) const;
1638
1955
void queue_position_top() const;
1639
1956
void queue_position_bottom() const;
1640
1957
1958
void set_priority(int prio) const;
1959
1641
1960
void use_interface(char const* net_interface) const;
1642
1961
1643
1962
void pause() const;
1646
1965
bool is_seed() const;
1647
1966
void force_recheck() const;
1648
1967
void clear_error() const;
1968
void set_upload_mode(bool m) const;
1969
1970
void flush_cache() const;
1649
1971
1650
1972
void resolve_countries(bool r);
1651
1973
bool resolve_countries() const;
1652
1974
1975
enum deadline_flags { alert_when_available = 1 };
1976
void set_piece_deadline(int index, int deadline, int flags = 0) const;
1977
1653
1978
void piece_availability(std::vector<int>& avail) const;
1654
1979
void piece_priority(int index, int priority) const;
1655
1980
int piece_priority(int index) const;
1665
1990
void auto_managed(bool m) const;
1666
1991
1667
1992
bool has_metadata() const;
1993
bool set_metadata(char const* buf, int size) const;
1668
1994
1669
1995
boost::filesystem::path save_path() const;
1670
1996
void move_storage(boost::filesystem::path const& save_path) const;
1997
void move_storage(boost::filesystem::wpath const& save_path) const;
1671
1998
void rename_file(int index, boost::filesystem::path) const;
1999
void rename_file(int index, boost::filesystem::wpath) const;
1672
2000
storage_interface* get_storage_impl() const;
1673
2001
2002
bool super_seeding() const;
2003
void super_seeding(bool on) const;
2004
2005
enum flags_t { overwrite_existing = 1 };
2006
void add_piece(int piece, char const* data, int flags = 0) const;
2007
void read_piece(int piece) const;
2008
1674
2009
sha1_hash info_hash() const;
1675
2010
1676
2011
bool operator==(torrent_handle const&) const;
1683
2018
valid handle. If you try to perform any operation on an uninitialized handle,
1684
2019
it will throw ``invalid_handle``.
1685
2020
1686
.. warning:: All operations on a ``torrent_handle`` may throw invalid_handle_
2021
.. warning:: All operations on a ``torrent_handle`` may throw libtorrent_exception_
1687
2022
exception, in case the handle is no longer refering to a torrent. There is
1688
2023
one exception ``is_valid()`` will never throw.
1689
2024
Since the torrents are processed by a background thread, there is no
1690
2025
guarantee that a handle will remain valid between two calls.
1691
2026
2027
set_piece_deadline()
2028
--------------------
2029
2030
::
2031
2032
enum deadline_flags { alert_when_available = 1 };
2033
void set_piece_deadline(int index, int deadline, int flags = 0) const;
2034
2035
This function sets or resets the deadline associated with a specific piece
2036
index (``index``). libtorrent will attempt to download this entire piece before
2037
the deadline expires. This is not necessarily possible, but pieces with a more
2038
recent deadline will always be prioritized over pieces with a deadline further
2039
ahead in time. The deadline (and flags) of a piece can be changed by calling this
2040
function again.
2041
2042
The ``flags`` parameter can be used to ask libtorrent to send an alert once the
2043
piece has been downloaded, by passing ``alert_when_available``. When set, the
2044
read_piece_alert_ alert will be delivered, with the piece data, when it's downloaded.
2045
2046
If the piece is already downloaded when this call is made, nothing happens, unless
2047
the ``alert_when_available`` flag is set, in which case it will do the same thing
2048
as calling `read_piece()`_ for ``index``.
2049
2050
``deadline`` is the number of milliseconds until this piece should be completed.
2051
1692
2052
1693
2053
piece_availability()
1694
2054
--------------------
1776
2136
to match the file priorities. In order to maintain sepcial priorities for
1777
2137
particular pieces, ``piece_priority`` has to be called again for those pieces.
1778
2138
2139
You cannot set the file priorities on a torrent that does not yet
2140
have metadata or a torrent that is a seed. ``file_priority(int, int)`` and
2141
``prioritize_files()`` are both no-ops for such torrents.
2142
1779
2143
file_progress()
1780
2144
---------------
1781
2145
1782
2146
::
1783
2147
1784
void file_progress(std::vector<size_type>& fp);
2148
void file_progress(std::vector<size_type>& fp, int flags = 0);
1785
2149
1786
2150
This function fills in the supplied vector with the the number of bytes downloaded
1787
2151
of each file in this torrent. The progress values are ordered the same as the files
1789
2153
Where *n* is the number of files, *m* is the number of downloading pieces and *j*
1790
2154
is the number of blocks in a piece.
1791
2155
2156
The ``flags`` parameter can be used to specify the granularity of the file progress. If
2157
left at the default value of 0, the progress will be as accurate as possible, but also
2158
more expensive to calculate. If ``torrent_handle::piece_granularity`` is specified,
2159
the progress will be specified in piece granularity. i.e. only pieces that have been
2160
fully downloaded and passed the hash check count. When specifying piece granularity,
2161
the operation is a lot cheaper, since libtorrent already keeps track of this internally
2162
and no calculation is required.
2163
1792
2164
1793
2165
save_path()
1794
2166
-----------
1806
2178
::
1807
2179
1808
2180
void move_storage(boost::filesystem::path const& save_path) const;
2181
void move_storage(boost::filesystem::wpath const& save_path) const;
1809
2182
1810
2183
Moves the file(s) that this torrent are currently seeding from or downloading to. If
1811
2184
the given ``save_path`` is not located on the same drive as the original save path,
1824
2197
::
1825
2198
1826
2199
void rename_file(int index, boost::filesystem::path) const;
2200
void rename_file(int index, boost::filesystem::wpath) const;
1827
2201
1828
2202
Renames the file with the given index asynchronously. The rename operation is complete
1829
2203
when either a ``file_renamed_alert`` or ``file_rename_failed_alert`` is posted.
1838
2212
Returns the storage implementation for this torrent. This depends on the
1839
2213
storage contructor function that was passed to ``session::add_torrent``.
1840
2214
1841
force_reannounce()
1842
------------------
2215
super_seeding()
2216
---------------
2217
2218
::
2219
2220
bool super_seeding() const;
2221
void super_seeding(bool on) const;
2222
2223
Enables or disabled super seeding/initial seeding for this torrent. The torrent
2224
needs to be a seed for this to take effect. The overload that returns a bool
2225
tells you of super seeding is enabled or not.
2226
2227
add_piece()
2228
-----------
2229
2230
::
2231
2232
enum flags_t { overwrite_existing = 1 };
2233
void add_piece(int piece, char const* data, int flags = 0) const;
2234
2235
This function will write ``data`` to the storage as piece ``piece``, as if it had
2236
been downloaded from a peer. ``data`` is expected to point to a buffer of as many
2237
bytes as the size of the specified piece. The data in the buffer is copied and
2238
passed on to the disk IO thread to be written at a later point.
2239
2240
By default, data that's already been downloaded is not overwritten by this buffer. If
2241
you trust this data to be correct (and pass the piece hash check) you may pass the
2242
``overwrite_existing`` flag. This will instruct libtorrent to overwrite any data that
2243
may already have been downloaded with this data.
2244
2245
Since the data is written asynchronously, you may know that is passed or failed the
2246
hash check by waiting for ``piece_finished_alert`` or ``has_failed_alert``.
2247
2248
read_piece()
2249
------------
2250
2251
::
2252
2253
void read_piece(int piece) const;
2254
2255
This function starts an asynchronous read operation of the specified piece from
2256
this torrent. You must have completed the download of the specified piece before
2257
calling this function.
2258
2259
When the read operation is completed, it is passed back through an alert,
2260
read_piece_alert_. In order to receive this alert, you must enable
2261
``alert::storage_notification`` in your alert mask (see `set_alert_mask()`_).
2262
2263
Note that if you read multiple pieces, the read operations are not guaranteed to
2264
finish in the same order as you initiated them.
2265
2266
force_reannounce() force_dht_announce()
2267
---------------------------------------
1843
2268
1844
2269
::
1845
2270
1846
2271
void force_reannounce() const;
1847
2272
void force_reannounce(boost::posix_time::time_duration) const;
2273
void force_dht_announce() const;
1848
2274
1849
2275
``force_reannounce()`` will force this torrent to do another tracker request, to receive new
1850
2276
peers. The second overload of ``force_reannounce`` that takes a ``time_duration`` as
1851
2277
argument will schedule a reannounce in that amount of time from now.
1852
2278
2279
``force_dht_announce`` will announce the torrent to the DHT immediately.
2280
1853
2281
scrape_tracker()
1854
2282
----------------
1855
2283
1876
2304
torrent. If the peer does not respond, or is not a member of this torrent, it will simply
1877
2305
be disconnected. No harm can be done by using this other than an unnecessary connection
1878
2306
attempt is made. If the torrent is uninitialized or in queued or checking mode, this
1879
will throw invalid_handle_. The second (optional) argument will be bitwised ORed into
2307
will throw libtorrent_exception_. The second (optional) argument will be bitwised ORed into
1880
2308
the source mask of this peer. Typically this is one of the source flags in peer_info_.
1881
2309
i.e. ``tracker``, ``pex``, ``dht`` etc.
1882
2310
1984
2412
torrent is active or not, you need to inspect both ``torrent_handle::is_paused()``
1985
2413
and ``session::is_paused()``.
1986
2414
2415
flush_cache()
2416
-------------
2417
2418
::
2419
2420
void flush_cache() const;
2421
2422
Instructs libtorrent to flush all the disk caches for this torrent and close all
2423
file handles. This is done asynchronously and you will be notified that it's complete
2424
through cache_flushed_alert_.
2425
2426
Note that by the time you get the alert, libtorrent may have cached more data for the
2427
torrent, but you are guaranteed that whatever cached data libtorrent had by the time
2428
you called ``torrent_handle::flush_cache()`` has been written to disk.
2429
1987
2430
force_recheck()
1988
2431
---------------
1989
2432
2007
2450
If the torrent is in an error state (i.e. ``torrent_status::error`` is non-empty), this
2008
2451
will clear the error and start the torrent again.
2009
2452
2453
set_upload_mode()
2454
-----------------
2455
2456
::
2457
2458
void set_upload_mode(bool m) const;
2459
2460
Explicitly sets the upload mode of the torrent. In upload mode, the torrent will not
2461
request any pieces. If the torrent is auto managed, it will automatically be taken out
2462
of upload mode periodically (see ``session_settings::optimistic_disk_retry``). Torrents
2463
are automatically put in upload mode whenever they encounter a disk write error.
2464
2465
``m`` should be true to enter upload mode, and false to leave it.
2466
2467
To test if a torrent is in upload mode, call ``torrent_handle::status()`` and inspect
2468
``torrent_status::upload_mode``.
2469
2010
2470
resolve_countries()
2011
2471
-------------------
2012
2472
2041
2501
``auto_managed()`` changes whether the torrent is auto managed or not. For more info,
2042
2502
see queuing_.
2043
2503
2044
has_metadata()
2045
--------------
2504
has_metadata() set_metadata()
2505
-----------------------------
2046
2506
2047
2507
::
2048
2508
2049
2509
bool has_metadata() const;
2050
2051
Returns true if this torrent has metadata (either it was started from a .torrent file or the
2052
metadata has been downloaded). The only scenario where this can return false is when the torrent
2053
was started torrent-less (i.e. with just an info-hash and tracker ip). Note that if the torrent
2054
doesn't have metadata, the member `get_torrent_info()`_ will throw.
2510
bool set_metadata(char const* buf, int size) const;
2511
2512
``has_metadata`` returns true if this torrent has metadata (either it was started from a
2513
.torrent file or the metadata has been downloaded). The only scenario where this can return
2514
false is when the torrent was started torrent-less (i.e. with just an info-hash and tracker
2515
ip). Note that if the torrent doesn't have metadata, the member `get_torrent_info()`_ will
2516
throw.
2517
2518
``set_metadata`` expects the *info* section of metadata. i.e. The buffer passed in will be
2519
hashed and verified against the info-hash. If it fails, a ``metadata_failed_alert`` will be
2520
generated. If it passes, a ``metadata_received_alert`` is generated. The function returns
2521
true if the metadata is successfully set on the torrent, and false otherwise. If the torrent
2522
already has metadata, this function will not affect the torrent, and false will be returned.
2523
2055
2524
2056
2525
set_tracker_login()
2057
2526
-------------------
2065
2534
of the tracker announce. Set this if the tracker requires authorization.
2066
2535
2067
2536
2068
trackers() replace_trackers()
2069
-----------------------------
2537
trackers() replace_trackers() add_tracker()
2538
-------------------------------------------
2070
2539
2071
2540
::
2072
2541
2073
std::vector<announce_entry> const& trackers() const;
2542
std::vector<announce_entry> trackers() const;
2074
2543
void replace_trackers(std::vector<announce_entry> const&) const;
2544
void add_tracker(announc_entry const& url);
2075
2545
2076
2546
``trackers()`` will return the list of trackers for this torrent. The
2077
2547
announce entry contains both a string ``url`` which specify the announce url
2080
2550
trackers for this torrent, you can use ``replace_trackers()`` which takes
2081
2551
a list of the same form as the one returned from ``trackers()`` and will
2082
2552
replace it. If you want an immediate effect, you have to call
2083
`force_reannounce()`_.
2553
`force_reannounce() force_dht_announce()`_. See `trackers()`_ for
2554
the definition of ``announce_entry``.
2555
2556
``add_tracker()`` will look if the specified tracker is already in the set.
2557
If it is, it doesn't do anything. If it's not in the current set of trackers,
2558
it will insert it in the tier specified in the announce_entry.
2559
2560
The updated set of trackers will be saved in the resume data, and when a torrent
2561
is started with resume data, the trackers from the resume data will replace the
2562
original ones.
2084
2563
2085
2564
2086
2565
add_url_seed() remove_url_seed() url_seeds()
2102
2581
2103
2582
See `HTTP seeding`_ for more information.
2104
2583
2584
add_http_seed() remove_http_seed() http_seeds()
2585
-----------------------------------------------
2586
2587
::
2588
2589
void add_http_seed(std::string const& url);
2590
void remove_http_seed(std::string const& url);
2591
std::set<std::string> http_seeds() const;
2592
2593
These functions are identical as the ``*_url_seed()`` variants, but they
2594
operate on BEP 17 web seeds instead of BEP 19.
2595
2596
See `HTTP seeding`_ for more information.
2105
2597
2106
2598
queue_position() queue_position_up() queue_position_down() queue_position_top() queue_position_bottom()
2107
2599
-------------------------------------------------------------------------------------------------------
2129
2621
closer to the front and down means closer to the back of the queue. Top and bottom refers
2130
2622
to the front and the back of the queue respectively.
2131
2623
2624
set_priority()
2625
--------------
2626
2627
::
2628
2629
void set_priority(int prio) const;
2630
2631
This sets the bandwidth priority of this torrent. The priority of a torrent determines
2632
how much bandwidth its peers are assigned when distributing upload and download rate quotas.
2633
A high number gives more bandwidth. The priority must be within the range [0, 255].
2634
2635
The default priority is 0, which is the lowest priority.
2636
2637
To query the priority of a torrent, use the ``status()`` call.
2638
2639
Torrents with higher priority will not nececcarily get as much bandwidth as they can
2640
consume, even if there's is more quota. Other peers will still be weighed in when
2641
bandwidth is being distributed. With other words, bandwidth is not distributed strictly
2642
in order of priority, but the priority is used as a weight.
2132
2643
2133
2644
use_interface()
2134
2645
---------------
2153
2664
``info_hash()`` returns the info-hash for the torrent.
2154
2665
2155
2666
2156
set_max_uploads() set_max_connections()
2157
---------------------------------------
2667
set_max_uploads() max_uploads() set_max_connections() max_connections()
2668
-----------------------------------------------------------------------
2158
2669
2159
2670
::
2160
2671
2161
2672
void set_max_uploads(int max_uploads) const;
2673
int max_uploads() const;
2162
2674
void set_max_connections(int max_connections) const;
2675
int max_connections() const;
2163
2676
2164
2677
``set_max_uploads()`` sets the maximum number of peers that's unchoked at the same time on this
2165
2678
torrent. If you set this to -1, there will be no limit.
2169
2682
This must be at least 2. The default is unlimited number of connections. If -1 is given to the
2170
2683
function, it means unlimited.
2171
2684
2685
``max_uploads()`` and ``max_connections()`` returns the current settings.
2686
2172
2687
2173
2688
save_resume_data()
2174
2689
------------------
2242
2757
2243
2758
std::auto_ptr<alert> holder = ses.pop_alert();
2244
2759
2245
if (dynamic_cast<save_resume_data_failed_alert const*>(a))
2760
if (alert_cast<save_resume_data_failed_alert>(a))
2246
2761
{
2247
2762
process_alert(a);
2248
2763
--num_resume_data;
2249
2764
continue;
2250
2765
}
2251
2766
2252
save_resume_data_alert const* rd = dynamic_cast<save_resume_data_alert const*>(a);
2767
save_resume_data_alert const* rd = alert_cast<save_resume_data_alert>(a);
2253
2768
if (rd == 0)
2254
2769
{
2255
2770
process_alert(a);
2274
2789
torrent_status status() const;
2275
2790
2276
2791
``status()`` will return a structure with information about the status of this
2277
torrent. If the torrent_handle_ is invalid, it will throw invalid_handle_ exception.
2792
torrent. If the torrent_handle_ is invalid, it will throw libtorrent_exception_ exception.
2278
2793
See torrent_status_.
2279
2794
2280
2795
2293
2808
{
2294
2809
int piece_index;
2295
2810
int blocks_in_piece;
2296
block_info blocks[256];
2297
2811
enum state_t { none, slow, medium, fast };
2298
2812
state_t piece_state;
2813
block_info* blocks;
2299
2814
};
2300
2815
2301
2816
``piece_index`` is the index of the piece in question. ``blocks_in_piece`` is the
2316
2831
enum block_state_t
2317
2832
{ none, requested, writing, finished };
2318
2833
2319
tcp::endpoint peer;
2834
void set_peer(tcp::endpoint const& ep);
2835
tcp::endpoint peer() const;
2836
2837
unsigned bytes_progress:15;
2838
unsigned block_size:15;
2320
2839
unsigned state:2;
2321
2840
unsigned num_peers:14;
2322
2841
};
2323
2842
2324
2843
2844
The ``blocks`` field points to an array of ``blocks_in_piece`` elements. This pointer is
2845
only valid until the next call to ``get_download_queue()`` for any torrent in the same session.
2846
They all share the storaga for the block arrays in their session object.
2847
2325
2848
The ``block_info`` array contains data for each individual block in the piece. Each block has
2326
2849
a state (``state``) which is any of:
2327
2850
2334
2857
``num_peers`` is the number of peers that is currently requesting this block. Typically this
2335
2858
is 0 or 1, but at the end of the torrent blocks may be requested by more peers in parallel to
2336
2859
speed things up.
2860
``bytes_progress`` is the number of bytes that have been received for this block, and
2861
``block_size`` is the total number of bytes in this block.
2337
2862
2338
2863
get_peer_info()
2339
2864
---------------
2344
2869
2345
2870
``get_peer_info()`` takes a reference to a vector that will be cleared and filled
2346
2871
with one entry for each peer connected to this torrent, given the handle is valid. If the
2347
torrent_handle_ is invalid, it will throw invalid_handle_ exception. Each entry in
2872
torrent_handle_ is invalid, it will throw libtorrent_exception_ exception. Each entry in
2348
2873
the vector contains information about that particular peer. See peer_info_.
2349
2874
2350
2875
2357
2882
2358
2883
Returns a const reference to the torrent_info_ object associated with this torrent.
2359
2884
This reference is valid as long as the torrent_handle_ is valid, no longer. If the
2360
torrent_handle_ is invalid or if it doesn't have any metadata, invalid_handle_
2885
torrent_handle_ is invalid or if it doesn't have any metadata, libtorrent_exception_
2361
2886
exception will be thrown. The torrent may be in a state without metadata only if
2362
2887
it was started without a .torrent file, i.e. by using the libtorrent extension of
2363
2888
just supplying a tracker and info-hash.
2393
2918
downloading,
2394
2919
finished,
2395
2920
seeding,
2396
allocating
2921
allocating,
2922
checking_resume_data
2397
2923
};
2398
2924
2399
2925
state_t state;
2400
2926
bool paused;
2401
2927
float progress;
2928
int progress_ppm;
2402
2929
std::string error;
2403
2930
2404
2931
boost::posix_time::time_duration next_announce;
2415
2942
size_type total_failed_bytes;
2416
2943
size_type total_redundant_bytes;
2417
2944
2418
float download_rate;
2419
float upload_rate;
2945
int download_rate;
2946
int upload_rate;
2420
2947
2421
float download_payload_rate;
2422
float upload_payload_rate;
2948
int download_payload_rate;
2949
int upload_payload_rate;
2423
2950
2424
2951
int num_peers;
2425
2952
2439
2966
size_type total_wanted;
2440
2967
2441
2968
int num_seeds;
2969
2970
int distributed_full_copies;
2971
int distributed_fraction;
2972
2442
2973
float distributed_copies;
2443
2974
2444
2975
int block_size;
2457
2988
size_type all_time_download;
2458
2989
2459
2990
int active_time;
2991
int finished_time;
2460
2992
int seeding_time;
2461
2993
2462
2994
int seed_rank;
2464
2996
int last_scrape;
2465
2997
2466
2998
bool has_incoming;
2999
3000
int sparse_regions;
3001
3002
bool seed_mode;
3003
3004
bool upload_mode;
3005
3006
int priority;
2467
3007
};
2468
3008
2469
3009
``progress`` is a value in the range [0, 1], that represents the progress of the
2470
torrent's current task. It may be checking files or downloading. The torrent's
2471
current task is in the ``state`` member, it will be one of the following:
2472
3010
torrent's current task. It may be checking files or downloading.
3011
3012
``progress_ppm`` reflects the same value as ``progress``, but instead in a range
3013
[0, 1000000] (ppm = parts per million). When floating point operations are disabled,
3014
this is the only alternative to the floating point value in ``progress``.
3015
3016
The torrent's current task is in the ``state`` member, it will be one of the following:
3017
3018
+--------------------------+----------------------------------------------------------+
3019
|``checking_resume_data`` |The torrent is currently checking the fastresume data and |
3020
| |comparing it to the files on disk. This is typically |
3021
| |completed in a fraction of a second, but if you add a |
3022
| |large number of torrents at once, they will queue up. |
2473
3023
+--------------------------+----------------------------------------------------------+
2474
3024
|``queued_for_checking`` |The torrent is in the queue for being checked. But there |
2475
3025
| |currently is another torrent that are being checked. |
2499
3049
+--------------------------+----------------------------------------------------------+
2500
3050
2501
3051
2502
When downloading, the progress is ``total_wanted_done`` / ``total_wanted``.
3052
When downloading, the progress is ``total_wanted_done`` / ``total_wanted``. This takes
3053
into account files whose priority have been set to 0. They are not considered.
2503
3054
2504
3055
``paused`` is set to true if the torrent is paused and false otherwise.
2505
3056
2582
3133
2583
3134
``total_wanted_done`` is the number of bytes we have downloaded, only counting the
2584
3135
pieces that we actually want to download. i.e. excluding any pieces that we have but
2585
are filtered as not wanted.
3136
have priority 0 (i.e. not wanted).
2586
3137
2587
3138
``total_wanted`` is the total number of bytes we want to download. This is also
2588
excluding pieces that have been filtered.
3139
excluding pieces whose priorities have been set to 0.
2589
3140
2590
3141
``num_seeds`` is the number of peers that are seeding that this client is
2591
3142
currently connected to.
2592
3143
2593
``distributed_copies`` is the number of distributed copies of the torrent.
2594
Note that one copy may be spread out among many peers. The integer part
2595
tells how many copies there are currently of the rarest piece(s) among the
2596
peers this client is connected to. The fractional part tells the share of
2597
pieces that have more copies than the rarest piece(s). For example: 2.5 would
2598
mean that the rarest pieces have only 2 copies among the peers this torrent is
2599
connected to, and that 50% of all the pieces have more than two copies.
3144
``distributed_full_copies`` is the number of distributed copies of the torrent.
3145
Note that one copy may be spread out among many peers. It tells how many copies
3146
there are currently of the rarest piece(s) among the peers this client is
3147
connected to.
3148
3149
``distributed_fraction`` tells the share of pieces that have more copies than
3150
the rarest piece(s). Divide this number by 1000 to get the fraction.
3151
3152
For example, if ``distributed_full_copies`` is 2 and ``distrbuted_fraction``
3153
is 500, it means that the rarest pieces have only 2 copies among the peers
3154
this torrent is connected to, and that 50% of all the pieces have more than
3155
two copies.
2600
3156
2601
3157
If we are a seed, the piece picker is deallocated as an optimization, and
2602
3158
piece availability is no longer tracked. In this case the distributed
2603
copies is set to -1.
3159
copies members are set to -1.
3160
3161
``distributed_copies`` is a floating point representation of the
3162
``distributed_full_copies`` as the integer part and ``distributed_fraction``
3163
/ 1000 as the fraction part. If floating point operations are disabled
3164
this value is always -1.
2604
3165
2605
3166
``block_size`` is the size of a block, in bytes. A block is a sub piece, it
2606
3167
is the number of bytes that each piece request asks for and the number of
2633
3194
payload byte counters. They are saved in and restored from resume data to keep totals
2634
3195
across sessions.
2635
3196
2636
``active_time`` and ``seeding_time`` are second counters. They keep track of the
2637
number of seconds this torrent has been active (not paused) and the number of
2638
seconds it has been active while being a seed. ``seeding_time`` should be >=
2639
``active_time`` They are saved in and restored from resume data, to keep totals
2640
across sessions.
3197
``active_time``, ``finished_time`` and ``seeding_time`` are second counters.
3198
They keep track of the number of seconds this torrent has been active (not
3199
paused) and the number of seconds it has been active while being finished and
3200
active while being a seed. ``seeding_time`` should be >= ``finished_time`` which
3201
should be >= ``active_time``. They are all saved in and restored from resume data,
3202
to keep totals across sessions.
2641
3203
2642
3204
``seed_rank`` is a rank of how important it is to seed the torrent, it is used
2643
3205
to determine which torrents to seed and which to queue. It is based on the peer
2649
3211
``has_incoming`` is true if there has ever been an incoming connection attempt
2650
3212
to this torrent.'
2651
3213
3214
``sparse_regions`` the number of regions of non-downloaded pieces in the
3215
torrent. This is an interesting metric on windows vista, since there is
3216
a limit on the number of sparse regions in a single file there.
3217
3218
``seed_mode`` is true if the torrent is in seed_mode. If the torrent was
3219
started in seed mode, it will leave seed mode once all pieces have been
3220
checked or as soon as one piece fails the hash check.
3221
3222
``upload_mode`` is true if the torrent is blocked from downloading. This
3223
typically happens when a disk write operation fails. If the torrent is
3224
auto-managed, it will periodically be taken out of this state, in the
3225
hope that the disk condition (be it disk full or permission errors) has
3226
been resolved. If the torrent is not auto-managed, you have to explicitly
3227
take it out of the upload mode by calling `set_upload_mode()`_ on the
3228
torrent_handle_.
2652
3229
2653
3230
peer_info
2654
3231
=========
2689
3266
2690
3267
int source;
2691
3268
2692
enum bw_state { bw_idle, bw_torrent, bw_global, bw_network };
3269
enum bw_state { bw_idle, bw_limit, bw_network, bw_disk };
2693
3270
2694
3271
char read_state;
2695
3272
char write_state;
2696
3273
2697
3274
asio::ip::tcp::endpoint ip;
2698
float up_speed;
2699
float down_speed;
2700
float payload_up_speed;
2701
float payload_down_speed;
3275
int up_speed;
3276
int down_speed;
3277
int payload_up_speed;
3278
int payload_down_speed;
2702
3279
size_type total_download;
2703
3280
size_type total_upload;
2704
3281
peer_id pid;
2754
3331
2755
3332
int rtt;
2756
3333
3334
int num_pieces;
3335
2757
3336
int download_rate_peak;
2758
3337
int upload_rate_peak;
2759
3338
2760
3339
float progress;
3340
int progress_ppm;
2761
3341
};
2762
3342
2763
3343
The ``flags`` attribute tells you in which state the peer is. It is set to
2845
3425
| | send or receive data. |
2846
3426
| | |
2847
3427
+------------------------+--------------------------------------------------------+
2848
| ``bw_torrent`` | The peer is waiting for the torrent to receive |
2849
| | bandwidth quota in order to forward the bandwidth |
2850
| | request to the global manager. |
2851
| | |
2852
+------------------------+--------------------------------------------------------+
2853
| ``bw_global`` | The peer is waiting for the global bandwidth manager |
2854
| | to receive more quota in order to handle the request. |
3428
| ``bw_limit`` | The peer is waiting for the rate limiter. |
2855
3429
| | |
2856
3430
+------------------------+--------------------------------------------------------+
2857
3431
| ``bw_network`` | The peer has quota and is currently waiting for a |
2860
3434
| | limits. |
2861
3435
| | |
2862
3436
+------------------------+--------------------------------------------------------+
3437
| ``bw_disk`` | The peer is waiting for the disk I/O thread to catch |
3438
| | up writing buffers to disk before downloading more. |
3439
| | |
3440
+------------------------+--------------------------------------------------------+
2863
3441
2864
3442
The ``ip`` field is the IP-address to this peer. The type is an asio endpoint. For
2865
3443
more info, see the asio_ documentation.
2964
3542
2965
3543
``pending_disk_bytes`` is the number of bytes this peer has pending in the
2966
3544
disk-io thread. Downloaded and waiting to be written to disk. This is what
2967
is capped by ``session_settings::max_outstanding_disk_bytes_per_connection``.
3545
is capped by ``session_settings::max_queued_disk_bytes``.
2968
3546
2969
3547
``send_quota`` and ``receive_quota`` are the number of bytes this peer has been
2970
3548
assigned to be allowed to send and receive until it has to request more quota
2973
3551
``rtt`` is an estimated round trip time to this peer, in milliseconds. It is
2974
3552
estimated by timing the the tcp ``connect()``. It may be 0 for incoming connections.
2975
3553
3554
``num_pieces`` is the number of pieces this peer has.
3555
2976
3556
``download_rate_peak`` and ``upload_rate_peak`` are the highest download and upload
2977
3557
rates seen on this connection. They are given in bytes per second. This number is
2978
3558
reset to 0 on reconnect.
2979
3559
2980
``progress`` is the progress of the peer.
3560
``progress`` is the progress of the peer in the range [0, 1]. This is always 0 when
3561
floating point operations are diabled, instead use ``progress_ppm``.
3562
3563
``progress_ppm`` indicates the download progress of the peer in the range [0, 1000000]
3564
(parts per million).
3565
3566
session customization
3567
=====================
3568
3569
You have some control over session configuration through the ``session_settings`` object. You
3570
create it and fill it with your settings and then use ``session::set_settings()``
3571
to apply them.
3572
3573
You have control over proxy and authorization settings and also the user-agent
3574
that will be sent to the tracker. The user-agent will also be used to identify the
3575
client with other peers.
3576
3577
presets
3578
-------
3579
3580
The default values of the session settings are set for a regular bittorrent client running
3581
on a desktop system. There are functions that can set the session settings to pre set
3582
settings for other environments. These can be used for the basis, and should be tweaked to
3583
fit your needs better.
3584
3585
::
3586
3587
session_settings min_memory_usage();
3588
session_settings high_performance_seed();
3589
3590
``min_memory_usage`` returns settings that will use the minimal amount of RAM, at the
3591
potential expense of upload and download performance. It adjusts the socket buffer sizes,
3592
disables the disk cache, lowers the send buffer watermarks so that each connection only has
3593
at most one block in use at any one time. It lowers the outstanding blocks send to the disk
3594
I/O thread so that connections only have one block waiting to be flushed to disk at any given
3595
time. It lowers the max number of peers in the peer list for torrents. It performs multiple
3596
smaller reads when it hashes pieces, instead of reading it all into memory before hashing.
3597
3598
This configuration is inteded to be the starting point for embedded devices. It will
3599
significantly reduce memory usage.
3600
3601
``high_performance_seed`` returns settings optimized for a seed box, serving many peers
3602
and that doesn't do any downloading. It has a 128 MB disk cache and has a limit of 400 files
3603
in its file pool. It support fast upload rates by allowing large send buffers.
3604
2981
3605
2982
3606
session_settings
2983
================
2984
2985
You have some control over tracker requests through the ``session_settings`` object. You
2986
create it and fill it with your settings and then use ``session::set_settings()``
2987
to apply them. You have control over proxy and authorization settings and also the user-agent
2988
that will be sent to the tracker. The user-agent is a good way to identify your client.
3607
----------------
2989
3608
2990
3609
::
2991
3610
3017
3636
bool lazy_bitfields;
3018
3637
int inactivity_timeout;
3019
3638
int unchoke_interval;
3020
int optimistic_unchoke_multiplier;
3639
int optimistic_unchoke_interval;
3021
3640
address announce_ip;
3022
3641
int num_want;
3023
3642
int initial_picker_threshold;
3024
3643
int allowed_fast_set_size;
3025
int max_outstanding_disk_bytes_per_connection;
3644
int max_queued_disk_bytes;
3026
3645
int handshake_timeout;
3027
3646
bool use_dht_as_fallback;
3028
3647
bool free_torrent_hashes;
3029
3648
bool upnp_ignore_nonrouters;
3030
3649
int send_buffer_watermark;
3031
3650
bool auto_upload_slots;
3651
bool auto_upload_slots_rate_based;
3032
3652
bool use_parole_mode;
3033
3653
int cache_size;
3654
int cache_buffer_chunk_size;
3034
3655
int cache_expiry;
3656
bool use_read_cache;
3657
3658
enum io_buffer_mode_t
3659
{
3660
enable_os_cache = 0,
3661
disable_os_cache_for_aligned_files = 1,
3662
disable_os_cache = 2
3663
};
3664
int disk_io_write_mode;
3665
int disk_io_read_mode;
3666
3035
3667
std::pair<int, int> outgoing_ports;
3036
3668
char peer_tos;
3037
3669
3038
3670
int active_downloads;
3039
3671
int active_seeds;
3040
3672
int active_limit;
3673
bool auto_manage_prefer_seeds;
3041
3674
bool dont_count_slow_torrents;
3042
3675
int auto_manage_interval;
3043
3676
float share_ratio_limit;
3056
3689
int auto_manage_startup;
3057
3690
3058
3691
bool rate_limit_ip_overhead;
3692
3693
bool announce_to_all_trackers;
3694
bool announce_to_all_tiers;
3695
3696
bool prefer_udp_trackers;
3697
bool strict_super_seeding;
3698
3699
int seeding_piece_quota;
3700
3701
int max_sparse_regions;
3702
3703
bool lock_disk_cache;
3704
3705
int max_rejects;
3706
3707
int recv_socket_buffer_size;
3708
int send_socket_buffer_size;
3709
3710
bool optimize_hashing_for_speed;
3711
3712
int file_checks_delay_per_block;
3713
3714
enum disk_cache_algo_t
3715
{ lru, largest_contiguous };
3716
3717
disk_cache_algo_t disk_cache_algorithm;
3718
3719
int read_cache_line_size;
3720
int write_cache_line_size;
3721
3722
int optimistic_disk_retry;
3723
bool disable_hash_check;
3724
3725
int max_suggest_pieces;
3726
3727
bool drop_skipped_requests;
3728
3729
bool low_prio_disk;
3730
3731
int local_service_announce_interval;
3732
3733
int udp_tracker_token_expiry;
3734
3735
bool report_true_downloaded;
3736
bool strict_end_game_mode;
3059
3737
};
3060
3738
3061
3739
``user_agent`` this is the client identification to the tracker.
3159
3837
unchoke limits are ignored for peers on the local network.
3160
3838
3161
3839
``connection_speed`` is the number of connection attempts that
3162
are made per second. If a number <= 0 is specified, it will default to
3163
200 connections per second.
3840
are made per second. If a number < 0 is specified, it will default to
3841
200 connections per second. If 0 is specified, it means don't make
3842
outgoing connections at all.
3164
3843
3165
3844
``send_redundant_have`` controls if have messages will be sent
3166
3845
to peers that already have the piece. This is typically not necessary,
3181
3860
is defined as 30 seconds in the protocol, and it should be significantly
3182
3861
longer than what it takes for TCP to ramp up to it's max rate.
3183
3862
3184
``optimistic_unchoke_multiplier`` is the number of unchoke intervals between
3185
each *optimistic* unchoke interval. On this timer, the currently optimistically
3863
``optimistic_unchoke_interval`` is the number of seconds between
3864
each *optimistic* unchoke. On this timer, the currently optimistically
3186
3865
unchoked peer will change.
3187
3866
3188
3867
``announce_ip`` is the ip address passed along to trackers as the ``&ip=`` parameter.
3199
3878
``allowed_fast_set_size`` is the number of pieces we allow peers to download
3200
3879
from us without being unchoked.
3201
3880
3202
``max_outstanding_disk_bytes_per_connection`` is the number of bytes each
3203
connection is allowed to have waiting in the disk I/O queue before it is
3204
throttled back. This limit is meant to stop fast internet connections to
3205
queue up bufferes indefinitely on slow hard-drives or storage.
3881
``max_queued_disk_bytes`` is the number maximum number of bytes, to be
3882
written to disk, that can wait in the disk I/O thread queue. This queue
3883
is only for waiting for the disk I/O thread to receive the job and either
3884
write it to disk or insert it in the write cache. When this limit is reached,
3885
the peer connections will stop reading data from their sockets, until the disk
3886
thread catches up. Setting this too low will severly limit your download rate.
3206
3887
3207
3888
``handshake_timeout`` specifies the number of seconds we allow a peer to
3208
3889
delay responding to a protocol handshake. If no response is received within
3240
3921
less than what has been set by ``session::set_max_uploads()``. To query the
3241
3922
current number of upload slots, see ``session_status::allowed_upload_slots``.
3242
3923
3924
When ``auto_upload_slots_rate_based`` is set, and ``auto_upload_slots`` is set,
3925
the max upload slots setting is used as a minimum number of unchoked slots.
3926
This algorithm is designed to prevent the peer from spreading its upload
3927
capacity too thin, but still open more slots in order to utilize the full capacity.
3928
3243
3929
``use_parole_mode`` specifies if parole mode should be used. Parole mode means
3244
3930
that peers that participate in pieces that fail the hash check are put in a mode
3245
3931
where they are only allowed to download whole pieces. If the whole piece a peer
3246
3932
in parole mode fails the hash check, it is banned. If a peer participates in a
3247
3933
piece that passes the hash check, it is taken out of parole mode.
3248
3934
3249
``cache_size`` is the disk write cache. It is specified in units of 16 KiB blocks.
3250
It defaults to 512 (= 8 MB).
3935
``cache_size`` is the disk write and read cache. It is specified in units of
3936
16 KiB blocks. It defaults to 1024 (= 16 MB). Buffers that are part of a peer's
3937
send or receive buffer also count against this limit. Send and receive buffers
3938
will never be denied to be allocated, but they will cause the actual cached blocks
3939
to be flushed or evicted.
3940
3941
Disk buffers are allocated using a pool allocator, the number of blocks that
3942
are allocated at a time when the pool needs to grow can be specified in
3943
``cache_buffer_chunk_size``. This defaults to 16 blocks. Lower numbers
3944
saves memory at the expense of more heap allocations. It must be at least 1.
3251
3945
3252
3946
``cache_expiry`` is the number of seconds from the last cached write to a piece
3253
3947
in the write cache, to when it's forcefully flushed to disk. Default is 60 second.
3254
3948
3949
``use_read_cache``, is set to true (default), the disk cache is also used to
3950
cache pieces read from disk. Blocks for writing pieces takes presedence.
3951
3952
``disk_io_write_mode`` and ``disk_io_read_mode`` determines how files are
3953
opened when they're in read only mode versus read and write mode. The options
3954
are:
3955
3956
* enable_os_cache
3957
This is the default and files are opened normally, with the OS caching
3958
reads and writes.
3959
* disable_os_cache_for_aligned_files
3960
This will open files in unbuffered mode for files where every read and
3961
write would be sector aligned. Using aligned disk offsets is a requirement
3962
on some operating systems.
3963
* disable_os_cache
3964
This opens all files in unbuffered mode (if allowed by the operating system).
3965
Linux and Windows, for instance, require disk offsets to be sector aligned,
3966
and in those cases, this option is the same as ``disable_os_caches_for_aligned_files``.
3967
3968
One reason to disable caching is that it may help the operating system from growing
3969
its file cache indefinitely. Since some OSes only allow aligned files to be opened
3970
in unbuffered mode, It is recommended to make the largest file in a torrent the first
3971
file (with offset 0) or use pad files to align all files to piece boundries.
3972
3255
3973
``outgoing_ports``, if set to something other than (0, 0) is a range of ports
3256
3974
used to bind outgoing sockets to. This may be useful for users whose router
3257
3975
allows them to assign QoS classes to traffic based on its local port. It is
3280
3998
limits. If there are non-auto managed torrents that use up all the slots, no
3281
3999
auto managed torrent will be activated.
3282
4000
4001
``auto_manage_prefer_seeds`` specifies if libtorrent should prefer giving seeds
4002
active slots or downloading torrents. The default is ``false``.
4003
3283
4004
if ``dont_count_slow_torrents`` is true, torrents without any payload transfers are
3284
4005
not subject to the ``active_seeds`` and ``active_downloads`` limits. This is intended
3285
4006
to make it more likely to utilize all available bandwidth, and avoid having torrents
3322
4043
should be much greater than the maximum number of connected peers.
3323
4044
Peers are evicted from the cache when the list grows passed 90% of
3324
4045
this limit, and once the size hits the limit, peers are no longer
3325
added to the list.
4046
added to the list. If this limit is set to 0, there is no limit on
4047
how many peers we'll keep in the peer list.
4048
4049
``max_paused_peerlist_size`` is the max peer list size used for torrents
4050
that are paused. This default to the same as ``max_peerlist_size``, but
4051
can be used to save memory for paused torrents, since it's not as
4052
important for them to keep a large peer list.
3326
4053
3327
4054
``min_announce_interval`` is the minimum allowed announce interval
3328
4055
for a tracker. This is specified in seconds, defaults to 5 minutes and
3342
4069
If ``rate_limit_ip_overhead`` is set to true, the estimated TCP/IP overhead is
3343
4070
drained from the rate limiters, to avoid exceeding the limits with the total traffic
3344
4071
4072
``announce_to_all_trackers`` controls how multi tracker torrents are
4073
treated. If this is set to true, all trackers in the same tier are
4074
announced to in parallel. If all trackers in tier 0 fails, all trackers
4075
in tier 1 are announced as well. If it's set to false, the behavior is as
4076
defined by the multi tracker specification. It defaults to false, which
4077
is the same behavior previous versions of libtorrent has had as well.
4078
4079
``announce_to_all_tiers`` also controls how multi tracker torrents are
4080
treated. When this is set to true, one tracker from each tier is announced
4081
to. This is the uTorrent behavior. This is false by default in order
4082
to comply with the multi-tracker specification.
4083
4084
``prefer_udp_trackers`` is true by default. It means that trackers may
4085
be rearranged in a way that udp trackers are always tried before http
4086
trackers for the same hostname. Setting this to fails means that the
4087
trackers' tier is respected and there's no preference of one protocol
4088
over another.
4089
4090
``strict_super_seeding`` when this is set to true, a piece has to
4091
have been forwarded to a third peer before another one is handed out.
4092
This is the traditional definition of super seeding.
4093
4094
``seeding_piece_quota`` is the number of pieces to send to a peer,
4095
when seeding, before rotating in another peer to the unchoke set.
4096
It defaults to 3 pieces, which means that when seeding, any peer we've
4097
sent more than this number of pieces to will be unchoked in favour of
4098
a choked peer.
4099
4100
``max_sparse_regions`` is a limit of the number of *sparse regions* in
4101
a torrent. A sparse region is defined as a hole of pieces we have not
4102
yet downloaded, in between pieces that have been downloaded. This is
4103
used as a hack for windows vista which has a bug where you cannot
4104
write files with more than a certain number of sparse regions. This
4105
limit is not hard, it will be exceeded. Once it's exceeded, pieces
4106
that will maintain or decrease the number of sparse regions are
4107
prioritized. To disable this functionality, set this to 0. It defaults
4108
to 0 on all platforms except windows.
4109
4110
``lock_disk_cache`` if lock disk cache is set to true the disk cache
4111
that's in use, will be locked in physical memory, preventing it from
4112
being swapped out.
4113
4114
``max_rejects`` is the number of piece requests we will reject in a row
4115
while a peer is choked before the peer is considered abusive and is
4116
disconnected.
4117
4118
4119
``recv_socket_buffer_size`` and ``send_socket_buffer_size`` specifies
4120
the buffer sizes set on peer sockets. 0 (which is the default) means
4121
the OS default (i.e. don't change the buffer sizes). The socket buffer
4122
sizes are changed using setsockopt() with SOL_SOCKET/SO_RCVBUF and
4123
SO_SNDBUFFER.
4124
4125
``optimize_hashing_for_speed`` chooses between two ways of reading back
4126
piece data from disk when its complete and needs to be verified against
4127
the piece hash. This happens if some blocks were flushed to the disk
4128
out of order. Everything that is flushed in order is hashed as it goes
4129
along. Optimizing for speed will allocate space to fit all the the
4130
remaingin, unhashed, part of the piece, reads the data into it in a single
4131
call and hashes it. This is the default. If ``optimizing_hashing_for_speed``
4132
is false, a single block will be allocated (16 kB), and the unhashed parts
4133
of the piece are read, one at a time, and hashed in this single block. This
4134
is appropriate on systems that are memory constrained.
4135
4136
``file_checks_delay_per_block`` is the number of milliseconds to sleep
4137
in between disk read operations when checking torrents. This defaults
4138
to 0, but can be set to higher numbers to slow down the rate at which
4139
data is read from the disk while checking. This may be useful for
4140
background tasks that doesn't matter if they take a bit longer, as long
4141
as they leave disk I/O time for other processes.
4142
4143
``disk_cache_algorithm`` tells the disk I/O thread which cache flush
4144
algorithm to use. The default algorithm is largest_contiguous. This
4145
flushes the entire piece, in the write cache, that was least recently
4146
written to. This is specified by the ``session_settings::lru`` enum
4147
value. ``session_settings::largest_contiguous`` will flush the largest
4148
sequences of contiguous blocks from the write cache, regarless of the
4149
piece's last use time.
4150
4151
``read_cache_line_size`` is the number of blocks to read into the read
4152
cache when a read cache miss occurs. Setting this to 0 is essentially
4153
the same thing as disabling read cache. The number of blocks read
4154
into the read cache is always capped by the piece boundry.
4155
4156
When a piece in the write cache has ``write_cache_line_size`` contiguous
4157
blocks in it, they will be flushed. Setting this to 1 effectively
4158
disables the write cache.
4159
4160
``optimistic_disk_retry`` is the number of seconds from a disk write
4161
errors occur on a torrent until libtorrent will take it out of the
4162
upload mode, to test if the error condition has been fixed.
4163
4164
libtorrent will only do this automatically for auto managed torrents.
4165
4166
You can explicitly take a torrent out of upload only mode using
4167
`set_upload_mode()`_.
4168
4169
``disable_hash_check`` controls if downloaded pieces are verified against
4170
the piece hashes in the torrent file or not. The default is false, i.e.
4171
to verify all downloaded data. It may be useful to turn this off for performance
4172
profiling and simulation scenarios. Do not disable the hash check for regular
4173
bittorrent clients.
4174
4175
``max_suggest_pieces`` is the max number of suggested piece indices received
4176
from a peer that's remembered. If a peer floods suggest messages, this limit
4177
prevents libtorrent from using too much RAM. It defaults to 10.
4178
4179
If ``drop_skipped_requests`` is set to true (it defaults to false), piece
4180
requests that have been skipped enough times when piece messages
4181
are received, will be considered lost. Requests are considered skipped
4182
when the returned piece messages are re-ordered compared to the order
4183
of the requests. This was an attempt to get out of dead-locks caused by
4184
BitComet peers silently ignoring some requests. It may cause problems
4185
at high rates, and high level of reordering in the uploading peer, that's
4186
why it's disabled by default.
4187
4188
``low_prio_disk`` determines if the disk I/O should use a normal
4189
or low priority policy. This defaults to true, which means that
4190
it's low priority by default. Other processes doing disk I/O will
4191
normally take priority in this mode. This is meant to improve the
4192
overall responsiveness of the system while downloading in the
4193
background. For high-performance server setups, this might not
4194
be desirable.
4195
4196
``local_service_announce_interval`` is the time between local
4197
network announces for a torrent. By default, when local service
4198
discovery is enabled a torrent announces itself every 5 minutes.
4199
This interval is specified in seconds.
4200
4201
``udp_tracker_token_expiry`` is the number of seconds libtorrent
4202
will keep UDP tracker connection tokens around for. This is specified
4203
to be 60 seconds, and defaults to that. The higher this value is, the
4204
fewer packets have to be sent to the UDP tracker. In order for higher
4205
values to work, the tracker needs to be configured to match the
4206
expiration time for tokens.
4207
4208
When ``report_true_downloaded`` is true, the ``&downloaded=`` argument
4209
sent to trackers will include redundant downloaded bytes. It defaults
4210
to ``false``, which means redundant bytes are not reported to the tracker.
4211
4212
``strict_end_game_mode`` defaults to true, and controls when a block
4213
may be requested twice. If this is ``true``, a block may only be requested
4214
twice when there's ay least one request to every piece that's left to
4215
download in the torrent. This may slow down progress on some pieces
4216
sometimes, but it may also avoid downloading a lot of redundant bytes.
4217
If this is ``false``, libtorrent attempts to use each peer connection
4218
to its max, by always requesting something, even if it means requesting
4219
something that has been requested from another peer already.
3345
4220
3346
4221
pe_settings
3347
4222
===========
3890
4765
Now we just need to know how to retrieve information from the entry_.
3891
4766
3892
4767
If ``bdecode()`` encounters invalid encoded data in the range given to it
3893
it will throw invalid_encoding_.
4768
it will throw libtorrent_exception_.
3894
4769
3895
4770
add_magnet_uri()
3896
4771
----------------
3899
4774
3900
4775
torrent_handle add_magnet_uri(session& ses, std::string const& uri
3901
4776
add_torrent_params p);
4777
torrent_handle add_magnet_uri(session& ses, std::string const& uri
4778
add_torrent_params p, error_code& ec);
3902
4779
3903
4780
This function parses the magnet URI (``uri``) as a bittorrent magnet link,
3904
4781
and adds the torrent to the specified session (``ses``). It returns the
3906
4783
failed. To control some initial settings of the torrent, sepcify those in
3907
4784
the ``add_torrent_params``, ``p``. See `add_torrent()`_.
3908
4785
4786
The overload that does not take an ``error_code`` throws an exception on
4787
error and is not available when building without exception support.
4788
3909
4789
For more information about magnet links, see `magnet links`_.
3910
4790
3911
4791
make_magnet_uri()
3931
4811
from the front of the queue is popped and returned.
3932
4812
You can then use the alert object and query
3933
4813
3934
By default, only errors are reported. ``session::set_alert_mask()`` can be
4814
By default, only errors are reported. `set_alert_mask()`_ can be
3935
4815
used to specify which kinds of events should be reported. The alert mask
3936
4816
is a bitmask with the following bits:
3937
4817
3970
4850
| ``performance_warning`` | Alerts when some limit is reached that might limit the download |
3971
4851
| | or upload rate. |
3972
4852
+--------------------------------+---------------------------------------------------------------------+
4853
| ``stats_notification`` | If you enable these alerts, you will receive a ``stats_alert`` |
4854
| | approximately once every second, for every active torrent. |
4855
| | These alerts contain all statistics counters for the interval since |
4856
| | the lasts stats alert. |
4857
+--------------------------------+---------------------------------------------------------------------+
3973
4858
| ``all_categories`` | The full bitmask, representing all available categories. |
3974
4859
+--------------------------------+---------------------------------------------------------------------+
3975
4860
3977
4862
alerts that belong to an enabled category are posted. Setting the alert bitmask to 0 will disable
3978
4863
all alerts
3979
4864
3980
When you get an alert, you can use ``typeid()`` or ``dynamic_cast<>`` to get more detailed
3981
information on exactly which type it is. i.e. what kind of error it is. You can also use a
3982
dispatcher_ mechanism that's available in libtorrent.
4865
When you get an alert, you can use ``alert_cast<>`` to attempt to cast the pointer to a
4866
more specific alert type, to be queried for more information about the alert. ``alert_cast``
4867
has the followinf signature::
4868
4869
template <T> T* alert_cast(alert* a);
4870
template <T> T const* alert_cast(alert const* a);
4871
4872
You can also use a dispatcher_ mechanism that's available in libtorrent.
3983
4873
3984
4874
All alert types are defined in the ``<libtorrent/alert_types.hpp>`` header file.
3985
4875
4004
4894
progress_notification = *implementation defined*,
4005
4895
ip_block_notification = *implementation defined*,
4006
4896
performance_warning = *implementation defined*,
4897
dht_notification = *implementation defined*,
4007
4898
4008
4899
all_categories = *implementation defined*
4009
4900
};
4050
4941
4051
4942
The specific alerts are:
4052
4943
4944
read_piece_alert
4945
----------------
4946
4947
This alert is posted when the asynchronous read operation initiated by
4948
a call to `read_piece()`_ is completed. If the read failed, the torrent
4949
is paused and an error state is set and the buffer member of the alert
4950
is 0. If successful, ``buffer`` points to a buffer containing all the data
4951
of the piece. ``piece`` is the piece index that was read. ``size`` is the
4952
number of bytes that was read.
4953
4954
::
4955
4956
struct read_piece_alert: torrent_alert
4957
{
4958
// ...
4959
boost::shared_ptr<char> buffer;
4960
int piece;
4961
int size;
4962
};
4963
4053
4964
external_ip_alert
4054
4965
-----------------
4055
4966
4071
4982
-------------------
4072
4983
4073
4984
This alert is generated when none of the ports, given in the port range, to
4074
session_ can be opened for listening.
4985
session_ can be opened for listening. The ``endpoint`` member is the
4986
interface and port that failed, ``error`` is the error code describing
4987
the failure.
4075
4988
4076
4989
libtorrent may sometimes try to listen on port 0, if all other ports failed.
4077
4990
Port 0 asks the operating system to pick a port that's free). If that fails
4080
4993
4081
4994
::
4082
4995
4083
struct external_ip_alert: alert
4996
struct listen_failed_alert: alert
4084
4997
{
4085
4998
// ...
4086
4999
tcp::endpoint endpoint;
4087
5000
error_code error;
4088
5001
};
4089
5002
4090
``endpoint`` is the address and port that libtorrent tried to listen on
4091
but failed.
4092
4093
``error`` is the error message from the failed socket operation.
5003
listen_succeeded_alert
5004
----------------------
5005
5006
This alert is posted when the listen port succeeds to be opened on a
5007
particular interface. ``endpoint`` is the endpoint that successfully
5008
was opened for listening.
5009
5010
::
5011
5012
struct listen_succeeded_alert: alert
5013
{
5014
// ...
5015
tcp::endpoint endpoint;
5016
};
4094
5017
4095
5018
4096
5019
portmap_error_alert
4108
5031
4109
5032
``type`` is 0 for NAT-PMP and 1 for UPnP.
4110
5033
5034
``error`` tells you what failed.
4111
5035
::
4112
5036
4113
5037
struct portmap_error_alert: alert
4115
5039
// ...
4116
5040
int mapping;
4117
5041
int type;
5042
error_code error;
4118
5043
};
4119
5044
4120
5045
portmap_alert
4142
5067
int type;
4143
5068
};
4144
5069
5070
portmap_log_alert
5071
-----------------
5072
5073
This alert is generated to log informational events related to either
5074
UPnP or NAT-PMP. They contain a log line and the type (0 = NAT-PMP
5075
and 1 = UPnP). Displaying these messages to an end user is only useful
5076
for debugging the UPnP or NAT-PMP implementation.
5077
5078
::
5079
5080
struct portmap_log_alert: alert
5081
{
5082
//...
5083
int type;
5084
std::string msg;
5085
};
5086
4145
5087
file_error_alert
4146
5088
----------------
4147
5089
4150
5092
4151
5093
``file`` is the path to the file that was accessed when the error occurred.
4152
5094
4153
``msg`` is the error message received from the OS.
5095
``error`` is the error code describing the error.
4154
5096
4155
5097
::
4156
5098
4158
5100
{
4159
5101
// ...
4160
5102
std::string file;
4161
std::string msg;
5103
error_code error;
4162
5104
};
4163
5105
4164
5106
file_renamed_alert
4165
------------------------
5107
------------------
4166
5108
4167
5109
This is posted as a response to a ``torrent_handle::rename_file`` call, if the rename
4168
5110
operation succeeds.
4191
5133
struct file_rename_failed_alert: torrent_alert
4192
5134
{
4193
5135
// ...
4194
std::string msg;
4195
5136
int index;
5137
error_code error;
4196
5138
};
4197
5139
4198
5140
The ``index`` member refers to the index of the file that was supposed to be renamed,
4199
``msg`` is the error message returned from the filesystem.
5141
``error`` is the error code returned from the filesystem.
4200
5142
4201
5143
tracker_announce_alert
4202
5144
----------------------
4357
5299
};
4358
5300
4359
5301
5302
peer_alert
5303
----------
5304
5305
The peer alert is a base class for alerts that refer to a specific peer. It includes all
5306
the information to identify the peer. i.e. ``ip`` and ``peer-id``.
5307
5308
::
5309
5310
struct peer_alert: torrent_alert
5311
{
5312
// ...
5313
tcp::endpoint ip;
5314
peer_id pid;
5315
};
5316
5317
peer_connect_alert
5318
------------------
5319
5320
This alert is posted every time an outgoing peer connect attempts succeeds.
5321
5322
::
5323
5324
struct peer_connect_alert: peer_alert
5325
{
5326
// ...
5327
};
5328
4360
5329
peer_ban_alert
4361
5330
--------------
4362
5331
4365
5334
4366
5335
::
4367
5336
4368
struct peer_ban_alert: torrent_alert
4369
{
4370
// ...
4371
asio::ip::tcp::endpoint ip;
5337
struct peer_ban_alert: peer_alert
5338
{
5339
// ...
5340
};
5341
5342
5343
peer_snubbed_alert
5344
------------------
5345
5346
This alert is generated when a peer is snubbed, when it stops sending data when we request
5347
it.
5348
5349
::
5350
5351
struct peer_snubbed_alert: peer_alert
5352
{
5353
// ...
5354
};
5355
5356
5357
peer_unsnubbed_alert
5358
--------------------
5359
5360
This alert is generated when a peer is unsnubbed. Essentially when it was snubbed for stalling
5361
sending data, and now it started sending data again.
5362
5363
::
5364
5365
struct peer_unsnubbed_alert: peer_alert
5366
{
5367
// ...
4372
5368
};
4373
5369
4374
5370
4378
5374
This alert is generated when a peer sends invalid data over the peer-peer protocol. The peer
4379
5375
will be disconnected, but you get its ip address from the alert, to identify it.
4380
5376
4381
::
4382
4383
struct peer_error_alert: torrent_alert
4384
{
4385
// ...
4386
asio::ip::tcp::endpoint ip;
4387
peer_id id;
5377
The ``error_code`` tells you what error caused this alert.
5378
5379
::
5380
5381
struct peer_error_alert: peer_alert
5382
{
5383
// ...
5384
error_code error;
5385
};
5386
5387
5388
peer_connected_alert
5389
--------------------
5390
5391
This alert is generated when a peer is connected.
5392
5393
::
5394
5395
struct peer_connected_alert: peer_alert
5396
{
5397
// ...
5398
};
5399
5400
5401
peer_disconnected_alert
5402
-----------------------
5403
5404
This alert is generated when a peer is disconnected for any reason (other than the ones
5405
covered by ``peer_error_alert``).
5406
5407
The ``error_code`` tells you what error caused peer to disconnect.
5408
5409
::
5410
5411
struct peer_disconnected_alert: peer_alert
5412
{
5413
// ...
5414
error_code error;
4388
5415
};
4389
5416
4390
5417
4397
5424
4398
5425
::
4399
5426
4400
struct invalid_request_alert: torrent_alert
5427
struct invalid_request_alert: peer_alert
4401
5428
{
4402
invalid_request_alert(
4403
peer_request const& r
4404
, torrent_handle const& h
4405
, asio::ip::tcp::endpoint const& send
4406
, peer_id const& pid
4407
, std::string const& msg);
4408
4409
virtual std::auto_ptr<alert> clone() const;
4410
4411
asio::ip::tcp::endpoint ip;
5429
// ...
4412
5430
peer_request request;
4413
peer_id id;
4414
5431
};
4415
5432
4416
5433
4427
5444
the index of the piece it want data from, ``start`` is the offset within the piece where the data
4428
5445
should be read, and ``length`` is the amount of data it wants.
4429
5446
5447
request_dropped_alert
5448
---------------------
5449
5450
This alert is generated when a peer rejects or ignores a piece request.
5451
5452
::
5453
5454
struct request_dropped_alert: peer_alert
5455
{
5456
// ...
5457
int block_index;
5458
int piece_index;
5459
};
5460
5461
5462
block_timeout_alert
5463
-------------------
5464
5465
This alert is generated when a block request times out.
5466
5467
::
5468
5469
struct block_timeout_alert: peer_alert
5470
{
5471
// ...
5472
int block_index;
5473
int piece_index;
5474
};
5475
5476
5477
block_finished_alert
5478
--------------------
5479
5480
This alert is generated when a block request receives a response.
5481
5482
::
5483
5484
struct block_finished_alert: peer_alert
5485
{
5486
// ...
5487
int block_index;
5488
int piece_index;
5489
};
5490
5491
5492
file_completed_alert
5493
--------------------
5494
5495
This is posted whenever an individual file completes its download. i.e.
5496
All pieces overlapping this file have passed their hash check.
5497
5498
::
5499
5500
struct file_completed_alert: torrent_alert
5501
{
5502
// ...
5503
int index;
5504
};
5505
5506
The ``index`` member refers to the index of the file that completed.
5507
5508
5509
block_downloading_alert
5510
-----------------------
5511
5512
This alert is generated when a block request is sent to a peer.
5513
5514
::
5515
5516
struct block_downloading_alert: peer_alert
5517
{
5518
// ...
5519
int block_index;
5520
int piece_index;
5521
};
5522
5523
5524
unwanted_block_alert
5525
--------------------
5526
5527
This alert is generated when a block is received that was not requested or
5528
whose request timed out.
5529
5530
::
5531
5532
struct unwanted_block_alert: peer_alert
5533
{
5534
// ...
5535
int block_index;
5536
int piece_index;
5537
};
5538
5539
5540
torrent_delete_failed_alert
5541
---------------------------
5542
5543
This alert is generated when a request to delete the files of a torrent fails.
5544
5545
The ``error_code`` tells you why it failed.
5546
5547
::
5548
5549
struct torrent_delete_failed_alert: torrent_alert
5550
{
5551
// ...
5552
error_code error;
5553
};
5554
5555
torrent_deleted_alert
5556
---------------------
5557
5558
This alert is generated when a request to delete the files of a torrent complete.
5559
5560
The ``info_hash`` is the info-hash of the torrent that was just deleted. Most of
5561
the time the torrent_handle in the ``torrent_alert`` will be invalid by the time
5562
this alert arrives, since the torrent is being deleted. The ``info_hash`` member
5563
is hence the main way of identifying which torrent just completed the delete.
5564
5565
This alert is posted in the ``storage_notification`` category, and that bit
5566
needs to be set in the alert mask.
5567
5568
::
5569
5570
struct torrent_deleted_alert: torrent_alert
5571
{
5572
// ...
5573
sha1_hash info_hash;
5574
};
5575
4430
5576
torrent_finished_alert
4431
5577
----------------------
4432
5578
4453
5599
{
4454
5600
outstanding_disk_buffer_limit_reached,
4455
5601
outstanding_request_limit_reached,
5602
upload_limit_too_low,
5603
download_limit_too_low,
5604
send_buffer_watermark_too_low
4456
5605
};
4457
5606
4458
5607
performance_warning_t warning_code;
4459
5608
};
4460
5609
4461
5610
5611
state_changed_alert
5612
-------------------
5613
5614
Generated whenever a torrent changes its state.
5615
5616
::
5617
5618
struct state_changed_alert: torrent_alert
5619
{
5620
// ...
5621
5622
torrent_status::state_t state;
5623
torrent_status::state_t prev_state;
5624
};
5625
5626
``state`` is the new state of the torrent. ``prev_state`` is the previous state.
5627
5628
4462
5629
metadata_failed_alert
4463
5630
---------------------
4464
5631
4484
5651
-------------------------
4485
5652
4486
5653
This alert is generated when a fastresume file has been passed to ``add_torrent`` but the
4487
files on disk did not match the fastresume file. The string explains the reason why the
5654
files on disk did not match the fastresume file. The ``error_code`` explains the reason why the
4488
5655
resume file was rejected.
4489
5656
4490
5657
::
4492
5659
struct fastresume_rejected_alert: torrent_alert
4493
5660
{
4494
5661
// ...
4495
std::string msg;
5662
error_code error;
4496
5663
};
4497
5664
4498
5665
4579
5746
-----------------------------
4580
5747
4581
5748
This alert is generated instead of ``save_resume_data_alert`` if there was an error
4582
generating the resume data. ``msg`` describes what went wrong.
5749
generating the resume data. ``error`` describes what went wrong.
4583
5750
4584
5751
::
4585
5752
4586
5753
struct save_resume_data_failed_alert: torrent_alert
4587
5754
{
4588
5755
// ...
4589
std::string msg;
5756
error_code error;
5757
};
5758
5759
stats_alert
5760
-----------
5761
5762
This alert is posted approximately once every second, and it contains
5763
byte counters of most statistics that's tracked for torrents. Each active
5764
torrent posts these alerts regularly.
5765
5766
::
5767
5768
struct stats_alert: torrent_alert
5769
{
5770
// ...
5771
enum stats_channel
5772
{
5773
upload_payload,
5774
upload_protocol,
5775
upload_ip_protocol,
5776
upload_dht_protocol,
5777
upload_tracker_protocol,
5778
download_payload,
5779
download_protocol,
5780
download_ip_protocol,
5781
download_dht_protocol,
5782
download_tracker_protocol,
5783
num_channels
5784
};
5785
5786
int transferred[num_channels];
5787
int interval;
5788
};
5789
5790
``transferred`` this is an array of samples. The enum describes what each
5791
sample is a measurement of. All of these are raw, and not smoothing is performed.
5792
5793
``interval`` the number of milliseconds during which these stats
5794
were collected. This is typically just above 1000, but if CPU is
5795
limited, it may be higher than that.
5796
5797
5798
cache_flushed_alert
5799
-------------------
5800
5801
This alert is posted when the disk cache has been flushed for a specific torrent
5802
as a result of a call to `flush_cache()`_. This alert belongs to the
5803
``storage_notification`` category, which must be enabled to let this alert through.
5804
5805
::
5806
5807
struct flush_cached_alert: torrent_alert
5808
{
5809
// ...
5810
};
5811
5812
dht_announce_alert
5813
------------------
5814
5815
This alert is generated when a DHT node announces to an info-hash on our DHT node. It belongs
5816
to the ``dht_notification`` category.
5817
5818
::
5819
5820
struct dht_announce_alert: alert
5821
{
5822
// ...
5823
address ip;
5824
int port;
5825
sha1_hash info_hash;
5826
};
5827
5828
dht_get_peers_alert
5829
-------------------
5830
5831
This alert is generated when a DHT node sends a ``get_peers`` message to our DHT node.
5832
It belongs to the ``dht_notification`` category.
5833
5834
::
5835
5836
struct dht_get_peers_alert: alert
5837
{
5838
// ...
5839
sha1_hash info_hash;
4590
5840
};
4591
5841
4592
5842
dispatcher
4598
5848
4599
5849
struct my_handler
4600
5850
{
4601
void operator()(portmap_error_alert const& a)
5851
void operator()(portmap_error_alert const& a) const
4602
5852
{
4603
5853
std::cout << "Portmapper: " << a.msg << std::endl;
4604
5854
}
4605
5855
4606
void operator()(tracker_warning_alert const& a)
5856
void operator()(tracker_warning_alert const& a) const
4607
5857
{
4608
5858
std::cout << "Tracker warning: " << a.msg << std::endl;
4609
5859
}
4610
5860
4611
void operator()(torrent_finished_alert const& a)
5861
void operator()(torrent_finished_alert const& a) const
4612
5862
{
4613
5863
// write fast resume data
4614
5864
// ...
4641
5891
exceptions
4642
5892
==========
4643
5893
4644
There are a number of exceptions that can be thrown from different places in libtorrent,
4645
here's a complete list with description.
4646
4647
4648
invalid_handle
4649
--------------
4650
4651
This exception is thrown when querying information from a torrent_handle_ that hasn't
4652
been initialized or that has become invalid.
4653
4654
::
4655
4656
struct invalid_handle: std::exception
4657
{
4658
const char* what() const throw();
4659
};
4660
4661
4662
duplicate_torrent
4663
-----------------
4664
4665
This is thrown by `add_torrent()`_ if the torrent already has been added to
4666
the session. Since `remove_torrent()`_ is asynchronous, this exception may
4667
be thrown if the torrent is removed and then immediately added again.
4668
4669
::
4670
4671
struct duplicate_torrent: std::exception
4672
{
4673
const char* what() const throw();
4674
};
4675
4676
4677
invalid_encoding
4678
----------------
4679
4680
This is thrown by ``bdecode()`` if the input data is not a valid bencoding.
4681
4682
::
4683
4684
struct invalid_encoding: std::exception
4685
{
4686
const char* what() const throw();
4687
};
4688
4689
4690
type_error
4691
----------
4692
4693
This is thrown from the accessors of ``entry`` if the data type of the ``entry`` doesn't
4694
match the type you want to extract from it.
4695
4696
::
4697
4698
struct type_error: std::runtime_error
4699
{
4700
type_error(const char* error);
4701
};
4702
4703
4704
invalid_torrent_file
5894
Many functions in libtorrent have two versions, one that throws exceptions on
5895
errors and one that takes an ``error_code`` reference which is filled with the
5896
error code on errors.
5897
5898
There is one exception class that is used for errors in libtorrent, it is based
5899
on boost.system's ``error_code`` class to carry the error code.
5900
5901
libtorrent_exception
4705
5902
--------------------
4706
5903
4707
This exception is thrown from the constructor of ``torrent_info`` if the given bencoded information
4708
doesn't meet the requirements on what information has to be present in a torrent file.
4709
4710
5904
::
4711
5905
4712
struct invalid_torrent_file: std::exception
5906
struct libtorrent_exception: std::exception
4713
5907
{
4714
const char* what() const throw();
5908
libtorrent_exception(error_code const& s);
5909
virtual const char* what() const throw();
5910
virtual ~libtorrent_exception() throw() {}
5911
boost::system::error_code error() const;
4715
5912
};
4716
5913
4717
5914
5915
error_code
5916
==========
5917
5918
libtorrent uses boost.system's ``error_code`` class to represent errors. libtorrent has
5919
its own error category (``libtorrent::libtorrent_category``) whith the following error
5920
codes:
5921
5922
====== ========================================= =================================================================
5923
code symbol description
5924
====== ========================================= =================================================================
5925
0 no_error Not an error
5926
------ ----------------------------------------- -----------------------------------------------------------------
5927
1 file_collision Two torrents has files which end up overwriting each other
5928
------ ----------------------------------------- -----------------------------------------------------------------
5929
2 failed_hash_check A piece did not match its piece hash
5930
------ ----------------------------------------- -----------------------------------------------------------------
5931
3 torrent_is_no_dict The .torrent file does not contain a bencoded dictionary at
5932
its top level
5933
------ ----------------------------------------- -----------------------------------------------------------------
5934
4 torrent_missing_info The .torrent file does not have an ``info`` dictionary
5935
------ ----------------------------------------- -----------------------------------------------------------------
5936
5 torrent_info_no_dict The .torrent file's ``info`` entry is not a dictionary
5937
------ ----------------------------------------- -----------------------------------------------------------------
5938
6 torrent_missing_piece_length The .torrent file does not have a ``piece length`` entry
5939
------ ----------------------------------------- -----------------------------------------------------------------
5940
7 torrent_missing_name The .torrent file does not have a ``name`` entry
5941
------ ----------------------------------------- -----------------------------------------------------------------
5942
8 torrent_invalid_name The .torrent file's name entry is invalid
5943
------ ----------------------------------------- -----------------------------------------------------------------
5944
9 torrent_invalid_length The length of a file, or of the whole .torrent file is invalid.
5945
Either negative or not an integer
5946
------ ----------------------------------------- -----------------------------------------------------------------
5947
10 torrent_file_parse_failed Failed to parse a file entry in the .torrent
5948
------ ----------------------------------------- -----------------------------------------------------------------
5949
11 torrent_missing_pieces The ``pieces`` field is missing or invalid in the .torrent file
5950
------ ----------------------------------------- -----------------------------------------------------------------
5951
12 torrent_invalid_hashes The ``pieces`` string has incorrect length
5952
------ ----------------------------------------- -----------------------------------------------------------------
5953
13 too_many_pieces_in_torrent The .torrent file has more pieces than is supported by libtorrent
5954
------ ----------------------------------------- -----------------------------------------------------------------
5955
14 invalid_swarm_metadata The metadata (.torrent file) that was received from the swarm
5956
matched the info-hash, but failed to be parsed
5957
------ ----------------------------------------- -----------------------------------------------------------------
5958
15 invalid_bencoding The file or buffer is not correctly bencoded
5959
------ ----------------------------------------- -----------------------------------------------------------------
5960
16 no_files_in_torrent The .torrent file does not contain any files
5961
------ ----------------------------------------- -----------------------------------------------------------------
5962
17 invalid_escaped_string The string was not properly url-encoded as expected
5963
------ ----------------------------------------- -----------------------------------------------------------------
5964
18 session_is_closing Operation is not permitted since the session is shutting down
5965
------ ----------------------------------------- -----------------------------------------------------------------
5966
19 duplicate_torrent There's already a torrent with that info-hash added to the
5967
session
5968
------ ----------------------------------------- -----------------------------------------------------------------
5969
20 invalid_torrent_handle The supplied torrent_handle is not referring to a valid torrent
5970
------ ----------------------------------------- -----------------------------------------------------------------
5971
21 invalid_entry_type The type requested from the entry did not match its type
5972
------ ----------------------------------------- -----------------------------------------------------------------
5973
22 missing_info_hash_in_uri The specified URI does not contain a valid info-hash
5974
------ ----------------------------------------- -----------------------------------------------------------------
5975
23 file_too_short One of the files in the torrent was unexpectadly small. This
5976
might be caused by files being changed by an external process
5977
------ ----------------------------------------- -----------------------------------------------------------------
5978
24 unsupported_url_protocol The URL used an unknown protocol. Currently ``http`` and
5979
``https`` (if built with openssl support) are recognized. For
5980
trackers ``udp`` is recognized as well.
5981
------ ----------------------------------------- -----------------------------------------------------------------
5982
25 url_parse_error The URL did not conform to URL syntax and failed to be parsed
5983
------ ----------------------------------------- -----------------------------------------------------------------
5984
26 peer_sent_empty_piece The peer sent a 'piece' message of length 0
5985
------ ----------------------------------------- -----------------------------------------------------------------
5986
27 parse_failed A bencoded structure was currupt and failed to be parsed
5987
------ ----------------------------------------- -----------------------------------------------------------------
5988
28 invalid_file_tag The fast resume file was missing or had an invalid file version
5989
tag
5990
------ ----------------------------------------- -----------------------------------------------------------------
5991
29 missing_info_hash The fast resume file was missing or had an invalid info-hash
5992
------ ----------------------------------------- -----------------------------------------------------------------
5993
30 mismatching_info_hash The info-hash in the resume file did not match the torrent
5994
------ ----------------------------------------- -----------------------------------------------------------------
5995
31 invalid_hostname The URL contained an invalid hostname
5996
------ ----------------------------------------- -----------------------------------------------------------------
5997
32 invalid_port The URL had an invalid port
5998
------ ----------------------------------------- -----------------------------------------------------------------
5999
33 port_blocked The port is blocked by the port-filter, and prevented the
6000
connection
6001
------ ----------------------------------------- -----------------------------------------------------------------
6002
34 expected_close_bracket_in_address The IPv6 address was expected to end with ']'
6003
------ ----------------------------------------- -----------------------------------------------------------------
6004
35 destructing_torrent The torrent is being destructed, preventing the operation to
6005
succeed
6006
------ ----------------------------------------- -----------------------------------------------------------------
6007
36 timed_out The connection timed out
6008
------ ----------------------------------------- -----------------------------------------------------------------
6009
37 upload_upload_connection The peer is upload only, and we are upload only. There's no point
6010
in keeping the connection
6011
------ ----------------------------------------- -----------------------------------------------------------------
6012
38 uninteresting_upload_peer The peer is upload only, and we're not interested in it. There's
6013
no point in keeping the connection
6014
------ ----------------------------------------- -----------------------------------------------------------------
6015
39 invalid_info_hash The peer sent an unknown info-hash
6016
------ ----------------------------------------- -----------------------------------------------------------------
6017
40 torrent_paused The torrent is paused, preventing the operation from succeeding
6018
------ ----------------------------------------- -----------------------------------------------------------------
6019
41 invalid_have The peer sent an invalid have message, either wrong size or
6020
referring to a piece that doesn't exist in the torrent
6021
------ ----------------------------------------- -----------------------------------------------------------------
6022
42 invalid_bitfield_size The bitfield message had the incorrect size
6023
------ ----------------------------------------- -----------------------------------------------------------------
6024
43 too_many_requests_when_choked The peer kept requesting pieces after it was choked, possible
6025
abuse attempt.
6026
------ ----------------------------------------- -----------------------------------------------------------------
6027
44 invalid_piece The peer sent a piece message that does not correspond to a
6028
piece request sent by the client
6029
------ ----------------------------------------- -----------------------------------------------------------------
6030
45 no_memory memory allocation failed
6031
------ ----------------------------------------- -----------------------------------------------------------------
6032
46 torrent_aborted The torrent is aborted, preventing the operation to succeed
6033
------ ----------------------------------------- -----------------------------------------------------------------
6034
47 self_connection The peer is a connection to ourself, no point in keeping it
6035
------ ----------------------------------------- -----------------------------------------------------------------
6036
48 invalid_piece_size The peer sent a piece message with invalid size, either negative
6037
or greater than one block
6038
------ ----------------------------------------- -----------------------------------------------------------------
6039
49 timed_out_no_interest The peer has not been interesting or interested in us for too
6040
long, no point in keeping it around
6041
------ ----------------------------------------- -----------------------------------------------------------------
6042
50 timed_out_inactivity The peer has not said anything in a long time, possibly dead
6043
------ ----------------------------------------- -----------------------------------------------------------------
6044
51 timed_out_no_handshake The peer did not send a handshake within a reasonable amount of
6045
time, it might not be a bittorrent peer
6046
------ ----------------------------------------- -----------------------------------------------------------------
6047
52 timed_out_no_request The peer has been unchoked for too long without requesting any
6048
data. It might be lying about its interest in us
6049
------ ----------------------------------------- -----------------------------------------------------------------
6050
53 invalid_choke The peer sent an invalid choke message
6051
------ ----------------------------------------- -----------------------------------------------------------------
6052
54 invalid_unchoke The peer send an invalid unchoke message
6053
------ ----------------------------------------- -----------------------------------------------------------------
6054
55 invalid_interested The peer sent an invalid interested message
6055
------ ----------------------------------------- -----------------------------------------------------------------
6056
56 invalid_not_interested The peer sent an invalid not-interested message
6057
------ ----------------------------------------- -----------------------------------------------------------------
6058
57 invalid_request The peer sent an invalid piece request message
6059
------ ----------------------------------------- -----------------------------------------------------------------
6060
58 invalid_hash_list The peer sent an invalid hash-list message (this is part of the
6061
merkle-torrent extension)
6062
------ ----------------------------------------- -----------------------------------------------------------------
6063
59 invalid_hash_piece The peer sent an invalid hash-piece message (this is part of the
6064
merkle-torrent extension)
6065
------ ----------------------------------------- -----------------------------------------------------------------
6066
60 invalid_cancel The peer sent an invalid cancel message
6067
------ ----------------------------------------- -----------------------------------------------------------------
6068
61 invalid_dht_port The peer sent an invalid DHT port-message
6069
------ ----------------------------------------- -----------------------------------------------------------------
6070
62 invalid_suggest The peer sent an invalid suggest piece-message
6071
------ ----------------------------------------- -----------------------------------------------------------------
6072
63 invalid_have_all The peer sent an invalid have all-message
6073
------ ----------------------------------------- -----------------------------------------------------------------
6074
64 invalid_have_none The peer sent an invalid have none-message
6075
------ ----------------------------------------- -----------------------------------------------------------------
6076
65 invalid_reject The peer sent an invalid reject message
6077
------ ----------------------------------------- -----------------------------------------------------------------
6078
66 invalid_allow_fast The peer sent an invalid allow fast-message
6079
------ ----------------------------------------- -----------------------------------------------------------------
6080
67 invalid_extended The peer sent an invalid extesion message ID
6081
------ ----------------------------------------- -----------------------------------------------------------------
6082
68 invalid_message The peer sent an invalid message ID
6083
------ ----------------------------------------- -----------------------------------------------------------------
6084
69 sync_hash_not_found The synchronization hash was not found in the encrypted handshake
6085
------ ----------------------------------------- -----------------------------------------------------------------
6086
70 invalid_encryption_constant The encryption constant in the handshake is invalid
6087
------ ----------------------------------------- -----------------------------------------------------------------
6088
71 no_plaintext_mode The peer does not support plaintext, which is the selected mode
6089
------ ----------------------------------------- -----------------------------------------------------------------
6090
72 no_rc4_mode The peer does not support rc4, which is the selected mode
6091
------ ----------------------------------------- -----------------------------------------------------------------
6092
73 unsupported_encryption_mode The peer does not support any of the encryption modes that the
6093
client supports
6094
------ ----------------------------------------- -----------------------------------------------------------------
6095
74 unsupported_encryption_mode_selected The peer selected an encryption mode that the client did not
6096
advertise and does not support
6097
------ ----------------------------------------- -----------------------------------------------------------------
6098
75 invalid_pad_size The pad size used in the encryption handshake is of invalid size
6099
------ ----------------------------------------- -----------------------------------------------------------------
6100
76 invalid_encrypt_handshake The encryption handshake is invalid
6101
------ ----------------------------------------- -----------------------------------------------------------------
6102
77 no_incoming_encrypted The client is set to not support incoming encrypted connections
6103
and this is an encrypted connection
6104
------ ----------------------------------------- -----------------------------------------------------------------
6105
78 no_incoming_regular The client is set to not support incoming regular bittorrent
6106
connections, and this is a regular connection
6107
------ ----------------------------------------- -----------------------------------------------------------------
6108
79 duplicate_peer_id The client is already connected to this peer-ID
6109
------ ----------------------------------------- -----------------------------------------------------------------
6110
80 torrent_removed Torrent was removed
6111
------ ----------------------------------------- -----------------------------------------------------------------
6112
81 packet_too_large The packet size exceeded the upper sanity check-limit
6113
------ ----------------------------------------- -----------------------------------------------------------------
6114
82 reserved
6115
------ ----------------------------------------- -----------------------------------------------------------------
6116
83 http_error The web server responded with an error
6117
------ ----------------------------------------- -----------------------------------------------------------------
6118
84 missing_location The web server response is missing a location header
6119
------ ----------------------------------------- -----------------------------------------------------------------
6120
85 invalid_redirection The web seed redirected to a path that no longer matches the
6121
.torrent directory structure
6122
------ ----------------------------------------- -----------------------------------------------------------------
6123
86 redirecting The connection was closed becaused it redirected to a different
6124
URL
6125
------ ----------------------------------------- -----------------------------------------------------------------
6126
87 invalid_range The HTTP range header is invalid
6127
------ ----------------------------------------- -----------------------------------------------------------------
6128
88 no_content_length The HTTP response did not have a content length
6129
------ ----------------------------------------- -----------------------------------------------------------------
6130
89 banned_by_ip_filter The IP is blocked by the IP filter
6131
------ ----------------------------------------- -----------------------------------------------------------------
6132
90 too_many_connections At the connection limit
6133
------ ----------------------------------------- -----------------------------------------------------------------
6134
91 peer_banned The peer is marked as banned
6135
------ ----------------------------------------- -----------------------------------------------------------------
6136
92 stopping_torrent The torrent is stopping, causing the operation to fail
6137
------ ----------------------------------------- -----------------------------------------------------------------
6138
93 too_many_corrupt_pieces The peer has sent too many corrupt pieces and is banned
6139
------ ----------------------------------------- -----------------------------------------------------------------
6140
94 torrent_not_ready The torrent is not ready to receive peers
6141
------ ----------------------------------------- -----------------------------------------------------------------
6142
95 peer_not_constructed The peer is not completely constructed yet
6143
------ ----------------------------------------- -----------------------------------------------------------------
6144
96 session_closing The session is closing, causing the operation to fail
6145
------ ----------------------------------------- -----------------------------------------------------------------
6146
97 optimistic_disconnect The peer was disconnected in order to leave room for a
6147
potentially better peer
6148
------ ----------------------------------------- -----------------------------------------------------------------
6149
98 torrent_finished The torrent is finished
6150
------ ----------------------------------------- -----------------------------------------------------------------
6151
99 no_router No UPnP router found
6152
------ ----------------------------------------- -----------------------------------------------------------------
6153
100 metadata_too_large The metadata message says the metadata exceeds the limit
6154
------ ----------------------------------------- -----------------------------------------------------------------
6155
101 invalid_metadata_request The peer sent an invalid metadata request message
6156
------ ----------------------------------------- -----------------------------------------------------------------
6157
102 invalid_metadata_size The peer advertised an invalid metadata size
6158
------ ----------------------------------------- -----------------------------------------------------------------
6159
103 invalid_metadata_offset The peer sent a message with an invalid metadata offset
6160
------ ----------------------------------------- -----------------------------------------------------------------
6161
104 invalid_metadata_message The peer sent an invalid metadata message
6162
------ ----------------------------------------- -----------------------------------------------------------------
6163
105 pex_message_too_large The peer sent a peer exchange message that was too large
6164
------ ----------------------------------------- -----------------------------------------------------------------
6165
106 invalid_pex_message The peer sent an invalid peer exchange message
6166
------ ----------------------------------------- -----------------------------------------------------------------
6167
107 invalid_lt_tracker_message The peer sent an invalid tracker exchange message
6168
====== ========================================= =================================================================
6169
6170
NAT-PMP errors:
6171
6172
====== ========================================= =================================================================
6173
code symbol description
6174
====== ========================================= =================================================================
6175
120 unsupported_protocol_version The NAT-PMP router responded with an unsupported protocol version
6176
------ ----------------------------------------- -----------------------------------------------------------------
6177
121 natpmp_not_authorized You are not authorized to map ports on this NAT-PMP router
6178
------ ----------------------------------------- -----------------------------------------------------------------
6179
122 network_failure The NAT-PMP router failed because of a network failure
6180
------ ----------------------------------------- -----------------------------------------------------------------
6181
123 no_resources The NAT-PMP router failed because of lack of resources
6182
------ ----------------------------------------- -----------------------------------------------------------------
6183
124 unsupported_opcode The NAT-PMP router failed because an unsupported opcode was sent
6184
====== ========================================= =================================================================
6185
6186
fastresume data errors:
6187
6188
====== ========================================= =================================================================
6189
code symbol description
6190
====== ========================================= =================================================================
6191
130 missing_file_sizes The resume data file is missing the 'file sizes' entry
6192
------ ----------------------------------------- -----------------------------------------------------------------
6193
131 no_files_in_resume_data The resume data file 'file sizes' entry is empty
6194
------ ----------------------------------------- -----------------------------------------------------------------
6195
132 missing_pieces The resume data file is missing the 'pieces' and 'slots' entry
6196
------ ----------------------------------------- -----------------------------------------------------------------
6197
133 mismatching_number_of_files The number of files in the resume data does not match the number
6198
of files in the torrent
6199
------ ----------------------------------------- -----------------------------------------------------------------
6200
134 mismatching_files_size One of the files on disk has a different size than in the fast
6201
resume file
6202
------ ----------------------------------------- -----------------------------------------------------------------
6203
135 mismatching_file_timestamp One of the files on disk has a different timestamp than in the
6204
fast resume file
6205
------ ----------------------------------------- -----------------------------------------------------------------
6206
136 not_a_dictionary The resume data file is not a dictionary
6207
------ ----------------------------------------- -----------------------------------------------------------------
6208
137 invalid_blocks_per_piece The 'blocks per piece' entry is invalid in the resume data file
6209
------ ----------------------------------------- -----------------------------------------------------------------
6210
138 missing_slots The resume file is missing the 'slots' entry, which is required
6211
for torrents with compact allocation
6212
------ ----------------------------------------- -----------------------------------------------------------------
6213
139 too_many_slots The resume file contains more slots than the torrent
6214
------ ----------------------------------------- -----------------------------------------------------------------
6215
140 invalid_slot_list The 'slot' entry is invalid in the resume data
6216
------ ----------------------------------------- -----------------------------------------------------------------
6217
141 invalid_piece_index One index in the 'slot' list is invalid
6218
------ ----------------------------------------- -----------------------------------------------------------------
6219
142 pieces_need_reorder The pieces on disk needs to be re-ordered for the specified
6220
allocation mode. This happens if you specify sparse allocation
6221
and the files on disk are using compact storage. The pieces needs
6222
to be moved to their right position
6223
====== ========================================= =================================================================
6224
6225
HTTP errors:
6226
6227
====== ========================================= =================================================================
6228
150 http_parse_error The HTTP header was not correctly formatted
6229
------ ----------------------------------------- -----------------------------------------------------------------
6230
151 http_missing_location The HTTP response was in the 300-399 range but lacked a location
6231
header
6232
------ ----------------------------------------- -----------------------------------------------------------------
6233
152 http_failed_decompress The HTTP response was encoded with gzip or deflate but
6234
decompressing it failed
6235
====== ========================================= =================================================================
6236
6237
The names of these error codes are declared in then ``libtorrent::errors`` namespace.
6238
6239
There is also another error category, ``libtorrent::upnp_category``, defining errors
6240
retrned by UPnP routers. Here's a (possibly incomplete) list of UPnP error codes:
6241
6242
====== ========================================= ====================================================
6243
code symbol description
6244
====== ========================================= ====================================================
6245
0 no_error No error
6246
------ ----------------------------------------- ----------------------------------------------------
6247
402 invalid_argument One of the arguments in the request is invalid
6248
------ ----------------------------------------- ----------------------------------------------------
6249
501 action_failed The request failed
6250
------ ----------------------------------------- ----------------------------------------------------
6251
714 value_not_in_array The specified value does not exist in the array
6252
------ ----------------------------------------- ----------------------------------------------------
6253
715 source_ip_cannot_be_wildcarded The source IP address cannot be wild-carded, but
6254
must be fully specified
6255
------ ----------------------------------------- ----------------------------------------------------
6256
716 external_port_cannot_be_wildcarded The external port cannot be wildcarded, but must
6257
be specified
6258
------ ----------------------------------------- ----------------------------------------------------
6259
718 port_mapping_conflict The port mapping entry specified conflicts with a
6260
mapping assigned previously to another client
6261
------ ----------------------------------------- ----------------------------------------------------
6262
724 internal_port_must_match_external Internal and external port value must be the same
6263
------ ----------------------------------------- ----------------------------------------------------
6264
725 only_permanent_leases_supported The NAT implementation only supports permanent
6265
lease times on port mappings
6266
------ ----------------------------------------- ----------------------------------------------------
6267
726 remote_host_must_be_wildcard RemoteHost must be a wildcard and cannot be a
6268
specific IP addres or DNS name
6269
------ ----------------------------------------- ----------------------------------------------------
6270
727 external_port_must_be_wildcard ExternalPort must be a wildcard and cannot be a
6271
specific port
6272
====== ========================================= ====================================================
6273
6274
The UPnP errors are declared in the ``libtorrent::upnp_errors`` namespace.
6275
6276
translating error codes
6277
-----------------------
6278
6279
The error_code::message() function will typically return a localized error string,
6280
for system errors. That is, errors that belong to the generic or system category.
6281
6282
Errors that belong to the libtorrent error category are not localized however, they
6283
are only available in english. In order to translate libtorrent errors, compare the
6284
error category of the ``error_code`` object against ``libtorrent::libtorrent_category``,
6285
and if matches, you know the error code refers to the list above. You can provide
6286
your own mapping from error code to string, which is localized. In this case, you
6287
cannot rely on ``error_code::message()`` to generate your strings.
6288
6289
The numeric values of the errors are part of the API and will stay the same, although
6290
new error codes may be appended at the end.
6291
6292
Here's a simple example of how to translate error codes::
6293
6294
std::string error_code_to_string(boost::system::error_code const& ec)
6295
{
6296
if (ec.category() != libtorrent::libtorrent_category)
6297
{
6298
return ec.message();
6299
}
6300
// the error is a libtorrent error
6301
6302
int code = ec.value();
6303
static const char const* swedish[] =
6304
{
6305
"inget fel",
6306
"en fil i torrenten kolliderar med en fil fr�n en annan torrent",
6307
"hash check misslyckades",
6308
"torrent filen �r inte en dictionary",
6309
"'info'-nyckeln saknas eller �r korrupt i torrentfilen",
6310
"'info'-f�ltet �r inte en dictionary",
6311
"'piece length' f�ltet saknas eller �r korrupt i torrentfilen",
6312
"torrentfilen saknar namnf�ltet",
6313
"ogiltigt namn i torrentfilen (kan vara en attack)",
6314
// ... more strings here
6315
};
6316
6317
// use the default error string in case we don't have it
6318
// in our translated list
6319
if (code < 0 || code >= sizeof(swedish)/sizeof(swedish[0]))
6320
return ec.message();
6321
6322
return swedish[code];
6323
}
6324
4718
6325
storage_interface
4719
6326
=================
4720
6327
4739
6346
4740
6347
The interface looks like this::
4741
6348
4742
4743
6349
struct storage_interface
4744
6350
{
4745
6351
virtual bool initialize(bool allocate_files) = 0;
4746
6352
virtual bool has_any_file() = 0;
4747
virtual int read(char* buf, int slot, int offset, int size) = 0;
4748
virtual int write(const char* buf, int slot, int offset, int size) = 0;
6353
virtual int readv(file::iovec_t const* bufs, int slot, int offset, int num_bufs) = 0;
6354
virtual int writev(file::iovec_t const* bufs, int slot, int offset, int num_bufs) = 0;
6355
virtual int sparse_end(int start) const;
4749
6356
virtual bool move_storage(fs::path save_path) = 0;
4750
virtual bool verify_resume_data(lazy_entry const& rd, std::string& error) = 0;
6357
virtual bool verify_resume_data(lazy_entry const& rd, error_code& error) = 0;
4751
6358
virtual bool write_resume_data(entry& rd) const = 0;
4752
6359
virtual bool move_slot(int src_slot, int dst_slot) = 0;
4753
6360
virtual bool swap_slots(int slot1, int slot2) = 0;
4754
6361
virtual bool swap_slots3(int slot1, int slot2, int slot3) = 0;
4755
virtual sha1_hash hash_for_slot(int slot, partial_hash& h, int piece_size) = 0;
4756
6362
virtual bool rename_file(int file, std::string const& new_name) = 0;
4757
6363
virtual bool release_files() = 0;
4758
6364
virtual bool delete_files() = 0;
4759
6365
virtual ~storage_interface() {}
6366
6367
// non virtual functions
6368
6369
disk_buffer_pool* disk_pool();
6370
void set_error(boost::filesystem::path const& file, error_code const& ec) const;
6371
error_code const& error() const;
6372
std::string const& error_file() const;
6373
void clear_error();
4760
6374
};
4761
6375
4762
6376
4784
6398
It should return true if any of the files that is used in this storage exists on disk.
4785
6399
If so, the storage will be checked for existing pieces before starting the download.
4786
6400
4787
read()
4788
------
4789
4790
::
4791
4792
int read(char* buf, int slot, int offset, int size) = 0;
4793
4794
This function should read the data in the given slot and at the given offset
4795
and ``size`` number of bytes. The data is to be copied to ``buf``.
4796
4797
The return value is the number of bytes actually read.
4798
4799
4800
write()
4801
-------
4802
4803
::
4804
6401
readv() writev()
6402
----------------
6403
6404
::
6405
6406
int readv(file::iovec_t const* buf, int slot, int offset, int num_bufs) = 0;
4805
6407
int write(const char* buf, int slot, int offset, int size) = 0;
4806
6408
4807
This function should write the data in ``buf`` to the given slot (``slot``) at offset
4808
``offset`` in that slot. The buffer size is ``size``.
4809
4810
The return value is the number of bytes actually written.
4811
6409
These functions should read or write the data in or to the given ``slot`` at the given ``offset``.
6410
It should read or write ``num_bufs`` buffers sequentially, where the size of each buffer
6411
is specified in the buffer array ``bufs``. The file::iovec_t type has the following members::
6412
6413
struct iovec_t
6414
{
6415
void* iov_base;
6416
size_t iov_len;
6417
};
6418
6419
The return value is the number of bytes actually read or written, or -1 on failure. If
6420
it returns -1, the error code is expected to be set to
6421
6422
Every buffer in ``bufs`` can be assumed to be page aligned and be of a page aligned size,
6423
except for the last buffer of the torrent. The allocated buffer can be assumed to fit a
6424
fully page aligned number of bytes though. This is useful when reading and writing the
6425
last piece of a file in unbuffered mode.
6426
6427
The ``offset`` is aligned to 16 kiB boundries *most of the time*, but there are rare
6428
exceptions when it's not. Specifically if the read cache is disabled/or full and a
6429
client requests unaligned data, or the file itself is not aligned in the torrent.
6430
Most clients request aligned data.
6431
6432
sparse_end()
6433
------------
6434
6435
::
6436
6437
int sparse_end(int start) const;
6438
6439
This function is optional. It is supposed to return the first piece, starting at
6440
``start`` that is fully contained within a data-region on disk (i.e. non-sparse
6441
region). The purpose of this is to skip parts of files that can be known to contain
6442
zeros when checking files.
4812
6443
4813
6444
move_storage()
4814
6445
--------------
4831
6462
4832
6463
::
4833
6464
4834
bool verify_resume_data(lazy_entry const& rd, std::string& error) = 0;
6465
bool verify_resume_data(lazy_entry const& rd, error_code& error) = 0;
4835
6466
4836
6467
This function should verify the resume data ``rd`` with the files
4837
6468
on disk. If the resume data seems to be up-to-date, return true. If
4904
6535
Returning ``true`` indicates an error occurred.
4905
6536
4906
6537
4907
hash_for_slot()
4908
---------------
4909
4910
::
4911
4912
sha1_hash hash_for_slot(int slot, partial_hash& h, int piece_size) = 0;
4913
4914
The function should read the remaining bytes of the slot and hash it with the
4915
sha-1 state in ``partion_hash``. The ``partial_hash`` struct looks like this::
4916
4917
struct partial_hash
4918
{
4919
partial_hash();
4920
int offset;
4921
hasher h;
4922
};
4923
4924
``offset`` is the number of bytes in the slot that has already been hashed, and
4925
``h`` is the sha-1 state of that hash. ``piece_size`` is the size of the piece
4926
that is stored in the given slot.
4927
4928
The function should return the hash of the piece stored in the slot.
4929
4930
6538
rename_file()
4931
6539
-------------
4932
6540
4963
6571
4964
6572
Returning ``true`` indicates an error occurred.
4965
6573
6574
The ``disk_buffer_pool`` is used to allocate and free disk buffers. It has the
6575
following members::
6576
6577
struct disk_buffer_pool : boost::noncopyable
6578
{
6579
char* allocate_buffer(char const* category);
6580
void free_buffer(char* buf);
6581
6582
char* allocate_buffers(int blocks, char const* category);
6583
void free_buffers(char* buf, int blocks);
6584
6585
int block_size() const { return m_block_size; }
6586
6587
void release_memory();
6588
};
6589
4966
6590
4967
6591
magnet links
4968
6592
============
5056
6680
5057
6681
The file format is a bencoded dictionary containing the following fields:
5058
6682
5059
+----------------------+--------------------------------------------------------------+
5060
| ``file-format`` | string: "libtorrent resume file" |
5061
| | |
5062
+----------------------+--------------------------------------------------------------+
5063
| ``file-version`` | integer: 1 |
5064
| | |
5065
+----------------------+--------------------------------------------------------------+
5066
| ``info-hash`` | string, the info hash of the torrent this data is saved for. |
5067
| | |
5068
+----------------------+--------------------------------------------------------------+
5069
| ``blocks per piece`` | integer, the number of blocks per piece. Must be: piece_size |
5070
| | / (16 * 1024). Clamped to be within the range [1, 256]. It |
5071
| | is the number of blocks per (normal sized) piece. Usually |
5072
| | each block is 16 * 1024 bytes in size. But if piece size is |
5073
| | greater than 4 megabytes, the block size will increase. |
5074
| | |
5075
+----------------------+--------------------------------------------------------------+
5076
| ``pieces`` | A string with piece flags, one character per piece. |
5077
| | Bit 1 means we have that piece. |
5078
+----------------------+--------------------------------------------------------------+
5079
| ``slots`` | list of integers. The list maps slots to piece indices. It |
5080
| | tells which piece is on which slot. If piece index is -2 it |
5081
| | means it is free, that there's no piece there. If it is -1, |
5082
| | means the slot isn't allocated on disk yet. The pieces have |
5083
| | to meet the following requirement: |
5084
| | |
5085
| | If there's a slot at the position of the piece index, |
5086
| | the piece must be located in that slot. |
5087
| | |
5088
+----------------------+--------------------------------------------------------------+
5089
| ``peers`` | list of dictionaries. Each dictionary has the following |
5090
| | layout: |
5091
| | |
5092
| | +----------+-----------------------------------------------+ |
5093
| | | ``ip`` | string, the ip address of the peer. This is | |
5094
| | | | not a binary representation of the ip | |
5095
| | | | address, but the string representation. It | |
5096
| | | | may be an IPv6 string or an IPv4 string. | |
5097
| | +----------+-----------------------------------------------+ |
5098
| | | ``port`` | integer, the listen port of the peer | |
5099
| | +----------+-----------------------------------------------+ |
5100
| | |
5101
| | These are the local peers we were connected to when this |
5102
| | fast-resume data was saved. |
5103
| | |
5104
+----------------------+--------------------------------------------------------------+
5105
| ``unfinished`` | list of dictionaries. Each dictionary represents an |
5106
| | piece, and has the following layout: |
5107
| | |
5108
| | +-------------+--------------------------------------------+ |
5109
| | | ``piece`` | integer, the index of the piece this entry | |
5110
| | | | refers to. | |
5111
| | +-------------+--------------------------------------------+ |
5112
| | | ``bitmask`` | string, a binary bitmask representing the | |
5113
| | | | blocks that have been downloaded in this | |
5114
| | | | piece. | |
5115
| | +-------------+--------------------------------------------+ |
5116
| | | ``adler32`` | The adler32 checksum of the data in the | |
5117
| | | | blocks specified by ``bitmask``. | |
5118
| | | | | |
5119
| | +-------------+--------------------------------------------+ |
5120
| | |
5121
+----------------------+--------------------------------------------------------------+
5122
| ``file sizes`` | list where each entry corresponds to a file in the file list |
5123
| | in the metadata. Each entry has a list of two values, the |
5124
| | first value is the size of the file in bytes, the second |
5125
| | is the time stamp when the last time someone wrote to it. |
5126
| | This information is used to compare with the files on disk. |
5127
| | All the files must match exactly this information in order |
5128
| | to consider the resume data as current. Otherwise a full |
5129
| | re-check is issued. |
5130
+----------------------+--------------------------------------------------------------+
5131
| ``allocation`` | The allocation mode for the storage. Can be either ``full`` |
5132
| | or ``compact``. If this is full, the file sizes and |
5133
| | timestamps are disregarded. Pieces are assumed not to have |
5134
| | moved around even if the files have been modified after the |
5135
| | last resume data checkpoint. |
5136
+----------------------+--------------------------------------------------------------+
6683
+--------------------------+--------------------------------------------------------------+
6684
| ``file-format`` | string: "libtorrent resume file" |
6685
| | |
6686
+--------------------------+--------------------------------------------------------------+
6687
| ``file-version`` | integer: 1 |
6688
| | |
6689
+--------------------------+--------------------------------------------------------------+
6690
| ``info-hash`` | string, the info hash of the torrent this data is saved for. |
6691
| | |
6692
+--------------------------+--------------------------------------------------------------+
6693
| ``blocks per piece`` | integer, the number of blocks per piece. Must be: piece_size |
6694
| | / (16 * 1024). Clamped to be within the range [1, 256]. It |
6695
| | is the number of blocks per (normal sized) piece. Usually |
6696
| | each block is 16 * 1024 bytes in size. But if piece size is |
6697
| | greater than 4 megabytes, the block size will increase. |
6698
| | |
6699
+--------------------------+--------------------------------------------------------------+
6700
| ``pieces`` | A string with piece flags, one character per piece. |
6701
| | Bit 1 means we have that piece. |
6702
| | Bit 2 means we have verified that this piece is correct. |
6703
| | This only applies when the torrent is in seed_mode. |
6704
+--------------------------+--------------------------------------------------------------+
6705
| ``slots`` | list of integers. The list maps slots to piece indices. It |
6706
| | tells which piece is on which slot. If piece index is -2 it |
6707
| | means it is free, that there's no piece there. If it is -1, |
6708
| | means the slot isn't allocated on disk yet. The pieces have |
6709
| | to meet the following requirement: |
6710
| | |
6711
| | If there's a slot at the position of the piece index, |
6712
| | the piece must be located in that slot. |
6713
| | |
6714
+--------------------------+--------------------------------------------------------------+
6715
| ``total_uploaded`` | integer. The number of bytes that have been uploaded in |
6716
| | total for this torrent. |
6717
+--------------------------+--------------------------------------------------------------+
6718
| ``total_downloaded`` | integer. The number of bytes that have been downloaded in |
6719
| | total for this torrent. |
6720
+--------------------------+--------------------------------------------------------------+
6721
| ``active_time`` | integer. The number of seconds this torrent has been active. |
6722
| | i.e. not paused. |
6723
+--------------------------+--------------------------------------------------------------+
6724
| ``seeding_time`` | integer. The number of seconds this torrent has been active |
6725
| | and seeding. |
6726
+--------------------------+--------------------------------------------------------------+
6727
| ``num_seeds`` | integer. An estimate of the number of seeds on this torrent |
6728
| | when the resume data was saved. This is scrape data or based |
6729
| | on the peer list if scrape data is unavailable. |
6730
+--------------------------+--------------------------------------------------------------+
6731
| ``num_downloaders`` | integer. An estimate of the number of downloaders on this |
6732
| | torrent when the resume data was last saved. This is used as |
6733
| | an initial estimate until we acquire up-to-date scrape info. |
6734
+--------------------------+--------------------------------------------------------------+
6735
| ``upload_rate_limit`` | integer. In case this torrent has a per-torrent upload rate |
6736
| | limit, this is that limit. In bytes per second. |
6737
+--------------------------+--------------------------------------------------------------+
6738
| ``download_rate_limit`` | integer. The download rate limit for this torrent in case |
6739
| | one is set, in bytes per second. |
6740
+--------------------------+--------------------------------------------------------------+
6741
| ``max_connections`` | integer. The max number of peer connections this torrent |
6742
| | may have, if a limit is set. |
6743
+--------------------------+--------------------------------------------------------------+
6744
| ``max_uploads`` | integer. The max number of unchoked peers this torrent may |
6745
| | have, if a limit is set. |
6746
+--------------------------+--------------------------------------------------------------+
6747
| ``seed_mode`` | integer. 1 if the torrent is in seed mode, 0 otherwise. |
6748
+--------------------------+--------------------------------------------------------------+
6749
| ``file_priority`` | list of integers. One entry per file in the torrent. Each |
6750
| | entry is the priority of the file with the same index. |
6751
+--------------------------+--------------------------------------------------------------+
6752
| ``piece_priority`` | string of bytes. Each byte is interpreted as an integer and |
6753
| | is the priority of that piece. |
6754
+--------------------------+--------------------------------------------------------------+
6755
| ``auto_managed`` | integer. 1 if the torrent is auto managed, otherwise 0. |
6756
+--------------------------+--------------------------------------------------------------+
6757
| ``sequential_download`` | integer. 1 if the torrent is in sequential download mode, |
6758
| | 0 otherwise. |
6759
+--------------------------+--------------------------------------------------------------+
6760
| ``paused`` | integer. 1 if the torrent is paused, 0 otherwise. |
6761
+--------------------------+--------------------------------------------------------------+
6762
| ``trackers`` | list of lists of strings. The top level list lists all |
6763
| | tracker tiers. Each second level list is one tier of |
6764
| | trackers. |
6765
+--------------------------+--------------------------------------------------------------+
6766
| ``mapped_files`` | list of strings. If any file in the torrent has been |
6767
| | renamed, this entry contains a list of all the filenames. |
6768
| | In the same order as in the torrent file. |
6769
+--------------------------+--------------------------------------------------------------+
6770
| ``url-list`` | list of strings. List of url-seed URLs used by this torrent. |
6771
| | The urls are expected to be properly encoded and not contain |
6772
| | any illegal url characters. |
6773
+--------------------------+--------------------------------------------------------------+
6774
| ``httpseeds`` | list of strings. List of httpseed URLs used by this torrent. |
6775
| | The urls are expected to be properly encoded and not contain |
6776
| | any illegal url characters. |
6777
+--------------------------+--------------------------------------------------------------+
6778
| ``merkle tree`` | string. In case this torrent is a merkle torrent, this is a |
6779
| | string containing the entire merkle tree, all nodes, |
6780
| | including the root and all leaves. The tree is not |
6781
| | necessarily complete, but complete enough to be able to send |
6782
| | any piece that we have, indicated by the have bitmask. |
6783
+--------------------------+--------------------------------------------------------------+
6784
| ``peers`` | list of dictionaries. Each dictionary has the following |
6785
| | layout: |
6786
| | |
6787
| | +----------+-----------------------------------------------+ |
6788
| | | ``ip`` | string, the ip address of the peer. This is | |
6789
| | | | not a binary representation of the ip | |
6790
| | | | address, but the string representation. It | |
6791
| | | | may be an IPv6 string or an IPv4 string. | |
6792
| | +----------+-----------------------------------------------+ |
6793
| | | ``port`` | integer, the listen port of the peer | |
6794
| | +----------+-----------------------------------------------+ |
6795
| | |
6796
| | These are the local peers we were connected to when this |
6797
| | fast-resume data was saved. |
6798
| | |
6799
+--------------------------+--------------------------------------------------------------+
6800
| ``unfinished`` | list of dictionaries. Each dictionary represents an |
6801
| | piece, and has the following layout: |
6802
| | |
6803
| | +-------------+--------------------------------------------+ |
6804
| | | ``piece`` | integer, the index of the piece this entry | |
6805
| | | | refers to. | |
6806
| | +-------------+--------------------------------------------+ |
6807
| | | ``bitmask`` | string, a binary bitmask representing the | |
6808
| | | | blocks that have been downloaded in this | |
6809
| | | | piece. | |
6810
| | +-------------+--------------------------------------------+ |
6811
| | | ``adler32`` | The adler32 checksum of the data in the | |
6812
| | | | blocks specified by ``bitmask``. | |
6813
| | | | | |
6814
| | +-------------+--------------------------------------------+ |
6815
| | |
6816
+--------------------------+--------------------------------------------------------------+
6817
| ``file sizes`` | list where each entry corresponds to a file in the file list |
6818
| | in the metadata. Each entry has a list of two values, the |
6819
| | first value is the size of the file in bytes, the second |
6820
| | is the time stamp when the last time someone wrote to it. |
6821
| | This information is used to compare with the files on disk. |
6822
| | All the files must match exactly this information in order |
6823
| | to consider the resume data as current. Otherwise a full |
6824
| | re-check is issued. |
6825
+--------------------------+--------------------------------------------------------------+
6826
| ``allocation`` | The allocation mode for the storage. Can be either ``full`` |
6827
| | or ``compact``. If this is full, the file sizes and |
6828
| | timestamps are disregarded. Pieces are assumed not to have |
6829
| | moved around even if the files have been modified after the |
6830
| | last resume data checkpoint. |
6831
+--------------------------+--------------------------------------------------------------+
5137
6832
5138
6833
threads
5139
6834
=======
5173
6868
argument to ``session::add_torrent()`` (see `add_torrent()`_).
5174
6869
5175
6870
The decision to use full allocation or compact allocation typically depends on whether
5176
any files are filtered and if the filesystem supports sparse files.
6871
any files have priority 0 and if the filesystem supports sparse files.
5177
6872
5178
6873
sparse allocation
5179
6874
-----------------
5219
6914
* The fast resume data will be more likely to be usable, regardless of crashes or
5220
6915
out of date data, since pieces won't move around.
5221
6916
5222
* Can be used with the filter files feature.
6917
* Can be used with prioritizing files to 0.
5223
6918
5224
6919
compact allocation
5225
6920
------------------
5233
6928
5234
6929
* Potentially more fragmentation in the filesystem.
5235
6930
5236
* Cannot be used while filtering files.
6931
* Cannot be used while having files with priority 0.
5237
6932
5238
6933
The benefits though, are:
5239
6934
5365
7060
HTTP seeding
5366
7061
------------
5367
7062
5368
The HTTP seed extension implements `this specification`__.
5369
5370
The libtorrent implementation assumes that, if the URL ends with a slash
7063
There are two kinds of HTTP seeding. One with that assumes a smart
7064
(and polite) client and one that assumes a smart server. These
7065
are specified in `BEP 19`_ and `BEP 17`_ respectively.
7066
7067
libtorrent supports both. In the libtorrent source code and API,
7068
BEP 19 urls are typically referred to as *url seeds* and BEP 17
7069
urls are typically referred to as *HTTP seeds*.
7070
7071
The libtorrent implementation of `BEP 19`_ assumes that, if the URL ends with a slash
5371
7072
('/'), the filename should be appended to it in order to request pieces from
5372
7073
that file. The way this works is that if the torrent is a single-file torrent,
5373
7074
only that filename is appended. If the torrent is a multi-file torrent, the
5374
7075
torrent's name '/' the file name is appended. This is the same directory
5375
7076
structure that libtorrent will download torrents into.
5376
7077
5377
__ http://www.getright.com/seedtorrent.html
5378
7078
.. _`BEP 17`: http://bittorrent.org/beps/bep_0017.html
7079
.. _`BEP 19`: http://bittorrent.org/beps/bep_0019.html
5379
7080
5380
7081
filename checks
5381
7082
===============
5391
7092
5392
7093
__ http://www.boost.org/libs/filesystem/doc/index.htm
5393
7094
5394
5395
acknowledgments
5396
===============
5397
5398
Written by Arvid Norberg. Copyright |copy| 2003-2006
5399
5400
Contributions by Magnus Jonsson, Daniel Wallin and Cory Nelson
5401
5402
Lots of testing, suggestions and contributions by Massaroddel and Tianhao Qiu.
5403
5404
Big thanks to Michael Wojciechowski and Peter Koeleman for making the autotools
5405
scripts.
5406
5407
Thanks to Reimond Retz for bugfixes, suggestions and testing
5408
5409
Thanks to `University of Ume�`__ for providing development and test hardware.
5410
5411
Project is hosted by sourceforge.
5412
5413
.. raw: html
5414
5415
<a href="http://sourceforge.net"><img src="http://sourceforge.net/sflogo.php?group_id=7994"/></a>
5416
5417
.. |copy| unicode:: 0xA9 .. copyright sign
5418
__ http://www.cs.umu.se
5419
Loggerhead is a web-based interface for Breezy
Version: 2.0.1