*** empty log message ***

docs/index.html

@@ -44,23 +44,24 @@
 <li><a class="reference" href="#big-number" id="id22" name="id22">big_number</a></li>
 <li><a class="reference" href="#hasher" id="id23" name="id23">hasher</a></li>
 <li><a class="reference" href="#fingerprint" id="id24" name="id24">fingerprint</a></li>
-<li><a class="reference" href="#exceptions" id="id25" name="id25">exceptions</a><ul>
-<li><a class="reference" href="#invalid-handle" id="id26" name="id26">invalid_handle</a></li>
-<li><a class="reference" href="#duplicate-torrent" id="id27" name="id27">duplicate_torrent</a></li>
-<li><a class="reference" href="#invalid-encoding" id="id28" name="id28">invalid_encoding</a></li>
-<li><a class="reference" href="#type-error" id="id29" name="id29">type_error</a></li>
-<li><a class="reference" href="#invalid-torrent-file" id="id30" name="id30">invalid_torrent_file</a></li>
+<li><a class="reference" href="#alert" id="id25" name="id25">alert</a></li>
+<li><a class="reference" href="#exceptions" id="id26" name="id26">exceptions</a><ul>
+<li><a class="reference" href="#invalid-handle" id="id27" name="id27">invalid_handle</a></li>
+<li><a class="reference" href="#duplicate-torrent" id="id28" name="id28">duplicate_torrent</a></li>
+<li><a class="reference" href="#invalid-encoding" id="id29" name="id29">invalid_encoding</a></li>
+<li><a class="reference" href="#type-error" id="id30" name="id30">type_error</a></li>
+<li><a class="reference" href="#invalid-torrent-file" id="id31" name="id31">invalid_torrent_file</a></li>
 </ul>
 </li>
-<li><a class="reference" href="#example-usage" id="id31" name="id31">example usage</a><ul>
-<li><a class="reference" href="#dump-torrent" id="id32" name="id32">dump_torrent</a></li>
-<li><a class="reference" href="#simple-client" id="id33" name="id33">simple client</a></li>
+<li><a class="reference" href="#example-usage" id="id32" name="id32">example usage</a><ul>
+<li><a class="reference" href="#dump-torrent" id="id33" name="id33">dump_torrent</a></li>
+<li><a class="reference" href="#simple-client" id="id34" name="id34">simple client</a></li>
 </ul>
 </li>
 </ul>
 </li>
-<li><a class="reference" href="#feedback" id="id34" name="id34">Feedback</a></li>
-<li><a class="reference" href="#aknowledgements" id="id35" name="id35">Aknowledgements</a></li>
+<li><a class="reference" href="#feedback" id="id35" name="id35">Feedback</a></li>
+<li><a class="reference" href="#aknowledgements" id="id36" name="id36">Aknowledgements</a></li>
 </ul>
 </div>
 <div class="section" id="introduction">
@@ -98,8 +99,7 @@ download to peers as free upload. To maintain a global 1:1 ratio.</li>
 <p>Functions that are yet to be implemented:</p>
 <blockquote>
 <ul class="simple">
-<li>more generous optimistic unchoke</li>
-<li>better choke/unchoke algorithm</li>
+<li>choke/unchoke policy for seed-mode</li>
 <li>fast resume</li>
 <li>number of connections limit</li>
 <li>better handling of peers that send bad data</li>
@@ -174,6 +174,10 @@ class session: public boost::noncopyable
 
         void set_http_settings(const http_settings&amp; settings);
         void set_upload_rate_limit(int bytes_per_second);
+
+        std::auto_ptr&lt;alert&gt; pop_alert();
+        void set_severity_level(alert::severity_t s);
+
 };
 </pre>
 <p>Once it's created, it will spawn the main thread that will do all the work.
@@ -208,6 +212,89 @@ about the torrent's progress, its peers etc. It is also used to abort a torrent.
 increase the port number by one and try again. If it still fails it will continue
 increasing the port number until it succeeds or has failed 9 ports. <em>This will
 change in the future to give more control of the listen-port.</em></p>
+<p>The <tt class="literal"><span class="pre">pop_alert()</span></tt> function is the interface for retrieving alerts, warnings and
+errors from libtorrent. If there hasn't occured any errors (matching your severity
+level) <tt class="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 query the
+<a class="reference" href="#alert">alert</a> object for information about the error or message. To retrieve any alerts, you
+have to select a severity level using <tt class="literal"><span class="pre">set_severity_level()</span></tt>. It defaults to
+<tt class="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 class="table">
+<colgroup>
+<col width="19%" />
+<col width="81%" />
+</colgroup>
+<tbody valign="top">
+<tr><td><tt class="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="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="literal"><span class="pre">critical</span></tt></td>
+<td>Signals errors that requires user interaction.</td>
+</tr>
+<tr><td><tt class="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="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="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="literal"><span class="pre">alert::none</span></tt> (the default) you will not recieve
+any events at all.</p>
+<p>When you get an alert, you can use <tt class="literal"><span class="pre">typeid()</span></tt> or <tt class="literal"><span class="pre">dynamic_cast&lt;&gt;</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
+dispatcher mechanism that's available in libtorrent.</p>
+<p>TODO: describe the type dispatching mechanism</p>
+<p>The currently available alert types are:</p>
+<blockquote>
+<ul class="simple">
+<li>tracker_alert</li>
+<li>hash_failed_alert</li>
+</ul>
+</blockquote>
+<p>You can try a <tt class="literal"><span class="pre">dynamic_cast</span></tt> to these types to get more message-pecific information. Here
+are their definitions:</p>
+<pre class="literal-block">
+struct tracker_alert: alert
+{
+        tracker_alert(const torrent_handle&amp; h, const std::string&amp; msg);
+        virtual std::auto_ptr&lt;alert&gt; clone() const;
+
+        torrent_handle handle;
+};
+
+struct hash_failed_alert: alert
+{
+        hash_failed_alert(
+                const torrent_handle&amp; h
+                , int index
+                , const std::string&amp; msg);
+
+        virtual std::auto_ptr&lt;alert&gt; clone() const;
+
+        torrent_handle handle;
+        int piece_index;
+};
+</pre>
 </div>
 <div class="section" id="parsing-torrent-files">
 <h2><a class="toc-backref" href="#id11" name="parsing-torrent-files">parsing torrent files</a></h2>
@@ -451,6 +538,7 @@ struct torrent_status
                 invalid_handle,
                 queued_for_checking,
                 checking_files,
+                connecting_to_tracker,
                 downloading,
                 seeding
         };
@@ -458,10 +546,16 @@ struct torrent_status
         state_t state;
         float progress;
         boost::posix_time::time_duration next_announce;
+
         std::size_t total_download;
         std::size_t total_upload;
+
+        std::size_t total_payload_download;
+        std::size_t total_payload_upload;
+
         float download_rate;
         float upload_rate;
+
         std::vector&lt;bool&gt; pieces;
         std::size_t total_done;
 };
@@ -471,8 +565,8 @@ torrent's current task. It may be checking files or downloading. The torrent's
 current task is in the <tt class="literal"><span class="pre">state</span></tt> member, it will be one of the following:</p>
 <table border class="table">
 <colgroup>
-<col width="28%" />
-<col width="72%" />
+<col width="31%" />
+<col width="69%" />
 </colgroup>
 <tbody valign="top">
 <tr><td><tt class="literal"><span class="pre">queued_for_checking</span></tt></td>
@@ -484,6 +578,10 @@ This torrent will wait for its turn.</td>
 <td>The torrent has not started its download yet, and is
 currently checking existing files.</td>
 </tr>
+<tr><td><tt class="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="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
@@ -499,6 +597,9 @@ is a pure seeder.</td>
 <p><tt class="literal"><span class="pre">next_announce</span></tt> is the time until the torrent will announce itself to the tracker.</p>
 <p><tt class="literal"><span class="pre">total_download</span></tt> and <tt class="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="literal"><span class="pre">total_payload_download</span></tt> and <tt class="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="literal"><span class="pre">pieces</span></tt> is the bitmask that representw which pieces we have (set to true) and
 the pieces we don't have.</p>
 <p><tt class="literal"><span class="pre">download_rate</span></tt> and <tt class="literal"><span class="pre">upload_rate</span></tt> are the total rates for all peers for this
@@ -792,12 +893,35 @@ sure not to clash with anybody else. Here are some taken id's:</p>
 version of your client. All these numbers must be within the range [0, 9].</p>
 <p><tt class="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="alert">
+<h2><a class="toc-backref" href="#id25" name="alert">alert</a></h2>
+<p>The <tt class="literal"><span class="pre">alert</span></tt> class is used to pass messages of events from the libtorrent code
+to the user. It is a 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&amp; msg);
+
+        virtual ~alert() {}
+
+        const std::string&amp; msg() const;
+        severity_t severity() const;
+
+        virtual std::auto_ptr&lt;alert&gt; clone() const = 0;
+};
+</pre>
+</div>
 <div class="section" id="exceptions">
-<h2><a class="toc-backref" href="#id25" name="exceptions">exceptions</a></h2>
+<h2><a class="toc-backref" href="#id26" name="exceptions">exceptions</a></h2>
 <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">
-<h3><a class="toc-backref" href="#id26" name="invalid-handle">invalid_handle</a></h3>
+<h3><a class="toc-backref" href="#id27" name="invalid-handle">invalid_handle</a></h3>
 <p>This exception is thrown when querying information from a <tt class="literal"><span class="pre">torrent_handle</span></tt> that hasn't
 been initialized or that has become invalid.</p>
 <pre class="literal-block">
@@ -808,7 +932,7 @@ struct invalid_handle: std::exception
 </pre>
 </div>
 <div class="section" id="duplicate-torrent">
-<h3><a class="toc-backref" href="#id27" name="duplicate-torrent">duplicate_torrent</a></h3>
+<h3><a class="toc-backref" href="#id28" name="duplicate-torrent">duplicate_torrent</a></h3>
 <p>This is thrown by <tt class="literal"><span class="pre">session::add_torrent()</span></tt> if the torrent already has been added to
 the session.</p>
 <pre class="literal-block">
@@ -819,7 +943,7 @@ struct duplicate_torrent: std::exception
 </pre>
 </div>
 <div class="section" id="invalid-encoding">
-<h3><a class="toc-backref" href="#id28" name="invalid-encoding">invalid_encoding</a></h3>
+<h3><a class="toc-backref" href="#id29" name="invalid-encoding">invalid_encoding</a></h3>
 <p>This is thrown by <tt class="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
@@ -829,7 +953,7 @@ struct invalid_encoding: std::exception
 </pre>
 </div>
 <div class="section" id="type-error">
-<h3><a class="toc-backref" href="#id29" name="type-error">type_error</a></h3>
+<h3><a class="toc-backref" href="#id30" name="type-error">type_error</a></h3>
 <p>This is thrown from the accessors of <tt class="literal"><span class="pre">entry</span></tt> if the data type of the <tt class="literal"><span class="pre">entry</span></tt> doesn't
 match the type you want to extract from it.</p>
 <pre class="literal-block">
@@ -840,7 +964,7 @@ struct type_error: std::runtime_error
 </pre>
 </div>
 <div class="section" id="invalid-torrent-file">
-<h3><a class="toc-backref" href="#id30" name="invalid-torrent-file">invalid_torrent_file</a></h3>
+<h3><a class="toc-backref" href="#id31" name="invalid-torrent-file">invalid_torrent_file</a></h3>
 <p>This exception is thrown from the constructor of <tt class="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">
@@ -852,9 +976,9 @@ struct invalid_torrent_file: std::exception
 </div>
 </div>
 <div class="section" id="example-usage">
-<h2><a class="toc-backref" href="#id31" name="example-usage">example usage</a></h2>
+<h2><a class="toc-backref" href="#id32" name="example-usage">example usage</a></h2>
 <div class="section" id="dump-torrent">
-<h3><a class="toc-backref" href="#id32" name="dump-torrent">dump_torrent</a></h3>
+<h3><a class="toc-backref" href="#id33" name="dump-torrent">dump_torrent</a></h3>
 <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">
@@ -918,7 +1042,7 @@ int main(int argc, char* argv[])
 </pre>
 </div>
 <div class="section" id="simple-client">
-<h3><a class="toc-backref" href="#id33" name="simple-client">simple client</a></h3>
+<h3><a class="toc-backref" href="#id34" name="simple-client">simple client</a></h3>
 <p>This is a simple client. It doesn't have much output to keep it simple:</p>
 <pre class="literal-block">
 #include &lt;iostream&gt;
@@ -971,12 +1095,12 @@ int main(int argc, char* argv[])
 </div>
 </div>
 <div class="section" id="feedback">
-<h1><a class="toc-backref" href="#id34" name="feedback">Feedback</a></h1>
+<h1><a class="toc-backref" href="#id35" name="feedback">Feedback</a></h1>
 <p>There's a <a class="reference" href="http://lists.sourceforge.net/lists/listinfo/libtorrent-discuss">mailing list</a>.</p>
 <p>You can usually find me as hydri in <tt class="literal"><span class="pre">#btports</span> <span class="pre">&#64;</span> <span class="pre">irc.freenode.net</span></tt>.</p>
 </div>
 <div class="section" id="aknowledgements">
-<h1><a class="toc-backref" href="#id35" name="aknowledgements">Aknowledgements</a></h1>
+<h1><a class="toc-backref" href="#id36" name="aknowledgements">Aknowledgements</a></h1>
 <p>Written by Arvid Norberg and Daniel Wallin. Copyright (c) 2003</p>
 <p>Contributions by Magnus Jonsson</p>
 <p>Thanks to Reimond Retz for bugfixes, suggestions and testing</p>