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

added documentation of udp-tracker protocol and finalized support for it.

Browse Source
This commit is contained in:
Arvid Norberg
2004-01-22 22:45:52 +00:00
parent b897315abb
commit a3b47ec826
12 changed files with 799 additions and 174 deletions
Download Patch File Download Diff File Expand all files Collapse all files

95
docs/manual.html
View File

@@ -13,57 +13,57 @@
<div class="contents topic" id="contents">
<p class="topic-title"><a name="contents">Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#introduction" id="id8" name="id8">introduction</a></li>
<li><a class="reference" href="#building" id="id9" name="id9">building</a></li>
<li><a class="reference" href="#using" id="id10" name="id10">using</a></li>
<li><a class="reference" href="#session" id="id11" name="id11">session</a></li>
<li><a class="reference" href="#parsing-torrent-files" id="id12" name="id12">parsing torrent files</a></li>
<li><a class="reference" href="#entry" id="id13" name="id13">entry</a></li>
<li><a class="reference" href="#torrent-info" id="id14" name="id14">torrent_info</a></li>
<li><a class="reference" href="#torrent-handle" id="id15" name="id15">torrent_handle</a><ul>
<li><a class="reference" href="#status" id="id16" name="id16">status()</a></li>
<li><a class="reference" href="#get-download-queue" id="id17" name="id17">get_download_queue()</a></li>
<li><a class="reference" href="#get-peer-info" id="id18" name="id18">get_peer_info()</a></li>
<li><a class="reference" href="#get-torrent-info" id="id19" name="id19">get_torrent_info()</a></li>
<li><a class="reference" href="#is-valid" id="id20" name="id20">is_valid()</a></li>
<li><a class="reference" href="#introduction" id="id9" name="id9">introduction</a></li>
<li><a class="reference" href="#building" id="id10" name="id10">building</a></li>
<li><a class="reference" href="#using" id="id11" name="id11">using</a></li>
<li><a class="reference" href="#session" id="id12" name="id12">session</a></li>
<li><a class="reference" href="#parsing-torrent-files" id="id13" name="id13">parsing torrent files</a></li>
<li><a class="reference" href="#entry" id="id14" name="id14">entry</a></li>
<li><a class="reference" href="#torrent-info" id="id15" name="id15">torrent_info</a></li>
<li><a class="reference" href="#torrent-handle" id="id16" name="id16">torrent_handle</a><ul>
<li><a class="reference" href="#status" id="id17" name="id17">status()</a></li>
<li><a class="reference" href="#get-download-queue" id="id18" name="id18">get_download_queue()</a></li>
<li><a class="reference" href="#get-peer-info" id="id19" name="id19">get_peer_info()</a></li>
<li><a class="reference" href="#get-torrent-info" id="id20" name="id20">get_torrent_info()</a></li>
<li><a class="reference" href="#is-valid" id="id21" name="id21">is_valid()</a></li>
</ul>
</li>
<li><a class="reference" href="#address" id="id21" name="id21">address</a></li>
<li><a class="reference" href="#http-settings" id="id22" name="id22">http_settings</a></li>
<li><a class="reference" href="#big-number" id="id23" name="id23">big_number</a></li>
<li><a class="reference" href="#hasher" id="id24" name="id24">hasher</a></li>
<li><a class="reference" href="#fingerprint" id="id25" name="id25">fingerprint</a><ul>
<li><a class="reference" href="#identify-client" id="id26" name="id26">identify_client</a></li>
<li><a class="reference" href="#address" id="id22" name="id22">address</a></li>
<li><a class="reference" href="#http-settings" id="id23" name="id23">http_settings</a></li>
<li><a class="reference" href="#big-number" id="id24" name="id24">big_number</a></li>
<li><a class="reference" href="#hasher" id="id25" name="id25">hasher</a></li>
<li><a class="reference" href="#fingerprint" id="id26" name="id26">fingerprint</a><ul>
<li><a class="reference" href="#identify-client" id="id27" name="id27">identify_client</a></li>
</ul>
</li>
<li><a class="reference" href="#alerts" id="id27" name="id27">alerts</a><ul>
<li><a class="reference" href="#tracker-alert" id="id28" name="id28">tracker_alert</a></li>
<li><a class="reference" href="#hash-failed-alert" id="id29" name="id29">hash_failed_alert</a></li>
<li><a class="reference" href="#peer-error-alert" id="id30" name="id30">peer_error_alert</a></li>
<li><a class="reference" href="#invalid-request-alert" id="id31" name="id31">invalid_request_alert</a></li>
<li><a class="reference" href="#torrent-finished-alert" id="id32" name="id32">torrent_finished_alert</a></li>
<li><a class="reference" href="#dispatcher" id="id33" name="id33">dispatcher</a></li>
<li><a class="reference" href="#alerts" id="id28" name="id28">alerts</a><ul>
<li><a class="reference" href="#tracker-alert" id="id29" name="id29">tracker_alert</a></li>
<li><a class="reference" href="#hash-failed-alert" id="id30" name="id30">hash_failed_alert</a></li>
<li><a class="reference" href="#peer-error-alert" id="id31" name="id31">peer_error_alert</a></li>
<li><a class="reference" href="#invalid-request-alert" id="id32" name="id32">invalid_request_alert</a></li>
<li><a class="reference" href="#torrent-finished-alert" id="id33" name="id33">torrent_finished_alert</a></li>
<li><a class="reference" href="#dispatcher" id="id34" name="id34">dispatcher</a></li>
</ul>
</li>
<li><a class="reference" href="#exceptions" id="id34" name="id34">exceptions</a><ul>
<li><a class="reference" href="#invalid-handle" id="id35" name="id35">invalid_handle</a></li>
<li><a class="reference" href="#duplicate-torrent" id="id36" name="id36">duplicate_torrent</a></li>
<li><a class="reference" href="#invalid-encoding" id="id37" name="id37">invalid_encoding</a></li>
<li><a class="reference" href="#type-error" id="id38" name="id38">type_error</a></li>
<li><a class="reference" href="#invalid-torrent-file" id="id39" name="id39">invalid_torrent_file</a></li>
<li><a class="reference" href="#exceptions" id="id35" name="id35">exceptions</a><ul>
<li><a class="reference" href="#invalid-handle" id="id36" name="id36">invalid_handle</a></li>
<li><a class="reference" href="#duplicate-torrent" id="id37" name="id37">duplicate_torrent</a></li>
<li><a class="reference" href="#invalid-encoding" id="id38" name="id38">invalid_encoding</a></li>
<li><a class="reference" href="#type-error" id="id39" name="id39">type_error</a></li>
<li><a class="reference" href="#invalid-torrent-file" id="id40" name="id40">invalid_torrent_file</a></li>
</ul>
</li>
<li><a class="reference" href="#examples" id="id40" name="id40">examples</a><ul>
<li><a class="reference" href="#dump-torrent" id="id41" name="id41">dump_torrent</a></li>
<li><a class="reference" href="#simple-client" id="id42" name="id42">simple client</a></li>
<li><a class="reference" href="#examples" id="id41" name="id41">examples</a><ul>
<li><a class="reference" href="#dump-torrent" id="id42" name="id42">dump_torrent</a></li>
<li><a class="reference" href="#simple-client" id="id43" name="id43">simple client</a></li>
</ul>
</li>
<li><a class="reference" href="#fast-resume" id="id43" name="id43">fast resume</a><ul>
<li><a class="reference" href="#file-format" id="id44" name="id44">file format</a></li>
<li><a class="reference" href="#fast-resume" id="id44" name="id44">fast resume</a><ul>
<li><a class="reference" href="#file-format" id="id45" name="id45">file format</a></li>
</ul>
</li>
<li><a class="reference" href="#extensions" id="id45" name="id45">extensions</a></li>
<li><a class="reference" href="#aknowledgements" id="id46" name="id46">Aknowledgements</a></li>
<li><a class="reference" href="#extensions" id="id46" name="id46">extensions</a></li>
<li><a class="reference" href="#aknowledgements" id="id47" name="id47">Aknowledgements</a></li>
</ul>
</div>
<div class="section" id="introduction">
@@ -103,6 +103,7 @@ peers in a separate fast-resume file.</li>
<li>Supports the extension protocol <a class="reference" href="http://nolar.com/azureus/extended.htm">described by Nolar</a>. See <a class="reference" href="#extensions">extensions</a>.</li>
<li>Supports files &gt; 2 gigabytes (currently only on windows).</li>
<li>Supports the <tt class="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>.</li>
</ul>
</blockquote>
<p>Functions that are yet to be implemented:</p>
@@ -223,7 +224,7 @@ The main thread will be idle as long it doesn't have any torrents to participate
You add torrents through the <tt class="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="literal"><span class="pre">save_path</span></tt> will be prepended to the directory-
structure in the torrent-file. <tt class="literal"><span class="pre">add_torrent</span></tt> will throw <tt class="literal"><span class="pre">duplicate_torrent</span></tt> exception
structure in the torrent-file. <tt class="literal"><span class="pre">add_torrent</span></tt> will throw <a class="reference" href="#duplicate-torrent">duplicate_torrent</a> exception
if the torrent already exists in the session.</p>
<p>The optional last parameter, <tt class="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
@@ -232,7 +233,7 @@ is available. The fast-resume data can be acquired from a running torrent by cal
the tracker that we've stopped participating in the swarm.</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="literal"><span class="pre">add_torrent()</span></tt> will throw
<tt class="literal"><span class="pre">duplicate_torrent</span></tt> which derives from <tt class="literal"><span class="pre">std::exception</span></tt>.</p>
<a class="reference" href="#duplicate-torrent">duplicate_torrent</a> which derives from <tt class="literal"><span class="pre">std::exception</span></tt>.</p>
<p>The difference between the two constructors is that one of them takes a fingerprint
as argument. If this 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
@@ -246,7 +247,6 @@ If some trackers are down, they will timout. All this before the destructor of s
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="literal"><span class="pre">set_http_settings()</span></tt>.</p>
<p>How to parse a torrent file and create a <tt class="literal"><span class="pre">torrent_info</span></tt> object is described below.</p>
<p>The <a class="reference" href="#torrent-handle">torrent_handle</a> returned by <tt class="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 constructor takes a listen port as argument, if the given port is busy it will
@@ -486,6 +486,7 @@ struct torrent_handle
boost::filsystem::path save_path() const;
void set_max_uploads(int max_uploads);
void set_max_connections(int max_connections);
sha1_hash info_hash() const;
@@ -517,6 +518,10 @@ as a standard client.</p>
<p><tt class="literal"><span class="pre">info_hash()</span></tt> returns the info hash for the torrent.</p>
<p><tt class="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="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>
<p><tt class="literal"><span class="pre">write_resume_data()</span></tt> generates fast-resume data and returns it as an entry. This entry
is suitable for being bencoded. For more information about how fast-resume works, see <a class="reference" href="#fast-resume">fast resume</a>.
It may throw <a class="reference" href="#invalid-handle">invalid_handle</a> if the torrent handle is invalid.</p>
@@ -752,7 +757,7 @@ the total number of bytes in this block.</p>
</div>
<div class="section" id="get-torrent-info">
<h2><a name="get-torrent-info">get_torrent_info()</a></h2>
<p>Returns a const reference to the <tt class="literal"><span class="pre">torrent_info</span></tt> object associated with this torrent.
<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, <a class="reference" href="#invalid-handle">invalid_handle</a> exception will be thrown.</p>
</div>
@@ -1440,8 +1445,8 @@ with future versions of bittorrent.</p>
</div>
<div class="section" id="aknowledgements">
<h1><a name="aknowledgements">Aknowledgements</a></h1>
<p>Written by Arvid Norberg and Daniel Wallin. Copyright (c) 2003</p>
<p>Contributions by Magnus Jonsson</p>
<p>Written by Arvid Norberg. Copyright (c) 2003</p>
<p>Contributions by Magnus Jonsson and Daniel Wallin</p>
<p>Thanks to Reimond Retz for bugfixes, suggestions and testing</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>