fix typo and document custom alerts

This commit is contained in:
Arvid Norberg 2012-02-12 10:11:14 +00:00
parent 10a7b1f8a5
commit 3a9d7fc66d
4 changed files with 114 additions and 17 deletions

View File

@ -55,23 +55,24 @@
<div class="contents topic" id="contents"> <div class="contents topic" id="contents">
<p class="topic-title first">Contents</p> <p class="topic-title first">Contents</p>
<ul class="simple"> <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> </ul>
</li> </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> </ul>
</li> </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> </ul>
</div> </div>
<p>libtorrent has a plugin interface for implementing extensions to the protocol. <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 <p>i.e. This function is always called when the torrent is in a state where it
can start downloading.</p> can start downloading.</p>
</div> </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"> <pre class="literal-block">
enum flags_t { enum flags_t {
first_time = 1, 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>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 <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> 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> </div>
<div id="footer"> <div id="footer">

View File

@ -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 i.e. This function is always called when the torrent is in a state where it
can start downloading. 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 ``buffer()`` returns the pointer without transferring responsibility. If
this buffer has been released, ``buffer()`` will return 0. 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

View File

@ -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 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 does not necessarily correspond to the piece with the same index (in
compact allocation mode it won't).</p> 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> <p>The interface looks like this:</p>
<pre class="literal-block"> <pre class="literal-block">
struct storage_interface struct storage_interface

View File

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