jiigen666/libtorrent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

first version with DHT support. Limited pipelining used by url-seeds. Fixed one configuration problem on FreeBSD.

Browse Source
This commit is contained in:
Arvid Norberg
2006-08-01 15:27:08 +00:00
parent f1548fd668
commit 5ef57265bf
52 changed files with 5211 additions and 212 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/index.html
View File

@@ -12,11 +12,12 @@
<h1 class="title">libtorrent</h1>
<table border="1" class="menu docutils">
<colgroup>
<col width="26%" />
<col width="19%" />
<col width="19%" />
<col width="14%" />
<col width="14%" />
<col width="11%" />
<col width="15%" />
<col width="21%" />
<col width="26%" />
</colgroup>
<tbody valign="top">
<tr><td><a class="reference" href="http://www.sourceforge.net/projects/libtorrent">sourceforge page</a></td>
@@ -24,6 +25,7 @@
<td><a class="reference" href="http://sourceforge.net/tracker/?group_id=79942&amp;atid=558250">report bugs</a></td>
<td><a class="reference" href="client_test.png">screenshot</a></td>
<td><a class="reference" href="http://lists.sourceforge.net/lists/listinfo/libtorrent-discuss">mailing list</a></td>
<td><a class="reference" href="projects.html">who's using libtorrent?</a></td>
</tr>
</tbody>
</table>

7
docs/index.rst
View File

@@ -5,15 +5,16 @@ libtorrent
.. class:: menu
=================== ============== ============== =========== ===============
`sourceforge page`_ documentation_ `report bugs`_ screenshot_ `mailing list`_
=================== ============== ============== =========== ===============
=================== ============== ============== =========== =============== ==========================
`sourceforge page`_ documentation_ `report bugs`_ screenshot_ `mailing list`_ `who's using libtorrent?`_
=================== ============== ============== =========== =============== ==========================
.. _sourceforge page: http://www.sourceforge.net/projects/libtorrent
.. _documentation: manual.html
.. _`report bugs`: http://sourceforge.net/tracker/?group_id=79942&atid=558250
.. _screenshot: client_test.png
.. _mailing list: http://lists.sourceforge.net/lists/listinfo/libtorrent-discuss
.. _`who's using libtorrent?`: projects.html
libtorrent is a C++ library that aims to be a good alternative to all the
other bittorrent implementations around. It is a

318
docs/manual.html
View File

@@ -46,127 +46,131 @@
<li><a class="reference" href="#status" id="id43" name="id43">status()</a></li>
<li><a class="reference" href="#is-listening-listen-port-listen-on" id="id44" name="id44">is_listening() listen_port() listen_on()</a></li>
<li><a class="reference" href="#pop-alert-set-severity-level" id="id45" name="id45">pop_alert() set_severity_level()</a></li>
<li><a class="reference" href="#start-dht-stop-dht-set-dht-settings-dht-state" id="id46" name="id46">start_dht() stop_dht() set_dht_settings() dht_state()</a></li>
</ul>
</li>
<li><a class="reference" href="#entry" id="id46" name="id46">entry</a><ul>
<li><a class="reference" href="#integer-string-list-dict-type" id="id47" name="id47">integer() string() list() dict() type()</a></li>
<li><a class="reference" href="#operator" id="id48" name="id48">operator[]</a></li>
<li><a class="reference" href="#find-key" id="id49" name="id49">find_key()</a></li>
<li><a class="reference" href="#entry" id="id47" name="id47">entry</a><ul>
<li><a class="reference" href="#integer-string-list-dict-type" id="id48" name="id48">integer() string() list() dict() type()</a></li>
<li><a class="reference" href="#operator" id="id49" name="id49">operator[]</a></li>
<li><a class="reference" href="#find-key" id="id50" name="id50">find_key()</a></li>
</ul>
</li>
<li><a class="reference" href="#torrent-info" id="id50" name="id50">torrent_info</a><ul>
<li><a class="reference" href="#id12" id="id51" name="id51">torrent_info()</a></li>
<li><a class="reference" href="#set-comment-set-piece-size-set-creator-set-hash-add-tracker-add-file" id="id52" name="id52">set_comment() set_piece_size() set_creator() set_hash() add_tracker() add_file()</a></li>
<li><a class="reference" href="#create-torrent" id="id53" name="id53">create_torrent()</a></li>
<li><a class="reference" href="#begin-files-end-files-rbegin-files-rend-files" id="id54" name="id54">begin_files() end_files() rbegin_files() rend_files()</a></li>
<li><a class="reference" href="#num-files-file-at" id="id55" name="id55">num_files() file_at()</a></li>
<li><a class="reference" href="#map-block" id="id56" name="id56">map_block()</a></li>
<li><a class="reference" href="#map-file" id="id57" name="id57">map_file()</a></li>
<li><a class="reference" href="#url-seeds" id="id58" name="id58">url_seeds()</a></li>
<li><a class="reference" href="#print" id="id59" name="id59">print()</a></li>
<li><a class="reference" href="#trackers" id="id60" name="id60">trackers()</a></li>
<li><a class="reference" href="#total-size-piece-length-piece-size-num-pieces" id="id61" name="id61">total_size() piece_length() piece_size() num_pieces()</a></li>
<li><a class="reference" href="#hash-for-piece-info-hash" id="id62" name="id62">hash_for_piece() info_hash()</a></li>
<li><a class="reference" href="#name-comment-creation-date-creator" id="id63" name="id63">name() comment() creation_date() creator()</a></li>
<li><a class="reference" href="#torrent-info" id="id51" name="id51">torrent_info</a><ul>
<li><a class="reference" href="#id12" id="id52" name="id52">torrent_info()</a></li>
<li><a class="reference" href="#set-comment-set-piece-size-set-creator-set-hash-add-tracker-add-file" id="id53" name="id53">set_comment() set_piece_size() set_creator() set_hash() add_tracker() add_file()</a></li>
<li><a class="reference" href="#create-torrent" id="id54" name="id54">create_torrent()</a></li>
<li><a class="reference" href="#begin-files-end-files-rbegin-files-rend-files" id="id55" name="id55">begin_files() end_files() rbegin_files() rend_files()</a></li>
<li><a class="reference" href="#num-files-file-at" id="id56" name="id56">num_files() file_at()</a></li>
<li><a class="reference" href="#map-block" id="id57" name="id57">map_block()</a></li>
<li><a class="reference" href="#map-file" id="id58" name="id58">map_file()</a></li>
<li><a class="reference" href="#url-seeds" id="id59" name="id59">url_seeds()</a></li>
<li><a class="reference" href="#print" id="id60" name="id60">print()</a></li>
<li><a class="reference" href="#trackers" id="id61" name="id61">trackers()</a></li>
<li><a class="reference" href="#total-size-piece-length-piece-size-num-pieces" id="id62" name="id62">total_size() piece_length() piece_size() num_pieces()</a></li>
<li><a class="reference" href="#hash-for-piece-info-hash" id="id63" name="id63">hash_for_piece() info_hash()</a></li>
<li><a class="reference" href="#name-comment-creation-date-creator" id="id64" name="id64">name() comment() creation_date() creator()</a></li>
<li><a class="reference" href="#priv-set-priv" id="id65" name="id65">priv() set_priv()</a></li>
<li><a class="reference" href="#nodes" id="id66" name="id66">nodes()</a></li>
<li><a class="reference" href="#add-node" id="id67" name="id67">add_node()</a></li>
</ul>
</li>
<li><a class="reference" href="#torrent-handle" id="id64" name="id64">torrent_handle</a><ul>
<li><a class="reference" href="#file-progress" id="id65" name="id65">file_progress()</a></li>
<li><a class="reference" href="#save-path" id="id66" name="id66">save_path()</a></li>
<li><a class="reference" href="#move-storage" id="id67" name="id67">move_storage()</a></li>
<li><a class="reference" href="#force-reannounce" id="id68" name="id68">force_reannounce()</a></li>
<li><a class="reference" href="#connect-peer" id="id69" name="id69">connect_peer()</a></li>
<li><a class="reference" href="#set-ratio" id="id70" name="id70">set_ratio()</a></li>
<li><a class="reference" href="#set-upload-limit-set-download-limit" id="id71" name="id71">set_upload_limit() set_download_limit()</a></li>
<li><a class="reference" href="#set-peer-upload-limit-set-peer-download-limit" id="id72" name="id72">set_peer_upload_limit() set_peer_download_limit()</a></li>
<li><a class="reference" href="#pause-resume-is-paused" id="id73" name="id73">pause() resume() is_paused()</a></li>
<li><a class="reference" href="#is-seed" id="id74" name="id74">is_seed()</a></li>
<li><a class="reference" href="#has-metadata" id="id75" name="id75">has_metadata()</a></li>
<li><a class="reference" href="#set-tracker-login" id="id76" name="id76">set_tracker_login()</a></li>
<li><a class="reference" href="#trackers-replace-trackers" id="id77" name="id77">trackers() replace_trackers()</a></li>
<li><a class="reference" href="#add-url-seed" id="id78" name="id78">add_url_seed()</a></li>
<li><a class="reference" href="#use-interface" id="id79" name="id79">use_interface()</a></li>
<li><a class="reference" href="#info-hash" id="id80" name="id80">info_hash()</a></li>
<li><a class="reference" href="#id14" id="id81" name="id81">set_max_uploads() set_max_connections()</a></li>
<li><a class="reference" href="#write-resume-data" id="id82" name="id82">write_resume_data()</a></li>
<li><a class="reference" href="#metadata" id="id83" name="id83">metadata()</a></li>
<li><a class="reference" href="#id15" id="id84" name="id84">status()</a></li>
<li><a class="reference" href="#get-download-queue" id="id85" name="id85">get_download_queue()</a></li>
<li><a class="reference" href="#get-peer-info" id="id86" name="id86">get_peer_info()</a></li>
<li><a class="reference" href="#get-torrent-info" id="id87" name="id87">get_torrent_info()</a></li>
<li><a class="reference" href="#is-valid" id="id88" name="id88">is_valid()</a></li>
<li><a class="reference" href="#torrent-handle" id="id68" name="id68">torrent_handle</a><ul>
<li><a class="reference" href="#file-progress" id="id69" name="id69">file_progress()</a></li>
<li><a class="reference" href="#save-path" id="id70" name="id70">save_path()</a></li>
<li><a class="reference" href="#move-storage" id="id71" name="id71">move_storage()</a></li>
<li><a class="reference" href="#force-reannounce" id="id72" name="id72">force_reannounce()</a></li>
<li><a class="reference" href="#connect-peer" id="id73" name="id73">connect_peer()</a></li>
<li><a class="reference" href="#set-ratio" id="id74" name="id74">set_ratio()</a></li>
<li><a class="reference" href="#set-upload-limit-set-download-limit" id="id75" name="id75">set_upload_limit() set_download_limit()</a></li>
<li><a class="reference" href="#set-peer-upload-limit-set-peer-download-limit" id="id76" name="id76">set_peer_upload_limit() set_peer_download_limit()</a></li>
<li><a class="reference" href="#pause-resume-is-paused" id="id77" name="id77">pause() resume() is_paused()</a></li>
<li><a class="reference" href="#is-seed" id="id78" name="id78">is_seed()</a></li>
<li><a class="reference" href="#has-metadata" id="id79" name="id79">has_metadata()</a></li>
<li><a class="reference" href="#set-tracker-login" id="id80" name="id80">set_tracker_login()</a></li>
<li><a class="reference" href="#trackers-replace-trackers" id="id81" name="id81">trackers() replace_trackers()</a></li>
<li><a class="reference" href="#add-url-seed" id="id82" name="id82">add_url_seed()</a></li>
<li><a class="reference" href="#use-interface" id="id83" name="id83">use_interface()</a></li>
<li><a class="reference" href="#info-hash" id="id84" name="id84">info_hash()</a></li>
<li><a class="reference" href="#id14" id="id85" name="id85">set_max_uploads() set_max_connections()</a></li>
<li><a class="reference" href="#write-resume-data" id="id86" name="id86">write_resume_data()</a></li>
<li><a class="reference" href="#metadata" id="id87" name="id87">metadata()</a></li>
<li><a class="reference" href="#id15" id="id88" name="id88">status()</a></li>
<li><a class="reference" href="#get-download-queue" id="id89" name="id89">get_download_queue()</a></li>
<li><a class="reference" href="#get-peer-info" id="id90" name="id90">get_peer_info()</a></li>
<li><a class="reference" href="#get-torrent-info" id="id91" name="id91">get_torrent_info()</a></li>
<li><a class="reference" href="#is-valid" id="id92" name="id92">is_valid()</a></li>
</ul>
</li>
<li><a class="reference" href="#torrent-status" id="id89" name="id89">torrent_status</a></li>
<li><a class="reference" href="#peer-info" id="id90" name="id90">peer_info</a></li>
<li><a class="reference" href="#session-settings" id="id91" name="id91">session_settings</a></li>
<li><a class="reference" href="#ip-filter" id="id92" name="id92">ip_filter</a><ul>
<li><a class="reference" href="#id18" id="id93" name="id93">ip_filter()</a></li>
<li><a class="reference" href="#add-rule" id="id94" name="id94">add_rule()</a></li>
<li><a class="reference" href="#access" id="id95" name="id95">access()</a></li>
<li><a class="reference" href="#export-filter" id="id96" name="id96">export_filter()</a></li>
<li><a class="reference" href="#torrent-status" id="id93" name="id93">torrent_status</a></li>
<li><a class="reference" href="#peer-info" id="id94" name="id94">peer_info</a></li>
<li><a class="reference" href="#session-settings" id="id95" name="id95">session_settings</a></li>
<li><a class="reference" href="#ip-filter" id="id96" name="id96">ip_filter</a><ul>
<li><a class="reference" href="#id18" id="id97" name="id97">ip_filter()</a></li>
<li><a class="reference" href="#add-rule" id="id98" name="id98">add_rule()</a></li>
<li><a class="reference" href="#access" id="id99" name="id99">access()</a></li>
<li><a class="reference" href="#export-filter" id="id100" name="id100">export_filter()</a></li>
</ul>
</li>
<li><a class="reference" href="#big-number" id="id97" name="id97">big_number</a></li>
<li><a class="reference" href="#hasher" id="id98" name="id98">hasher</a></li>
<li><a class="reference" href="#fingerprint" id="id99" name="id99">fingerprint</a></li>
<li><a class="reference" href="#free-functions" id="id100" name="id100">free functions</a><ul>
<li><a class="reference" href="#identify-client" id="id101" name="id101">identify_client()</a></li>
<li><a class="reference" href="#client-fingerprint" id="id102" name="id102">client_fingerprint()</a></li>
<li><a class="reference" href="#bdecode-bencode" id="id103" name="id103">bdecode() bencode()</a></li>
<li><a class="reference" href="#big-number" id="id101" name="id101">big_number</a></li>
<li><a class="reference" href="#hasher" id="id102" name="id102">hasher</a></li>
<li><a class="reference" href="#fingerprint" id="id103" name="id103">fingerprint</a></li>
<li><a class="reference" href="#free-functions" id="id104" name="id104">free functions</a><ul>
<li><a class="reference" href="#identify-client" id="id105" name="id105">identify_client()</a></li>
<li><a class="reference" href="#client-fingerprint" id="id106" name="id106">client_fingerprint()</a></li>
<li><a class="reference" href="#bdecode-bencode" id="id107" name="id107">bdecode() bencode()</a></li>
</ul>
</li>
<li><a class="reference" href="#alerts" id="id104" name="id104">alerts</a><ul>
<li><a class="reference" href="#listen-failed-alert" id="id105" name="id105">listen_failed_alert</a></li>
<li><a class="reference" href="#file-error-alert" id="id106" name="id106">file_error_alert</a></li>
<li><a class="reference" href="#tracker-announce-alert" id="id107" name="id107">tracker_announce_alert</a></li>
<li><a class="reference" href="#tracker-alert" id="id108" name="id108">tracker_alert</a></li>
<li><a class="reference" href="#tracker-reply-alert" id="id109" name="id109">tracker_reply_alert</a></li>
<li><a class="reference" href="#tracker-warning-alert" id="id110" name="id110">tracker_warning_alert</a></li>
<li><a class="reference" href="#url-seed-alert" id="id111" name="id111">url_seed_alert</a></li>
<li><a class="reference" href="#hash-failed-alert" id="id112" name="id112">hash_failed_alert</a></li>
<li><a class="reference" href="#peer-ban-alert" id="id113" name="id113">peer_ban_alert</a></li>
<li><a class="reference" href="#peer-error-alert" id="id114" name="id114">peer_error_alert</a></li>
<li><a class="reference" href="#invalid-request-alert" id="id115" name="id115">invalid_request_alert</a></li>
<li><a class="reference" href="#torrent-finished-alert" id="id116" name="id116">torrent_finished_alert</a></li>
<li><a class="reference" href="#metadata-failed-alert" id="id117" name="id117">metadata_failed_alert</a></li>
<li><a class="reference" href="#metadata-received-alert" id="id118" name="id118">metadata_received_alert</a></li>
<li><a class="reference" href="#fastresume-rejected-alert" id="id119" name="id119">fastresume_rejected_alert</a></li>
<li><a class="reference" href="#dispatcher" id="id120" name="id120">dispatcher</a></li>
<li><a class="reference" href="#alerts" id="id108" name="id108">alerts</a><ul>
<li><a class="reference" href="#listen-failed-alert" id="id109" name="id109">listen_failed_alert</a></li>
<li><a class="reference" href="#file-error-alert" id="id110" name="id110">file_error_alert</a></li>
<li><a class="reference" href="#tracker-announce-alert" id="id111" name="id111">tracker_announce_alert</a></li>
<li><a class="reference" href="#tracker-alert" id="id112" name="id112">tracker_alert</a></li>
<li><a class="reference" href="#tracker-reply-alert" id="id113" name="id113">tracker_reply_alert</a></li>
<li><a class="reference" href="#tracker-warning-alert" id="id114" name="id114">tracker_warning_alert</a></li>
<li><a class="reference" href="#url-seed-alert" id="id115" name="id115">url_seed_alert</a></li>
<li><a class="reference" href="#hash-failed-alert" id="id116" name="id116">hash_failed_alert</a></li>
<li><a class="reference" href="#peer-ban-alert" id="id117" name="id117">peer_ban_alert</a></li>
<li><a class="reference" href="#peer-error-alert" id="id118" name="id118">peer_error_alert</a></li>
<li><a class="reference" href="#invalid-request-alert" id="id119" name="id119">invalid_request_alert</a></li>
<li><a class="reference" href="#torrent-finished-alert" id="id120" name="id120">torrent_finished_alert</a></li>
<li><a class="reference" href="#metadata-failed-alert" id="id121" name="id121">metadata_failed_alert</a></li>
<li><a class="reference" href="#metadata-received-alert" id="id122" name="id122">metadata_received_alert</a></li>
<li><a class="reference" href="#fastresume-rejected-alert" id="id123" name="id123">fastresume_rejected_alert</a></li>
<li><a class="reference" href="#dispatcher" id="id124" name="id124">dispatcher</a></li>
</ul>
</li>
<li><a class="reference" href="#exceptions" id="id121" name="id121">exceptions</a><ul>
<li><a class="reference" href="#invalid-handle" id="id122" name="id122">invalid_handle</a></li>
<li><a class="reference" href="#duplicate-torrent" id="id123" name="id123">duplicate_torrent</a></li>
<li><a class="reference" href="#invalid-encoding" id="id124" name="id124">invalid_encoding</a></li>
<li><a class="reference" href="#type-error" id="id125" name="id125">type_error</a></li>
<li><a class="reference" href="#invalid-torrent-file" id="id126" name="id126">invalid_torrent_file</a></li>
<li><a class="reference" href="#exceptions" id="id125" name="id125">exceptions</a><ul>
<li><a class="reference" href="#invalid-handle" id="id126" name="id126">invalid_handle</a></li>
<li><a class="reference" href="#duplicate-torrent" id="id127" name="id127">duplicate_torrent</a></li>
<li><a class="reference" href="#invalid-encoding" id="id128" name="id128">invalid_encoding</a></li>
<li><a class="reference" href="#type-error" id="id129" name="id129">type_error</a></li>
<li><a class="reference" href="#invalid-torrent-file" id="id130" name="id130">invalid_torrent_file</a></li>
</ul>
</li>
<li><a class="reference" href="#examples" id="id127" name="id127">examples</a><ul>
<li><a class="reference" href="#dump-torrent" id="id128" name="id128">dump_torrent</a></li>
<li><a class="reference" href="#simple-client" id="id129" name="id129">simple client</a></li>
<li><a class="reference" href="#make-torrent" id="id130" name="id130">make_torrent</a></li>
<li><a class="reference" href="#examples" id="id131" name="id131">examples</a><ul>
<li><a class="reference" href="#dump-torrent" id="id132" name="id132">dump_torrent</a></li>
<li><a class="reference" href="#simple-client" id="id133" name="id133">simple client</a></li>
<li><a class="reference" href="#make-torrent" id="id134" name="id134">make_torrent</a></li>
</ul>
</li>
<li><a class="reference" href="#fast-resume" id="id131" name="id131">fast resume</a><ul>
<li><a class="reference" href="#file-format" id="id132" name="id132">file format</a></li>
<li><a class="reference" href="#fast-resume" id="id135" name="id135">fast resume</a><ul>
<li><a class="reference" href="#file-format" id="id136" name="id136">file format</a></li>
</ul>
</li>
<li><a class="reference" href="#threads" id="id133" name="id133">threads</a></li>
<li><a class="reference" href="#storage-allocation" id="id134" name="id134">storage allocation</a><ul>
<li><a class="reference" href="#full-allocation" id="id135" name="id135">full allocation</a></li>
<li><a class="reference" href="#compact-allocation" id="id136" name="id136">compact allocation</a></li>
<li><a class="reference" href="#threads" id="id137" name="id137">threads</a></li>
<li><a class="reference" href="#storage-allocation" id="id138" name="id138">storage allocation</a><ul>
<li><a class="reference" href="#full-allocation" id="id139" name="id139">full allocation</a></li>
<li><a class="reference" href="#compact-allocation" id="id140" name="id140">compact allocation</a></li>
</ul>
</li>
<li><a class="reference" href="#extensions" id="id137" name="id137">extensions</a><ul>
<li><a class="reference" href="#chat-messages" id="id138" name="id138">chat messages</a></li>
<li><a class="reference" href="#metadata-from-peers" id="id139" name="id139">metadata from peers</a></li>
<li><a class="reference" href="#http-seeding" id="id140" name="id140">HTTP seeding</a></li>
<li><a class="reference" href="#extensions" id="id141" name="id141">extensions</a><ul>
<li><a class="reference" href="#chat-messages" id="id142" name="id142">chat messages</a></li>
<li><a class="reference" href="#metadata-from-peers" id="id143" name="id143">metadata from peers</a></li>
<li><a class="reference" href="#http-seeding" id="id144" name="id144">HTTP seeding</a></li>
</ul>
</li>
<li><a class="reference" href="#filename-checks" id="id141" name="id141">filename checks</a></li>
<li><a class="reference" href="#acknowledgments" id="id142" name="id142">acknowledgments</a></li>
<li><a class="reference" href="#filename-checks" id="id145" name="id145">filename checks</a></li>
<li><a class="reference" href="#acknowledgments" id="id146" name="id146">acknowledgments</a></li>
</ul>
</div>
<div class="section" id="introduction">
@@ -185,6 +189,7 @@ example client.</p>
project (including this documentation). The current state includes the
following features:</p>
<ul class="simple">
<li>Trackerless torrents (using a kademlia DHT)</li>
<li>multitracker extension support (as <a class="reference" href="http://home.elp.rr.com/tur/multitracker-spec.txt">specified by John Hoffman</a>)</li>
<li>serves multiple torrents on a single port and in a single thread</li>
<li>gzipped tracker-responses</li>
@@ -580,6 +585,10 @@ should be defined when building libtorrent as
a shared library. (This is set by the Jamfile
when <tt class="docutils literal"><span class="pre">link=shared</span></tt> is set).</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">TORRENT_DISABLE_DHT</span></tt></td>
<td>If this is defined, the support for trackerless
torrents will be disabled.</td>
</tr>
</tbody>
</table>
<p>If you experience that libtorrent uses unreasonable amounts of cpu, it will
@@ -667,9 +676,15 @@ class session: public boost::noncopyable
std::pair&lt;int, int&gt; const&amp; port_range
, char const* interface = 0);
std::auto_ptr&lt;alert&gt; pop_alert();
void set_severity_level(alert::severity_t s);
void start_dht();
void stop_dht();
void set_dht_settings(dht_settings const&amp; settings);
entry dht_state() const;
void add_dht_node(std::pair&lt;std::string, int&gt; const&amp; node);
};
</pre>
<p>Once it's created, the session object will spawn the main thread that will do all the work.
@@ -921,6 +936,60 @@ void set_severity_level(alert::severity_t s);
<tt class="docutils literal"><span class="pre">set_severity_level()</span></tt> you can filter how serious the event has to be for you to
receive it through <tt class="docutils literal"><span class="pre">pop_alert()</span></tt>. For information, see <a class="reference" href="#alerts">alerts</a>.</p>
</div>
<div class="section" id="start-dht-stop-dht-set-dht-settings-dht-state">
<h2><a name="start-dht-stop-dht-set-dht-settings-dht-state">start_dht() stop_dht() set_dht_settings() dht_state()</a></h2>
<blockquote>
<pre class="literal-block">
void start_dht(entry const&amp; startup_state);
void stop_dht();
void set_dht_settings(dht_settings const&amp; settings);
entry dht_state() const;
void add_dht_node(std::pair&lt;std::string, int&gt; const&amp; node);
</pre>
</blockquote>
<p>These functions are not available in case <tt class="docutils literal"><span class="pre">TORRENT_DISABLE_DHT</span></tt> is
defined. <tt class="docutils literal"><span class="pre">start_dht</span></tt> starts the dht node and makes the trackerless service
available to torrents. The startup state is optional and can contain nodes
and the node id from the previous session. The dht node state is a bencoded
dictionary with the following entries:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">nodes</span></tt></dt>
<dd>is a string with the nodes written as 6 bytes each. 4 bytes ip
address and 2 bytes port number. Both are written in big endian byte order.</dd>
<dt><tt class="docutils literal"><span class="pre">node-id</span></tt></dt>
<dd>The node id written as a readable string as a hexadecimal number.</dd>
</dl>
<p><tt class="docutils literal"><span class="pre">dht_state</span></tt> will return the current state of the dht node, this can be used
to start up the node again, passing this entry to <tt class="docutils literal"><span class="pre">start_dht</span></tt>. It is a good
idea to save this to disk when the session is closed, and read it up again
when starting.</p>
<p><tt class="docutils literal"><span class="pre">stop_dht</span></tt> stops the dht node.</p>
<p><tt class="docutils literal"><span class="pre">add_dht_node</span></tt> adds a node to the routing table. This can be used if your
client has its own source of bootstrapping nodes.</p>
<p><tt class="docutils literal"><span class="pre">set_dht_settings</span></tt> sets some parameters availavle to the dht node. The
struct has the following members:</p>
<pre class="literal-block">
struct dht_settings
{
int max_peers_reply;
int search_branching;
int service_port;
int max_fail_count;
};
</pre>
<p><tt class="docutils literal"><span class="pre">max_peers_reply</span></tt> is the maximum number of peers the node will send in
response to a <tt class="docutils literal"><span class="pre">get_peers</span></tt> message from another node.</p>
<p><tt class="docutils literal"><span class="pre">search_branching</span></tt> is the number of concurrent search request the node will
send when announcing and refreshing the routing table. This parameter is
called alpha in the kademlia paper.</p>
<p><tt class="docutils literal"><span class="pre">service_port</span></tt> is the udp port the node will listen to. (currently this
cannot be changed while the node is running).</p>
<p><tt class="docutils literal"><span class="pre">max_fail_count</span></tt> is the maximum number of failed tries to contact a node
before it is removed from the routing table. If there are known working nodes
that are ready to replace a failing node, it will be replaced immediately,
this limit is only used to clear out nodes that don't have any node that can
replace them.</p>
</div>
</div>
<div class="section" id="entry">
<h1><a name="entry">entry</a></h1>
@@ -1113,6 +1182,9 @@ public:
std::vector&lt;announce_entry&gt; const&amp; trackers() const;
bool priv() const;
void set_priv(bool v);
std::vector&lt;std::string&gt; const&amp; url_seeds() const;
size_type total_size() const;
@@ -1123,6 +1195,9 @@ public:
std::string const&amp; comment() const;
std::string const&amp; creator() const;
std::vector&lt;std::pair&lt;std::string, int&gt; &gt; const&amp; nodes() const;
void add_node(std::pair&lt;std::string, int&gt; const&amp; node);
boost::optional&lt;boost::posix_time::ptime&gt;
creation_date() const;
@@ -1201,6 +1276,8 @@ You can save this data as a torrent file with bencode() (see <a class="reference
complete example, see <a class="reference" href="#make-torrent">make_torrent</a>.</p>
<p>This function is not const because it will also set the info-hash of the <tt class="docutils literal"><span class="pre">torrent_info</span></tt>
object.</p>
<p>Note that a torrent file must include at least one file, and it must have at
least one tracker url or at least one DHT node.</p>
</div>
<div class="section" id="begin-files-end-files-rbegin-files-rend-files">
<h2><a name="begin-files-end-files-rbegin-files-rend-files">begin_files() end_files() rbegin_files() rend_files()</a></h2>
@@ -1390,6 +1467,38 @@ in the torrent file, this will return a date of January 1:st 1970.</p>
<p><tt class="docutils literal"><span class="pre">creator()</span></tt> returns the creator string in the torrent. If there is no creator string
it will return an empty string.</p>
</div>
<div class="section" id="priv-set-priv">
<h2><a name="priv-set-priv">priv() set_priv()</a></h2>
<blockquote>
<pre class="literal-block">
bool priv() const;
void set_priv(bool v);
</pre>
</blockquote>
<p><tt class="docutils literal"><span class="pre">priv()</span></tt> returns true if this torrent is private. i.e., it should not be
distributed on the trackerless network (the kademlia DHT).</p>
<p><tt class="docutils literal"><span class="pre">set_priv()</span></tt> sets or clears the private flag on this torrent.</p>
</div>
<div class="section" id="nodes">
<h2><a name="nodes">nodes()</a></h2>
<blockquote>
<pre class="literal-block">
std::vector&lt;std::pair&lt;std::string, int&gt; &gt; const&amp; nodes() const;
</pre>
</blockquote>
<p>If this torrent contains any DHT nodes, they are put in this vector in their original
form (host name and port number).</p>
</div>
<div class="section" id="add-node">
<h2><a name="add-node">add_node()</a></h2>
<blockquote>
<pre class="literal-block">
void add_node(std::pair&lt;std::string, int&gt; const&amp; node);
</pre>
</blockquote>
<p>This is used when creating torrent. Use this to add a known DHT node. It may
be used, by the client, to bootstrap into the DHT network.</p>
</div>
</div>
<div class="section" id="torrent-handle">
<h1><a name="torrent-handle">torrent_handle</a></h1>
@@ -2141,6 +2250,7 @@ struct session_settings
int whole_pieces_threshold;
int peer_timeout;
int urlseed_timeout;
int urlseed_pipeline_size;
};
</pre>
<p><tt class="docutils literal"><span class="pre">proxy_ip</span></tt> may be a hostname or ip to a http proxy to use. If this is
@@ -2204,6 +2314,10 @@ in the protocol specification. After half the time out, a keep alive message
is sent.</p>
<p><tt class="docutils literal"><span class="pre">urlseed_timeout</span></tt> is the same as <tt class="docutils literal"><span class="pre">peer_timeout</span></tt> but applies only to
url seeds. This value defaults to 20 seconds.</p>
<p><tt class="docutils literal"><span class="pre">urlseed_pipeline_size</span></tt> controls the pipelining with the web server. When
using persistent connections to HTTP 1.1 servers, the client is allowed to
send more requests before the first response is received. This number controls
the number of outstanding requests to use with url-seeds. Default is 5.</p>
</div>
<div class="section" id="ip-filter">
<h1><a name="ip-filter">ip_filter</a></h1>
@@ -3360,7 +3474,6 @@ bittorrent client.</p>
<p>Extension name: &quot;chat&quot;</p>
<p>The payload in the packet is a bencoded dictionary with any
combination of the following entries:</p>
<blockquote>
<table border="1" class="docutils">
<colgroup>
<col width="15%" />
@@ -3381,7 +3494,6 @@ Any unrecognized strings should be ignored.</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section" id="metadata-from-peers">
<h2><a name="metadata-from-peers">metadata from peers</a></h2>
@@ -3402,7 +3514,6 @@ are put as payload to the extension message. The three packets are:</p>
</ul>
</blockquote>
<p>request metadata:</p>
<blockquote>
<table border="1" class="docutils">
<colgroup>
<col width="17%" />
@@ -3441,9 +3552,7 @@ metadata.</td>
</tr>
</tbody>
</table>
</blockquote>
<p>metadata:</p>
<blockquote>
<table border="1" class="docutils">
<colgroup>
<col width="17%" />
@@ -3481,9 +3590,7 @@ protocol packet.</td>
</tr>
</tbody>
</table>
</blockquote>
<p>Don't have metadata:</p>
<blockquote>
<table border="1" class="docutils">
<colgroup>
<col width="17%" />
@@ -3506,7 +3613,6 @@ doesn't have any metadata.</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section" id="http-seeding">
<h2><a name="http-seeding">HTTP seeding</a></h2>

236
docs/manual.rst
View File

@@ -27,6 +27,7 @@ libtorrent is still being developed, however it is stable. It is an ongoing
project (including this documentation). The current state includes the
following features:
* Trackerless torrents (using a kademlia DHT)
* multitracker extension support (as `specified by John Hoffman`__)
* serves multiple torrents on a single port and in a single thread
* gzipped tracker-responses
@@ -474,6 +475,9 @@ defines you can use to control the build.
| | a shared library. (This is set by the Jamfile |
| | when ``link=shared`` is set). |
+--------------------------------+-------------------------------------------------+
| ``TORRENT_DISABLE_DHT`` | If this is defined, the support for trackerless |
|<7C> | torrents will be disabled. |
+--------------------------------+-------------------------------------------------+
If you experience that libtorrent uses unreasonable amounts of cpu, it will
@@ -558,9 +562,15 @@ The ``session`` class has the following synopsis::
std::pair<int, int> const& port_range
, char const* interface = 0);
std::auto_ptr<alert> pop_alert();
void set_severity_level(alert::severity_t s);
void start_dht();
void stop_dht();
void set_dht_settings(dht_settings const& settings);
entry dht_state() const;
void add_dht_node(std::pair<std::string, int> const& node);
};
Once it's created, the session object will spawn the main thread that will do all the work.
@@ -836,6 +846,68 @@ pop_alert() set_severity_level()
receive it through ``pop_alert()``. For information, see alerts_.
start_dht() stop_dht() set_dht_settings() dht_state()
-----------------------------------------------------
::
void start_dht(entry const& startup_state);
void stop_dht();
void set_dht_settings(dht_settings const& settings);
entry dht_state() const;
void add_dht_node(std::pair<std::string, int> const& node);
These functions are not available in case ``TORRENT_DISABLE_DHT`` is
defined. ``start_dht`` starts the dht node and makes the trackerless service
available to torrents. The startup state is optional and can contain nodes
and the node id from the previous session. The dht node state is a bencoded
dictionary with the following entries:
``nodes``
is a string with the nodes written as 6 bytes each. 4 bytes ip
address and 2 bytes port number. Both are written in big endian byte order.
``node-id``
The node id written as a readable string as a hexadecimal number.
``dht_state`` will return the current state of the dht node, this can be used
to start up the node again, passing this entry to ``start_dht``. It is a good
idea to save this to disk when the session is closed, and read it up again
when starting.
``stop_dht`` stops the dht node.
``add_dht_node`` adds a node to the routing table. This can be used if your
client has its own source of bootstrapping nodes.
``set_dht_settings`` sets some parameters availavle to the dht node. The
struct has the following members::
struct dht_settings
{
int max_peers_reply;
int search_branching;
int service_port;
int max_fail_count;
};
``max_peers_reply`` is the maximum number of peers the node will send in
response to a ``get_peers`` message from another node.
``search_branching`` is the number of concurrent search request the node will
send when announcing and refreshing the routing table. This parameter is
called alpha in the kademlia paper.
``service_port`` is the udp port the node will listen to. (currently this
cannot be changed while the node is running).
``max_fail_count`` is the maximum number of failed tries to contact a node
before it is removed from the routing table. If there are known working nodes
that are ready to replace a failing node, it will be replaced immediately,
this limit is only used to clear out nodes that don't have any node that can
replace them.
entry
=====
@@ -1041,6 +1113,9 @@ The ``torrent_info`` has the following synopsis::
std::vector<announce_entry> const& trackers() const;
bool priv() const;
void set_priv(bool v);
std::vector<std::string> const& url_seeds() const;
size_type total_size() const;
@@ -1051,6 +1126,9 @@ The ``torrent_info`` has the following synopsis::
std::string const& comment() const;
std::string const& creator() const;
std::vector<std::pair<std::string, int> > const& nodes() const;
void add_node(std::pair<std::string, int> const& node);
boost::optional<boost::posix_time::ptime>
creation_date() const;
@@ -1141,6 +1219,9 @@ complete example, see make_torrent_.
This function is not const because it will also set the info-hash of the ``torrent_info``
object.
Note that a torrent file must include at least one file, and it must have at
least one tracker url or at least one DHT node.
begin_files() end_files() rbegin_files() rend_files()
-----------------------------------------------------
@@ -1354,6 +1435,42 @@ it will return an empty string.
__ http://www.boost.org/libs/date_time/doc/class_ptime.html
priv() set_priv()
-----------------
::
bool priv() const;
void set_priv(bool v);
``priv()`` returns true if this torrent is private. i.e., it should not be
distributed on the trackerless network (the kademlia DHT).
``set_priv()`` sets or clears the private flag on this torrent.
nodes()
-------
::
std::vector<std::pair<std::string, int> > const& nodes() const;
If this torrent contains any DHT nodes, they are put in this vector in their original
form (host name and port number).
add_node()
----------
::
void add_node(std::pair<std::string, int> const& node);
This is used when creating torrent. Use this to add a known DHT node. It may
be used, by the client, to bootstrap into the DHT network.
torrent_handle
==============
@@ -2146,6 +2263,7 @@ that will be sent to the tracker. The user-agent is a good way to identify your
int whole_pieces_threshold;
int peer_timeout;
int urlseed_timeout;
int urlseed_pipeline_size;
};
``proxy_ip`` may be a hostname or ip to a http proxy to use. If this is
@@ -2225,6 +2343,10 @@ is sent.
``urlseed_timeout`` is the same as ``peer_timeout`` but applies only to
url seeds. This value defaults to 20 seconds.
``urlseed_pipeline_size`` controls the pipelining with the web server. When
using persistent connections to HTTP 1.1 servers, the client is allowed to
send more requests before the first response is received. This number controls
the number of outstanding requests to use with url-seeds. Default is 5.
ip_filter
=========
@@ -3476,17 +3598,17 @@ Extension name: "chat"
The payload in the packet is a bencoded dictionary with any
combination of the following entries:
+----------+--------------------------------------------------------+
| "msg" | This is a string that contains a message that |
| | should be displayed to the user. |
+----------+--------------------------------------------------------+
| "ctrl" | This is a control string that can tell a client that |
| | it is ignored (to make the user aware of that) and |
| | it can also tell a client that it is no longer ignored.|
| | These notifications are encoded as the strings: |
| | "ignored" and "not ignored". |
| | Any unrecognized strings should be ignored. |
+----------+--------------------------------------------------------+
+----------+--------------------------------------------------------+
| "msg" | This is a string that contains a message that |
| | should be displayed to the user. |
+----------+--------------------------------------------------------+
| "ctrl" | This is a control string that can tell a client that |
| | it is ignored (to make the user aware of that) and |
| | it can also tell a client that it is no longer ignored.|
| | These notifications are encoded as the strings: |
| | "ignored" and "not ignored". |
| | Any unrecognized strings should be ignored. |
+----------+--------------------------------------------------------+
metadata from peers
-------------------
@@ -3510,57 +3632,57 @@ are put as payload to the extension message. The three packets are:
request metadata:
+-----------+---------------+----------------------------------------+
| size | name | description |
+===========+===============+========================================+
| uint8_t | msg_type | Determines the kind of message this is |
| | | 0 means 'request metadata' |
+-----------+---------------+----------------------------------------+
| uint8_t | start | The start of the metadata block that |
| | | is requested. It is given in 256:ths |
| | | of the total size of the metadata, |
| | | since the requesting client don't know |
| | | the size of the metadata. |
+-----------+---------------+----------------------------------------+
| uint8_t | size | The size of the metadata block that is |
| | | requested. This is also given in |
| | | 256:ths of the total size of the |
| | | metadata. The size is given as size-1. |
| | | That means that if this field is set |
| | | 0, the request wants one 256:th of the |
| | | metadata. |
+-----------+---------------+----------------------------------------+
+-----------+---------------+----------------------------------------+
| size | name | description |
+===========+===============+========================================+
| uint8_t | msg_type | Determines the kind of message this is |
| | | 0 means 'request metadata' |
+-----------+---------------+----------------------------------------+
| uint8_t | start | The start of the metadata block that |
| | | is requested. It is given in 256:ths |
| | | of the total size of the metadata, |
| | | since the requesting client don't know |
| | | the size of the metadata. |
+-----------+---------------+----------------------------------------+
| uint8_t | size | The size of the metadata block that is |
| | | requested. This is also given in |
| | | 256:ths of the total size of the |
| | | metadata. The size is given as size-1. |
| | | That means that if this field is set |
| | | 0, the request wants one 256:th of the |
| | | metadata. |
+-----------+---------------+----------------------------------------+
metadata:
+-----------+---------------+----------------------------------------+
| size | name | description |
+===========+===============+========================================+
| uint8_t | msg_type | 1 means 'metadata' |
+-----------+---------------+----------------------------------------+
| int32_t | total_size | The total size of the metadata, given |
| | | in number of bytes. |
+-----------+---------------+----------------------------------------+
| int32_t | offset | The offset of where the metadata block |
| | | in this message belongs in the final |
| | | metadata. This is given in bytes. |
+-----------+---------------+----------------------------------------+
| uint8_t[] | metadata | The actual metadata block. The size of |
| | | this part is given implicit by the |
| | | length prefix in the bittorrent |
| | | protocol packet. |
+-----------+---------------+----------------------------------------+
+-----------+---------------+----------------------------------------+
| size | name | description |
+===========+===============+========================================+
| uint8_t | msg_type | 1 means 'metadata' |
+-----------+---------------+----------------------------------------+
| int32_t | total_size | The total size of the metadata, given |
| | | in number of bytes. |
+-----------+---------------+----------------------------------------+
| int32_t | offset | The offset of where the metadata block |
| | | in this message belongs in the final |
| | | metadata. This is given in bytes. |
+-----------+---------------+----------------------------------------+
| uint8_t[] | metadata | The actual metadata block. The size of |
| | | this part is given implicit by the |
| | | length prefix in the bittorrent |
| | | protocol packet. |
+-----------+---------------+----------------------------------------+
Don't have metadata:
+-----------+---------------+----------------------------------------+
| size | name | description |
+===========+===============+========================================+
| uint8_t | msg_type | 2 means 'I don't have metadata'. |
| | | This message is sent as a reply to a |
| | | metadata request if the the client |
| | | doesn't have any metadata. |
+-----------+---------------+----------------------------------------+
+-----------+---------------+----------------------------------------+
| size | name | description |
+===========+===============+========================================+
| uint8_t | msg_type | 2 means 'I don't have metadata'. |
| | | This message is sent as a reply to a |
| | | metadata request if the the client |
| | | doesn't have any metadata. |
+-----------+---------------+----------------------------------------+
HTTP seeding
------------