fix typo and document custom alerts

docs/libtorrent_plugins.html

@@ -55,23 +55,24 @@
 <div class="contents topic" id="contents">
 <p class="topic-title first">Contents</p>
 <ul class="simple">
-<li><a class="reference internal" href="#libtorrent-plugins" id="id2">libtorrent plugins</a><ul>
+<li><a class="reference internal" href="#libtorrent-plugins" id="id1">libtorrent plugins</a><ul>
-<li><a class="reference internal" href="#a-word-of-caution" id="id3">a word of caution</a></li>
+<li><a class="reference internal" href="#a-word-of-caution" id="id2">a word of caution</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#plugin-interface" id="id4">plugin interface</a></li>
+<li><a class="reference internal" href="#plugin-interface" id="id3">plugin interface</a></li>
-<li><a class="reference internal" href="#plugin" id="id5">plugin</a></li>
+<li><a class="reference internal" href="#plugin" id="id4">plugin</a></li>
-<li><a class="reference internal" href="#torrent-plugin" id="id6">torrent_plugin</a><ul>
+<li><a class="reference internal" href="#torrent-plugin" id="id5">torrent_plugin</a><ul>
-<li><a class="reference internal" href="#new-connection" id="id7">new_connection()</a></li>
+<li><a class="reference internal" href="#new-connection" id="id6">new_connection()</a></li>
-<li><a class="reference internal" href="#on-piece-pass-on-piece-fail" id="id8">on_piece_pass() on_piece_fail()</a></li>
+<li><a class="reference internal" href="#on-piece-pass-on-piece-fail" id="id7">on_piece_pass() on_piece_fail()</a></li>
-<li><a class="reference internal" href="#tick" id="id9">tick()</a></li>
+<li><a class="reference internal" href="#tick" id="id8">tick()</a></li>
-<li><a class="reference internal" href="#on-pause-on-resume" id="id10">on_pause() on_resume()</a></li>
+<li><a class="reference internal" href="#on-pause-on-resume" id="id9">on_pause() on_resume()</a></li>
-<li><a class="reference internal" href="#on-files-checked" id="id11">on_files_checked()</a></li>
+<li><a class="reference internal" href="#on-files-checked" id="id10">on_files_checked()</a></li>
-<li><a class="reference internal" href="#id1" id="id12">on_files_checked()</a></li>
+<li><a class="reference internal" href="#on-add-peer" id="id11">on_add_peer()</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#peer-plugin" id="id13">peer_plugin</a></li>
+<li><a class="reference internal" href="#peer-plugin" id="id12">peer_plugin</a></li>
-<li><a class="reference internal" href="#disk-buffer-holder" id="id14">disk_buffer_holder</a></li>
+<li><a class="reference internal" href="#disk-buffer-holder" id="id13">disk_buffer_holder</a></li>
+<li><a class="reference internal" href="#custom-alerts" id="id14">custom alerts</a></li>
 </ul>
 </div>
 <p>libtorrent has a plugin interface for implementing extensions to the protocol.
@@ -250,8 +251,8 @@ checked. If there are no files to check, this function is called immediately.</p
 <p>i.e. This function is always called when the torrent is in a state where it
 can start downloading.</p>
 </div>
-<div class="section" id="id1">
+<div class="section" id="on-add-peer">
-<h2>on_files_checked()</h2>
+<h2>on_add_peer()</h2>
 <pre class="literal-block">
 enum flags_t {
         first_time = 1,
@@ -341,6 +342,42 @@ buffer and transferres ownership and responsibility to free it to the caller.</p
 <p>A disk buffer is freed by passing it to <tt class="docutils literal"><span class="pre">session_impl::free_disk_buffer()</span></tt>.</p>
 <p><tt class="docutils literal"><span class="pre">buffer()</span></tt> returns the pointer without transferring responsibility. If
 this buffer has been released, <tt class="docutils literal"><span class="pre">buffer()</span></tt> will return 0.</p>
+</div>
+<div class="section" id="custom-alerts">
+<h1>custom alerts</h1>
+<p>Since plugins are running within internal libtorrent threads, one convenient
+way to communicate with the client is to post custom alerts.</p>
+<p>The expected interface of any alert, apart from deriving from the <tt class="docutils literal"><span class="pre">alert</span></tt>
+base class, looks like this:</p>
+<pre class="literal-block">
+const static int alert_type = <em>&lt;unique alert ID&gt;</em>;
+virtual int type() const { return alert_type; }
+
+virtual std::string message() const;
+
+virtual std::auto_ptr&lt;alert&gt; clone() const
+{ return std::auto_ptr&lt;alert&gt;(new name(*this)); }
+
+const static int static_category = <em>&lt;bitmask of alert::category_t flags&gt;</em>;
+virtual int category() const { return static_category; }
+
+virtual char const* what() const { return <em>&lt;string literal of the name of this alert&gt;</em>; }
+</pre>
+<p>The <tt class="docutils literal"><span class="pre">alert_type</span></tt> is used for the type-checking in <tt class="docutils literal"><span class="pre">alert_cast</span></tt>. It must not collide with
+any other alert. The built-in alerts in libtorrent will not use alert type IDs greater than
+<tt class="docutils literal"><span class="pre">user_alert_id</span></tt>. When defining your own alert, make sure it's greater than this constant.</p>
+<p><tt class="docutils literal"><span class="pre">type()</span></tt> is the run-time equivalence of the <tt class="docutils literal"><span class="pre">alert_type</span></tt>.</p>
+<p>The <tt class="docutils literal"><span class="pre">message()</span></tt> virtual function is expected to construct a useful string representation
+of the alert and the event or data it represents. Something convenient to put in a log file
+for instance.</p>
+<p><tt class="docutils literal"><span class="pre">clone()</span></tt> is used internally to copy alerts. The suggested implementation of simply
+allocating a new instance as a copy of <tt class="docutils literal"><span class="pre">*this</span></tt> is all that's expected.</p>
+<p>The static category is required for checking wether or not the category for a specific alert
+is enabled or not, without instantiating the alert. The <tt class="docutils literal"><span class="pre">category</span></tt> virtual function is
+the run-time equivalence.</p>
+<p>The <tt class="docutils literal"><span class="pre">what()</span></tt> virtual function may simply be a string literal of the class name of
+your alert.</p>
+<p>For more information, see the alert section in the <a class="reference external" href="manual.html">main manual</a>.</p>
 </div>
     </div>
     <div id="footer">

docs/libtorrent_plugins.rst

@@ -216,8 +216,8 @@ checked. If there are no files to check, this function is called immediately.
 i.e. This function is always called when the torrent is in a state where it
 can start downloading.
 
-on_files_checked()
+on_add_peer()
-------------------
+-------------
 
 ::
 
@@ -316,3 +316,51 @@ A disk buffer is freed by passing it to ``session_impl::free_disk_buffer()``.
 ``buffer()`` returns the pointer without transferring responsibility. If
 this buffer has been released, ``buffer()`` will return 0.
 
+custom alerts
+=============
+
+Since plugins are running within internal libtorrent threads, one convenient
+way to communicate with the client is to post custom alerts.
+
+The expected interface of any alert, apart from deriving from the ``alert``
+base class, looks like this:
+
+.. parsed-literal::
+
+	const static int alert_type = *<unique alert ID>*;
+	virtual int type() const { return alert_type; }
+
+	virtual std::string message() const;
+
+	virtual std::auto_ptr<alert> clone() const
+	{ return std::auto_ptr<alert>(new name(\*this)); }
+
+	const static int static_category = *<bitmask of alert::category_t flags>*;
+	virtual int category() const { return static_category; }
+
+	virtual char const* what() const { return *<string literal of the name of this alert>*; }
+
+The ``alert_type`` is used for the type-checking in ``alert_cast``. It must not collide with
+any other alert. The built-in alerts in libtorrent will not use alert type IDs greater than
+``user_alert_id``. When defining your own alert, make sure it's greater than this constant.
+
+``type()`` is the run-time equivalence of the ``alert_type``.
+
+The ``message()`` virtual function is expected to construct a useful string representation
+of the alert and the event or data it represents. Something convenient to put in a log file
+for instance.
+
+``clone()`` is used internally to copy alerts. The suggested implementation of simply
+allocating a new instance as a copy of ``*this`` is all that's expected.
+
+The static category is required for checking wether or not the category for a specific alert
+is enabled or not, without instantiating the alert. The ``category`` virtual function is
+the run-time equivalence.
+
+The ``what()`` virtual function may simply be a string literal of the class name of
+your alert.
+
+For more information, see the alert section in the `main manual`_.
+
+.. _`main manual`: manual.html
+

docs/manual.html

@@ -8068,6 +8068,11 @@ of bytes. All access is done by writing and reading whole or partial
 slots. One slot is one piece in the torrent, but the data in the slot
 does not necessarily correspond to the piece with the same index (in
 compact allocation mode it won't).</p>
+<p>libtorrent comes with two built-in storage implementations; <tt class="docutils literal"><span class="pre">default_storage</span></tt>
+and <tt class="docutils literal"><span class="pre">disabled_storage</span></tt>. Their constructor functions are called <tt class="docutils literal"><span class="pre">default_storage_constructor</span></tt>
+and <tt class="docutils literal"><span class="pre">disabled_storage_constructor</span></tt> respectively. The disabled storage does
+just what it sounds like. It throws away data that's written, and it
+reads garbage. It's useful mostly for benchmarking and profiling purpose.</p>
 <p>The interface looks like this:</p>
 <pre class="literal-block">
 struct storage_interface

include/libtorrent/alert_types.hpp

@@ -53,6 +53,10 @@ POSSIBILITY OF SUCH DAMAGE.
 
 namespace libtorrent
 {
+
+	// user defined alerts should use IDs greater than this
+	const static int user_alert_id = 10000;
+
 	struct TORRENT_EXPORT torrent_alert: alert
 	{
 		torrent_alert(torrent_handle const& h)
@@ -1322,6 +1326,9 @@ namespace libtorrent
 
 		std::vector<torrent_status> status;
 	};
+
+#undef TORRENT_DEFINE_ALERT
+
 }