From 5df0e97d217c2b4150f668d03ceb23c6f9429eca Mon Sep 17 00:00:00 2001
From: Arvid Norberg <arvid@libtorrent.org>
Date: Tue, 16 Aug 2005 11:45:37 +0000
Subject: [PATCH] *** empty log message ***

---
 docs/manual.html | 156 +++++++++++++++++++++++++++--------------------
 docs/manual.rst  |  39 +++++++++---
 2 files changed, 120 insertions(+), 75 deletions(-)

diff --git a/docs/manual.html b/docs/manual.html
index aa04030cf..73750e168 100755
--- a/docs/manual.html
+++ b/docs/manual.html
@@ -73,85 +73,86 @@
 <li><a class="reference" href="#is-seed" id="id59" name="id59">is_seed()</a></li>
 <li><a class="reference" href="#has-metadata" id="id60" name="id60">has_metadata()</a></li>
 <li><a class="reference" href="#set-tracker-login" id="id61" name="id61">set_tracker_login()</a></li>
-<li><a class="reference" href="#use-interface" id="id62" name="id62">use_interface()</a></li>
-<li><a class="reference" href="#info-hash" id="id63" name="id63">info_hash()</a></li>
-<li><a class="reference" href="#id11" id="id64" name="id64">set_max_uploads() set_max_connections()</a></li>
-<li><a class="reference" href="#write-resume-data" id="id65" name="id65">write_resume_data()</a></li>
-<li><a class="reference" href="#metadata" id="id66" name="id66">metadata()</a></li>
-<li><a class="reference" href="#id12" id="id67" name="id67">status()</a></li>
-<li><a class="reference" href="#get-download-queue" id="id68" name="id68">get_download_queue()</a></li>
-<li><a class="reference" href="#get-peer-info" id="id69" name="id69">get_peer_info()</a></li>
-<li><a class="reference" href="#get-torrent-info" id="id70" name="id70">get_torrent_info()</a></li>
-<li><a class="reference" href="#is-valid" id="id71" name="id71">is_valid()</a></li>
+<li><a class="reference" href="#trackers-replace-trackers" id="id62" name="id62">trackers() replace_trackers()</a></li>
+<li><a class="reference" href="#use-interface" id="id63" name="id63">use_interface()</a></li>
+<li><a class="reference" href="#info-hash" id="id64" name="id64">info_hash()</a></li>
+<li><a class="reference" href="#id11" id="id65" name="id65">set_max_uploads() set_max_connections()</a></li>
+<li><a class="reference" href="#write-resume-data" id="id66" name="id66">write_resume_data()</a></li>
+<li><a class="reference" href="#metadata" id="id67" name="id67">metadata()</a></li>
+<li><a class="reference" href="#id12" id="id68" name="id68">status()</a></li>
+<li><a class="reference" href="#get-download-queue" id="id69" name="id69">get_download_queue()</a></li>
+<li><a class="reference" href="#get-peer-info" id="id70" name="id70">get_peer_info()</a></li>
+<li><a class="reference" href="#get-torrent-info" id="id71" name="id71">get_torrent_info()</a></li>
+<li><a class="reference" href="#is-valid" id="id72" name="id72">is_valid()</a></li>
 </ul>
 </li>
-<li><a class="reference" href="#torrent-status" id="id72" name="id72">torrent_status</a></li>
-<li><a class="reference" href="#peer-info" id="id73" name="id73">peer_info</a></li>
-<li><a class="reference" href="#address" id="id74" name="id74">address</a></li>
-<li><a class="reference" href="#http-settings" id="id75" name="id75">http_settings</a></li>
-<li><a class="reference" href="#ip-filter" id="id76" name="id76">ip_filter</a><ul>
-<li><a class="reference" href="#id14" id="id77" name="id77">ip_filter()</a></li>
-<li><a class="reference" href="#add-rule" id="id78" name="id78">add_rule()</a></li>
-<li><a class="reference" href="#access" id="id79" name="id79">access()</a></li>
-<li><a class="reference" href="#export-filter" id="id80" name="id80">export_filter()</a></li>
+<li><a class="reference" href="#torrent-status" id="id73" name="id73">torrent_status</a></li>
+<li><a class="reference" href="#peer-info" id="id74" name="id74">peer_info</a></li>
+<li><a class="reference" href="#address" id="id75" name="id75">address</a></li>
+<li><a class="reference" href="#http-settings" id="id76" name="id76">http_settings</a></li>
+<li><a class="reference" href="#ip-filter" id="id77" name="id77">ip_filter</a><ul>
+<li><a class="reference" href="#id14" id="id78" name="id78">ip_filter()</a></li>
+<li><a class="reference" href="#add-rule" id="id79" name="id79">add_rule()</a></li>
+<li><a class="reference" href="#access" id="id80" name="id80">access()</a></li>
+<li><a class="reference" href="#export-filter" id="id81" name="id81">export_filter()</a></li>
 </ul>
 </li>
-<li><a class="reference" href="#big-number" id="id81" name="id81">big_number</a></li>
-<li><a class="reference" href="#hasher" id="id82" name="id82">hasher</a></li>
-<li><a class="reference" href="#fingerprint" id="id83" name="id83">fingerprint</a></li>
-<li><a class="reference" href="#free-functions" id="id84" name="id84">free functions</a><ul>
-<li><a class="reference" href="#identify-client" id="id85" name="id85">identify_client()</a></li>
-<li><a class="reference" href="#bdecode-bencode" id="id86" name="id86">bdecode() bencode()</a></li>
+<li><a class="reference" href="#big-number" id="id82" name="id82">big_number</a></li>
+<li><a class="reference" href="#hasher" id="id83" name="id83">hasher</a></li>
+<li><a class="reference" href="#fingerprint" id="id84" name="id84">fingerprint</a></li>
+<li><a class="reference" href="#free-functions" id="id85" name="id85">free functions</a><ul>
+<li><a class="reference" href="#identify-client" id="id86" name="id86">identify_client()</a></li>
+<li><a class="reference" href="#bdecode-bencode" id="id87" name="id87">bdecode() bencode()</a></li>
 </ul>
 </li>
-<li><a class="reference" href="#alerts" id="id87" name="id87">alerts</a><ul>
-<li><a class="reference" href="#listen-failed-alert" id="id88" name="id88">listen_failed_alert</a></li>
-<li><a class="reference" href="#file-error-alert" id="id89" name="id89">file_error_alert</a></li>
-<li><a class="reference" href="#tracker-announce-alert" id="id90" name="id90">tracker_announce_alert</a></li>
-<li><a class="reference" href="#tracker-alert" id="id91" name="id91">tracker_alert</a></li>
-<li><a class="reference" href="#tracker-reply-alert" id="id92" name="id92">tracker_reply_alert</a></li>
-<li><a class="reference" href="#tracker-warning-alert" id="id93" name="id93">tracker_warning_alert</a></li>
-<li><a class="reference" href="#hash-failed-alert" id="id94" name="id94">hash_failed_alert</a></li>
-<li><a class="reference" href="#peer-ban-alert" id="id95" name="id95">peer_ban_alert</a></li>
-<li><a class="reference" href="#peer-error-alert" id="id96" name="id96">peer_error_alert</a></li>
-<li><a class="reference" href="#invalid-request-alert" id="id97" name="id97">invalid_request_alert</a></li>
-<li><a class="reference" href="#torrent-finished-alert" id="id98" name="id98">torrent_finished_alert</a></li>
-<li><a class="reference" href="#metadata-received-alert" id="id99" name="id99">metadata_received_alert</a></li>
-<li><a class="reference" href="#fastresume-rejected-alert" id="id100" name="id100">fastresume_rejected_alert</a></li>
-<li><a class="reference" href="#dispatcher" id="id101" name="id101">dispatcher</a></li>
+<li><a class="reference" href="#alerts" id="id88" name="id88">alerts</a><ul>
+<li><a class="reference" href="#listen-failed-alert" id="id89" name="id89">listen_failed_alert</a></li>
+<li><a class="reference" href="#file-error-alert" id="id90" name="id90">file_error_alert</a></li>
+<li><a class="reference" href="#tracker-announce-alert" id="id91" name="id91">tracker_announce_alert</a></li>
+<li><a class="reference" href="#tracker-alert" id="id92" name="id92">tracker_alert</a></li>
+<li><a class="reference" href="#tracker-reply-alert" id="id93" name="id93">tracker_reply_alert</a></li>
+<li><a class="reference" href="#tracker-warning-alert" id="id94" name="id94">tracker_warning_alert</a></li>
+<li><a class="reference" href="#hash-failed-alert" id="id95" name="id95">hash_failed_alert</a></li>
+<li><a class="reference" href="#peer-ban-alert" id="id96" name="id96">peer_ban_alert</a></li>
+<li><a class="reference" href="#peer-error-alert" id="id97" name="id97">peer_error_alert</a></li>
+<li><a class="reference" href="#invalid-request-alert" id="id98" name="id98">invalid_request_alert</a></li>
+<li><a class="reference" href="#torrent-finished-alert" id="id99" name="id99">torrent_finished_alert</a></li>
+<li><a class="reference" href="#metadata-received-alert" id="id100" name="id100">metadata_received_alert</a></li>
+<li><a class="reference" href="#fastresume-rejected-alert" id="id101" name="id101">fastresume_rejected_alert</a></li>
+<li><a class="reference" href="#dispatcher" id="id102" name="id102">dispatcher</a></li>
 </ul>
 </li>
-<li><a class="reference" href="#exceptions" id="id102" name="id102">exceptions</a><ul>
-<li><a class="reference" href="#invalid-handle" id="id103" name="id103">invalid_handle</a></li>
-<li><a class="reference" href="#duplicate-torrent" id="id104" name="id104">duplicate_torrent</a></li>
-<li><a class="reference" href="#invalid-encoding" id="id105" name="id105">invalid_encoding</a></li>
-<li><a class="reference" href="#type-error" id="id106" name="id106">type_error</a></li>
-<li><a class="reference" href="#invalid-torrent-file" id="id107" name="id107">invalid_torrent_file</a></li>
+<li><a class="reference" href="#exceptions" id="id103" name="id103">exceptions</a><ul>
+<li><a class="reference" href="#invalid-handle" id="id104" name="id104">invalid_handle</a></li>
+<li><a class="reference" href="#duplicate-torrent" id="id105" name="id105">duplicate_torrent</a></li>
+<li><a class="reference" href="#invalid-encoding" id="id106" name="id106">invalid_encoding</a></li>
+<li><a class="reference" href="#type-error" id="id107" name="id107">type_error</a></li>
+<li><a class="reference" href="#invalid-torrent-file" id="id108" name="id108">invalid_torrent_file</a></li>
 </ul>
 </li>
-<li><a class="reference" href="#examples" id="id108" name="id108">examples</a><ul>
-<li><a class="reference" href="#dump-torrent" id="id109" name="id109">dump_torrent</a></li>
-<li><a class="reference" href="#simple-client" id="id110" name="id110">simple client</a></li>
-<li><a class="reference" href="#make-torrent" id="id111" name="id111">make_torrent</a></li>
+<li><a class="reference" href="#examples" id="id109" name="id109">examples</a><ul>
+<li><a class="reference" href="#dump-torrent" id="id110" name="id110">dump_torrent</a></li>
+<li><a class="reference" href="#simple-client" id="id111" name="id111">simple client</a></li>
+<li><a class="reference" href="#make-torrent" id="id112" name="id112">make_torrent</a></li>
 </ul>
 </li>
-<li><a class="reference" href="#fast-resume" id="id112" name="id112">fast resume</a><ul>
-<li><a class="reference" href="#file-format" id="id113" name="id113">file format</a></li>
+<li><a class="reference" href="#fast-resume" id="id113" name="id113">fast resume</a><ul>
+<li><a class="reference" href="#file-format" id="id114" name="id114">file format</a></li>
 </ul>
 </li>
-<li><a class="reference" href="#threads" id="id114" name="id114">threads</a></li>
-<li><a class="reference" href="#storage-allocation" id="id115" name="id115">storage allocation</a><ul>
-<li><a class="reference" href="#full-allocation" id="id116" name="id116">full allocation</a></li>
-<li><a class="reference" href="#compact-allocation" id="id117" name="id117">compact allocation</a></li>
+<li><a class="reference" href="#threads" id="id115" name="id115">threads</a></li>
+<li><a class="reference" href="#storage-allocation" id="id116" name="id116">storage allocation</a><ul>
+<li><a class="reference" href="#full-allocation" id="id117" name="id117">full allocation</a></li>
+<li><a class="reference" href="#compact-allocation" id="id118" name="id118">compact allocation</a></li>
 </ul>
 </li>
-<li><a class="reference" href="#extensions" id="id118" name="id118">extensions</a><ul>
-<li><a class="reference" href="#chat-messages" id="id119" name="id119">chat messages</a></li>
-<li><a class="reference" href="#metadata-from-peers" id="id120" name="id120">metadata from peers</a></li>
+<li><a class="reference" href="#extensions" id="id119" name="id119">extensions</a><ul>
+<li><a class="reference" href="#chat-messages" id="id120" name="id120">chat messages</a></li>
+<li><a class="reference" href="#metadata-from-peers" id="id121" name="id121">metadata from peers</a></li>
 </ul>
 </li>
-<li><a class="reference" href="#filename-checks" id="id121" name="id121">filename checks</a></li>
-<li><a class="reference" href="#acknowledgements" id="id122" name="id122">acknowledgements</a></li>
+<li><a class="reference" href="#filename-checks" id="id122" name="id122">filename checks</a></li>
+<li><a class="reference" href="#acknowledgements" id="id123" name="id123">acknowledgements</a></li>
 </ul>
 </div>
 <div class="section" id="introduction">
@@ -329,6 +330,9 @@ libtorrent as a dll too, by typing <tt class="docutils literal"><span class="pre
 explicitly build a static library.</p>
 <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.
@@ -368,7 +372,7 @@ error telling you what failed.</p>
 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 in some cases that
+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
@@ -400,6 +404,8 @@ spaces in their names to remove the spaces or move the libtorrent directory.</p>
 <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 test, 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">
@@ -1180,7 +1186,6 @@ struct torrent_handle
 <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><strong>TODO: document trackers() and replace_trackers()</strong></p>
 <p><strong>TODO: document filter_piece(), filter_pieces(), is_piece_filtered(), filtered_pieces() and filter_files()</strong></p>
 <div class="section" id="save-path">
 <h2><a name="save-path">save_path()</a></h2>
@@ -1305,6 +1310,23 @@ void set_tracker_login(std::string const&amp; username, std::string const&amp; p
 <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&lt;announce_entry&gt; const&amp; trackers() const;
+void replace_trackers(std::vector&lt;announce_entry&gt; const&amp;);
+</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>
@@ -1461,6 +1483,7 @@ it has been added to the session. Usually this is because the storage for the to
 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><strong>TODO: document storage</strong></p>
 </div>
 </div>
 <div class="section" id="torrent-status">
@@ -3038,8 +3061,6 @@ doesn't have any metadata.</td>
 </tbody>
 </table>
 </blockquote>
-<p>The current implementation of this extension in libtorrent is experimental,
-and not optimal in any way.</p>
 </div>
 </div>
 <div class="section" id="filename-checks">
@@ -3057,9 +3078,10 @@ boost::filesystem::path::default_name_check(boost::filesystem::native);
 <h1><a name="acknowledgements">acknowledgements</a></h1>
 <p>Written by Arvid Norberg. Copyright (c) 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>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>
diff --git a/docs/manual.rst b/docs/manual.rst
index 7c6e86064..92f271b9c 100755
--- a/docs/manual.rst
+++ b/docs/manual.rst
@@ -213,6 +213,10 @@ explicitly build a static library.
 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.
 
+To build the examples, just change directory to the examples directory and
+invoke ``bjam`` from there. To build and run the tests, go to the test
+directory and run ``bjam``.
+
 Note that if you're building on windows using the ``msvc`` toolset, you cannot run it
 from a cygwin terminal, you'll have to run it from a ``cmd`` terminal. The same goes for
 cygwin, if you're building with gcc in cygwin you'll have to run it from a cygwin terminal.
@@ -255,7 +259,7 @@ 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 in some cases that
+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 ``/opt/local/lib`` and headers are installed to
@@ -291,6 +295,9 @@ Step 2: Building libtorrent
 Once the configure script is run successfully, you just type ``make`` and
 libtorrent, the examples and the tests will be built.
 
+When libtorrent is built it may be a good idea to run the test, you do this
+my running ``make check``.
+
 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::
 
@@ -1116,8 +1123,6 @@ The default constructor will initialize the handle to an invalid state. Which me
 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 ``invalid_handle``.
 
-**TODO: document trackers() and replace_trackers()**
-
 **TODO: document filter_piece(), filter_pieces(), is_piece_filtered(), filtered_pieces() and filter_files()**
 
 save_path()
@@ -1251,6 +1256,24 @@ set_tracker_login()
 of the tracker announce. Set this if the tracker requires authorization.
 
 
+trackers() replace_trackers()
+-----------------------------
+
+  ::
+
+		std::vector<announce_entry> const& trackers() const;
+		void replace_trackers(std::vector<announce_entry> const&);
+
+``trackers()`` will return the list of trackers for this torrent. The
+announce entry contains both a string ``url`` which specifu the announce url
+for the tracker as well as an int ``tier``, 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 ``replace_trackers()`` which takes
+a list of the same form as the one returned from ``trackers()`` and will
+replace it. If you want an immediate effect, you have to call
+`force_reannounce()`_.
+
+
 use_interface()
 ---------------
 
@@ -1419,6 +1442,7 @@ somehow invalid or if the filenames are not allowed (and hence cannot be opened/
 your filesystem. If such an error occurs, a file_error_alert_ is generated and all handles
 that refers to that torrent will become invalid.
 
+**TODO: document storage**
 
 
 torrent_status
@@ -3039,9 +3063,6 @@ Don't have metadata:
 	|           |               | doesn't have any metadata.             |
 	+-----------+---------------+----------------------------------------+
 
-The current implementation of this extension in libtorrent is experimental,
-and not optimal in any way.
-
 
 filename checks
 ===============
@@ -3065,10 +3086,12 @@ Written by Arvid Norberg. Copyright (c) 2003-2005
 
 Contributions by Magnus Jonsson, Daniel Wallin and Cory Nelson
 
+Big thanks to Michael Wojciechowski and Peter Koeleman for making the autotools
+scripts.
+
 Thanks to Reimond Retz for bugfixes, suggestions and testing
 
-Thanks to `University of Umeå`__ for providing development and
-test hardware.
+Thanks to `University of Umeå`__ for providing development and test hardware.
 
 Project is hosted by sourceforge.