forked from premiere/premiere-libtorrent
3279 lines
167 KiB
HTML
Executable File
3279 lines
167 KiB
HTML
Executable File
<?xml version="1.0" encoding="utf-8" ?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
<meta name="generator" content="Docutils 0.3.8: http://docutils.sourceforge.net/" />
|
|
<title>libtorrent manual</title>
|
|
<meta name="author" content="Arvid Norberg, arvid@rasterbar.com" />
|
|
<link rel="stylesheet" href="style.css" type="text/css" />
|
|
</head>
|
|
<body>
|
|
<div class="document" id="libtorrent-manual">
|
|
<h1 class="title">libtorrent manual</h1>
|
|
<table class="docinfo" frame="void" rules="none">
|
|
<col class="docinfo-name" />
|
|
<col class="docinfo-content" />
|
|
<tbody valign="top">
|
|
<tr><th class="docinfo-name">Author:</th>
|
|
<td>Arvid Norberg, <a class="last reference" href="mailto:arvid@rasterbar.com">arvid@rasterbar.com</a></td></tr>
|
|
</tbody>
|
|
</table>
|
|
<div class="contents topic" id="table-of-contents">
|
|
<p class="topic-title first"><a name="table-of-contents">Table of contents</a></p>
|
|
<ul class="simple">
|
|
<li><a class="reference" href="#introduction" id="id21" name="id21">introduction</a></li>
|
|
<li><a class="reference" href="#downloading-and-building" id="id22" name="id22">downloading and building</a><ul>
|
|
<li><a class="reference" href="#building-with-bbv2" id="id23" name="id23">building with BBv2</a></li>
|
|
<li><a class="reference" href="#building-with-autotools" id="id24" name="id24">building with autotools</a></li>
|
|
<li><a class="reference" href="#building-with-other-build-systems" id="id25" name="id25">building with other build systems</a></li>
|
|
<li><a class="reference" href="#build-configurations" id="id26" name="id26">build configurations</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#overview" id="id27" name="id27">overview</a></li>
|
|
<li><a class="reference" href="#session" id="id28" name="id28">session</a><ul>
|
|
<li><a class="reference" href="#id7" id="id29" name="id29">session()</a></li>
|
|
<li><a class="reference" href="#id8" id="id30" name="id30">~session()</a></li>
|
|
<li><a class="reference" href="#add-torrent" id="id31" name="id31">add_torrent()</a></li>
|
|
<li><a class="reference" href="#remove-torrent" id="id32" name="id32">remove_torrent()</a></li>
|
|
<li><a class="reference" href="#disable-extensions-enable-extension" id="id33" name="id33">disable_extensions() enable_extension()</a></li>
|
|
<li><a class="reference" href="#set-upload-rate-limit-set-download-rate-limit" id="id34" name="id34">set_upload_rate_limit() set_download_rate_limit()</a></li>
|
|
<li><a class="reference" href="#set-max-uploads-set-max-connections" id="id35" name="id35">set_max_uploads() set_max_connections()</a></li>
|
|
<li><a class="reference" href="#set-max-half-open-connections" id="id36" name="id36">set_max_half_open_connections()</a></li>
|
|
<li><a class="reference" href="#set-ip-filter" id="id37" name="id37">set_ip_filter()</a></li>
|
|
<li><a class="reference" href="#status" id="id38" name="id38">status()</a></li>
|
|
<li><a class="reference" href="#is-listening-listen-port-listen-on" id="id39" name="id39">is_listening() listen_port() listen_on()</a></li>
|
|
<li><a class="reference" href="#pop-alert-set-severity-level" id="id40" name="id40">pop_alert() set_severity_level()</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#entry" id="id41" name="id41">entry</a><ul>
|
|
<li><a class="reference" href="#integer-string-list-dict-type" id="id42" name="id42">integer() string() list() dict() type()</a></li>
|
|
<li><a class="reference" href="#operator" id="id43" name="id43">operator[]</a></li>
|
|
<li><a class="reference" href="#find-key" id="id44" name="id44">find_key()</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#torrent-info" id="id45" name="id45">torrent_info</a><ul>
|
|
<li><a class="reference" href="#id9" id="id46" name="id46">torrent_info()</a></li>
|
|
<li><a class="reference" href="#set-comment-set-piece-size-set-creator-set-hash-add-tracker-add-file" id="id47" name="id47">set_comment() set_piece_size() set_creator() set_hash() add_tracker() add_file()</a></li>
|
|
<li><a class="reference" href="#create-torrent" id="id48" name="id48">create_torrent()</a></li>
|
|
<li><a class="reference" href="#begin-files-end-files-rbegin-files-rend-files" id="id49" name="id49">begin_files() end_files() rbegin_files() rend_files()</a></li>
|
|
<li><a class="reference" href="#num-files-file-at" id="id50" name="id50">num_files() file_at()</a></li>
|
|
<li><a class="reference" href="#print" id="id51" name="id51">print()</a></li>
|
|
<li><a class="reference" href="#trackers" id="id52" name="id52">trackers()</a></li>
|
|
<li><a class="reference" href="#total-size-piece-length-piece-size-num-pieces" id="id53" name="id53">total_size() piece_length() piece_size() num_pieces()</a></li>
|
|
<li><a class="reference" href="#hash-for-piece-info-hash" id="id54" name="id54">hash_for_piece() info_hash()</a></li>
|
|
<li><a class="reference" href="#name-comment-creation-date-creator" id="id55" name="id55">name() comment() creation_date() creator()</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#torrent-handle" id="id56" name="id56">torrent_handle</a><ul>
|
|
<li><a class="reference" href="#save-path" id="id57" name="id57">save_path()</a></li>
|
|
<li><a class="reference" href="#move-storage" id="id58" name="id58">move_storage()</a></li>
|
|
<li><a class="reference" href="#force-reannounce" id="id59" name="id59">force_reannounce()</a></li>
|
|
<li><a class="reference" href="#connect-peer" id="id60" name="id60">connect_peer()</a></li>
|
|
<li><a class="reference" href="#set-ratio" id="id61" name="id61">set_ratio()</a></li>
|
|
<li><a class="reference" href="#set-upload-limit-set-download-limit" id="id62" name="id62">set_upload_limit() set_download_limit()</a></li>
|
|
<li><a class="reference" href="#pause-resume-is-paused" id="id63" name="id63">pause() resume() is_paused()</a></li>
|
|
<li><a class="reference" href="#is-seed" id="id64" name="id64">is_seed()</a></li>
|
|
<li><a class="reference" href="#has-metadata" id="id65" name="id65">has_metadata()</a></li>
|
|
<li><a class="reference" href="#set-tracker-login" id="id66" name="id66">set_tracker_login()</a></li>
|
|
<li><a class="reference" href="#trackers-replace-trackers" id="id67" name="id67">trackers() replace_trackers()</a></li>
|
|
<li><a class="reference" href="#use-interface" id="id68" name="id68">use_interface()</a></li>
|
|
<li><a class="reference" href="#info-hash" id="id69" name="id69">info_hash()</a></li>
|
|
<li><a class="reference" href="#id11" id="id70" name="id70">set_max_uploads() set_max_connections()</a></li>
|
|
<li><a class="reference" href="#write-resume-data" id="id71" name="id71">write_resume_data()</a></li>
|
|
<li><a class="reference" href="#metadata" id="id72" name="id72">metadata()</a></li>
|
|
<li><a class="reference" href="#id12" id="id73" name="id73">status()</a></li>
|
|
<li><a class="reference" href="#get-download-queue" id="id74" name="id74">get_download_queue()</a></li>
|
|
<li><a class="reference" href="#get-peer-info" id="id75" name="id75">get_peer_info()</a></li>
|
|
<li><a class="reference" href="#get-torrent-info" id="id76" name="id76">get_torrent_info()</a></li>
|
|
<li><a class="reference" href="#is-valid" id="id77" name="id77">is_valid()</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#torrent-status" id="id78" name="id78">torrent_status</a></li>
|
|
<li><a class="reference" href="#peer-info" id="id79" name="id79">peer_info</a></li>
|
|
<li><a class="reference" href="#address" id="id80" name="id80">address</a></li>
|
|
<li><a class="reference" href="#http-settings" id="id81" name="id81">http_settings</a></li>
|
|
<li><a class="reference" href="#ip-filter" id="id82" name="id82">ip_filter</a><ul>
|
|
<li><a class="reference" href="#id14" id="id83" name="id83">ip_filter()</a></li>
|
|
<li><a class="reference" href="#add-rule" id="id84" name="id84">add_rule()</a></li>
|
|
<li><a class="reference" href="#access" id="id85" name="id85">access()</a></li>
|
|
<li><a class="reference" href="#export-filter" id="id86" name="id86">export_filter()</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#big-number" id="id87" name="id87">big_number</a></li>
|
|
<li><a class="reference" href="#hasher" id="id88" name="id88">hasher</a></li>
|
|
<li><a class="reference" href="#fingerprint" id="id89" name="id89">fingerprint</a></li>
|
|
<li><a class="reference" href="#free-functions" id="id90" name="id90">free functions</a><ul>
|
|
<li><a class="reference" href="#identify-client" id="id91" name="id91">identify_client()</a></li>
|
|
<li><a class="reference" href="#bdecode-bencode" id="id92" name="id92">bdecode() bencode()</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#alerts" id="id93" name="id93">alerts</a><ul>
|
|
<li><a class="reference" href="#listen-failed-alert" id="id94" name="id94">listen_failed_alert</a></li>
|
|
<li><a class="reference" href="#file-error-alert" id="id95" name="id95">file_error_alert</a></li>
|
|
<li><a class="reference" href="#tracker-announce-alert" id="id96" name="id96">tracker_announce_alert</a></li>
|
|
<li><a class="reference" href="#tracker-alert" id="id97" name="id97">tracker_alert</a></li>
|
|
<li><a class="reference" href="#tracker-reply-alert" id="id98" name="id98">tracker_reply_alert</a></li>
|
|
<li><a class="reference" href="#tracker-warning-alert" id="id99" name="id99">tracker_warning_alert</a></li>
|
|
<li><a class="reference" href="#hash-failed-alert" id="id100" name="id100">hash_failed_alert</a></li>
|
|
<li><a class="reference" href="#peer-ban-alert" id="id101" name="id101">peer_ban_alert</a></li>
|
|
<li><a class="reference" href="#peer-error-alert" id="id102" name="id102">peer_error_alert</a></li>
|
|
<li><a class="reference" href="#invalid-request-alert" id="id103" name="id103">invalid_request_alert</a></li>
|
|
<li><a class="reference" href="#torrent-finished-alert" id="id104" name="id104">torrent_finished_alert</a></li>
|
|
<li><a class="reference" href="#metadata-failed-alert" id="id105" name="id105">metadata_failed_alert</a></li>
|
|
<li><a class="reference" href="#metadata-received-alert" id="id106" name="id106">metadata_received_alert</a></li>
|
|
<li><a class="reference" href="#fastresume-rejected-alert" id="id107" name="id107">fastresume_rejected_alert</a></li>
|
|
<li><a class="reference" href="#dispatcher" id="id108" name="id108">dispatcher</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#exceptions" id="id109" name="id109">exceptions</a><ul>
|
|
<li><a class="reference" href="#invalid-handle" id="id110" name="id110">invalid_handle</a></li>
|
|
<li><a class="reference" href="#duplicate-torrent" id="id111" name="id111">duplicate_torrent</a></li>
|
|
<li><a class="reference" href="#invalid-encoding" id="id112" name="id112">invalid_encoding</a></li>
|
|
<li><a class="reference" href="#type-error" id="id113" name="id113">type_error</a></li>
|
|
<li><a class="reference" href="#invalid-torrent-file" id="id114" name="id114">invalid_torrent_file</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#examples" id="id115" name="id115">examples</a><ul>
|
|
<li><a class="reference" href="#dump-torrent" id="id116" name="id116">dump_torrent</a></li>
|
|
<li><a class="reference" href="#simple-client" id="id117" name="id117">simple client</a></li>
|
|
<li><a class="reference" href="#make-torrent" id="id118" name="id118">make_torrent</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#fast-resume" id="id119" name="id119">fast resume</a><ul>
|
|
<li><a class="reference" href="#file-format" id="id120" name="id120">file format</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#threads" id="id121" name="id121">threads</a></li>
|
|
<li><a class="reference" href="#storage-allocation" id="id122" name="id122">storage allocation</a><ul>
|
|
<li><a class="reference" href="#full-allocation" id="id123" name="id123">full allocation</a></li>
|
|
<li><a class="reference" href="#compact-allocation" id="id124" name="id124">compact allocation</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#extensions" id="id125" name="id125">extensions</a><ul>
|
|
<li><a class="reference" href="#chat-messages" id="id126" name="id126">chat messages</a></li>
|
|
<li><a class="reference" href="#metadata-from-peers" id="id127" name="id127">metadata from peers</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference" href="#filename-checks" id="id128" name="id128">filename checks</a></li>
|
|
<li><a class="reference" href="#acknowledgements" id="id129" name="id129">acknowledgements</a></li>
|
|
</ul>
|
|
</div>
|
|
<div class="section" id="introduction">
|
|
<h1><a name="introduction">introduction</a></h1>
|
|
<p>libtorrent is a C++ library that aims to be a good alternative to all the
|
|
other bittorrent implementations around. It is a
|
|
library and not a full featured client, although it comes with a working
|
|
example client.</p>
|
|
<p>The main goals of libtorrent are:</p>
|
|
<blockquote>
|
|
<ul class="simple">
|
|
<li>to be cpu efficient</li>
|
|
<li>to be memory efficient</li>
|
|
<li>to be very easy to use</li>
|
|
</ul>
|
|
</blockquote>
|
|
<p>libtorrent is still being developed, however it is stable. It is an ongoing
|
|
project (including this documentation). The current state includes the
|
|
following features:</p>
|
|
<blockquote>
|
|
<ul class="simple">
|
|
<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 a single thread</li>
|
|
<li>supports http proxies and proxy authentication</li>
|
|
<li>gzipped tracker-responses</li>
|
|
<li>piece picking on block-level like in <a class="reference" href="http://azureus.sourceforge.net">Azureus</a> (as opposed to piece-level).
|
|
This means it can download parts of the same piece from different peers.
|
|
It will also prefer to download whole pieces from single peers if the
|
|
download speed is high enough from that particular peer.</li>
|
|
<li>queues torrents for file check, instead of checking all of them in parallel.</li>
|
|
<li>uses separate threads for checking files and for main downloader, with a
|
|
fool-proof thread-safe library interface. (i.e. There's no way for the
|
|
user to cause a deadlock). (see <a class="reference" href="#threads">threads</a>)</li>
|
|
<li>can limit the upload and download bandwidth usage and the maximum number of
|
|
unchoked peers</li>
|
|
<li>piece-wise, unordered, incremental file allocation</li>
|
|
<li>implements fair trade. User settable trade-ratio, must at least be 1:1,
|
|
but one can choose to trade 1 for 2 or any other ratio that isn't unfair
|
|
to the other party.</li>
|
|
<li>fast resume support, a way to get rid of the costly piece check at the
|
|
start of a resumed torrent. Saves the storage state, piece_picker state
|
|
as well as all local peers in a separate fast-resume file.</li>
|
|
<li>supports an <a class="reference" href="extension_protocol.html">extension protocol</a>. See <a class="reference" href="#extensions">extensions</a>.</li>
|
|
<li>supports files > 2 gigabytes.</li>
|
|
<li>supports the <tt class="docutils literal"><span class="pre">no_peer_id=1</span></tt> extension that will ease the load off trackers.</li>
|
|
<li>supports the <a class="reference" href="udp_tracker_protocol.html">udp-tracker protocol</a> by Olaf van der Spek.</li>
|
|
<li>possibility to limit the number of connections.</li>
|
|
<li>delays have messages if there's no other outgoing traffic to the peer, and
|
|
doesn't send have messages to peers that already has the piece. This saves
|
|
bandwidth.</li>
|
|
<li>does not have any requirements on the piece order in a torrent that it
|
|
resumes. This means it can resume a torrent downloaded by any client.</li>
|
|
<li>adjusts the length of the request queue depending on download rate.</li>
|
|
<li>supports the <tt class="docutils literal"><span class="pre">compact=1</span></tt> tracker parameter.</li>
|
|
<li>selective downloading. The ability to select which parts of a torrent you
|
|
want to download.</li>
|
|
<li>ip filter</li>
|
|
</ul>
|
|
</blockquote>
|
|
<p>libtorrent is portable at least among Windows, MacOS X and other UNIX-systems. It uses Boost.Thread,
|
|
Boost.Filesystem, Boost.Date_time and various other boost libraries as well as zlib.</p>
|
|
<p>libtorrent has been successfully compiled and tested on:</p>
|
|
<blockquote>
|
|
<ul class="simple">
|
|
<li>Windows 2000 vc7.1</li>
|
|
<li>Linux x86 GCC 3.0.4, GCC 3.2.3, GCC 3.4.2</li>
|
|
<li>MacOS X (darwin), (Apple's) GCC 3.3, (Apple's) GCC 4.0</li>
|
|
<li>SunOS 5.8 GCC 3.1</li>
|
|
<li>Cygwin GCC 3.3.3</li>
|
|
</ul>
|
|
</blockquote>
|
|
<p>Fails on:</p>
|
|
<blockquote>
|
|
<ul class="simple">
|
|
<li>GCC 2.95.4</li>
|
|
<li>msvc6 sp5</li>
|
|
</ul>
|
|
</blockquote>
|
|
<p>libtorrent is released under the <a class="reference" href="http://www.opensource.org/licenses/bsd-license.php">BSD-license</a>.</p>
|
|
</div>
|
|
<div class="section" id="downloading-and-building">
|
|
<h1><a name="downloading-and-building">downloading and building</a></h1>
|
|
<p>To acquire the latest version of libtorrent, you'll have to grab it from CVS.
|
|
You'll find instructions on how to do this <a class="reference" href="http://sourceforge.net/cvs/?group_id=79942">here</a> (see Anonymous CVS access).</p>
|
|
<p>The build systems supported "out of the box" in libtorrent are boost-build v2
|
|
(BBv2) and autotools (for unix-like systems). If you still can't build after
|
|
following these instructions, you can usually get help in the <tt class="docutils literal"><span class="pre">#libtorrent</span></tt>
|
|
IRC channel on <tt class="docutils literal"><span class="pre">irc.freenode.net</span></tt>.</p>
|
|
<div class="section" id="building-with-bbv2">
|
|
<h2><a name="building-with-bbv2">building with BBv2</a></h2>
|
|
<p>The primary reason to use boost-build is that it will automatically build the
|
|
dependent boost libraries with the correct compiler settings, in order to
|
|
ensure that the build targets are link compatible (see <a class="reference" href="http://boost.org/more/separate_compilation.html">boost guidelines</a>
|
|
for some details on this issue).</p>
|
|
<p>Since BBv2 will build the boost libraries for you, you need the full boost
|
|
source package. Having boost installed via some package system is usually not
|
|
enough (and even if it is enough, the necessary environment variables are
|
|
usually not set by the package installer).</p>
|
|
<div class="section" id="step-1-download-boost">
|
|
<h3><a name="step-1-download-boost">Step 1: Download boost</a></h3>
|
|
<p>You'll find boost <a class="reference" href="http://sourceforge.net/project/showfiles.php?group_id=7586">here</a>.</p>
|
|
<p>Extract the archive to some directory where you want it. For the sake of this
|
|
guide, let's assume you extract the package to <tt class="docutils literal"><span class="pre">c:\boost_1_33_0</span></tt> (I'm using
|
|
a windows path in this example since if you're on linux/unix you're more likely
|
|
to use the autotools). You'll need at least version 1.32 of the boost library
|
|
in order to build libtorrent.</p>
|
|
<p>If you use 1.32, you need to download BBv2 separately, so for now, let's
|
|
assume you will use version 1.33.</p>
|
|
</div>
|
|
<div class="section" id="step-2-setup-bbv2">
|
|
<h3><a name="step-2-setup-bbv2">Step 2: Setup BBv2</a></h3>
|
|
<p>First you need to build <tt class="docutils literal"><span class="pre">bjam</span></tt>. You do this by opening a terminal (In
|
|
windows, run <tt class="docutils literal"><span class="pre">cmd</span></tt>). Change directory to
|
|
<tt class="docutils literal"><span class="pre">c:\boost_1_33_0\tools\build\jam_src</span></tt>. Then run the script called
|
|
<tt class="docutils literal"><span class="pre">build.bat</span></tt> or <tt class="docutils literal"><span class="pre">build.sh</span></tt> on a unix system. This will build <tt class="docutils literal"><span class="pre">bjam</span></tt> and
|
|
place it in a directory starting with <tt class="docutils literal"><span class="pre">bin.</span></tt> and then have the name of your
|
|
platform. Copy the <tt class="docutils literal"><span class="pre">bjam.exe</span></tt> (or <tt class="docutils literal"><span class="pre">bjam</span></tt> on a unix system) to a place
|
|
that's in you shell's <tt class="docutils literal"><span class="pre">PATH</span></tt>. On linux systems a place commonly used may be
|
|
<tt class="docutils literal"><span class="pre">/usr/local/bin</span></tt> or on windows <tt class="docutils literal"><span class="pre">c:\windows</span></tt> (you can also add directories
|
|
to the search paths by modifying the environment variable called <tt class="docutils literal"><span class="pre">PATH</span></tt>).</p>
|
|
<p>Now you have <tt class="docutils literal"><span class="pre">bjam</span></tt> installed. <tt class="docutils literal"><span class="pre">bjam</span></tt> can be considered an interpreter
|
|
that the boost-build system is implemented on. So boost-build uses <tt class="docutils literal"><span class="pre">bjam</span></tt>.
|
|
So, to complete the installation you need to make two more things. You need to
|
|
set the environment variable <tt class="docutils literal"><span class="pre">BOOST_BUILD_PATH</span></tt>. This is the path that tells
|
|
<tt class="docutils literal"><span class="pre">bjam</span></tt> where it can find boost-build, your configuration file and all the
|
|
toolsets (descriptions used by boost-build to know how to use different
|
|
compilers on different platforms). Assuming the boost install path above, set
|
|
it to <tt class="docutils literal"><span class="pre">c:\boost_1_33_0\tools\build\v2</span></tt>.</p>
|
|
<p>The last thing to do to complete the setup of BBv2 is to modify your
|
|
<tt class="docutils literal"><span class="pre">user-config.jam</span></tt> file. It is located in <tt class="docutils literal"><span class="pre">c:\boost_1_33\tools\build\v2</span></tt>.
|
|
Depending on your platform and which compiler you're using, you should add a
|
|
line for each compiler and compiler version you have installed on your system
|
|
that you want to be able to use with BBv2. For example, if you're using
|
|
Microsoft Visual Studio 7.1 (2003), just add a line:</p>
|
|
<pre class="literal-block">
|
|
using msvc : 7.1 ;
|
|
</pre>
|
|
<p>If you use GCC, add the line:</p>
|
|
<pre class="literal-block">
|
|
using gcc ;
|
|
</pre>
|
|
<p>If you have more than one version of GCC installed, you can add the
|
|
commandline used to invoke g++ after the version number, like this:</p>
|
|
<pre class="literal-block">
|
|
using gcc : 3.3 : g++-3.3 ;
|
|
using gcc : 4.0 : g++-4.0 ;
|
|
</pre>
|
|
<p>Another toolset worth mentioning is the <tt class="docutils literal"><span class="pre">darwin</span></tt> toolset (For MacOS X).
|
|
From Tiger (10.4) MacOS X comes with both GCC 3.3 and GCC 4.0. Then you can
|
|
use the following toolsets:</p>
|
|
<pre class="literal-block">
|
|
using darwin : 3.3 : g++-3.3 ;
|
|
using darwin : 4.0 : g++-4.0 ;
|
|
</pre>
|
|
<p>Note that the spaces around the semi-colons and colons are important!</p>
|
|
</div>
|
|
<div class="section" id="step-3-building-libtorrent">
|
|
<h3><a name="step-3-building-libtorrent">Step 3: Building libtorrent</a></h3>
|
|
<p>When building libtorrent, the <tt class="docutils literal"><span class="pre">Jamfile</span></tt> expects the environment variable
|
|
<tt class="docutils literal"><span class="pre">BOOST_ROOT</span></tt> to be set to the boost installation directory. It uses this to
|
|
find the boost libraries it depends on, so they can be built and their headers
|
|
files found. So, set this to <tt class="docutils literal"><span class="pre">c:\boost_1_33_0</span></tt>.</p>
|
|
<p>Then the only thing left is simply to invoke <tt class="docutils literal"><span class="pre">bjam</span></tt>. If you want to specify
|
|
a specific toolset to use (compiler) you can just add that to the commandline.
|
|
For example:</p>
|
|
<pre class="literal-block">
|
|
bjam msvc-7.1 link=static
|
|
bjam gcc-3.3 link=static
|
|
bjam darwin-4.0 link=static
|
|
</pre>
|
|
<p>To build different versions you can also just add the name of the build
|
|
variant. Some default build variants in BBv2 are <tt class="docutils literal"><span class="pre">release</span></tt>, <tt class="docutils literal"><span class="pre">debug</span></tt>,
|
|
<tt class="docutils literal"><span class="pre">profile</span></tt>.</p>
|
|
<p>You can build libtorrent as a dll too, by typing <tt class="docutils literal"><span class="pre">link=shared</span></tt>, or
|
|
<tt class="docutils literal"><span class="pre">link=static</span></tt> to build a static library. <tt class="docutils literal"><span class="pre">link=shared</span></tt> is the default.</p>
|
|
<p>If you want to explicitly say how to link against the runtime library, you
|
|
can set the <tt class="docutils literal"><span class="pre">runtime-link</span></tt> feature on the commandline, either to <tt class="docutils literal"><span class="pre">shared</span></tt>
|
|
or <tt class="docutils literal"><span class="pre">static</span></tt>. Most operating systems will only allow linking shared against
|
|
the runtime, but on windows you can do both. Example:</p>
|
|
<pre class="literal-block">
|
|
bjam msvc-7.1 link=static runtime-link=static
|
|
</pre>
|
|
<div class="warning">
|
|
<p class="first admonition-title">Warning</p>
|
|
<p class="last">If you link statically to the runtime library, you cannot build libtorrent
|
|
as a shared library (DLL), since you will get separate heaps in the library
|
|
and in the client application. It will result in crashes.</p>
|
|
</div>
|
|
<p>The build targets are put in a directory called bin, and under it they are
|
|
sorted in directories depending on the toolset and build variant used.</p>
|
|
<p>To build the examples, just change directory to the examples directory and
|
|
invoke <tt class="docutils literal"><span class="pre">bjam</span></tt> from there. To build and run the tests, go to the test
|
|
directory and run <tt class="docutils literal"><span class="pre">bjam</span></tt>.</p>
|
|
<p>Note that if you're building on windows using the <tt class="docutils literal"><span class="pre">msvc</span></tt> toolset, you cannot run it
|
|
from a cygwin terminal, you'll have to run it from a <tt class="docutils literal"><span class="pre">cmd</span></tt> terminal. The same goes for
|
|
cygwin, if you're building with gcc in cygwin you'll have to run it from a cygwin terminal.
|
|
Also, make sure the paths are correct in the different environments. In cygwin, the paths
|
|
(<tt class="docutils literal"><span class="pre">BOOST_BUILD_PATH</span></tt> and <tt class="docutils literal"><span class="pre">BOOST_ROOT</span></tt>) should be in the typical unix-format (e.g.
|
|
<tt class="docutils literal"><span class="pre">/cygdrive/c/boost_1_33_0</span></tt>). In the windows environment, they should have the typical
|
|
windows format (<tt class="docutils literal"><span class="pre">c:/boost_1_33_0</span></tt>).</p>
|
|
<p>The <tt class="docutils literal"><span class="pre">Jamfile</span></tt> will define <tt class="docutils literal"><span class="pre">NDEBUG</span></tt> when it's building a release build.
|
|
There are two other build variants available in the <tt class="docutils literal"><span class="pre">Jamfile</span></tt>. debug_log
|
|
and release_log, these two variants inherits from the debug and release
|
|
variants respectively, but adds extra logging (<tt class="docutils literal"><span class="pre">TORRENT_VERBOSE_LOGGING</span></tt>).
|
|
For more build configuration flags see <a class="reference" href="#build-configurations">Build configurations</a>.</p>
|
|
<p>The <tt class="docutils literal"><span class="pre">Jamfile</span></tt> has the following build variants:</p>
|
|
<blockquote>
|
|
<ul class="simple">
|
|
<li><tt class="docutils literal"><span class="pre">release</span></tt> - release version without any logging</li>
|
|
<li><tt class="docutils literal"><span class="pre">release_log</span></tt> - release version with standard logging</li>
|
|
<li><tt class="docutils literal"><span class="pre">release_vlog</span></tt> - release version with verbose logging (all peer connections are logged)</li>
|
|
<li><tt class="docutils literal"><span class="pre">debug</span></tt> - debug version without any logging</li>
|
|
<li><tt class="docutils literal"><span class="pre">debug_log</span></tt> - debug version with standard logging</li>
|
|
<li><tt class="docutils literal"><span class="pre">debug_vlog</span></tt> - debug version with verbose logging</li>
|
|
</ul>
|
|
</blockquote>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="building-with-autotools">
|
|
<h2><a name="building-with-autotools">building with autotools</a></h2>
|
|
<p>First of all, you need to install <tt class="docutils literal"><span class="pre">automake</span></tt> and <tt class="docutils literal"><span class="pre">autoconf</span></tt>. Many
|
|
unix/linux systems comes with these preinstalled.</p>
|
|
<div class="section" id="step-1-running-configure">
|
|
<h3><a name="step-1-running-configure">Step 1: Running configure</a></h3>
|
|
<p>In your shell, change directory to the libtorrent directory and run
|
|
<tt class="docutils literal"><span class="pre">./configure</span></tt>. This will look for libraries and C++ features that libtorrent
|
|
is dependent on. If something is missing or can't be found it will print an
|
|
error telling you what failed.</p>
|
|
<p>The most likely problem you may encounter is that the configure script won't
|
|
find the boost libraries. Make sure you have boost installed on your system.
|
|
The easiest way to install boost is usually to use the preferred package
|
|
system on your platform. Usually libraries and headers are installed in
|
|
standard directories where the compiler will find them, but sometimes that
|
|
may not be the case. For example when installing boost on darwin using
|
|
darwinports (the package system based on BSD ports) all libraries are
|
|
installed to <tt class="docutils literal"><span class="pre">/opt/local/lib</span></tt> and headers are installed to
|
|
<tt class="docutils literal"><span class="pre">/opt/local/include</span></tt>. By default the compiler will not look in these
|
|
directories. You have to set the enviornment variables <tt class="docutils literal"><span class="pre">LDFLAGS</span></tt> and
|
|
<tt class="docutils literal"><span class="pre">CXXFLAGS</span></tt> in order to make the compiler find those libs. In this example
|
|
you'd set them like this:</p>
|
|
<pre class="literal-block">
|
|
export LDFLAGS=-L/opt/local/lib
|
|
export CXXFLAGS=-I/opt/local/include
|
|
</pre>
|
|
<p>If you need to set these variables, it may be a good idea to add those lines
|
|
to your <tt class="docutils literal"><span class="pre">~/.profile</span></tt> or <tt class="docutils literal"><span class="pre">~/.tcshrc</span></tt> depending on your shell.</p>
|
|
<p>You know that the boost libraries were found if you see the following output
|
|
from the configure script:</p>
|
|
<pre class="literal-block">
|
|
checking whether the Boost::DateTime library is available... yes
|
|
checking for main in -lboost_date_time... yes
|
|
checking whether the Boost::Filesystem library is available... yes
|
|
checking for main in -lboost_filesystem... yes
|
|
checking whether the Boost::Thread library is available... yes
|
|
checking for main in -lboost_thread... yes
|
|
</pre>
|
|
<p>Another possible source of problems may be if the path to your libtorrent
|
|
directory contains spaces. Make sure you either rename the directories with
|
|
spaces in their names to remove the spaces or move the libtorrent directory.</p>
|
|
</div>
|
|
<div class="section" id="creating-a-debug-build">
|
|
<h3><a name="creating-a-debug-build">Creating a debug build</a></h3>
|
|
<p>To tell configure to build a debug version (with debug info, asserts
|
|
and invariant checks enabled), you have to run the configure script
|
|
with the following option:</p>
|
|
<pre class="literal-block">
|
|
./configure --enable-debug=yes
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="creating-a-release-build">
|
|
<h3><a name="creating-a-release-build">Creating a release build</a></h3>
|
|
<p>To tell the configure to build a release version (without debug info,
|
|
asserts and invariant checks), you have to run the configure script
|
|
with the following option:</p>
|
|
<pre class="literal-block">
|
|
./configure --enable-debug=no
|
|
</pre>
|
|
<p>The above option make use of -DNDEBUG, which is used throughout libtorrent.</p>
|
|
</div>
|
|
<div class="section" id="step-2-building-libtorrent">
|
|
<h3><a name="step-2-building-libtorrent">Step 2: Building libtorrent</a></h3>
|
|
<p>Once the configure script is run successfully, you just type <tt class="docutils literal"><span class="pre">make</span></tt> and
|
|
libtorrent, the examples and the tests will be built.</p>
|
|
<p>When libtorrent is built it may be a good idea to run the tests, you do this
|
|
my running <tt class="docutils literal"><span class="pre">make</span> <span class="pre">check</span></tt>.</p>
|
|
<p>If you want to build a release version (without debug info, asserts and
|
|
invariant checks), you have to rerun the configure script and rebuild, like this:</p>
|
|
<pre class="literal-block">
|
|
./configure --disable-debug
|
|
make clean
|
|
make
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="building-with-other-build-systems">
|
|
<h2><a name="building-with-other-build-systems">building with other build systems</a></h2>
|
|
<p>If you're making your own project file, note that there are two versions of
|
|
the file abstraction. There's one <tt class="docutils literal"><span class="pre">file_win.cpp</span></tt> which relies on windows
|
|
file API that supports files larger than 2 Gigabytes. This does not work in
|
|
vc6 for some reason, possibly because it may require windows NT and above.
|
|
The other file, <tt class="docutils literal"><span class="pre">file.cpp</span></tt> is the default implementation that simply relies
|
|
on the standard low level io routines (<tt class="docutils literal"><span class="pre">read()</span></tt>, <tt class="docutils literal"><span class="pre">write()</span></tt>, <tt class="docutils literal"><span class="pre">open()</span></tt>
|
|
etc.), this implementation doesn't do anything special to support unicode
|
|
filenames, so if your target is Windows 2000 and up, you may want to use
|
|
<tt class="docutils literal"><span class="pre">file_win.cpp</span></tt> which supports unicode filenames.</p>
|
|
<p>If you're building in MS Visual Studio, you may have to set the compiler
|
|
options "force conformance in for loop scope", "treat wchar_t as built-in
|
|
type" and "Enable Run-Time Type Info" to Yes.</p>
|
|
</div>
|
|
<div class="section" id="build-configurations">
|
|
<h2><a name="build-configurations">build configurations</a></h2>
|
|
<p>By default libtorrent is built In debug mode, and will have pretty expensive
|
|
invariant checks and asserts built into it. If you want to disable such checks
|
|
(you want to do that in a release build) you can see the table below for which
|
|
defines you can use to control the build.</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="40%" />
|
|
<col width="60%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr><th>macro</th>
|
|
<th>description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<tr><td><tt class="docutils literal"><span class="pre">NDEBUG</span></tt></td>
|
|
<td>If you define this macro, all asserts,
|
|
invariant checks and general debug code will be
|
|
removed. This option takes precedence over
|
|
other debug settings.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">TORRENT_LOGGING</span></tt></td>
|
|
<td>This macro will enable logging of the session
|
|
events, such as tracker announces and incoming
|
|
connections (as well as blocked connections).</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">TORRENT_VERBOSE_LOGGING</span></tt></td>
|
|
<td>If you define this macro, every peer connection
|
|
will log its traffic to a log file as well as
|
|
the session log.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">TORRENT_STORAGE_DEBUG</span></tt></td>
|
|
<td>This will enable extra expensive invariant
|
|
checks in the storage, including logging of
|
|
piece sorting.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">UNICODE</span></tt></td>
|
|
<td>If building on windows this will make sure the
|
|
UTF-8 strings in pathnames are converted into
|
|
UTF-16 before they are passed to the file
|
|
operations.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">LITTLE_ENDIAN</span></tt></td>
|
|
<td>This will use the little endian version of the
|
|
sha-1 code. If defined on a big-endian system
|
|
the sha-1 hashes will be incorrect and fail.
|
|
If it is not defined and <tt class="docutils literal"><span class="pre">__BIG_ENDIAN__</span></tt>
|
|
isn't defined either (it is defined by Apple's
|
|
GCC) both little-endian and big-endian versions
|
|
will be built and the correct code will be
|
|
chosen at run-time.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">TORRENT_LINKING_SHARED</span></tt></td>
|
|
<td>If this is defined when including the
|
|
libtorrent headers, the classes and functions
|
|
will be tagged with <tt class="docutils literal"><span class="pre">__declspec(dllimport)</span></tt>
|
|
on msvc and default visibility on GCC 4 and
|
|
later. Set this in your project if you're
|
|
linking against 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_BUILDING_SHARED</span></tt></td>
|
|
<td>If this is defined, the functions and classes
|
|
in libtorrent are marked with
|
|
<tt class="docutils literal"><span class="pre">__declspec(dllexport)</span></tt> on msvc, or with
|
|
default visibility on GCC 4 and later. This
|
|
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>
|
|
</tbody>
|
|
</table>
|
|
<p>If you experience that libtorrent uses unreasonable amounts of cpu, it will
|
|
definately help to define <tt class="docutils literal"><span class="pre">NDEBUG</span></tt>, since it will remove the invariant checks
|
|
within the library.</p>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="overview">
|
|
<h1><a name="overview">overview</a></h1>
|
|
<p>The interface of libtorrent consists of a few classes. The main class is
|
|
the <tt class="docutils literal"><span class="pre">session</span></tt>, it contains the main loop that serves all torrents.</p>
|
|
<p>The basic usage is as follows:</p>
|
|
<ul>
|
|
<li><p class="first">conststruct a session</p>
|
|
</li>
|
|
<li><p class="first">parse .torrent-files and add them to the session (see <a class="reference" href="#bdecode-bencode">bdecode() bencode()</a>)</p>
|
|
</li>
|
|
<li><p class="first">main loop (see <a class="reference" href="#session">session</a>)</p>
|
|
<blockquote>
|
|
<ul class="simple">
|
|
<li>query the torrent_handles for progress (see <a class="reference" href="#torrent-handle">torrent_handle</a>)</li>
|
|
<li>query the session for information</li>
|
|
<li>add and remove torrents from the session at run-time</li>
|
|
</ul>
|
|
</blockquote>
|
|
</li>
|
|
<li><p class="first">save resume data for all torrent_handles (optional, see
|
|
<a class="reference" href="#write-resume-data">write_resume_data()</a>)</p>
|
|
</li>
|
|
<li><p class="first">destruct session object</p>
|
|
</li>
|
|
</ul>
|
|
<p>Each class and function is described in this manual.</p>
|
|
</div>
|
|
<div class="section" id="session">
|
|
<h1><a name="session">session</a></h1>
|
|
<p>The <tt class="docutils literal"><span class="pre">session</span></tt> class has the following synopsis:</p>
|
|
<pre class="literal-block">
|
|
class session: public boost::noncopyable
|
|
{
|
|
|
|
session(const fingerprint& print
|
|
= libtorrent::fingerprint("LT", 0, 1, 0, 0));
|
|
|
|
session(
|
|
const fingerprint& print
|
|
, std::pair<int, int> listen_port_range
|
|
, const char* listen_interface = 0);
|
|
|
|
torrent_handle add_torrent(
|
|
torrent_info const& ti
|
|
, boost::filesystem::path const& save_path
|
|
, entry const& resume_data = entry()
|
|
, bool compact_mode = true
|
|
, int block_size = 16 * 1024);
|
|
|
|
torrent_handle add_torrent(
|
|
char const* tracker_url
|
|
, sha1_hash const& info_hash
|
|
, boost::filesystem::path const& save_path
|
|
, entry const& resume_data = entry()
|
|
, bool compact_mode = true
|
|
, int block_size = 16 * 1024);
|
|
|
|
void remove_torrent(torrent_handle const& h);
|
|
|
|
void disable_extensions();
|
|
void enable_extension(peer_connection::extension_index);
|
|
|
|
void set_http_settings(const http_settings& settings);
|
|
|
|
void set_upload_rate_limit(int bytes_per_second);
|
|
void set_download_rate_limit(int bytes_per_second);
|
|
void set_max_uploads(int limit);
|
|
void set_max_connections(int limit);
|
|
void set_max_half_open_connections(int limit);
|
|
|
|
void set_ip_filter(ip_filter const& f);
|
|
|
|
session_status status() const;
|
|
|
|
bool is_listening() const;
|
|
unsigned short listen_port() const;
|
|
bool listen_on(
|
|
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);
|
|
};
|
|
</pre>
|
|
<p>Once it's created, the session object will spawn the main thread that will do all the work.
|
|
The main thread will be idle as long it doesn't have any torrents to participate in.</p>
|
|
<div class="section" id="id7">
|
|
<h2><a name="id7">session()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
session(fingerprint const& print = libtorrent::fingerprint("LT", 0, 1, 0, 0));
|
|
session(fingerprint const& print
|
|
, std::pair<int, int> listen_port_range
|
|
, char const* listen_interface = 0);
|
|
</pre>
|
|
</blockquote>
|
|
<p>If the fingerprint in the first overload is ommited, the client will get a default
|
|
fingerprint stating the version of libtorrent. The fingerprint is a short string that will be
|
|
used in the peer-id to identify the client and the client's version. For more details see the
|
|
<a class="reference" href="#fingerprint">fingerprint</a> class. The constructor that only takes a fingerprint will not open a
|
|
listen port for the session, to get it running you'll have to call <tt class="docutils literal"><span class="pre">session::listen_on()</span></tt>.
|
|
The other constructor, that takes a port range and an interface as well as the fingerprint
|
|
will automatically try to listen on a port on the given interface. For more information about
|
|
the parameters, see <tt class="docutils literal"><span class="pre">listen_on()</span></tt> function.</p>
|
|
</div>
|
|
<div class="section" id="id8">
|
|
<h2><a name="id8">~session()</a></h2>
|
|
<p>The destructor of session will notify all trackers that our torrents have been shut down.
|
|
If some trackers are down, they will time out. All this before the destructor of session
|
|
returns. So, it's adviced that any kind of interface (such as windows) are closed before
|
|
destructing the sessoin object. Because it can take a few second for it to finish. The
|
|
timeout can be set with <tt class="docutils literal"><span class="pre">set_http_settings()</span></tt>.</p>
|
|
</div>
|
|
<div class="section" id="add-torrent">
|
|
<h2><a name="add-torrent">add_torrent()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
torrent_handle add_torrent(
|
|
torrent_info const& ti
|
|
, boost::filesystem::path const& save_path
|
|
, entry const& resume_data = entry()
|
|
, bool compact_mode = true
|
|
, int block_size = 16 * 1024);
|
|
|
|
torrent_handle add_torrent(
|
|
char const* tracker_url
|
|
, sha1_hash const& info_hash
|
|
, boost::filesystem::path const& save_path
|
|
, entry const& resume_data = entry()
|
|
, bool compact_mode = true
|
|
, int block_size = 16 * 1024);
|
|
</pre>
|
|
</blockquote>
|
|
<p>You add torrents through the <tt class="docutils literal"><span class="pre">add_torrent()</span></tt> function where you give an
|
|
object representing the information found in the torrent file and the path where you
|
|
want to save the files. The <tt class="docutils literal"><span class="pre">save_path</span></tt> will be prepended to the directory
|
|
structure in the torrent-file.</p>
|
|
<p>If the torrent you are trying to add already exists in the session (is either queued
|
|
for checking, being checked or downloading) <tt class="docutils literal"><span class="pre">add_torrent()</span></tt> will throw
|
|
<a class="reference" href="#duplicate-torrent">duplicate_torrent</a> which derives from <tt class="docutils literal"><span class="pre">std::exception</span></tt>.</p>
|
|
<p>The optional parameter, <tt class="docutils literal"><span class="pre">resume_data</span></tt> can be given if up to date fast-resume data
|
|
is available. The fast-resume data can be acquired from a running torrent by calling
|
|
<tt class="docutils literal"><span class="pre">torrent_handle::write_resume_data()</span></tt>. See <a class="reference" href="#fast-resume">fast resume</a>.</p>
|
|
<p>The <tt class="docutils literal"><span class="pre">compact_mode</span></tt> paramater refers to the layout of the storage for this torrent. If
|
|
set to true (default), the storage will grow as more pieces are downloaded, and pieces
|
|
are rearranged to finally be in their correct places once the entire torrent has been
|
|
downloaded. If it is false, the entire storage is allocated before download begins. I.e.
|
|
the files contained in the torrent are filled with zeroes, and each downloaded piece
|
|
is put in its final place directly when downloaded. For more info, see <a class="reference" href="#storage-allocation">storage allocation</a>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">block_size</span></tt> sets the preferred request size, i.e. the number of bytes to request from
|
|
a peer at a time. This block size must be a divisor of the piece size, and since the piece
|
|
size is an even power of 2, so must the block size be. If the block size given here turns
|
|
out to be greater than the piece size, it will simply be clamped to the piece size.</p>
|
|
<p>The <a class="reference" href="#torrent-handle">torrent_handle</a> returned by <tt class="docutils literal"><span class="pre">add_torrent()</span></tt> can be used to retrieve information
|
|
about the torrent's progress, its peers etc. It is also used to abort a torrent.</p>
|
|
<p>The second overload that takes a tracker url and an info-hash instead of metadata
|
|
(<tt class="docutils literal"><span class="pre">torrent_info</span></tt>) can be used with torrents where (at least some) peers support
|
|
the metadata extension. For the overload to be available, libtorrent must be built
|
|
with extensions enabled (<tt class="docutils literal"><span class="pre">TORRENT_ENABLE_EXTENSIONS</span></tt> defined).</p>
|
|
</div>
|
|
<div class="section" id="remove-torrent">
|
|
<h2><a name="remove-torrent">remove_torrent()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void remove_torrent(torrent_handle const& h);
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">remove_torrent()</span></tt> will close all peer connections associated with the torrent and tell
|
|
the tracker that we've stopped participating in the swarm.</p>
|
|
</div>
|
|
<div class="section" id="disable-extensions-enable-extension">
|
|
<h2><a name="disable-extensions-enable-extension">disable_extensions() enable_extension()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void disable_extensions();
|
|
void enable_extension(peer_connection::extension_index);
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">disable_extensions()</span></tt> will disable all extensions available in libtorrent.
|
|
<tt class="docutils literal"><span class="pre">enable_extension()</span></tt> will enable a single extension. The available extensions
|
|
are enumerated in the <tt class="docutils literal"><span class="pre">peer_connection</span></tt> class. These are the available extensions:</p>
|
|
<pre class="literal-block">
|
|
enum extension_index
|
|
{
|
|
extended_chat_message,
|
|
extended_metadata_message,
|
|
extended_peer_exchange_message,
|
|
extended_listen_port_message,
|
|
num_supported_extensions
|
|
};
|
|
</pre>
|
|
<p><em>peer_exchange is not implemented yet</em></p>
|
|
<p>By default, all extensions are enabled.
|
|
For more information about the extensions, see the <a class="reference" href="#extensions">extensions</a> section.</p>
|
|
</div>
|
|
<div class="section" id="set-upload-rate-limit-set-download-rate-limit">
|
|
<h2><a name="set-upload-rate-limit-set-download-rate-limit">set_upload_rate_limit() set_download_rate_limit()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void set_upload_rate_limit(int bytes_per_second);
|
|
void set_download_rate_limit(int bytes_per_second);
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">set_upload_rate_limit()</span></tt> set the maximum number of bytes allowed to be
|
|
sent to peers per second. This bandwidth is distributed among all the peers. If
|
|
you don't want to limit upload rate, you can set this to -1 (the default).
|
|
<tt class="docutils literal"><span class="pre">set_download_rate_limit()</span></tt> works the same way but for download rate instead
|
|
of upload rate.</p>
|
|
</div>
|
|
<div class="section" id="set-max-uploads-set-max-connections">
|
|
<h2><a name="set-max-uploads-set-max-connections">set_max_uploads() set_max_connections()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void set_max_uploads(int limit);
|
|
void set_max_connections(int limit);
|
|
</pre>
|
|
</blockquote>
|
|
<p>These functions will set a global limit on the number of unchoked peers (uploads)
|
|
and the number of connections opened. The number of connections is set to a hard
|
|
minimum of at least two connections per torrent, so if you set a too low
|
|
connections limit, and open too many torrents, the limit will not be met. The
|
|
number of uploads is at least one per torrent.</p>
|
|
</div>
|
|
<div class="section" id="set-max-half-open-connections">
|
|
<h2><a name="set-max-half-open-connections">set_max_half_open_connections()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void set_max_half_open_connections(int limit);
|
|
</pre>
|
|
</blockquote>
|
|
<p>Sets the maximum number of half-open connections libtorrent will have when
|
|
connecting to peers. A half-open connection is one where connect() has been
|
|
called, but the connection still hasn't been established (nor filed). Windows
|
|
XP Service Pack 2 sets a defaul, system wide, limit of the number of half-open
|
|
connections to 10. So, this limit can be used to work nicer together with
|
|
other network applications on that system. The default is to have no limit,
|
|
and passing -1 as the limit, means to have no limit. When limiting the number
|
|
of simultaneous connection attempts, peers will be put in a queue waiting for
|
|
their turn to get connected.</p>
|
|
</div>
|
|
<div class="section" id="set-ip-filter">
|
|
<h2><a name="set-ip-filter">set_ip_filter()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void set_ip_filter(ip_filter const& filter);
|
|
</pre>
|
|
</blockquote>
|
|
<p>Sets a filter that will be used to reject and accept incoming as well as outgoing
|
|
connections based on their originating ip address. The default filter will allow
|
|
connections to any ip address. To build a set of rules for which addresses are
|
|
accepted and not, see <a class="reference" href="#ip-filter">ip_filter</a>.</p>
|
|
</div>
|
|
<div class="section" id="status">
|
|
<h2><a name="status">status()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
session_status status() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">status()</span></tt> returns session wide-statistics and status. The <tt class="docutils literal"><span class="pre">session_status</span></tt>
|
|
struct has the following members:</p>
|
|
<pre class="literal-block">
|
|
struct session_status
|
|
{
|
|
bool has_incoming_connections;
|
|
|
|
float upload_rate;
|
|
float download_rate;
|
|
|
|
float payload_upload_rate;
|
|
float payload_download_rate;
|
|
|
|
size_type total_download;
|
|
size_type total_upload;
|
|
|
|
size_type total_payload_download;
|
|
size_type total_payload_upload;
|
|
|
|
int num_peers;
|
|
};
|
|
</pre>
|
|
<p><tt class="docutils literal"><span class="pre">has_incoming_connections</span></tt> is false as long as no incoming connections have been
|
|
established on the listening socket. Every time you change the listen port, this will
|
|
be reset to false.</p>
|
|
<p><tt class="docutils literal"><span class="pre">upload_rate</span></tt>, <tt class="docutils literal"><span class="pre">download_rate</span></tt>, <tt class="docutils literal"><span class="pre">payload_download_rate</span></tt> and <tt class="docutils literal"><span class="pre">payload_upload_rate</span></tt>
|
|
are the total download and upload rates accumulated from all torrents. The payload
|
|
versions is the payload download only.</p>
|
|
<p><tt class="docutils literal"><span class="pre">total_download</span></tt> and <tt class="docutils literal"><span class="pre">total_upload</span></tt> are the total number of bytes downloaded and
|
|
uploaded to and from all torrents. <tt class="docutils literal"><span class="pre">total_payload_download</span></tt> and <tt class="docutils literal"><span class="pre">total_payload_upload</span></tt>
|
|
are the same thing but where only the payload is considered.</p>
|
|
<p><tt class="docutils literal"><span class="pre">num_peers</span></tt> is the total number of peer connections this session have.</p>
|
|
</div>
|
|
<div class="section" id="is-listening-listen-port-listen-on">
|
|
<h2><a name="is-listening-listen-port-listen-on">is_listening() listen_port() listen_on()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
bool is_listening() const;
|
|
unsigned short listen_port() const;
|
|
bool listen_on(
|
|
std::pair<int, int> const& port_range
|
|
, char const* interface = 0);
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">is_listening()</span></tt> will tell you wether or not the session has successfully
|
|
opened a listening port. If it hasn't, this function will return false, and
|
|
then you can use <tt class="docutils literal"><span class="pre">listen_on()</span></tt> to make another try.</p>
|
|
<p><tt class="docutils literal"><span class="pre">listen_port()</span></tt> returns the port we ended up listening on. Since you just pass
|
|
a port-range to the constructor and to <tt class="docutils literal"><span class="pre">listen_on()</span></tt>, to know which port it
|
|
ended up using, you have to ask the session using this function.</p>
|
|
<p><tt class="docutils literal"><span class="pre">listen_on()</span></tt> will change the listen port and/or the listen interface. If the
|
|
session is already listening on a port, this socket will be closed and a new socket
|
|
will be opened with these new settings. The port range is the ports it will try
|
|
to listen on, if the first port fails, it will continue trying the next port within
|
|
the range and so on. The interface parameter can be left as 0, in that case the
|
|
os will decide which interface to listen on, otherwise it should be the ip-address
|
|
of the interface you want the listener socket bound to. <tt class="docutils literal"><span class="pre">listen_on()</span></tt> returns true
|
|
if it managed to open the socket, and false if it failed. If it fails, it will also
|
|
generate an appropriate alert (<a class="reference" href="#listen-failed-alert">listen_failed_alert</a>).</p>
|
|
<p>The interface parameter can also be a hostname that will resolve to the device you
|
|
want to listen on.</p>
|
|
</div>
|
|
<div class="section" id="pop-alert-set-severity-level">
|
|
<h2><a name="pop-alert-set-severity-level">pop_alert() set_severity_level()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
std::auto_ptr<alert> pop_alert();
|
|
void set_severity_level(alert::severity_t s);
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">pop_alert()</span></tt> is used to ask the session if any errors or events has occured. With
|
|
<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>
|
|
<div class="section" id="entry">
|
|
<h1><a name="entry">entry</a></h1>
|
|
<p>The <tt class="docutils literal"><span class="pre">entry</span></tt> class represents one node in a bencoded hierarchy. It works as a
|
|
variant type, it can be either a list, a dictionary (<tt class="docutils literal"><span class="pre">std::map</span></tt>), an integer
|
|
or a string. This is its synopsis:</p>
|
|
<pre class="literal-block">
|
|
class entry
|
|
{
|
|
public:
|
|
|
|
typedef std::map<std::string, entry> dictionary_type;
|
|
typedef std::string string_type;
|
|
typedef std::list<entry> list_type;
|
|
typedef size_type integer_type;
|
|
|
|
enum data_type
|
|
{
|
|
int_t,
|
|
string_t,
|
|
list_t,
|
|
dictionary_t,
|
|
undefined_t
|
|
};
|
|
|
|
data_type type() const;
|
|
|
|
entry(dictionary_type const&);
|
|
entry(string_type const&);
|
|
entry(list_type const&);
|
|
entry(integer_type const&);
|
|
|
|
entry();
|
|
entry(data_type t);
|
|
entry(entry const& e);
|
|
~entry();
|
|
|
|
void operator=(entry const& e);
|
|
void operator=(dictionary_type const&);
|
|
void operator=(string_type const&);
|
|
void operator=(list_type const&);
|
|
void operator=(integer_type const&);
|
|
|
|
integer_type& integer();
|
|
integer_type const& integer() const;
|
|
string_type& string();
|
|
string_type const& string() const;
|
|
list_type& list();
|
|
list_type const& list() const;
|
|
dictionary_type& dict();
|
|
dictionary_type const& dict() const;
|
|
|
|
// these functions requires that the entry
|
|
// is a dictionary, otherwise they will throw
|
|
entry& operator[](char const* key);
|
|
entry& operator[](std::string const& key);
|
|
entry const& operator[](char const* key) const;
|
|
entry const& operator[](std::string const& key) const;
|
|
entry* find_key(char const* key);
|
|
entry const* find_key(char const* key) const;
|
|
|
|
void print(std::ostream& os, int indent = 0) const;
|
|
};
|
|
</pre>
|
|
<p><em>TODO: finish documentation of entry.</em></p>
|
|
<div class="section" id="integer-string-list-dict-type">
|
|
<h2><a name="integer-string-list-dict-type">integer() string() list() dict() type()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
integer_type& integer();
|
|
integer_type const& integer() const;
|
|
string_type& string();
|
|
string_type const& string() const;
|
|
list_type& list();
|
|
list_type const& list() const;
|
|
dictionary_type& dict();
|
|
dictionary_type const& dict() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>The <tt class="docutils literal"><span class="pre">integer()</span></tt>, <tt class="docutils literal"><span class="pre">string()</span></tt>, <tt class="docutils literal"><span class="pre">list()</span></tt> and <tt class="docutils literal"><span class="pre">dict()</span></tt> functions
|
|
are accessors that return the respecive type. If the <tt class="docutils literal"><span class="pre">entry</span></tt> object isn't of the
|
|
type you request, the accessor will throw <a class="reference" href="#type-error">type_error</a> (which derives from
|
|
<tt class="docutils literal"><span class="pre">std::runtime_error</span></tt>). You can ask an <tt class="docutils literal"><span class="pre">entry</span></tt> for its type through the
|
|
<tt class="docutils literal"><span class="pre">type()</span></tt> function.</p>
|
|
<p>The <tt class="docutils literal"><span class="pre">print()</span></tt> function is there for debug purposes only.</p>
|
|
<p>If you want to create an <tt class="docutils literal"><span class="pre">entry</span></tt> you give it the type you want it to have in its
|
|
constructor, and then use one of the non-const accessors to get a reference which you then
|
|
can assign the value you want it to have.</p>
|
|
<p>The typical code to get info from a torrent file will then look like this:</p>
|
|
<pre class="literal-block">
|
|
entry torrent_file;
|
|
// ...
|
|
|
|
// throws if this is not a dictionary
|
|
entry::dictionary_type const& dict = torrent_file.dict();
|
|
entry::dictionary_type::const_iterator i;
|
|
i = dict.find("announce");
|
|
if (i != dict.end())
|
|
{
|
|
std::string tracker_url = i->second.string();
|
|
std::cout << tracker_url << "\n";
|
|
}
|
|
</pre>
|
|
<p>The following code is equivalent, but a little bit shorter:</p>
|
|
<pre class="literal-block">
|
|
entry torrent_file;
|
|
// ...
|
|
|
|
// throws if this is not a dictionary
|
|
if (entry* i = torrent_file.find_key("announce"))
|
|
{
|
|
std::string tracker_url = i->string();
|
|
std::cout << tracker_url << "\n";
|
|
}
|
|
</pre>
|
|
<p>To make it easier to extract information from a torrent file, the class <a class="reference" href="#torrent-info">torrent_info</a>
|
|
exists.</p>
|
|
</div>
|
|
<div class="section" id="operator">
|
|
<h2><a name="operator">operator[]</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
entry& operator[](char const* key);
|
|
entry& operator[](std::string const& key);
|
|
entry const& operator[](char const* key) const;
|
|
entry const& operator[](std::string const& key) const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>All of these functions requires the entry to be a dictionary, if it isn't they
|
|
will throw <tt class="docutils literal"><span class="pre">libtorrent::type_error</span></tt>.</p>
|
|
<p>The non-const versions of the <tt class="docutils literal"><span class="pre">operator[]</span></tt> will return a reference to either
|
|
the existing element at the given key or, if there is no element with the
|
|
given key, a reference to a newly inserted element at that key.</p>
|
|
<p>The const version of <tt class="docutils literal"><span class="pre">operator[]</span></tt> will only return a reference to an
|
|
existing element at the given key. If the key is not found, it will throw
|
|
<tt class="docutils literal"><span class="pre">libtorrent::type_error</span></tt>.</p>
|
|
</div>
|
|
<div class="section" id="find-key">
|
|
<h2><a name="find-key">find_key()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
entry* find_key(char const* key);
|
|
entry const* find_key(char const* key) const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>These functions requires the entry to be a dictionary, if it isn't they
|
|
will throw <tt class="docutils literal"><span class="pre">libtorrent::type_error</span></tt>.</p>
|
|
<p>They will look for an element at the given key in the dictionary, if the
|
|
element cannot be found, they will return 0. If an element with the given
|
|
key is found, the return a pointer to it.</p>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="torrent-info">
|
|
<h1><a name="torrent-info">torrent_info</a></h1>
|
|
<p>The <tt class="docutils literal"><span class="pre">torrent_info</span></tt> has the following synopsis:</p>
|
|
<pre class="literal-block">
|
|
class torrent_info
|
|
{
|
|
public:
|
|
|
|
torrent_info();
|
|
torrent_info(sha1_hash const& info_hash);
|
|
torrent_info(entry const& torrent_file);
|
|
|
|
entry create_torrent() const;
|
|
void set_comment(char const* str);
|
|
void set_piece_size(int size);
|
|
void set_creator(char const* str);
|
|
void set_hash(int index, sha1_hash const& h);
|
|
void add_tracker(std::string const& url, int tier = 0);
|
|
void add_file(boost::filesystem::path file, size_type size);
|
|
|
|
typedef std::vector<file_entry>::const_iterator file_iterator;
|
|
typedef std::vector<file_entry>::const_reverse_iterator
|
|
reverse_file_iterator;
|
|
|
|
file_iterator begin_files() const;
|
|
file_iterator end_files() const;
|
|
reverse_file_iterator rbegin_files() const;
|
|
reverse_file_iterator rend_files() const;
|
|
|
|
int num_files() const;
|
|
file_entry const& file_at(int index) const;
|
|
|
|
std::vector<announce_entry> const& trackers() const;
|
|
|
|
size_type total_size() const;
|
|
size_type piece_length() const;
|
|
int num_pieces() const;
|
|
sha1_hash const& info_hash() const;
|
|
std::stirng const& name() const;
|
|
std::string const& comment() const;
|
|
std::string const& creator() const;
|
|
|
|
boost::optional<boost::posix_time::ptime>
|
|
creation_date() const;
|
|
|
|
|
|
void print(std::ostream& os) const;
|
|
|
|
size_type piece_size(unsigned int index) const;
|
|
sha1_hash const& hash_for_piece(unsigned int index) const;
|
|
};
|
|
</pre>
|
|
<div class="section" id="id9">
|
|
<h2><a name="id9">torrent_info()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
torrent_info();
|
|
torrent_info(sha1_hash const& info_hash);
|
|
torrent_info(entry const& torrent_file);
|
|
</pre>
|
|
</blockquote>
|
|
<p>The default constructor of <tt class="docutils literal"><span class="pre">torrent_info</span></tt> is used when creating torrent files. It will
|
|
initialize the object to an empty torrent, containing no files. The info hash will be set
|
|
to 0 when this constructor is used. To use the empty <tt class="docutils literal"><span class="pre">torrent_info</span></tt> object, add files
|
|
and piece hashes, announce URLs and optionally a creator tag and comment. To do this you
|
|
use the members <tt class="docutils literal"><span class="pre">set_comment()</span></tt>, <tt class="docutils literal"><span class="pre">set_piece_size()</span></tt>, <tt class="docutils literal"><span class="pre">set_creator()</span></tt>, <tt class="docutils literal"><span class="pre">set_hash()</span></tt>
|
|
etc.</p>
|
|
<p>The contructor that takes an info-hash is identical to the default constructor with the
|
|
exception that it will initialize the info-hash to the given value. This is used internally
|
|
when downloading torrents without the metadata. The metadata will be created by libtorrent
|
|
as soon as it has been downloaded from the swarm.</p>
|
|
<p>The last constructor is the one that is used in most cases. It will create a <tt class="docutils literal"><span class="pre">torrent_info</span></tt>
|
|
object from the information found in the given torrent_file. The <tt class="docutils literal"><span class="pre">entry</span></tt> represents a tree
|
|
node in an bencoded file. To load an ordinary .torrent file into an <tt class="docutils literal"><span class="pre">entry</span></tt>, use bdecode(),
|
|
see <a class="reference" href="#bdecode-bencode">bdecode() bencode()</a>.</p>
|
|
</div>
|
|
<div class="section" id="set-comment-set-piece-size-set-creator-set-hash-add-tracker-add-file">
|
|
<h2><a name="set-comment-set-piece-size-set-creator-set-hash-add-tracker-add-file">set_comment() set_piece_size() set_creator() set_hash() add_tracker() add_file()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void set_comment(char const* str);
|
|
void set_piece_size(int size);
|
|
void set_creator(char const* str);
|
|
void set_hash(int index, sha1_hash const& h);
|
|
void add_tracker(std::string const& url, int tier = 0);
|
|
void add_file(boost::filesystem::path file, size_type size);
|
|
</pre>
|
|
</blockquote>
|
|
<p>These files are used when creating a torrent file. <tt class="docutils literal"><span class="pre">set_comment()</span></tt> will simply set
|
|
the comment that belongs to this torrent. The comment can be retrieved with the
|
|
<tt class="docutils literal"><span class="pre">comment()</span></tt> member. The string should be UTF-8 encoded.</p>
|
|
<p><tt class="docutils literal"><span class="pre">set_piece_size()</span></tt> will set the size of each piece in this torrent. The piece size must
|
|
be an even multiple of 2. i.e. usually something like 256 kiB, 512 kiB, 1024 kiB etc. The
|
|
size is given in number of bytes.</p>
|
|
<p><tt class="docutils literal"><span class="pre">set_creator()</span></tt> is an optional attribute that can be used to identify your application
|
|
that was used to create the torrent file. The string should be UTF-8 encoded.</p>
|
|
<p><tt class="docutils literal"><span class="pre">set_hash()</span></tt> writes the hash for the piece with the given piece-index. You have to call
|
|
this function for every piece in the torrent. Usually the <a class="reference" href="#hasher">hasher</a> is used to calculate
|
|
the sha1-hash for a piece.</p>
|
|
<p><tt class="docutils literal"><span class="pre">add_tracker()</span></tt> adds a tracker to the announce-list. The <tt class="docutils literal"><span class="pre">tier</span></tt> determines the order in
|
|
which the trackers are to be tried. For more iformation see <a class="reference" href="#trackers">trackers()</a>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">add_file()</span></tt> adds a file to the torrent. The order in which you add files will determine
|
|
the order in which they are placed in the torrent file. You have to add at least one file
|
|
to the torrent. The <tt class="docutils literal"><span class="pre">path</span></tt> you give has to be a relative path from the root directory
|
|
of the torrent. The <tt class="docutils literal"><span class="pre">size</span></tt> is given in bytes.</p>
|
|
<p>When you have added all the files and hashes to your torrent, you can generate an <tt class="docutils literal"><span class="pre">entry</span></tt>
|
|
which then can be encoded as a .torrent file. You do this by calling <a class="reference" href="#create-torrent">create_torrent()</a>.</p>
|
|
<p>For a complete example of how to create a torrent from a file structure, see <a class="reference" href="#make-torrent">make_torrent</a>.</p>
|
|
</div>
|
|
<div class="section" id="create-torrent">
|
|
<h2><a name="create-torrent">create_torrent()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
entry create_torrent();
|
|
</pre>
|
|
</blockquote>
|
|
<p>Returns an <tt class="docutils literal"><span class="pre">entry</span></tt> representing the bencoded tree of data that makes up a .torrent file.
|
|
You can save this data as a torrent file with bencode() (see <a class="reference" href="#bdecode-bencode">bdecode() bencode()</a>), for a
|
|
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>
|
|
</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>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
file_iterator begin_files() const;
|
|
file_iterator end_files() const;
|
|
reverse_file_iterator rbegin_files() const;
|
|
reverse_file_iterator rend_files() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>This class will need some explanation. First of all, to get a list of all files
|
|
in the torrent, you can use <tt class="docutils literal"><span class="pre">begin_files()</span></tt>, <tt class="docutils literal"><span class="pre">end_files()</span></tt>,
|
|
<tt class="docutils literal"><span class="pre">rbegin_files()</span></tt> and <tt class="docutils literal"><span class="pre">rend_files()</span></tt>. These will give you standard vector
|
|
iterators with the type <tt class="docutils literal"><span class="pre">file_entry</span></tt>.</p>
|
|
<p>The <tt class="docutils literal"><span class="pre">path</span></tt> is the full (relative) path of each file. i.e. if it is a multi-file
|
|
torrent, all the files starts with a directory with the same name as <tt class="docutils literal"><span class="pre">torrent_info::name()</span></tt>.
|
|
The filenames are encoded with UTF-8.</p>
|
|
<pre class="literal-block">
|
|
struct file_entry
|
|
{
|
|
boost::filesystem::path path;
|
|
size_type size;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="num-files-file-at">
|
|
<h2><a name="num-files-file-at">num_files() file_at()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
int num_files() const;
|
|
file_entry const& file_at(int index) const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>If you need index-access to files you can use the <tt class="docutils literal"><span class="pre">num_files()</span></tt> and <tt class="docutils literal"><span class="pre">file_at()</span></tt>
|
|
to access files using indices.</p>
|
|
</div>
|
|
<div class="section" id="print">
|
|
<h2><a name="print">print()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void print(std::ostream& os) const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>The <tt class="docutils literal"><span class="pre">print()</span></tt> function is there for debug purposes only. It will print the info from
|
|
the torrent file to the given outstream.</p>
|
|
</div>
|
|
<div class="section" id="trackers">
|
|
<h2><a name="trackers">trackers()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
std::vector<announce_entry> const& trackers() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>The <tt class="docutils literal"><span class="pre">trackers()</span></tt> function will return a sorted vector of <tt class="docutils literal"><span class="pre">announce_entry</span></tt>.
|
|
Each announce entry contains a string, which is the tracker url, and a tier index. The
|
|
tier index is the high-level priority. No matter which trackers that works or not, the
|
|
ones with lower tier will always be tried before the one with higher tier number.</p>
|
|
<pre class="literal-block">
|
|
struct announce_entry
|
|
{
|
|
announce_entry(std::string const& url);
|
|
std::string url;
|
|
int tier;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="total-size-piece-length-piece-size-num-pieces">
|
|
<h2><a name="total-size-piece-length-piece-size-num-pieces">total_size() piece_length() piece_size() num_pieces()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
size_type total_size() const;
|
|
size_type piece_length() const;
|
|
size_type piece_size(unsigned int index) const;
|
|
int num_pieces() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">total_size()</span></tt>, <tt class="docutils literal"><span class="pre">piece_length()</span></tt> and <tt class="docutils literal"><span class="pre">num_pieces()</span></tt> returns the total
|
|
number of bytes the torrent-file represents (all the files in it), the number of byte for
|
|
each piece and the total number of pieces, respectively. The difference between
|
|
<tt class="docutils literal"><span class="pre">piece_size()</span></tt> and <tt class="docutils literal"><span class="pre">piece_length()</span></tt> is that <tt class="docutils literal"><span class="pre">piece_size()</span></tt> takes
|
|
the piece index as argument and gives you the exact size of that piece. It will always
|
|
be the same as <tt class="docutils literal"><span class="pre">piece_length()</span></tt> except in the case of the last piece, which may
|
|
be smaller.</p>
|
|
</div>
|
|
<div class="section" id="hash-for-piece-info-hash">
|
|
<h2><a name="hash-for-piece-info-hash">hash_for_piece() info_hash()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
size_type piece_size(unsigned int index) const;
|
|
sha1_hash const& hash_for_piece(unsigned int index) const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">hash_for_piece()</span></tt> takes a piece-index and returns the 20-bytes sha1-hash for that
|
|
piece and <tt class="docutils literal"><span class="pre">info_hash()</span></tt> returns the 20-bytes sha1-hash for the info-section of the
|
|
torrent file. For more information on the <tt class="docutils literal"><span class="pre">sha1_hash</span></tt>, see the <a class="reference" href="#big-number">big_number</a> class.</p>
|
|
</div>
|
|
<div class="section" id="name-comment-creation-date-creator">
|
|
<h2><a name="name-comment-creation-date-creator">name() comment() creation_date() creator()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
std::string const& name() const;
|
|
std::string const& comment() const;
|
|
boost::optional<boost::posix_time::ptime> creation_date() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">name()</span></tt> returns the name of the torrent.</p>
|
|
<p><tt class="docutils literal"><span class="pre">comment()</span></tt> returns the comment associated with the torrent. If there's no comment,
|
|
it will return an empty string. <tt class="docutils literal"><span class="pre">creation_date()</span></tt> returns a <a class="reference" href="http://www.boost.org/libs/date_time/doc/class_ptime.html">boost::posix_time::ptime</a>
|
|
object, representing the time when this torrent file was created. If there's no timestamp
|
|
in the torrent file, this will return a date of january 1:st 1970.</p>
|
|
<p>Both the name and the comment is UTF-8 encoded strings.</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>
|
|
<div class="section" id="torrent-handle">
|
|
<h1><a name="torrent-handle">torrent_handle</a></h1>
|
|
<p>You will usually have to store your torrent handles somewhere, since it's the
|
|
object through which you retrieve infromation about the torrent and aborts the torrent.
|
|
Its declaration looks like this:</p>
|
|
<pre class="literal-block">
|
|
struct torrent_handle
|
|
{
|
|
torrent_handle();
|
|
|
|
torrent_status status();
|
|
void get_download_queue(std::vector<partial_piece_info>& queue) const;
|
|
void get_peer_info(std::vector<peer_info>& v) const;
|
|
torrent_info const& get_torrent_info() const;
|
|
bool is_valid() const;
|
|
|
|
entry write_resume_data() const;
|
|
std::vector<char> const& metadata() const;
|
|
void force_reannounce() const;
|
|
void connect_peer(address const& adr) const;
|
|
|
|
void set_tracker_login(std::string const& username
|
|
, std::string const& password) const;
|
|
|
|
std::vector<announce_entry> const& trackers() const;
|
|
void replace_trackers(std::vector<announce_entry> const&);
|
|
|
|
void set_ratio(float ratio) const;
|
|
void set_max_uploads(int max_uploads) const;
|
|
void set_max_connections(int max_connections) const;
|
|
void set_upload_limit(int limit) const;
|
|
void set_download_limit(int limit) const;
|
|
void use_interface(char const* net_interface) const;
|
|
|
|
void pause() const;
|
|
void resume() const;
|
|
bool is_paused() const;
|
|
bool is_seed() const;
|
|
|
|
void filter_piece(int index, bool filter) const;
|
|
void filter_pieces(std::vector<bool> const& bitmask) const;
|
|
bool is_piece_filtered(int index) const;
|
|
std::vector<bool> filtered_pieces() const;
|
|
|
|
void filter_files(std::vector<bool> const& files) const;
|
|
|
|
bool has_metadata() const;
|
|
|
|
boost::filsystem::path save_path() const;
|
|
bool move_storage(boost::filesystem::path const& save_path) const;
|
|
|
|
sha1_hash info_hash() const;
|
|
|
|
bool operator==(torrent_handle const&) const;
|
|
bool operator!=(torrent_handle const&) const;
|
|
bool operator<(torrent_handle const&) const;
|
|
};
|
|
</pre>
|
|
<p>The default constructor will initialize the handle to an invalid state. Which means you cannot
|
|
perform any operation on it, unless you first assign it a valid handle. If you try to perform
|
|
any operation on an uninitialized handle, it will throw <tt class="docutils literal"><span class="pre">invalid_handle</span></tt>.</p>
|
|
<p><em>TODO: document filter_piece(), filter_pieces(), is_piece_filtered(), filtered_pieces() and filter_files()</em></p>
|
|
<div class="section" id="save-path">
|
|
<h2><a name="save-path">save_path()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
boost::filsystem::path save_path() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">save_path()</span></tt> returns the path that was given to <a class="reference" href="#add-torrent">add_torrent()</a> when this torrent
|
|
was started.</p>
|
|
</div>
|
|
<div class="section" id="move-storage">
|
|
<h2><a name="move-storage">move_storage()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
bool move_storage(boost::filsystem::path const& save_path) const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>Moves the file(s) that this torrent are currently seeding from or downloading to. This
|
|
operation will only have the desired effect if the given <tt class="docutils literal"><span class="pre">save_path</span></tt> is located on
|
|
the same drive as the original save path. If the move operation fails, this function
|
|
returns false, otherwise true. Post condition for successful operation is:
|
|
<tt class="docutils literal"><span class="pre">save_path()</span> <span class="pre">==</span> <span class="pre">save_path</span></tt>.</p>
|
|
</div>
|
|
<div class="section" id="force-reannounce">
|
|
<h2><a name="force-reannounce">force_reannounce()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void force_reannounce() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">force_reannounce()</span></tt> will force this torrent to do another tracker request, to receive new
|
|
peers. If the torrent is invalid, queued or in checking mode, this functions will throw
|
|
<a class="reference" href="#invalid-handle">invalid_handle</a>.</p>
|
|
</div>
|
|
<div class="section" id="connect-peer">
|
|
<h2><a name="connect-peer">connect_peer()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void connect_peer(address const& adr) const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">connect_peer()</span></tt> is a way to manually connect to peers that one believe is a part of the
|
|
torrent. If the peer does not respond, or is not a member of this torrent, it will simply
|
|
be disconnected. No harm can be done by using this other than an unnecessary connection
|
|
attempt is made. If the torrent is uninitialized or in queued or checking mode, this
|
|
will throw <a class="reference" href="#invalid-handle">invalid_handle</a>.</p>
|
|
</div>
|
|
<div class="section" id="set-ratio">
|
|
<h2><a name="set-ratio">set_ratio()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void set_ratio(float ratio) const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">set_ratio()</span></tt> sets the desired download / upload ratio. If set to 0, it is considered being
|
|
infinite. i.e. the client will always upload as much as it can, no matter how much it gets back
|
|
in return. With this setting it will work much like the standard clients.</p>
|
|
<p>Besides 0, the ratio can be set to any number greater than or equal to 1. It means how much to
|
|
attempt to upload in return for each download. e.g. if set to 2, the client will try to upload
|
|
2 bytes for every byte received. The default setting for this is 0, which will make it work
|
|
as a standard client.</p>
|
|
</div>
|
|
<div class="section" id="set-upload-limit-set-download-limit">
|
|
<h2><a name="set-upload-limit-set-download-limit">set_upload_limit() set_download_limit()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void set_upload_limit(int limit) const;
|
|
void set_download_limit(int limit) const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">set_upload_limit</span></tt> will limit the upload bandwidth used by this particular torrent to the
|
|
limit you set. It is given as the number of bytes per second the torrent is allowed to upload.
|
|
<tt class="docutils literal"><span class="pre">set_download_limit</span></tt> works the same way but for download bandwidth instead of upload bandwidth.
|
|
Note that setting a higher limit on a torrent then the global limit (<tt class="docutils literal"><span class="pre">session::set_upload_rate_limit</span></tt>)
|
|
will not override the global rate limit. The torrent can never upload more than the global rate
|
|
limit.</p>
|
|
</div>
|
|
<div class="section" id="pause-resume-is-paused">
|
|
<h2><a name="pause-resume-is-paused">pause() resume() is_paused()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void pause() const;
|
|
void resume() const;
|
|
bool is_paused() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">pause()</span></tt>, and <tt class="docutils literal"><span class="pre">resume()</span></tt> will disconnect all peers and reconnect all peers respectively.
|
|
When a torrent is paused, it will however remember all share ratios to all peers and remember
|
|
all potential (not connected) peers. You can use <tt class="docutils literal"><span class="pre">is_paused()</span></tt> to determine if a torrent
|
|
is currently paused. Torrents may be paused automatically if there is a file error (eg. disk full)
|
|
or something similar. See <a class="reference" href="#file-error-alert">file_error_alert</a>.</p>
|
|
</div>
|
|
<div class="section" id="is-seed">
|
|
<h2><a name="is-seed">is_seed()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
bool is_seed() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>Returns true if the torrent is in seed mode (i.e. if it has finished downloading).</p>
|
|
</div>
|
|
<div class="section" id="has-metadata">
|
|
<h2><a name="has-metadata">has_metadata()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
bool has_metadata() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>Returns true if this torrent has metadata (either it was started from a .torrent file or the
|
|
metadata has been downloaded). The only scenario where this can return false is when the torrent
|
|
was started torrent-less (i.e. with just an info-hash and tracker ip). Note that if the torrent
|
|
doesn't have metadata, the member <a class="reference" href="#get-torrent-info">get_torrent_info()</a> will throw.</p>
|
|
</div>
|
|
<div class="section" id="set-tracker-login">
|
|
<h2><a name="set-tracker-login">set_tracker_login()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void set_tracker_login(std::string const& username
|
|
, std::string const& password) const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">set_tracker_login()</span></tt> sets a username and password that will be sent along in the HTTP-request
|
|
of the tracker announce. Set this if the tracker requires authorization.</p>
|
|
</div>
|
|
<div class="section" id="trackers-replace-trackers">
|
|
<h2><a name="trackers-replace-trackers">trackers() replace_trackers()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
std::vector<announce_entry> const& trackers() const;
|
|
void replace_trackers(std::vector<announce_entry> const&) const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">trackers()</span></tt> will return the list of trackers for this torrent. The
|
|
announce entry contains both a string <tt class="docutils literal"><span class="pre">url</span></tt> which specifu the announce url
|
|
for the tracker as well as an int <tt class="docutils literal"><span class="pre">tier</span></tt>, which is specifies the order in
|
|
which this tracker is tried. If you want libtorrent to use another list of
|
|
trackers for this torrent, you can use <tt class="docutils literal"><span class="pre">replace_trackers()</span></tt> which takes
|
|
a list of the same form as the one returned from <tt class="docutils literal"><span class="pre">trackers()</span></tt> and will
|
|
replace it. If you want an immediate effect, you have to call
|
|
<a class="reference" href="#force-reannounce">force_reannounce()</a>.</p>
|
|
</div>
|
|
<div class="section" id="use-interface">
|
|
<h2><a name="use-interface">use_interface()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void use_interface(char const* net_interface) const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">use_interface()</span></tt> sets the network interface this torrent will use when it opens outgoing
|
|
connections. By default, it uses the same interface as the <a class="reference" href="#session">session</a> uses to listen on. The
|
|
parameter can be a string containing an ip-address or a hostname.</p>
|
|
</div>
|
|
<div class="section" id="info-hash">
|
|
<h2><a name="info-hash">info_hash()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
sha1_hash info_hash() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">info_hash()</span></tt> returns the info-hash for the torrent.</p>
|
|
</div>
|
|
<div class="section" id="id11">
|
|
<h2><a name="id11">set_max_uploads() set_max_connections()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void set_max_uploads(int max_uploads) const;
|
|
void set_max_connections(int max_connections) const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">set_max_uploads()</span></tt> sets the maximum number of peers that's unchoked at the same time on this
|
|
torrent. If you set this to -1, there will be no limit.</p>
|
|
<p><tt class="docutils literal"><span class="pre">set_max_connections()</span></tt> sets the maximum number of connection this torrent will open. If all
|
|
connections are used up, incoming connections may be refused or poor connections may be closed.
|
|
This must be at least 2. The default is unlimited number of connections. If -1 is given to the
|
|
function, it means unlimited.</p>
|
|
</div>
|
|
<div class="section" id="write-resume-data">
|
|
<h2><a name="write-resume-data">write_resume_data()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
entry write_resume_data() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">write_resume_data()</span></tt> generates fast-resume data and returns it as an <a class="reference" href="#entry">entry</a>. This <a class="reference" href="#entry">entry</a>
|
|
is suitable for being bencoded. For more information about how fast-resume works, see <a class="reference" href="#fast-resume">fast resume</a>.</p>
|
|
<p>There are three cases where this function will just return an empty <tt class="docutils literal"><span class="pre">entry</span></tt>:</p>
|
|
<blockquote>
|
|
<ol class="arabic simple">
|
|
<li>The torrent handle is invalid.</li>
|
|
<li>The torrent is checking (or is queued for checking) its storage, it will obviously
|
|
not be ready to write resume data.</li>
|
|
<li>The torrent hasn't received valid metadata and was started without metadata
|
|
(see libtorrent's <a class="reference" href="#metadata-from-peers">metadata from peers</a> extension)</li>
|
|
</ol>
|
|
</blockquote>
|
|
<p>Note that by the time this function returns, the resume data may already be invalid if the torrent
|
|
is still downloading! The recommended practice is to first pause the torrent, then generate the
|
|
fast resume data, and then close it down.</p>
|
|
</div>
|
|
<div class="section" id="metadata">
|
|
<h2><a name="metadata">metadata()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
std::vector<char> const& metadata() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">metadata()</span></tt> will return a reference to a buffer containing the exact info part of the
|
|
.torrent file. This buffer will be valid as long as the torrent is still running. When hashed,
|
|
it will produce the same hash as the info-hash.</p>
|
|
</div>
|
|
<div class="section" id="id12">
|
|
<h2><a name="id12">status()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
torrent_status status() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">status()</span></tt> will return a structure with information about the status of this
|
|
torrent. If the <a class="reference" href="#torrent-handle">torrent_handle</a> is invalid, it will throw <a class="reference" href="#invalid-handle">invalid_handle</a> exception.
|
|
See <a class="reference" href="#torrent-status">torrent_status</a>.</p>
|
|
</div>
|
|
<div class="section" id="get-download-queue">
|
|
<h2><a name="get-download-queue">get_download_queue()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void get_download_queue(std::vector<partial_piece_info>& queue) const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">get_download_queue()</span></tt> takes a non-const reference to a vector which it will fill with
|
|
information about pieces that are partially downloaded or not downloaded at all but partially
|
|
requested. The entry in the vector (<tt class="docutils literal"><span class="pre">partial_piece_info</span></tt>) looks like this:</p>
|
|
<pre class="literal-block">
|
|
struct partial_piece_info
|
|
{
|
|
enum { max_blocks_per_piece };
|
|
int piece_index;
|
|
int blocks_in_piece;
|
|
std::bitset<max_blocks_per_piece> requested_blocks;
|
|
std::bitset<max_blocks_per_piece> finished_blocks;
|
|
address peer[max_blocks_per_piece];
|
|
int num_downloads[max_blocks_per_piece];
|
|
};
|
|
</pre>
|
|
<p><tt class="docutils literal"><span class="pre">piece_index</span></tt> is the index of the piece in question. <tt class="docutils literal"><span class="pre">blocks_in_piece</span></tt> is the
|
|
number of blocks in this particular piece. This number will be the same for most pieces, but
|
|
the last piece may have fewer blocks than the standard pieces.</p>
|
|
<p><tt class="docutils literal"><span class="pre">requested_blocks</span></tt> is a bitset with one bit per block in the piece. If a bit is set, it
|
|
means that that block has been requested, but not necessarily fully downloaded yet. To know
|
|
from whom the block has been requested, have a look in the <tt class="docutils literal"><span class="pre">peer</span></tt> array. The bit-index
|
|
in the <tt class="docutils literal"><span class="pre">requested_blocks</span></tt> and <tt class="docutils literal"><span class="pre">finished_blocks</span></tt> correspons to the array-index into
|
|
<tt class="docutils literal"><span class="pre">peers</span></tt> and <tt class="docutils literal"><span class="pre">num_downloads</span></tt>. The array of peers is contains the address of the
|
|
peer the piece was requested from. If a piece hasn't been requested (the bit in
|
|
<tt class="docutils literal"><span class="pre">requested_blocks</span></tt> is not set) the peer array entry will be undefined.</p>
|
|
<p>The <tt class="docutils literal"><span class="pre">finished_blocks</span></tt> is a bitset where each bit says if the block is fully downloaded
|
|
or not. And the <tt class="docutils literal"><span class="pre">num_downloads</span></tt> array says how many times that block has been downloaded.
|
|
When a piece fails a hash verification, single blocks may be redownloaded to see if the hash teast
|
|
may pass then.</p>
|
|
</div>
|
|
<div class="section" id="get-peer-info">
|
|
<h2><a name="get-peer-info">get_peer_info()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void get_peer_info(std::vector<peer_info>&) const;
|
|
</pre>
|
|
</blockquote>
|
|
<p><tt class="docutils literal"><span class="pre">get_peer_info()</span></tt> takes a reference to a vector that will be cleared and filled
|
|
with one entry for each peer connected to this torrent, given the handle is valid. If the
|
|
<a class="reference" href="#torrent-handle">torrent_handle</a> is invalid, it will throw <a class="reference" href="#invalid-handle">invalid_handle</a> exception. Each entry in
|
|
the vector contains information about that particular peer. See <a class="reference" href="#peer-info">peer_info</a>.</p>
|
|
</div>
|
|
<div class="section" id="get-torrent-info">
|
|
<h2><a name="get-torrent-info">get_torrent_info()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
torrent_info const& get_torrent_info() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>Returns a const reference to the <a class="reference" href="#torrent-info">torrent_info</a> object associated with this torrent.
|
|
This reference is valid as long as the <a class="reference" href="#torrent-handle">torrent_handle</a> is valid, no longer. If the
|
|
<a class="reference" href="#torrent-handle">torrent_handle</a> is invalid or if it doesn't have any metadata, <a class="reference" href="#invalid-handle">invalid_handle</a>
|
|
exception will be thrown. The torrent may be in a state without metadata only if
|
|
it was started without a .torrent file, i.e. by using the libtorrent extension of
|
|
just supplying a tracker and info-hash.</p>
|
|
</div>
|
|
<div class="section" id="is-valid">
|
|
<h2><a name="is-valid">is_valid()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
bool is_valid() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>Returns true if this handle refers to a valid torrent and false if it hasn't been initialized
|
|
or if the torrent it refers to has been aborted. Note that a handle may become invalid after
|
|
it has been added to the session. Usually this is because the storage for the torrent is
|
|
somehow invalid or if the filenames are not allowed (and hence cannot be opened/created) on
|
|
your filesystem. If such an error occurs, a <a class="reference" href="#file-error-alert">file_error_alert</a> is generated and all handles
|
|
that refers to that torrent will become invalid.</p>
|
|
<p><em>TODO: document storage</em></p>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="torrent-status">
|
|
<h1><a name="torrent-status">torrent_status</a></h1>
|
|
<p>It contains the following fields:</p>
|
|
<pre class="literal-block">
|
|
struct torrent_status
|
|
{
|
|
enum state_t
|
|
{
|
|
queued_for_checking,
|
|
checking_files,
|
|
connecting_to_tracker,
|
|
downloading,
|
|
finished,
|
|
seeding,
|
|
allocating
|
|
};
|
|
|
|
state_t state;
|
|
bool paused;
|
|
float progress;
|
|
boost::posix_time::time_duration next_announce;
|
|
boost::posix_time::time_duration announce_interval;
|
|
|
|
std::string current_tracker;
|
|
|
|
size_type total_download;
|
|
size_type total_upload;
|
|
|
|
size_type total_payload_download;
|
|
size_type total_payload_upload;
|
|
|
|
size_type total_failed_bytes;
|
|
|
|
float download_rate;
|
|
float upload_rate;
|
|
|
|
float download_payload_rate;
|
|
float upload_payload_rate;
|
|
|
|
int num_peers;
|
|
|
|
int num_complete;
|
|
int num_incomplete;
|
|
|
|
const std::vector<bool>* pieces;
|
|
size_type total_done;
|
|
size_type total_wanted_done;
|
|
size_type total_wanted;
|
|
|
|
int num_seeds;
|
|
float distributed_copies;
|
|
|
|
int block_size;
|
|
};
|
|
</pre>
|
|
<p><tt class="docutils literal"><span class="pre">progress</span></tt> is a value in the range [0, 1], that represents the progress of the
|
|
torrent's current task. It may be checking files or downloading. The torrent's
|
|
current task is in the <tt class="docutils literal"><span class="pre">state</span></tt> member, it will be one of the following:</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="31%" />
|
|
<col width="69%" />
|
|
</colgroup>
|
|
<tbody valign="top">
|
|
<tr><td><tt class="docutils literal"><span class="pre">queued_for_checking</span></tt></td>
|
|
<td>The torrent is in the queue for being checked. But there
|
|
currently is another torrent that are being checked.
|
|
This torrent will wait for its turn.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">checking_files</span></tt></td>
|
|
<td>The torrent has not started its download yet, and is
|
|
currently checking existing files.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">connecting_to_tracker</span></tt></td>
|
|
<td>The torrent has sent a request to the tracker and is
|
|
currently waiting for a response</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">downloading</span></tt></td>
|
|
<td>The torrent is being downloaded. This is the state
|
|
most torrents will be in most of the time. The progress
|
|
meter will tell how much of the files that has been
|
|
downloaded.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">finished</span></tt></td>
|
|
<td>In this state the torrent has finished downloading but
|
|
still doesn't have the entire torrent. i.e. some pieces
|
|
are filtered and won't get downloaded.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">seeding</span></tt></td>
|
|
<td>In this state the torrent has finished downloading and
|
|
is a pure seeder.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">allocating</span></tt></td>
|
|
<td>If the torrent was started in full allocation mode, this
|
|
indicates that the (disk) storage for the torrent is
|
|
allocated.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>When downloading, the progress is <tt class="docutils literal"><span class="pre">total_wanted_done</span></tt> / <tt class="docutils literal"><span class="pre">total_wanted</span></tt>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">paused</span></tt> is set to true if the torrent is paused and false otherwise.</p>
|
|
<p><tt class="docutils literal"><span class="pre">next_announce</span></tt> is the time until the torrent will announce itself to the tracker. And
|
|
<tt class="docutils literal"><span class="pre">announce_interval</span></tt> is the time the tracker want us to wait until we announce ourself
|
|
again the next time.</p>
|
|
<p><tt class="docutils literal"><span class="pre">current_tracker</span></tt> is the URL of the last working tracker. If no tracker request has
|
|
been successful yet, it's set to an empty string.</p>
|
|
<p><tt class="docutils literal"><span class="pre">total_download</span></tt> and <tt class="docutils literal"><span class="pre">total_upload</span></tt> is the number of bytes downloaded and
|
|
uploaded to all peers, accumulated, <em>this session</em> only.</p>
|
|
<p><tt class="docutils literal"><span class="pre">total_payload_download</span></tt> and <tt class="docutils literal"><span class="pre">total_payload_upload</span></tt> counts the amount of bytes
|
|
send and received this session, but only the actual oayload data (i.e the interesting
|
|
data), these counters ignore any protocol overhead.</p>
|
|
<p><tt class="docutils literal"><span class="pre">total_failed_bytes</span></tt> is the number of bytes that has been downloaded and that
|
|
has failed the piece hash test. In other words, this is just how much crap that
|
|
has been downloaded.</p>
|
|
<p><tt class="docutils literal"><span class="pre">pieces</span></tt> is the bitmask that represents which pieces we have (set to true) and
|
|
the pieces we don't have. It's a pointer and may be set to 0 if the torrent isn't
|
|
downloading or seeding.</p>
|
|
<p><tt class="docutils literal"><span class="pre">download_rate</span></tt> and <tt class="docutils literal"><span class="pre">upload_rate</span></tt> are the total rates for all peers for this
|
|
torrent. These will usually have better precision than summing the rates from
|
|
all peers. The rates are given as the number of bytes per second. The
|
|
<tt class="docutils literal"><span class="pre">download_payload_rate</span></tt> and <tt class="docutils literal"><span class="pre">upload_payload_rate</span></tt> respectively is the
|
|
total transfer rate of payload only, not counting protocol chatter. This might
|
|
be slightly smaller than the other rates, but if projected over a long time
|
|
(e.g. when calculating ETA:s) the difference may be noticable.</p>
|
|
<p><tt class="docutils literal"><span class="pre">num_peers</span></tt> is the number of peers this torrent currently is connected to.</p>
|
|
<p><tt class="docutils literal"><span class="pre">num_complete</span></tt> and <tt class="docutils literal"><span class="pre">num_incomplete</span></tt> are set to -1 if the tracker did not
|
|
send any scrape data in its announce reply. This data is optional and may
|
|
not be available from all trackers. If these are not -1, they are the total
|
|
number of peers that are seeding (complete) and the total number of peers
|
|
that are still downloading (incomplete) this torrent.</p>
|
|
<p><tt class="docutils literal"><span class="pre">total_done</span></tt> is the total number of bytes of the file(s) that we have. All
|
|
this does not necessarily has to be downloaded during this session (that's
|
|
<tt class="docutils literal"><span class="pre">total_download_payload</span></tt>).</p>
|
|
<p><tt class="docutils literal"><span class="pre">total_wanted_done</span></tt> is the number of bytes we have downloadd, only counting the
|
|
pieces that we actually want to download. i.e. excluding any pieces that we have but
|
|
are filtered as not wanted.</p>
|
|
<p><tt class="docutils literal"><span class="pre">total_wanted</span></tt> is the total number of bytes we want to download. This is also
|
|
excluding pieces that have been filtered.</p>
|
|
<p><tt class="docutils literal"><span class="pre">num_seeds</span></tt> is the number of peers that are seeding that this client is
|
|
currently connected to.</p>
|
|
<p><tt class="docutils literal"><span class="pre">distributed_copies</span></tt> is the number of distributed copies of the torrent.
|
|
Note that one copy may be spread out among many peers. The integer part
|
|
tells how many copies there are currently of the rarest piece(s) among the
|
|
peers this client is connected to. The fractional part tells the share of
|
|
pieces that have more copies than the rarest piece(s). For example: 2.5 would
|
|
mean that the rarest pieces have only 2 copies among the peers this torrent is
|
|
connected to, and that 50% of all the pieces have more than two copies.</p>
|
|
<p><tt class="docutils literal"><span class="pre">block_size</span></tt> is the size of a block, in bytes. A block is a sub piece, it
|
|
is the number of bytes that each piece request asks for and the number of
|
|
bytes that each bit in the <tt class="docutils literal"><span class="pre">partial_piece_info</span></tt>'s bitset represents
|
|
(see <a class="reference" href="#get-download-queue">get_download_queue()</a>). This is typically 16 kB, but it may be
|
|
larger if the pieces are larger.</p>
|
|
</div>
|
|
<div class="section" id="peer-info">
|
|
<h1><a name="peer-info">peer_info</a></h1>
|
|
<p>It contains the following fields:</p>
|
|
<pre class="literal-block">
|
|
struct peer_info
|
|
{
|
|
enum
|
|
{
|
|
interesting = 0x1,
|
|
choked = 0x2,
|
|
remote_interested = 0x4,
|
|
remote_choked = 0x8,
|
|
supports_extensions = 0x10,
|
|
local_connection = 0x20,
|
|
connecting = 0x40,
|
|
queued = 0x80
|
|
};
|
|
unsigned int flags;
|
|
address ip;
|
|
float up_speed;
|
|
float down_speed;
|
|
float payload_up_speed;
|
|
float payload_down_speed;
|
|
size_type total_download;
|
|
size_type total_upload;
|
|
peer_id id;
|
|
std::vector<bool> pieces;
|
|
bool seed;
|
|
int upload_limit;
|
|
int upload_ceiling;
|
|
|
|
size_type load_balancing;
|
|
|
|
int download_queue_length;
|
|
int upload_queue_length;
|
|
|
|
int downloading_piece_index;
|
|
int downloading_block_index;
|
|
int downloading_progress;
|
|
int downloading_total;
|
|
};
|
|
</pre>
|
|
<p>The <tt class="docutils literal"><span class="pre">flags</span></tt> attribute tells you in which state the peer is. It is set to
|
|
any combination of the enums above. The following table describes each flag:</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="31%" />
|
|
<col width="69%" />
|
|
</colgroup>
|
|
<tbody valign="top">
|
|
<tr><td><tt class="docutils literal"><span class="pre">interesting</span></tt></td>
|
|
<td><strong>we</strong> are interested in pieces from this peer.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">choked</span></tt></td>
|
|
<td><strong>we</strong> have choked this peer.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">remote_interested</span></tt></td>
|
|
<td>the peer is interested in <strong>us</strong></td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">remote_choked</span></tt></td>
|
|
<td>the peer has choked <strong>us</strong>.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">support_extensions</span></tt></td>
|
|
<td>means that this peer supports the
|
|
<a class="reference" href="extension_protocol.html">extension protocol</a>.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">local_connection</span></tt></td>
|
|
<td>The connection was initiated by us, the peer has a
|
|
listen port open, and that port is the same as in the
|
|
<a class="reference" href="#address">address</a> of this peer. If this flag is not set, this
|
|
peer connection was opened by this peer connecting to
|
|
us.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">connecting</span></tt></td>
|
|
<td>The connection is in a half-open state (i.e. it is
|
|
being connected).</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">queued</span></tt></td>
|
|
<td>The connection is currently queued for a connection
|
|
attempt. This may happen if there is a limit set on
|
|
the number of half-open TCP connections.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>The <tt class="docutils literal"><span class="pre">ip</span></tt> field is the IP-address to this peer. Its type is a wrapper around the
|
|
actual address and the port number. See <a class="reference" href="#address">address</a> class.</p>
|
|
<p><tt class="docutils literal"><span class="pre">up_speed</span></tt> and <tt class="docutils literal"><span class="pre">down_speed</span></tt> contains the current upload and download speed
|
|
we have to and from this peer (including any protocol messages). The transfer rates
|
|
of payload data only are found in <tt class="docutils literal"><span class="pre">payload_up_speed</span></tt> and <tt class="docutils literal"><span class="pre">payload_down_speed</span></tt>.
|
|
These figures are updated aproximately once every second.</p>
|
|
<p><tt class="docutils literal"><span class="pre">total_download</span></tt> and <tt class="docutils literal"><span class="pre">total_upload</span></tt> are the total number of bytes downloaded
|
|
from and uploaded to this peer. These numbers do not include the protocol chatter, but only
|
|
the payload data.</p>
|
|
<p><tt class="docutils literal"><span class="pre">id</span></tt> is the peer's id as used in the bit torrent protocol. This id can be used to
|
|
extract 'fingerprints' from the peer. Sometimes it can tell you which client the peer
|
|
is using. See identify_client()_</p>
|
|
<p><tt class="docutils literal"><span class="pre">pieces</span></tt> is a vector of booleans that has as many entries as there are pieces
|
|
in the torrent. Each boolean tells you if the peer has that piece (if it's set to true)
|
|
or if the peer miss that piece (set to false).</p>
|
|
<p><tt class="docutils literal"><span class="pre">seed</span></tt> is true if this peer is a seed.</p>
|
|
<p><tt class="docutils literal"><span class="pre">upload_limit</span></tt> is the number of bytes per second we are allowed to send to this
|
|
peer every second. It may be -1 if there's no limit. The upload limits of all peers
|
|
should sum up to the upload limit set by <tt class="docutils literal"><span class="pre">session::set_upload_limit</span></tt>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">upload_ceiling</span></tt> is the current maximum allowed upload rate given the cownload
|
|
rate and share ratio. If the global upload rate is inlimited, the <tt class="docutils literal"><span class="pre">upload_limit</span></tt>
|
|
for every peer will be the same as their <tt class="docutils literal"><span class="pre">upload_ceiling</span></tt>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">load_balancing</span></tt> is a measurment of the balancing of free download (that we get)
|
|
and free upload that we give. Every peer gets a certain amount of free upload, but
|
|
this member says how much <em>extra</em> free upload this peer has got. If it is a negative
|
|
number it means that this was a peer from which we have got this amount of free
|
|
download.</p>
|
|
<p><tt class="docutils literal"><span class="pre">download_queue_length</span></tt> is the number of piece-requests we have sent to this peer
|
|
that hasn't been answered with a piece yet.</p>
|
|
<p><tt class="docutils literal"><span class="pre">upload_queue_length</span></tt> is the number of piece-requests we have received from this peer
|
|
that we haven't answered with a piece yet.</p>
|
|
<p>You can know which piece, and which part of that piece, that is currently being
|
|
downloaded from a specific peer by looking at the next four members.
|
|
<tt class="docutils literal"><span class="pre">downloading_piece_index</span></tt> is the index of the piece that is currently being downloaded.
|
|
This may be set to -1 if there's currently no piece downloading from this peer. If it is
|
|
>= 0, the other three members are valid. <tt class="docutils literal"><span class="pre">downloading_block_index</span></tt> is the index of the
|
|
block (or sub-piece) that is being downloaded. <tt class="docutils literal"><span class="pre">downloading_progress</span></tt> is the number
|
|
of bytes of this block we have received from the peer, and <tt class="docutils literal"><span class="pre">downloading_total</span></tt> is
|
|
the total number of bytes in this block.</p>
|
|
</div>
|
|
<div class="section" id="address">
|
|
<h1><a name="address">address</a></h1>
|
|
<p>The <tt class="docutils literal"><span class="pre">address</span></tt> class represents a name of a network endpoint (usually referred to as
|
|
IP-address) and a port number. This is the same thing as a <tt class="docutils literal"><span class="pre">sockaddr_in</span></tt> would contain.
|
|
Its declaration looks like this:</p>
|
|
<pre class="literal-block">
|
|
class address
|
|
{
|
|
public:
|
|
address();
|
|
address(unsigned char a
|
|
, unsigned char b
|
|
, unsigned char c
|
|
, unsigned char d
|
|
, unsigned short port);
|
|
address(unsigned int addr, unsigned short port);
|
|
address(const std::string& addr, unsigned short port);
|
|
address(const address& a);
|
|
~address();
|
|
|
|
std::string as_string() const;
|
|
unsigned int ip() const;
|
|
unsigned short port() const;
|
|
|
|
bool operator<(const address& a) const;
|
|
bool operator!=(const address& a) const;
|
|
bool operator==(const address& a) const;
|
|
};
|
|
</pre>
|
|
<p>It is less-than comparable to make it possible to use it as a key in a map. <tt class="docutils literal"><span class="pre">as_string()</span></tt> may block
|
|
while it does the DNS lookup, it returns a string that points to the address represented by the object.</p>
|
|
<p><tt class="docutils literal"><span class="pre">ip()</span></tt> will return the 32-bit ip-address as an integer. <tt class="docutils literal"><span class="pre">port()</span></tt> returns the port number.</p>
|
|
</div>
|
|
<div class="section" id="http-settings">
|
|
<h1><a name="http-settings">http_settings</a></h1>
|
|
<p>You have some control over tracker requests through the <tt class="docutils literal"><span class="pre">http_settings</span></tt> object. You
|
|
create it and fill it with your settings and then use <tt class="docutils literal"><span class="pre">session::set_http_settings()</span></tt>
|
|
to apply them. You have control over proxy and authorization settings and also the user-agent
|
|
that will be sent to the tracker. The user-agent is a good way to identify your client.</p>
|
|
<pre class="literal-block">
|
|
struct http_settings
|
|
{
|
|
http_settings();
|
|
std::string proxy_ip;
|
|
int proxy_port;
|
|
std::string proxy_login;
|
|
std::string proxy_password;
|
|
std::string user_agent;
|
|
int tracker_timeout;
|
|
int tracker_maximum_response_length;
|
|
};
|
|
</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
|
|
an empty string, no http proxy will be used.</p>
|
|
<p><tt class="docutils literal"><span class="pre">proxy_port</span></tt> is the port on which the http proxy listens. If <tt class="docutils literal"><span class="pre">proxy_ip</span></tt>
|
|
is empty, this will be ignored.</p>
|
|
<p><tt class="docutils literal"><span class="pre">proxy_login</span></tt> should be the login username for the http proxy, if this
|
|
empty, the http proxy will be tried to be used without authentication.</p>
|
|
<p><tt class="docutils literal"><span class="pre">proxy_password</span></tt> the password string for the http proxy.</p>
|
|
<p><tt class="docutils literal"><span class="pre">user_agent</span></tt> this is the client identification to the tracker. It will
|
|
be followed by the string "(libtorrent)" to identify that this library
|
|
is being used. This should be set to your client's name and version number.</p>
|
|
<p><tt class="docutils literal"><span class="pre">tracker_timeout</span></tt> is the number of seconds the tracker connection will
|
|
wait until it considers the tracker to have timed-out. Default value is 10
|
|
seconds.</p>
|
|
<p><tt class="docutils literal"><span class="pre">tracker_maximum_response_length</span></tt> is the maximum number of bytes in a
|
|
tracker response. If a response size passes this number it will be rejected
|
|
and the connection will be closed. On gzipped responses this size is measured
|
|
on the uncompressed data. So, if you get 20 bytes of gzip response that'll
|
|
expand to 2 megs, it will be interrupted before the entire response has been
|
|
uncompressed (given your limit is lower than 2 megs). Default limit is
|
|
1 megabyte.</p>
|
|
</div>
|
|
<div class="section" id="ip-filter">
|
|
<h1><a name="ip-filter">ip_filter</a></h1>
|
|
<p>The <tt class="docutils literal"><span class="pre">ip_filter</span></tt> class is a set of rules that uniquely categorizes all
|
|
ip addresses as allowed or disallowed. The default constructor creates
|
|
a single rule that allowes all addresses (0.0.0.0 - 255.255.255.255).</p>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
class ip_filter
|
|
{
|
|
public:
|
|
enum access_flags { blocked = 1 };
|
|
|
|
ip_filter();
|
|
void add_rule(address first, address last, int flags);
|
|
int access(address const& addr) const;
|
|
|
|
struct ip_range
|
|
{
|
|
address first;
|
|
address last;
|
|
int flags;
|
|
};
|
|
|
|
std::vector<ip_range> export_filter() const;
|
|
};
|
|
</pre>
|
|
</blockquote>
|
|
<div class="section" id="id14">
|
|
<h2><a name="id14">ip_filter()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
ip_filter()
|
|
</pre>
|
|
</blockquote>
|
|
<p>Creates a default filter that doesn't filter any address.</p>
|
|
<p>postcondition:
|
|
<tt class="docutils literal"><span class="pre">access(x)</span> <span class="pre">==</span> <span class="pre">0</span></tt> for every <tt class="docutils literal"><span class="pre">x</span></tt></p>
|
|
</div>
|
|
<div class="section" id="add-rule">
|
|
<h2><a name="add-rule">add_rule()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
void add_rule(address first, address last, int flags);
|
|
</pre>
|
|
</blockquote>
|
|
<p>Adds a rule to the filter. <tt class="docutils literal"><span class="pre">first</span></tt> and <tt class="docutils literal"><span class="pre">last</span></tt> defines a range of
|
|
ip addresses that will be marked with the given flags. The <tt class="docutils literal"><span class="pre">flags</span></tt>
|
|
can currenly be 0, which means allowed, or <tt class="docutils literal"><span class="pre">ip_filter::blocked</span></tt>, which
|
|
means disallowed.</p>
|
|
<p>postcondition:
|
|
<tt class="docutils literal"><span class="pre">access(x)</span> <span class="pre">==</span> <span class="pre">flags</span></tt> for every <tt class="docutils literal"><span class="pre">x</span></tt> in the range [<tt class="docutils literal"><span class="pre">first</span></tt>, <tt class="docutils literal"><span class="pre">last</span></tt>]</p>
|
|
<p>This means that in a case of overlapping ranges, the last one applied takes
|
|
precedence.</p>
|
|
</div>
|
|
<div class="section" id="access">
|
|
<h2><a name="access">access()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
int access(address const& addr) const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>Returns the access permissions for the given address (<tt class="docutils literal"><span class="pre">addr</span></tt>). The permission
|
|
can currently be 0 or <tt class="docutils literal"><span class="pre">ip_filter::blocked</span></tt>. The complexity of this operation
|
|
is O(<tt class="docutils literal"><span class="pre">log</span></tt> n), where n is the minimum number of non-overlapping ranges to describe
|
|
the current filter.</p>
|
|
</div>
|
|
<div class="section" id="export-filter">
|
|
<h2><a name="export-filter">export_filter()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
std::vector<ip_range> export_filter() const;
|
|
</pre>
|
|
</blockquote>
|
|
<p>This function will return the current state of the filter in the minimum number of
|
|
ranges possible. They are sorted from ranges in low addresses to high addresses. Each
|
|
entry in the returned vector is a range with the access control specified in its
|
|
<tt class="docutils literal"><span class="pre">flags</span></tt> field.</p>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="big-number">
|
|
<h1><a name="big-number">big_number</a></h1>
|
|
<p>Both the <tt class="docutils literal"><span class="pre">peer_id</span></tt> and <tt class="docutils literal"><span class="pre">sha1_hash</span></tt> types are typedefs of the class
|
|
<tt class="docutils literal"><span class="pre">big_number</span></tt>. It represents 20 bytes of data. Its synopsis follows:</p>
|
|
<pre class="literal-block">
|
|
class big_number
|
|
{
|
|
public:
|
|
bool operator==(const big_number& n) const;
|
|
bool operator!=(const big_number& n) const;
|
|
bool operator<(const big_number& n) const;
|
|
|
|
const unsigned char* begin() const;
|
|
const unsigned char* end() const;
|
|
|
|
unsigned char* begin();
|
|
unsigned char* end();
|
|
};
|
|
</pre>
|
|
<p>The iterators gives you access to individual bytes.</p>
|
|
</div>
|
|
<div class="section" id="hasher">
|
|
<h1><a name="hasher">hasher</a></h1>
|
|
<p>This class creates sha1-hashes. Its declaration looks like this:</p>
|
|
<pre class="literal-block">
|
|
class hasher
|
|
{
|
|
public:
|
|
hasher();
|
|
|
|
void update(const char* data, unsigned int len);
|
|
sha1_hash final();
|
|
void reset();
|
|
};
|
|
</pre>
|
|
<p>You use it by first instantiating it, then call <tt class="docutils literal"><span class="pre">update()</span></tt> to feed it
|
|
with data. i.e. you don't have to keep the entire buffer of which you want to
|
|
create the hash in memory. You can feed the hasher parts of it at a time. When
|
|
You have fed the hasher with all the data, you call <tt class="docutils literal"><span class="pre">final()</span></tt> and it
|
|
will return the sha1-hash of the data.</p>
|
|
<p>If you want to reuse the hasher object once you have created a hash, you have to
|
|
call <tt class="docutils literal"><span class="pre">reset()</span></tt> to reinitialize it.</p>
|
|
<p>The sha1-algorithm used was implemented by Steve Reid and released as public domain.
|
|
For more info, see <tt class="docutils literal"><span class="pre">src/sha1.cpp</span></tt>.</p>
|
|
</div>
|
|
<div class="section" id="fingerprint">
|
|
<h1><a name="fingerprint">fingerprint</a></h1>
|
|
<p>The fingerprint class represents information about a client and its version. It is used
|
|
to encode this information into the client's peer id.</p>
|
|
<p>This is the class declaration:</p>
|
|
<pre class="literal-block">
|
|
struct fingerprint
|
|
{
|
|
fingerprint(const char* id_string, int major, int minor
|
|
, int revision, int tag);
|
|
|
|
std::string to_string() const;
|
|
|
|
char id[2];
|
|
char major_version;
|
|
char minor_version;
|
|
char revision_version;
|
|
char tag_version;
|
|
|
|
};
|
|
</pre>
|
|
<p>The constructor takes a <tt class="docutils literal"><span class="pre">char</span> <span class="pre">const*</span></tt> that should point to a string constant containing
|
|
exactly two characters. These are the characters that should be unique for your client. Make
|
|
sure not to clash with anybody else. Here are some taken id's:</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="30%" />
|
|
<col width="70%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr><th>id chars</th>
|
|
<th>client</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<tr><td>'AZ'</td>
|
|
<td>Azureus</td>
|
|
</tr>
|
|
<tr><td>'LT'</td>
|
|
<td>libtorrent (default)</td>
|
|
</tr>
|
|
<tr><td>'BX'</td>
|
|
<td>BittorrentX</td>
|
|
</tr>
|
|
<tr><td>'MT'</td>
|
|
<td>Moonlight Torrent</td>
|
|
</tr>
|
|
<tr><td>'TS'</td>
|
|
<td>Torrent Storm</td>
|
|
</tr>
|
|
<tr><td>'SS'</td>
|
|
<td>Swarm Scope</td>
|
|
</tr>
|
|
<tr><td>'XT'</td>
|
|
<td>Xan Torrent</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>There's currently an informal directory of client id's <a class="reference" href="http://wiki.theory.org/BitTorrentSpecification#peer_id">here</a>.</p>
|
|
<p>The <tt class="docutils literal"><span class="pre">major</span></tt>, <tt class="docutils literal"><span class="pre">minor</span></tt>, <tt class="docutils literal"><span class="pre">revision</span></tt> and <tt class="docutils literal"><span class="pre">tag</span></tt> parameters are used to identify the
|
|
version of your client. All these numbers must be within the range [0, 9].</p>
|
|
<p><tt class="docutils literal"><span class="pre">to_string()</span></tt> will generate the actual string put in the peer-id, and return it.</p>
|
|
</div>
|
|
<div class="section" id="free-functions">
|
|
<h1><a name="free-functions">free functions</a></h1>
|
|
<div class="section" id="identify-client">
|
|
<h2><a name="identify-client">identify_client()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
std::string identify_client(peer_id const& id);
|
|
</pre>
|
|
</blockquote>
|
|
<p>This function is declared in the header <tt class="docutils literal"><span class="pre"><libtorrent/identify_client.hpp></span></tt>. It can can be used
|
|
to extract a string describing a client version from its peer-id. It will recognize most clients
|
|
that have this kind of identification in the peer-id.</p>
|
|
</div>
|
|
<div class="section" id="bdecode-bencode">
|
|
<h2><a name="bdecode-bencode">bdecode() bencode()</a></h2>
|
|
<blockquote>
|
|
<pre class="literal-block">
|
|
template<class InIt> entry bdecode(InIt start, InIt end);
|
|
template<class OutIt> void bencode(OutIt out, const entry& e);
|
|
</pre>
|
|
</blockquote>
|
|
<p>These functions will encode data to <a class="reference" href="http://wiki.theory.org/index.php/BitTorrentSpecification">bencoded</a> or decode <a class="reference" href="http://wiki.theory.org/index.php/BitTorrentSpecification">bencoded</a> data.</p>
|
|
<p>The <a class="reference" href="#entry">entry</a> class is the internal representation of the bencoded data
|
|
and it can be used to retreive information, an <a class="reference" href="#entry">entry</a> can also be build by
|
|
the program and given to <tt class="docutils literal"><span class="pre">bencode()</span></tt> to encode it into the <tt class="docutils literal"><span class="pre">OutIt</span></tt>
|
|
iterator.</p>
|
|
<p>The <tt class="docutils literal"><span class="pre">OutIt</span></tt> and <tt class="docutils literal"><span class="pre">InIt</span></tt> are iterators
|
|
(<a class="reference" href="http://www.sgi.com/tech/stl/InputIterator.html">InputIterator</a> and <a class="reference" href="http://www.sgi.com/tech/stl/OutputIterator.html">OutputIterator</a> respectively). They
|
|
are templates and are usually instantiated as <a class="reference" href="http://www.sgi.com/tech/stl/ostream_iterator.html">ostream_iterator</a>,
|
|
<a class="reference" href="http://www.sgi.com/tech/stl/back_insert_iterator.html">back_insert_iterator</a> or <a class="reference" href="http://www.sgi.com/tech/stl/istream_iterator.html">istream_iterator</a>. These
|
|
functions will assume that the iterator refers to a character
|
|
(<tt class="docutils literal"><span class="pre">char</span></tt>). So, if you want to encode entry <tt class="docutils literal"><span class="pre">e</span></tt> into a buffer
|
|
in memory, you can do it like this:</p>
|
|
<pre class="literal-block">
|
|
std::vector<char> buffer;
|
|
bencode(std::back_inserter(buf), e);
|
|
</pre>
|
|
<p>If you want to decode a torrent file from a buffer in memory, you can do it like this:</p>
|
|
<pre class="literal-block">
|
|
std::vector<char> buffer;
|
|
// ...
|
|
entry e = bdecode(buf.begin(), buf.end());
|
|
</pre>
|
|
<p>Or, if you have a raw char buffer:</p>
|
|
<pre class="literal-block">
|
|
const char* buf;
|
|
// ...
|
|
entry e = bdecode(buf, buf + data_size);
|
|
</pre>
|
|
<p>Now we just need to know how to retrieve information from the <a class="reference" href="#entry">entry</a>.</p>
|
|
<p>If <tt class="docutils literal"><span class="pre">bdecode()</span></tt> encounters invalid encoded data in the range given to it
|
|
it will throw <a class="reference" href="#invalid-encoding">invalid_encoding</a>.</p>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="alerts">
|
|
<h1><a name="alerts">alerts</a></h1>
|
|
<p>The <tt class="docutils literal"><span class="pre">pop_alert()</span></tt> function on session is the interface for retrieving
|
|
alerts, warnings, messages and errors from libtorrent. If there hasn't
|
|
occured any errors (matching your severity level) <tt class="docutils literal"><span class="pre">pop_alert()</span></tt> will
|
|
return a zero pointer. If there has been some error, it will return a pointer
|
|
to an alert object describing it. You can then use the alert object and query
|
|
it for information about the error or message. To retrieve any alerts, you have
|
|
to select a severity level using <tt class="docutils literal"><span class="pre">session::set_severity_level()</span></tt>. It defaults to
|
|
<tt class="docutils literal"><span class="pre">alert::none</span></tt>, which means that you don't get any messages at all, ever.
|
|
You have the following levels to select among:</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="19%" />
|
|
<col width="81%" />
|
|
</colgroup>
|
|
<tbody valign="top">
|
|
<tr><td><tt class="docutils literal"><span class="pre">none</span></tt></td>
|
|
<td>No alert will ever have this severity level, which
|
|
effectively filters all messages.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">fatal</span></tt></td>
|
|
<td>Fatal errors will have this severity level. Examples can
|
|
be disk full or something else that will make it
|
|
impossible to continue normal execution.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">critical</span></tt></td>
|
|
<td>Signals errors that requires user interaction or
|
|
messages that almost never should be ignored. For
|
|
example, a chat message received from another peer is
|
|
announced as severity <tt class="docutils literal"><span class="pre">critical</span></tt>.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">warning</span></tt></td>
|
|
<td>Messages with the warning severity can be a tracker that
|
|
times out or responds with invalid data. It will be
|
|
retried automatically, and the possible next tracker in
|
|
a multitracker sequence will be tried. It does not
|
|
require any user interaction.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">info</span></tt></td>
|
|
<td>Events that can be considered normal, but still deserves
|
|
an event. This could be a piece hash that fails.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">debug</span></tt></td>
|
|
<td>This will include alot of debug events that can be used
|
|
both for debugging libtorrent but also when debugging
|
|
other clients that are connected to libtorrent. It will
|
|
report strange behaviors among the connected peers.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>When setting a severity level, you will receive messages of that severity and all
|
|
messages that are more sever. If you set <tt class="docutils literal"><span class="pre">alert::none</span></tt> (the default) you will not recieve
|
|
any events at all.</p>
|
|
<p>When you set a severuty level other than <tt class="docutils literal"><span class="pre">none</span></tt>, you have the responsibility to call
|
|
<tt class="docutils literal"><span class="pre">pop_alert()</span></tt> from time to time. If you don't do that, the alert queue will just grow.</p>
|
|
<p>When you get an alert, you can use <tt class="docutils literal"><span class="pre">typeid()</span></tt> or <tt class="docutils literal"><span class="pre">dynamic_cast<></span></tt> to get more detailed
|
|
information on exactly which type it is. i.e. what kind of error it is. You can also use a
|
|
<a class="reference" href="#dispatcher">dispatcher</a> mechanism that's available in libtorrent.</p>
|
|
<p>All alert types are defined in the <tt class="docutils literal"><span class="pre"><libtorrent/alert_types.hpp></span></tt> header file.</p>
|
|
<p>The <tt class="docutils literal"><span class="pre">alert</span></tt> class is the base class that specific messages are derived from. This
|
|
is its synopsis:</p>
|
|
<pre class="literal-block">
|
|
class alert
|
|
{
|
|
public:
|
|
|
|
enum severity_t { debug, info, warning, critital, fatal, none };
|
|
|
|
alert(severity_t severity, const std::string& msg);
|
|
virtual ~alert();
|
|
|
|
std::string const& msg() const;
|
|
severity_t severity() const;
|
|
|
|
virtual std::auto_ptr<alert> clone() const = 0;
|
|
};
|
|
</pre>
|
|
<p>This means that all alerts have at least a string describing it. They also
|
|
have a severity level that can be used to sort them or present them to the
|
|
user in different ways.</p>
|
|
<p>The specific alerts, that all derives from <tt class="docutils literal"><span class="pre">alert</span></tt>, are:</p>
|
|
<div class="section" id="listen-failed-alert">
|
|
<h2><a name="listen-failed-alert">listen_failed_alert</a></h2>
|
|
<p>This alert is generated when none of the ports, given in the port range, to
|
|
<a class="reference" href="#session">session</a> can be opened for listening. This alert is generated as severity
|
|
level <tt class="docutils literal"><span class="pre">fatal</span></tt>.</p>
|
|
<pre class="literal-block">
|
|
struct listen_failed_alert: alert
|
|
{
|
|
listen_failed_alert(const std::string& msg);
|
|
virtual std::auto_ptr<alert> clone() const;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="file-error-alert">
|
|
<h2><a name="file-error-alert">file_error_alert</a></h2>
|
|
<p>If the storage fails to read or write files that it needs access to, this alert is
|
|
generated and the torrent is paused. It is generated as severity level <tt class="docutils literal"><span class="pre">fatal</span></tt>.</p>
|
|
<pre class="literal-block">
|
|
struct file_error_alert: alert
|
|
{
|
|
file_error_alert(
|
|
const torrent_handle& h
|
|
, const std::string& msg);
|
|
|
|
virtual std::auto_ptr<alert> clone() const;
|
|
torrent_handle handle;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="tracker-announce-alert">
|
|
<h2><a name="tracker-announce-alert">tracker_announce_alert</a></h2>
|
|
<p>This alert is generated each time a tracker announce is sent (or attempted to be sent).
|
|
It is generated at severity level <tt class="docutils literal"><span class="pre">info</span></tt>.</p>
|
|
<pre class="literal-block">
|
|
struct tracker_announce_alert: alert
|
|
{
|
|
tracker_announce_alert(
|
|
const torrent_handle& h
|
|
, const std::string& msg);
|
|
|
|
virtual std::auto_ptr<alert> clone() const;
|
|
torrent_handle handle;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="tracker-alert">
|
|
<h2><a name="tracker-alert">tracker_alert</a></h2>
|
|
<p>This alert is generated on tracker time outs, premature disconnects, invalid response or
|
|
a HTTP response other than "200 OK". From the alert you can get the handle to the torrent
|
|
the tracker belongs to. This alert is generated as severity level <tt class="docutils literal"><span class="pre">warning</span></tt>.</p>
|
|
<p>The <tt class="docutils literal"><span class="pre">times_in_row</span></tt> member says how many times in a row this tracker has failed.
|
|
<tt class="docutils literal"><span class="pre">status_code</span></tt> is the code returned from the HTTP server. 401 means the tracker needs
|
|
authentication, 404 means not found etc. If the tracker timed out, the code will be set
|
|
to 0.</p>
|
|
<pre class="literal-block">
|
|
struct tracker_alert: alert
|
|
{
|
|
tracker_alert(const torrent_handle& h, int times, int status
|
|
, const std::string& msg);
|
|
virtual std::auto_ptr<alert> clone() const;
|
|
|
|
torrent_handle handle;
|
|
int times_in_row;
|
|
int status_code;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="tracker-reply-alert">
|
|
<h2><a name="tracker-reply-alert">tracker_reply_alert</a></h2>
|
|
<p>This alert is only for informational purpose. It is generated when a tracker announce
|
|
succeeds. It is generated with severity level <tt class="docutils literal"><span class="pre">info</span></tt>.</p>
|
|
<pre class="literal-block">
|
|
struct tracker_reply_alert: alert
|
|
{
|
|
tracker_reply_alert(const torrent_handle& h
|
|
, const std::string& msg);
|
|
|
|
virtual std::auto_ptr<alert> clone() const;
|
|
torrent_handle handle;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="tracker-warning-alert">
|
|
<h2><a name="tracker-warning-alert">tracker_warning_alert</a></h2>
|
|
<p>This alert is triggered if the tracker reply contains a warning field. Usually this
|
|
means that the tracker announce was successful, but the tracker has a message to
|
|
the client. The message string in the alert will contain the warning message from
|
|
the tracker. It is generated with severity level <tt class="docutils literal"><span class="pre">warning</span></tt>.</p>
|
|
<pre class="literal-block">
|
|
struct tracker_warning_alert: alert
|
|
{
|
|
tracker_warning_alert(torrent_handle const& h
|
|
, std::string const& msg);
|
|
|
|
virtual std::auto_ptr<alert> clone() const;
|
|
torrent_handle handle;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="hash-failed-alert">
|
|
<h2><a name="hash-failed-alert">hash_failed_alert</a></h2>
|
|
<p>This alert is generated when a finished piece fails its hash check. You can get the handle
|
|
to the torrent which got the failed piece and the index of the piece itself from the alert.
|
|
This alert is generated as severity level <tt class="docutils literal"><span class="pre">info</span></tt>.</p>
|
|
<pre class="literal-block">
|
|
struct hash_failed_alert: alert
|
|
{
|
|
hash_failed_alert(
|
|
const torrent_handle& h
|
|
, int index
|
|
, const std::string& msg);
|
|
|
|
virtual std::auto_ptr<alert> clone() const;
|
|
torrent_handle handle;
|
|
int piece_index;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="peer-ban-alert">
|
|
<h2><a name="peer-ban-alert">peer_ban_alert</a></h2>
|
|
<p>This alert is generated when a peer is banned because it has sent too many corrupt pieces
|
|
to us. It is generated at severity level <tt class="docutils literal"><span class="pre">info</span></tt>. The <tt class="docutils literal"><span class="pre">handle</span></tt> member is a <a class="reference" href="#torrent-handle">torrent_handle</a>
|
|
to the torrent that this peer was a member of.</p>
|
|
<pre class="literal-block">
|
|
struct peer_ban_alert: alert
|
|
{
|
|
peer_ban_alert(
|
|
address const& pip
|
|
, torrent_handle h
|
|
, const std::string& msg);
|
|
|
|
virtual std::auto_ptr<alert> clone() const;
|
|
address ip;
|
|
torrent_handle handle;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="peer-error-alert">
|
|
<h2><a name="peer-error-alert">peer_error_alert</a></h2>
|
|
<p>This alert is generated when a peer sends invalid data over the peer-peer protocol. The peer
|
|
will be disconnected, but you get its ip address from the alert, to identify it. This alert
|
|
is generated as severity level <tt class="docutils literal"><span class="pre">debug</span></tt>.</p>
|
|
<pre class="literal-block">
|
|
struct peer_error_alert: alert
|
|
{
|
|
peer_error_alert(
|
|
address const& pip
|
|
, peer_id const& pid
|
|
, const std::string& msg);
|
|
|
|
virtual std::auto_ptr<alert> clone() const;
|
|
address ip;
|
|
peer_id id;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="invalid-request-alert">
|
|
<h2><a name="invalid-request-alert">invalid_request_alert</a></h2>
|
|
<p>This is a debug alert that is generated by an incoming invalid piece request. The <tt class="docutils literal"><span class="pre">handle</span></tt>
|
|
is a handle to the torrent the peer is a member of. <tt class="docutils literal"><span class="pre">ìp</span></tt> is the address of the peer and the
|
|
<tt class="docutils literal"><span class="pre">request</span></tt> is the actual incoming request from the peer. The alert is generated as severity level
|
|
<tt class="docutils literal"><span class="pre">debug</span></tt>.</p>
|
|
<pre class="literal-block">
|
|
struct invalid_request_alert: alert
|
|
{
|
|
invalid_request_alert(
|
|
peer_request const& r
|
|
, torrent_handle const& h
|
|
, address const& send
|
|
, peer_id const& pid
|
|
, std::string const& msg);
|
|
|
|
virtual std::auto_ptr<alert> clone() const;
|
|
torrent_handle handle;
|
|
address ip;
|
|
peer_request request;
|
|
peer_id id;
|
|
};
|
|
|
|
|
|
struct peer_request
|
|
{
|
|
int piece;
|
|
int start;
|
|
int length;
|
|
bool operator==(peer_request const& r) const;
|
|
};
|
|
</pre>
|
|
<p>The <tt class="docutils literal"><span class="pre">peer_request</span></tt> contains the values the client sent in its <tt class="docutils literal"><span class="pre">request</span></tt> message. <tt class="docutils literal"><span class="pre">piece</span></tt> is
|
|
the index of the piece it want data from, <tt class="docutils literal"><span class="pre">start</span></tt> is the offset within the piece where the data
|
|
should be read, and <tt class="docutils literal"><span class="pre">length</span></tt> is the amount of data it wants.</p>
|
|
</div>
|
|
<div class="section" id="torrent-finished-alert">
|
|
<h2><a name="torrent-finished-alert">torrent_finished_alert</a></h2>
|
|
<p>This alert is generated when a torrent switches from being a downloader to a seed.
|
|
It will only be generated once per torrent. It contains a torrent_handle to the
|
|
torrent in question. This alert is generated as severity level <tt class="docutils literal"><span class="pre">info</span></tt>.</p>
|
|
<pre class="literal-block">
|
|
struct torrent_finished_alert: alert
|
|
{
|
|
torrent_finished_alert(
|
|
const torrent_handle& h
|
|
, const std::string& msg);
|
|
|
|
virtual std::auto_ptr<alert> clone() const;
|
|
torrent_handle handle;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="metadata-failed-alert">
|
|
<h2><a name="metadata-failed-alert">metadata_failed_alert</a></h2>
|
|
<p>This alert is generated when the metadata has been completely received and the info-hash
|
|
failed to match it. i.e. the metadata that was received was corrupt. libtorrent will
|
|
automatically retry to fetch it in this case. This is only relevant when running a
|
|
torrent-less download, with the metadata extension provided by libtorrent.
|
|
It is generated at severity level <tt class="docutils literal"><span class="pre">info</span></tt>.</p>
|
|
<pre class="literal-block">
|
|
struct metadata_received_alert: alert
|
|
{
|
|
metadata_received_alert(
|
|
const torrent_handle& h
|
|
, const std::string& msg);
|
|
|
|
virtual std::auto_ptr<alert> clone() const;
|
|
torrent_handle handle;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="metadata-received-alert">
|
|
<h2><a name="metadata-received-alert">metadata_received_alert</a></h2>
|
|
<p>This alert is generated when the metadata has been completely received and the torrent
|
|
can start downloading. It is not generated on torrents that are started with metadata, but
|
|
only those that needs to download it from peers (when utilizing the libtorrent extension).
|
|
It is generated at severity level <tt class="docutils literal"><span class="pre">info</span></tt>.</p>
|
|
<pre class="literal-block">
|
|
struct metadata_received_alert: alert
|
|
{
|
|
metadata_received_alert(
|
|
const torrent_handle& h
|
|
, const std::string& msg);
|
|
|
|
virtual std::auto_ptr<alert> clone() const;
|
|
torrent_handle handle;
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="fastresume-rejected-alert">
|
|
<h2><a name="fastresume-rejected-alert">fastresume_rejected_alert</a></h2>
|
|
<p>This alert is generated when a fastresume file has been passed to <tt class="docutils literal"><span class="pre">add_torrent</span></tt> but the
|
|
files on disk did not match the fastresume file. The string explaints the reason why the
|
|
resume file was rejected. It is generated at severity level <tt class="docutils literal"><span class="pre">warning</span></tt>.</p>
|
|
<pre class="literal-block">
|
|
struct fastresume_rejected_alert: alert
|
|
{
|
|
fastresume_rejected_alert(torrent_handle const& h
|
|
, std::string const& msg);
|
|
|
|
virtual std::auto_ptr<alert> clone() const;
|
|
torrent_handle handle;
|
|
};
|
|
</pre>
|
|
<!-- chat_message_alert
|
|
- - - - - - - - - - - - - - - - - -
|
|
|
|
This alert is generated when you receive a chat message from another peer. Chat messages
|
|
are supported as an extension ("chat"). It is generated as severity level ``critical``,
|
|
even though it doesn't necessarily require any user intervention, it's high priority
|
|
since you would almost never want to ignore such a message. The alert class contain
|
|
a torrent_handle_ to the torrent in which the sender-peer is a member and the ip
|
|
of the sending peer.
|
|
|
|
::
|
|
|
|
struct chat_message_alert: alert
|
|
{
|
|
chat_message_alert(const torrent_handle& h
|
|
, const address& sender
|
|
, const std::string& msg);
|
|
|
|
virtual std::auto_ptr<alert> clone() const;
|
|
|
|
torrent_handle handle;
|
|
address ip;
|
|
}; -->
|
|
</div>
|
|
<div class="section" id="dispatcher">
|
|
<h2><a name="dispatcher">dispatcher</a></h2>
|
|
<p><em>TODO: describe the dispatcher mechanism</em></p>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="exceptions">
|
|
<h1><a name="exceptions">exceptions</a></h1>
|
|
<p>There are a number of exceptions that can be thrown from different places in libtorrent,
|
|
here's a complete list with description.</p>
|
|
<div class="section" id="invalid-handle">
|
|
<h2><a name="invalid-handle">invalid_handle</a></h2>
|
|
<p>This exception is thrown when querying information from a <a class="reference" href="#torrent-handle">torrent_handle</a> that hasn't
|
|
been initialized or that has become invalid.</p>
|
|
<pre class="literal-block">
|
|
struct invalid_handle: std::exception
|
|
{
|
|
const char* what() const throw();
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="duplicate-torrent">
|
|
<h2><a name="duplicate-torrent">duplicate_torrent</a></h2>
|
|
<p>This is thrown by <a class="reference" href="#add-torrent">add_torrent()</a> if the torrent already has been added to
|
|
the session.</p>
|
|
<pre class="literal-block">
|
|
struct duplicate_torrent: std::exception
|
|
{
|
|
const char* what() const throw();
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="invalid-encoding">
|
|
<h2><a name="invalid-encoding">invalid_encoding</a></h2>
|
|
<p>This is thrown by <tt class="docutils literal"><span class="pre">bdecode()</span></tt> if the input data is not a valid bencoding.</p>
|
|
<pre class="literal-block">
|
|
struct invalid_encoding: std::exception
|
|
{
|
|
const char* what() const throw();
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="type-error">
|
|
<h2><a name="type-error">type_error</a></h2>
|
|
<p>This is thrown from the accessors of <tt class="docutils literal"><span class="pre">entry</span></tt> if the data type of the <tt class="docutils literal"><span class="pre">entry</span></tt> doesn't
|
|
match the type you want to extract from it.</p>
|
|
<pre class="literal-block">
|
|
struct type_error: std::runtime_error
|
|
{
|
|
type_error(const char* error);
|
|
};
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="invalid-torrent-file">
|
|
<h2><a name="invalid-torrent-file">invalid_torrent_file</a></h2>
|
|
<p>This exception is thrown from the constructor of <tt class="docutils literal"><span class="pre">torrent_info</span></tt> if the given bencoded information
|
|
doesn't meet the requirements on what information has to be present in a torrent file.</p>
|
|
<pre class="literal-block">
|
|
struct invalid_torrent_file: std::exception
|
|
{
|
|
const char* what() const throw();
|
|
};
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="examples">
|
|
<h1><a name="examples">examples</a></h1>
|
|
<p>Except for the example programs in this manual, there's also a bigger example
|
|
of a (little bit) more complete client, <tt class="docutils literal"><span class="pre">client_test</span></tt>. There are separate
|
|
instructions for how to use it <a class="reference" href="client_test.html">here</a> if you'd like to try it.</p>
|
|
<div class="section" id="dump-torrent">
|
|
<h2><a name="dump-torrent">dump_torrent</a></h2>
|
|
<p>This is an example of a program that will take a torrent-file as a parameter and
|
|
print information about it to std out:</p>
|
|
<pre class="literal-block">
|
|
#include <iostream>
|
|
#include <fstream>
|
|
#include <iterator>
|
|
#include <exception>
|
|
#include <iomanip>
|
|
|
|
#include "libtorrent/entry.hpp"
|
|
#include "libtorrent/bencode.hpp"
|
|
#include "libtorrent/torrent_info.hpp"
|
|
|
|
|
|
int main(int argc, char* argv[])
|
|
{
|
|
using namespace libtorrent;
|
|
|
|
if (argc != 2)
|
|
{
|
|
std::cerr << "usage: dump_torrent torrent-file\n";
|
|
return 1;
|
|
}
|
|
|
|
try
|
|
{
|
|
std::ifstream in(argv[1], std::ios_base::binary);
|
|
in.unsetf(std::ios_base::skipws);
|
|
entry e = bdecode(std::istream_iterator<char>(in)
|
|
, std::istream_iterator<char>());
|
|
torrent_info t(e);
|
|
|
|
// print info about torrent
|
|
std::cout << "\n\n----- torrent file info -----\n\n";
|
|
std::cout << "trackers:\n";
|
|
for (std::vector<announce_entry>::const_iterator i
|
|
= t.trackers().begin(), end(t.trackers().end); i != end; ++i)
|
|
{
|
|
std::cout << i->tier << ": " << i->url << "\n";
|
|
}
|
|
|
|
std::cout << "number of pieces: " << t.num_pieces() << "\n";
|
|
std::cout << "piece length: " << t.piece_length() << "\n";
|
|
std::cout << "files:\n";
|
|
for (torrent_info::file_iterator i = t.begin_files();
|
|
i != t.end_files(); ++i)
|
|
{
|
|
std::cout << " " << std::setw(11) << i->size
|
|
<< " " << i->path << " " << i->filename << "\n";
|
|
}
|
|
|
|
}
|
|
catch (std::exception& e)
|
|
{
|
|
std::cout << e.what() << "\n";
|
|
}
|
|
|
|
return 0;
|
|
}
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="simple-client">
|
|
<h2><a name="simple-client">simple client</a></h2>
|
|
<p>This is a simple client. It doesn't have much output to keep it simple:</p>
|
|
<pre class="literal-block">
|
|
#include <iostream>
|
|
#include <fstream>
|
|
#include <iterator>
|
|
#include <exception>
|
|
|
|
#include <boost/format.hpp>
|
|
#include <boost/date_time/posix_time/posix_time.hpp>
|
|
|
|
#include "libtorrent/entry.hpp"
|
|
#include "libtorrent/bencode.hpp"
|
|
#include "libtorrent/session.hpp"
|
|
#include "libtorrent/http_settings.hpp"
|
|
|
|
int main(int argc, char* argv[])
|
|
{
|
|
using namespace libtorrent;
|
|
|
|
if (argc != 2)
|
|
{
|
|
std::cerr << "usage: ./simple_cient torrent-file\n"
|
|
"to stop the client, press return.\n";
|
|
return 1;
|
|
}
|
|
|
|
try
|
|
{
|
|
session s;
|
|
s.listen_on(std::make_pair(6881, 6889));
|
|
|
|
std::ifstream in(argv[1], std::ios_base::binary);
|
|
in.unsetf(std::ios_base::skipws);
|
|
entry e = bdecode(std::istream_iterator<char>(in)
|
|
, std::istream_iterator<char>());
|
|
s.add_torrent(torrent_info(e), "");
|
|
|
|
// wait for the user to end
|
|
char a;
|
|
std::cin.unsetf(std::ios_base::skipws);
|
|
std::cin >> a;
|
|
}
|
|
catch (std::exception& e)
|
|
{
|
|
std::cout << e.what() << "\n";
|
|
}
|
|
return 0;
|
|
}
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="make-torrent">
|
|
<h2><a name="make-torrent">make_torrent</a></h2>
|
|
<p>Shows how to create a torrent from a directory tree:</p>
|
|
<pre class="literal-block">
|
|
#include <iostream>
|
|
#include <fstream>
|
|
#include <iterator>
|
|
#include <iomanip>
|
|
|
|
#include "libtorrent/entry.hpp"
|
|
#include "libtorrent/bencode.hpp"
|
|
#include "libtorrent/torrent_info.hpp"
|
|
#include "libtorrent/file.hpp"
|
|
#include "libtorrent/storage.hpp"
|
|
#include "libtorrent/hasher.hpp"
|
|
|
|
#include <boost/filesystem/operations.hpp>
|
|
#include <boost/filesystem/path.hpp>
|
|
#include <boost/filesystem/fstream.hpp>
|
|
|
|
using namespace boost::filesystem;
|
|
using namespace libtorrent;
|
|
|
|
void add_files(torrent_info& t, path const& p, path const& l)
|
|
{
|
|
path f(p / l);
|
|
if (is_directory(f))
|
|
{
|
|
for (directory_iterator i(f), end; i != end; ++i)
|
|
add_files(t, p, l / i->leaf());
|
|
}
|
|
else
|
|
{
|
|
std::cerr << "adding \"" << l.string() << "\"\n";
|
|
file fi(f, file::in);
|
|
fi.seek(0, file::end);
|
|
libtorrent::size_type size = fi.tell();
|
|
t.add_file(l, size);
|
|
}
|
|
}
|
|
|
|
int main(int argc, char* argv[])
|
|
{
|
|
using namespace libtorrent;
|
|
using namespace boost::filesystem;
|
|
|
|
if (argc != 4)
|
|
{
|
|
std::cerr << "usage: make_torrent <output torrent-file> "
|
|
"<announce url> <file or directory to create torrent from>\n";
|
|
return 1;
|
|
}
|
|
|
|
boost::filesystem::path::default_name_check(native);
|
|
|
|
try
|
|
{
|
|
torrent_info t;
|
|
path full_path = initial_path() / path(argv[3]);
|
|
ofstream out(initial_path() / path(argv[1]), std::ios_base::binary);
|
|
|
|
int piece_size = 256 * 1024;
|
|
char const* creator_str = "libtorrent";
|
|
|
|
add_files(t, full_path.branch_path(), full_path.leaf());
|
|
t.set_piece_size(piece_size);
|
|
|
|
storage st(t, full_path.branch_path());
|
|
t.add_tracker(argv[2]);
|
|
|
|
// calculate the hash for all pieces
|
|
int num = t.num_pieces();
|
|
std::vector<char> buf(piece_size);
|
|
for (int i = 0; i < num; ++i)
|
|
{
|
|
st.read(&buf[0], i, 0, t.piece_size(i));
|
|
hasher h(&buf[0], t.piece_size(i));
|
|
t.set_hash(i, h.final());
|
|
std::cerr << (i+1) << "/" << num << "\r";
|
|
}
|
|
|
|
t.set_creator(creator_str);
|
|
|
|
// create the torrent and print it to out
|
|
entry e = t.create_torrent();
|
|
libtorrent::bencode(std::ostream_iterator<char>(out), e);
|
|
}
|
|
catch (std::exception& e)
|
|
{
|
|
std::cerr << e.what() << "\n";
|
|
}
|
|
|
|
return 0;
|
|
}
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="fast-resume">
|
|
<h1><a name="fast-resume">fast resume</a></h1>
|
|
<p>The fast resume mechanism is a way to remember which pieces are downloaded
|
|
and where they are put between sessions. You can generate fast resume data by
|
|
calling <tt class="docutils literal"><span class="pre">torrent_handle::write_resume_data()</span></tt> on <a class="reference" href="#torrent-handle">torrent_handle</a>. You can
|
|
then save this data to disk and use it when resuming the torrent. libtorrent
|
|
will not check the piece hashes then, and rely on the information given in the
|
|
fast-resume data. The fast-resume data also contains information about which
|
|
blocks, in the unfinished pieces, were downloaded, so it will not have to
|
|
start from scratch on the partially downloaded pieces.</p>
|
|
<p>To use the fast-resume data you simply give it to <a class="reference" href="#add-torrent">add_torrent()</a>, and it
|
|
will skip the time consuming checks. It may have to do the checking anyway, if
|
|
the fast-resume data is corrupt or doesn't fit the storage for that torrent,
|
|
then it will not trust the fast-resume data and just do the checking.</p>
|
|
<div class="section" id="file-format">
|
|
<h2><a name="file-format">file format</a></h2>
|
|
<p>The file format is a bencoded dictionary containing the following fields:</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="26%" />
|
|
<col width="74%" />
|
|
</colgroup>
|
|
<tbody valign="top">
|
|
<tr><td><tt class="docutils literal"><span class="pre">file-format</span></tt></td>
|
|
<td>string: "libtorrent resume file"</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">file-version</span></tt></td>
|
|
<td>integer: 1</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">info-hash</span></tt></td>
|
|
<td>string, the info hash of the torrent this data is saved for.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">blocks</span> <span class="pre">per</span> <span class="pre">piece</span></tt></td>
|
|
<td>integer, the number of blocks per piece. Must be: piece_size
|
|
/ (16 * 1024). Clamped to be within the range [1, 256]. It
|
|
is the number of blocks per (normal sized) piece. Usually
|
|
each block is 16 * 1024 bytes in size. But if piece size is
|
|
greater than 4 megabytes, the block size will increase.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">slots</span></tt></td>
|
|
<td><p class="first">list of integers. The list mappes slots to piece indices. It
|
|
tells which piece is on which slot. If piece index is -2 it
|
|
means it is free, that there's no piece there. If it is -1,
|
|
means the slot isn't allocated on disk yet. The pieces have
|
|
to meet the following requirement:</p>
|
|
<p class="last">If there's a slot at the position of the piece index,
|
|
the piece must be located in that slot.</p>
|
|
</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">peers</span></tt></td>
|
|
<td><p class="first">list of dictionaries. Each dictionary has the following
|
|
layout:</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="18%" />
|
|
<col width="82%" />
|
|
</colgroup>
|
|
<tbody valign="top">
|
|
<tr><td><tt class="docutils literal"><span class="pre">ip</span></tt></td>
|
|
<td>string, the ip address of the peer.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">port</span></tt></td>
|
|
<td>integer, the listen port of the peer</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p class="last">These are the local peers we were connected to when this
|
|
fast-resume data was saved.</p>
|
|
</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">unfinished</span></tt></td>
|
|
<td><p class="first">list of dictionaries. Each dictionary represents an
|
|
piece, and has the following layout:</p>
|
|
<table border="1" class="last docutils">
|
|
<colgroup>
|
|
<col width="23%" />
|
|
<col width="77%" />
|
|
</colgroup>
|
|
<tbody valign="top">
|
|
<tr><td><tt class="docutils literal"><span class="pre">piece</span></tt></td>
|
|
<td>integer, the index of the piece this entry
|
|
refers to.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">bitmask</span></tt></td>
|
|
<td>string, a binary bitmask representing the
|
|
blocks that have been downloaded in this
|
|
piece.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">adler32</span></tt></td>
|
|
<td>The adler32 checksum of the data in the
|
|
blocks specified by <tt class="docutils literal"><span class="pre">bitmask</span></tt>.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">file</span> <span class="pre">sizes</span></tt></td>
|
|
<td>list where each entry corresponds to a file in the file list
|
|
in the metadata. Each entry has a list of two values, the
|
|
first value is the size of the file in bytes, the second
|
|
is the timestamp when the last time someone wrote to it.
|
|
This information is used to compare with the files on disk.
|
|
All the files must match exactly this information in order
|
|
to consider the resume data as current. Otherwise a full
|
|
re-check is issued.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="threads">
|
|
<h1><a name="threads">threads</a></h1>
|
|
<p>libtorrent starts 3 threads.</p>
|
|
<blockquote>
|
|
<ul class="simple">
|
|
<li>The first thread is the main thread that will sit
|
|
idle in a <tt class="docutils literal"><span class="pre">select()</span></tt> call most of the time. This thread runs the main loop
|
|
that will send and receive data on all connections.</li>
|
|
<li>The second thread is a hash-check thread. Whenever a torrent is added it will
|
|
first be passed to this thread for checking the files that may already have been
|
|
downloaded. If there is any resume data this thread will make sure it is valid
|
|
and matches the files. Once the torrent has been checked, it is passed on to the
|
|
main thread that will start it. The hash-check thread has a queue of torrents,
|
|
it will only check one torrent at a time.</li>
|
|
<li>The third thread is spawned the first time a tracker is contacted. It is used
|
|
for doing calls to <tt class="docutils literal"><span class="pre">gethostbyname()</span></tt>. Since this call is blocking (and may block
|
|
for several seconds if the dns server is down or slow) it is necessary to run this
|
|
in its own thread to avoid stalling the main thread.</li>
|
|
</ul>
|
|
</blockquote>
|
|
</div>
|
|
<div class="section" id="storage-allocation">
|
|
<h1><a name="storage-allocation">storage allocation</a></h1>
|
|
<p>There are two modes in which storage (files on disk) are allocated in libtorrent.</p>
|
|
<blockquote>
|
|
<ul class="simple">
|
|
<li>The traditional <em>full allocation</em> mode, where the entire files are filled up with
|
|
zeroes before anything is downloaded.</li>
|
|
<li>And the <em>compact allocation</em> mode, where only files are allocated for actual
|
|
pieces that have been downloaded. This is the default allocation mode in libtorrent.</li>
|
|
</ul>
|
|
</blockquote>
|
|
<p>The allocation mode is selected when a torrent is started. It is passed as a boolean
|
|
argument to <tt class="docutils literal"><span class="pre">session::add_torrent()</span></tt> (see <a class="reference" href="#add-torrent">add_torrent()</a>). These two modes have
|
|
different drawbacks and benefits.</p>
|
|
<div class="section" id="full-allocation">
|
|
<h2><a name="full-allocation">full allocation</a></h2>
|
|
<p>When a torrent is started in full allocation mode, the checker thread (see <a class="reference" href="#threads">threads</a>)
|
|
will make sure that the entire storage is allocated, and fill any gaps with zeroes.
|
|
It will of course still check for existing pieces and fast resume data. The main
|
|
drawbacks of this mode are:</p>
|
|
<blockquote>
|
|
<ul class="simple">
|
|
<li>It will take longer to start the torrent, since it will need to fill the files
|
|
with zeroes. This delay is linearly dependent on the size of the download.</li>
|
|
<li>The download will occupy unnecessary disk space between download sessions.</li>
|
|
<li>Disk caches usually perform extremely poorly with random access to large files
|
|
and may slow down a download considerably.</li>
|
|
</ul>
|
|
</blockquote>
|
|
<p>The benefit of thise mode are:</p>
|
|
<blockquote>
|
|
<ul class="simple">
|
|
<li>Downloaded pieces are written directly to their final place in the files and the
|
|
total number of disk operations will be fewer and may also play nicer to
|
|
filesystems' file allocation, and reduce fragmentation.</li>
|
|
<li>No risk of a download failing because of a full disk during download.</li>
|
|
</ul>
|
|
</blockquote>
|
|
</div>
|
|
<div class="section" id="compact-allocation">
|
|
<h2><a name="compact-allocation">compact allocation</a></h2>
|
|
<p>The compact allocation will only allocate as much storage as it needs to keep the
|
|
pieces downloaded so far. This means that pieces will be moved around to be placed
|
|
at their final position in the files while downloading (to make sure the completed
|
|
download has all its pieces in the correct place). So, the main drawbacks are:</p>
|
|
<blockquote>
|
|
<ul class="simple">
|
|
<li>More disk operations while downloading since pieces are moved around.</li>
|
|
<li>Potentially more fragmentation in the filesystem.</li>
|
|
</ul>
|
|
</blockquote>
|
|
<p>The benefits though, are:</p>
|
|
<blockquote>
|
|
<ul class="simple">
|
|
<li>No startup delay, since the files doesn't need allocating.</li>
|
|
<li>The download will not use unnecessary disk space.</li>
|
|
<li>Disk caches perform much better than in full allocation and raises the download
|
|
speed limit imposed by the disk.</li>
|
|
</ul>
|
|
</blockquote>
|
|
<p>The algorithm that is used when allocating pieces and slots isn't very complicated.
|
|
For the interested, a description follows.</p>
|
|
<p>storing a piece:</p>
|
|
<ol class="arabic simple">
|
|
<li>let <strong>A</strong> be a newly downloaded piece, with index <strong>n</strong>.</li>
|
|
<li>let <strong>s</strong> be the number of slots allocated in the file we're
|
|
downloading to. (the number of pieces it has room for).</li>
|
|
<li>if <strong>n</strong> >= <strong>s</strong> then allocate a new slot and put the piece there.</li>
|
|
<li>if <strong>n</strong> < <strong>s</strong> then allocate a new slot, move the data at
|
|
slot <strong>n</strong> to the new slot and put <strong>A</strong> in slot <strong>n</strong>.</li>
|
|
</ol>
|
|
<p>allocating a new slot:</p>
|
|
<ol class="arabic simple">
|
|
<li>if there's an unassigned slot (a slot that doesn't
|
|
contain any piece), return that slot index.</li>
|
|
<li>append the new slot at the end of the file (or find an unused slot).</li>
|
|
<li>let <strong>i</strong> be the index of newly allocated slot</li>
|
|
<li>if we have downloaded piece index <strong>i</strong> already (to slot <strong>j</strong>) then<ol class="arabic">
|
|
<li>move the data at slot <strong>j</strong> to slot <strong>i</strong>.</li>
|
|
<li>return slot index <strong>j</strong> as the newly allocated free slot.</li>
|
|
</ol>
|
|
</li>
|
|
<li>return <strong>i</strong> as the newly allocated slot.</li>
|
|
</ol>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="extensions">
|
|
<h1><a name="extensions">extensions</a></h1>
|
|
<p>These extensions all operates within the <a class="reference" href="extension_protocol.html">extension protocol</a>. The
|
|
name of the extension is the name used in the extension-list packets,
|
|
and the payload is the data in the extended message (not counting the
|
|
length-prefix, message-id nor extension-id).</p>
|
|
<p>Note that since this protocol relies on one of the reserved bits in the
|
|
handshake, it may be incompatible with future versions of the mainline
|
|
bittorrent client.</p>
|
|
<p>These are the extensions that are currently implemented.</p>
|
|
<div class="section" id="chat-messages">
|
|
<h2><a name="chat-messages">chat messages</a></h2>
|
|
<p>Extension name: "chat"</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%" />
|
|
<col width="85%" />
|
|
</colgroup>
|
|
<tbody valign="top">
|
|
<tr><td>"msg"</td>
|
|
<td>This is a string that contains a message that
|
|
should be displayed to the user.</td>
|
|
</tr>
|
|
<tr><td>"ctrl"</td>
|
|
<td>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.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</blockquote>
|
|
</div>
|
|
<div class="section" id="metadata-from-peers">
|
|
<h2><a name="metadata-from-peers">metadata from peers</a></h2>
|
|
<p>Extension name: "metadata"</p>
|
|
<p>The point with this extension is that you don't have to distribute the
|
|
metadata (.torrent-file) separately. The metadata can be distributed
|
|
through the bittorrent swarm. The only thing you need to download such
|
|
a torrent is the tracker url and the info-hash of the torrent.</p>
|
|
<p>It works by assuming that the initial seeder has the metadata and that
|
|
the metadata will propagate through the network as more peers join.</p>
|
|
<p>There are three kinds of messages in the metadata extension. These packets
|
|
are put as payload to the extension message. The three packets are:</p>
|
|
<blockquote>
|
|
<ul class="simple">
|
|
<li>request metadata</li>
|
|
<li>metadata</li>
|
|
<li>don't have metadata</li>
|
|
</ul>
|
|
</blockquote>
|
|
<p>request metadata:</p>
|
|
<blockquote>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="17%" />
|
|
<col width="23%" />
|
|
<col width="61%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr><th>size</th>
|
|
<th>name</th>
|
|
<th>description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<tr><td>uint8_t</td>
|
|
<td>msg_type</td>
|
|
<td>Determines the kind of message this is
|
|
0 means 'request metadata'</td>
|
|
</tr>
|
|
<tr><td>uint8_t</td>
|
|
<td>start</td>
|
|
<td>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.</td>
|
|
</tr>
|
|
<tr><td>uint8_t</td>
|
|
<td>size</td>
|
|
<td>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.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</blockquote>
|
|
<p>metadata:</p>
|
|
<blockquote>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="17%" />
|
|
<col width="23%" />
|
|
<col width="61%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr><th>size</th>
|
|
<th>name</th>
|
|
<th>description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<tr><td>uint8_t</td>
|
|
<td>msg_type</td>
|
|
<td>1 means 'metadata'</td>
|
|
</tr>
|
|
<tr><td>int32_t</td>
|
|
<td>total_size</td>
|
|
<td>The total size of the metadata, given
|
|
in number of bytes.</td>
|
|
</tr>
|
|
<tr><td>int32_t</td>
|
|
<td>offset</td>
|
|
<td>The offset of where the metadata block
|
|
in this message belongs in the final
|
|
metadata. This is given in bytes.</td>
|
|
</tr>
|
|
<tr><td>uint8_t[]</td>
|
|
<td>metadata</td>
|
|
<td>The actual metadata block. The size of
|
|
this part is given implicit by the
|
|
length prefix in the bittorrent
|
|
protocol packet.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</blockquote>
|
|
<p>Don't have metadata:</p>
|
|
<blockquote>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="17%" />
|
|
<col width="23%" />
|
|
<col width="61%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr><th>size</th>
|
|
<th>name</th>
|
|
<th>description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<tr><td>uint8_t</td>
|
|
<td>msg_type</td>
|
|
<td>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.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</blockquote>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="filename-checks">
|
|
<h1><a name="filename-checks">filename checks</a></h1>
|
|
<p>Boost.Filesystem will by default check all its paths to make sure they conform
|
|
to filename requirements on many platforms. If you don't want this check, you can
|
|
set it to either only check for native filesystem requirements or turn it off
|
|
alltogether. You can use:</p>
|
|
<pre class="literal-block">
|
|
boost::filesystem::path::default_name_check(boost::filesystem::native);
|
|
</pre>
|
|
<p>for example. For more information, see the <a class="reference" href="http://www.boost.org/libs/filesystem/doc/index.htm">Boost.Filesystem docs</a>.</p>
|
|
</div>
|
|
<div class="section" id="acknowledgements">
|
|
<h1><a name="acknowledgements">acknowledgements</a></h1>
|
|
<p>Written by Arvid Norberg. Copyright © 2003-2005</p>
|
|
<p>Contributions by Magnus Jonsson, Daniel Wallin and Cory Nelson</p>
|
|
<p>Big thanks to Michael Wojciechowski and Peter Koeleman for making the autotools
|
|
scripts.</p>
|
|
<p>Thanks to Reimond Retz for bugfixes, suggestions and testing</p>
|
|
<p>Thanks to <a class="reference" href="http://www.cs.umu.se">University of Umeå</a> for providing development and test hardware.</p>
|
|
<p>Project is hosted by sourceforge.</p>
|
|
<p><a class="reference" href="http://sourceforge.net"><img alt="sf_logo" src="http://sourceforge.net/sflogo.php?group_id=7994" /></a></p>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html>
|