regenerate documentation

docs/gen_reference_doc.py

@@ -486,6 +486,8 @@ def consume_ifdef(lno, lines, warn_on_ifdefs = False):
 
 	if l == '#ifndef TORRENT_NO_DEPRECATE' or \
 		l == '#ifdef TORRENT_DEBUG' or \
+		(l.startswith('#if ') and ' TORRENT_USE_ASSERTS' in l) or \
+		(l.startswith('#if ') and ' TORRENT_USE_INVARIANT_CHECKS' in l) or \
 		l == '#ifdef TORRENT_ASIO_DEBUGGING' or \
 		(l.startswith('#if') and 'defined TORRENT_DEBUG' in l) or \
 		(l.startswith('#if') and 'defined TORRENT_ASIO_DEBUGGING' in l):

docs/reference-Core.html

@@ -1104,7 +1104,7 @@ struct torrent_handle
       , std::string const& dh_params
       , std::string const& passphrase = "");
    storage_interface* <strong>get_storage_impl</strong> () const;
-   boost::intrusive_ptr&lt;torrent_info&gt; <strong>torrent_file</strong> () const;
+   boost::intrusive_ptr&lt;torrent_info const&gt; <strong>torrent_file</strong> () const;
    void <strong>use_interface</strong> (const char* net_interface) const;
    void <strong>piece_availability</strong> (std::vector&lt;int&gt;&amp; avail) const;
    int <strong>piece_priority</strong> (int index) const;
@@ -1115,9 +1115,8 @@ struct torrent_handle
    void <strong>prioritize_files</strong> (std::vector&lt;int&gt; const&amp; files) const;
    void <strong>file_priority</strong> (int index, int priority) const;
    std::vector&lt;int&gt; <strong>file_priorities</strong> () const;
-   void <strong>force_reannounce</strong> () const;
+   void <strong>force_reannounce</strong> (int seconds = 0, int tracker_index = -1) const;
    void <strong>force_dht_announce</strong> () const;
-   void <strong>force_reannounce</strong> (boost::posix_time::time_duration) const;
    void <strong>scrape_tracker</strong> () const;
    int <strong>upload_limit</strong> () const;
    int <strong>download_limit</strong> () const;
@@ -1700,14 +1699,15 @@ storage contructor function that was passed to add_torrent.</p>
 <div class="section" id="torrent-file">
 <h2>torrent_file()</h2>
 <pre class="literal-block">
-boost::intrusive_ptr&lt;torrent_info&gt; <strong>torrent_file</strong> () const;
+boost::intrusive_ptr&lt;torrent_info const&gt; <strong>torrent_file</strong> () const;
 </pre>
-<p>Returns a pointer to the <a class="reference external" href="reference-Core.html#torrent_info">torrent_info</a> object associated with this torrent. The
+<p>Returns a pointer to the <a class="reference external" href="reference-Core.html#torrent_info">torrent_info</a> object associated with this
-<a class="reference external" href="reference-Core.html#torrent_info">torrent_info</a> object is a copy of the internal object. If the torrent doesn't
+torrent. The <a class="reference external" href="reference-Core.html#torrent_info">torrent_info</a> object may be a copy of the internal object.
-have metadata, the object being returned will not be fully filled in.
+If the torrent doesn't have metadata, the pointer will not be
-The torrent may be in a state without metadata only if
+initialized (i.e. a NULL pointer). The torrent may be in a state
-it was started without a .torrent file, e.g. by using the libtorrent extension of
+without metadata only if it was started without a .torrent file, e.g.
-just supplying a tracker and info-hash.</p>
+by using the libtorrent extension of just supplying a tracker and
+info-hash.</p>
 <a name="use_interface()"></a></div>
 <div class="section" id="use-interface">
 <h2>use_interface()</h2>
@@ -1803,26 +1803,20 @@ have metadata or a torrent that is a seed. <tt class="docutils literal">file_pri
 <div class="section" id="force-reannounce-force-dht-announce">
 <h2>force_reannounce() force_dht_announce()</h2>
 <pre class="literal-block">
-void <strong>force_reannounce</strong> () const;
+void <strong>force_reannounce</strong> (int seconds = 0, int tracker_index = -1) const;
 void <strong>force_dht_announce</strong> () const;
 </pre>
-<p><tt class="docutils literal">force_reannounce()</tt> will force this torrent to do another tracker request, to receive new
+<p><tt class="docutils literal">force_reannounce()</tt> will force this torrent to do another tracker
-peers. The second overload of <tt class="docutils literal">force_reannounce</tt> that takes a <tt class="docutils literal">time_duration</tt> as
+request, to receive new peers. The <tt class="docutils literal">seconds</tt> argument specifies how
-argument will schedule a reannounce in that amount of time from now.</p>
+many seconds from now to issue the tracker announces.</p>
-<p>If the tracker's <tt class="docutils literal">min_interval</tt> has not passed since the last announce, the forced
+<p>If the tracker's <tt class="docutils literal">min_interval</tt> has not passed since the last
-announce will be scheduled to happen immediately as the <tt class="docutils literal">min_interval</tt> expires. This is
+announce, the forced announce will be scheduled to happen immediately
-to honor trackers minimum re-announce interval settings.</p>
+as the <tt class="docutils literal">min_interval</tt> expires. This is to honor trackers minimum
-<p><tt class="docutils literal">force_dht_announce</tt> will announce the torrent to the DHT immediately.</p>
+re-announce interval settings.</p>
-<a name="force_reannounce()"></a></div>
+<p>The <tt class="docutils literal">tracker_index</tt> argument specifies which tracker to re-announce.
-<div class="section" id="force-reannounce">
+If set to -1 (which is the default), all trackers are re-announce.</p>
-<h2>force_reannounce()</h2>
+<p><tt class="docutils literal">force_dht_announce</tt> will announce the torrent to the DHT
-<pre class="literal-block">
+immediately.</p>
-void <strong>force_reannounce</strong> (boost::posix_time::time_duration) const;
-</pre>
-<p>forces a reannounce in the specified amount of time.
-This overrides the default announce interval, and no
-announce will take place until the given time has
-timed out.</p>
 <a name="scrape_tracker()"></a></div>
 <div class="section" id="scrape-tracker">
 <h2>scrape_tracker()</h2>
@@ -2259,7 +2253,7 @@ struct torrent_status
    int last_scrape;
    int sparse_regions;
    int priority;
-   boost::uint8_t state;
+   state_t state;
    bool need_save_resume;
    bool ip_filter_applies;
    bool upload_mode;
@@ -2273,6 +2267,7 @@ struct torrent_status
    bool has_metadata;
    bool has_incoming;
    bool seed_mode;
+   bool moving_storage;
    sha1_hash info_hash;
 };
 </pre>
@@ -2744,6 +2739,12 @@ to this torrent.</dd>
 started in seed mode, it will leave seed mode once all pieces have been
 checked or as soon as one piece fails the hash check.</dd>
 </dl>
+<a name="moving_storage"></a><dl class="docutils">
+<dt>moving_storage</dt>
+<dd>this is true if this torrent's storage is currently being moved from
+one location to another. This may potentially be a long operation
+if a large file ends up being copied from one drive to another.</dd>
+</dl>
 <a name="info_hash"></a><dl class="docutils">
 <dt>info_hash</dt>
 <dd>the info-hash for this torrent</dd>

docs/reference-Error_Codes.html

@@ -630,6 +630,11 @@ over SSL.</td>
 <td>The peer tried to connect to a torrent with a certificate
 for a different torrent.</td>
 </tr>
+<tr><td>not_an_ssl_torrent</td>
+<td>113</td>
+<td>the torrent is not an SSL torrent, and the operation requires
+an SSL torrent</td>
+</tr>
 <tr><td>unsupported_protocol_version</td>
 <td>120</td>
 <td>The NAT-PMP router responded with an unsupported protocol version</td>

docs/reference-Plugins.html

@@ -354,7 +354,7 @@ struct peer_plugin
 {
    virtual char const* <strong>type</strong> () const;
    virtual void <strong>add_handshake</strong> (entry&amp;);
-   virtual void <strong>on_disconnect</strong> (error_code const&amp; ec);
+   virtual void <strong>on_disconnect</strong> (error_code const&amp; /<em>ec</em>/);
    virtual void <strong>on_connected</strong> ();
    virtual bool <strong>on_handshake</strong> (char const* /<em>reserved_bits</em>/);
    virtual bool <strong>on_extension_handshake</strong> (lazy_entry const&amp;);
@@ -374,7 +374,7 @@ struct peer_plugin
    virtual bool <strong>on_suggest</strong> (int /<em>index</em>/);
    virtual bool <strong>on_cancel</strong> (peer_request const&amp;);
    virtual bool <strong>on_dont_have</strong> (int /<em>index</em>/);
-   virtual bool <strong>can_disconnect</strong> (error_code const&amp; ec);
+   virtual bool <strong>can_disconnect</strong> (error_code const&amp; /<em>ec</em>/);
    virtual bool <strong>on_extended</strong> (int /<em>length</em>/, int /<em>msg</em>/,
       buffer::const_interval /<em>body</em>/);
    virtual bool <strong>on_unknown_message</strong> (int /<em>length</em>/, int /<em>msg</em>/,
@@ -404,7 +404,7 @@ this is not called for web seeds</p>
 <div class="section" id="on-disconnect">
 <h3>on_disconnect()</h3>
 <pre class="literal-block">
-virtual void <strong>on_disconnect</strong> (error_code const&amp; ec);
+virtual void <strong>on_disconnect</strong> (error_code const&amp; /<em>ec</em>/);
 </pre>
 <p>called when the peer is being disconnected.</p>
 <a name="on_connected()"></a></div>
@@ -482,7 +482,7 @@ handler.</p>
 <div class="section" id="can-disconnect">
 <h3>can_disconnect()</h3>
 <pre class="literal-block">
-virtual bool <strong>can_disconnect</strong> (error_code const&amp; ec);
+virtual bool <strong>can_disconnect</strong> (error_code const&amp; /<em>ec</em>/);
 </pre>
 <p>called when libtorrent think this peer should be disconnected.
 if the <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> returns false, the peer will not be disconnected.</p>

docs/reference-Session.html

@@ -55,14 +55,14 @@
 <div class="contents topic" id="table-of-contents">
 <p class="topic-title first">Table of contents</p>
 <ul class="simple">
-<li><a class="reference internal" href="#add-torrent-params" id="id159">add_torrent_params</a></li>
+<li><a class="reference internal" href="#add-torrent-params" id="id161">add_torrent_params</a></li>
-<li><a class="reference internal" href="#cache-status" id="id160">cache_status</a></li>
+<li><a class="reference internal" href="#cache-status" id="id162">cache_status</a></li>
-<li><a class="reference internal" href="#session-proxy" id="id161">session_proxy</a></li>
+<li><a class="reference internal" href="#session-proxy" id="id163">session_proxy</a></li>
-<li><a class="reference internal" href="#id36" id="id162">session</a></li>
+<li><a class="reference internal" href="#id36" id="id164">session</a></li>
-<li><a class="reference internal" href="#dht-lookup" id="id163">dht_lookup</a></li>
+<li><a class="reference internal" href="#dht-lookup" id="id165">dht_lookup</a></li>
-<li><a class="reference internal" href="#dht-routing-bucket" id="id164">dht_routing_bucket</a></li>
+<li><a class="reference internal" href="#dht-routing-bucket" id="id166">dht_routing_bucket</a></li>
-<li><a class="reference internal" href="#utp-status" id="id165">utp_status</a></li>
+<li><a class="reference internal" href="#utp-status" id="id167">utp_status</a></li>
-<li><a class="reference internal" href="#session-status" id="id166">session_status</a></li>
+<li><a class="reference internal" href="#session-status" id="id168">session_status</a></li>
 </ul>
 </div>
 <a name="add_torrent_params"></a><div class="section" id="add-torrent-params">
@@ -630,6 +630,8 @@ class session: public boost::noncopyable
    void <strong>start_lsd</strong> ();
    void <strong>stop_upnp</strong> ();
    void <strong>start_upnp</strong> ();
+   void <strong>delete_port_mapping</strong> (int handle);
+   int <strong>add_port_mapping</strong> (protocol_type t, int external_port, int local_port);
    void <strong>stop_natpmp</strong> ();
    void <strong>start_natpmp</strong> ();
 
@@ -660,6 +662,12 @@ class session: public boost::noncopyable
       add_default_plugins,
       start_default_features,
    };
+
+   enum protocol_type
+   {
+      udp,
+      tcp,
+   };
 };
 </pre>
 <a name="session()"></a><div class="section" id="id40">
@@ -1267,6 +1275,18 @@ arbitrary port mappings. Mapping status is returned through the
 <a class="reference external" href="reference-Alerts.html#portmap_alert">portmap_alert</a> and the <a class="reference external" href="reference-Alerts.html#portmap_error_alert">portmap_error_alert</a>. The object will be valid until
 <tt class="docutils literal">stop_upnp()</tt> is called. See <a class="reference external" href="manual-ref.html#upnp-and-nat-pmp">upnp and nat pmp</a>.</p>
 <p>It is off by default.</p>
+<a name="add_port_mapping()"></a>
+<a name="delete_port_mapping()"></a></div>
+<div class="section" id="add-port-mapping-delete-port-mapping">
+<h2>add_port_mapping() delete_port_mapping()</h2>
+<pre class="literal-block">
+void <strong>delete_port_mapping</strong> (int handle);
+int <strong>add_port_mapping</strong> (protocol_type t, int external_port, int local_port);
+</pre>
+<p>add_port_mapping adds a port forwarding on UPnP and/or NAT-PMP,
+whichever is enabled. The return value is a handle referring to
+the port mapping that was just created. Pass it to <a class="reference external" href="reference-Session.html#delete_port_mapping()">delete_port_mapping()</a>
+to remove it.</p>
 <a name="start_natpmp()"></a>
 <a name="stop_natpmp()"></a></div>
 <div class="section" id="start-natpmp-stop-natpmp">
@@ -1406,6 +1426,33 @@ arbitrary port mappings. Mapping status is returned through the
 </tr>
 </tbody>
 </table>
+<a name="protocol_type"></a></div>
+<div class="section" id="enum-protocol-type">
+<h2>enum protocol_type</h2>
+<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/session.hpp">libtorrent/session.hpp</a>&quot;</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="23%" />
+<col width="27%" />
+<col width="50%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head">name</th>
+<th class="head">value</th>
+<th class="head">description</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td>udp</td>
+<td>1</td>
+<td>&nbsp;</td>
+</tr>
+<tr><td>tcp</td>
+<td>2</td>
+<td>&nbsp;</td>
+</tr>
+</tbody>
+</table>
 <a name="dht_lookup"></a></div>
 </div>
 <div class="section" id="dht-lookup">