premiere
/
premiere-libtorrent
2
2
Fork 1
Code Issues Pull Requests Releases Wiki Activity
premiere-libtorrent/docs/libtorrent_plugins.html

190 lines
9.6 KiB
HTML
Raw Normal View History

doc updates and started adding documentation for new plugin interface
2006-11-27 01:04:20 +01:00
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
fixed incorrectly named members of session_status, fixed compilation error in ut_pex, documentation updates
2006-11-28 19:18:37 +01:00
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
doc updates and started adding documentation for new plugin interface
2006-11-27 01:04:20 +01:00
<title></title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" href="style.css" type="text/css" />
</head>
<body>
<div class="document">
fixed incorrectly named members of session_status, fixed compilation error in ut_pex, documentation updates
2006-11-28 19:18:37 +01:00
doc updates and started adding documentation for new plugin interface
2006-11-27 01:04:20 +01:00
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>Arvid Norberg, <a class="last reference" href="mailto:arvid&#64;rasterbar.com">arvid&#64;rasterbar.com</a></td></tr>
</tbody>
</table>
fixed incorrectly named members of session_status, fixed compilation error in ut_pex, documentation updates
2006-11-28 19:18:37 +01:00
<div class="section">
<h1><a id="libtorrent-plugins" name="libtorrent-plugins">libtorrent plugins</a></h1>
doc updates and started adding documentation for new plugin interface
2006-11-27 01:04:20 +01:00
<div class="contents topic" id="table-of-contents">
fixed incorrectly named members of session_status, fixed compilation error in ut_pex, documentation updates
2006-11-28 19:18:37 +01:00
<p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
doc updates and started adding documentation for new plugin interface
2006-11-27 01:04:20 +01:00
<ul class="simple">
<li><a class="reference" href="#libtorrent-plugins" id="id1" name="id1">libtorrent plugins</a><ul>
<li><a class="reference" href="#a-word-of-caution" id="id2" name="id2">a word of caution</a></li>
</ul>
</li>
<li><a class="reference" href="#plugin-interface" id="id3" name="id3">plugin interface</a></li>
<li><a class="reference" href="#torrent-plugin" id="id4" name="id4">torrent_plugin</a><ul>
<li><a class="reference" href="#new-connection" id="id5" name="id5">new_connection()</a></li>
<li><a class="reference" href="#on-piece-pass-on-piece-fail" id="id6" name="id6">on_piece_pass() on_piece_fail()</a></li>
<li><a class="reference" href="#tick" id="id7" name="id7">tick()</a></li>
<li><a class="reference" href="#on-pause-on-resume" id="id8" name="id8">on_pause() on_resume()</a></li>
</ul>
</li>
<li><a class="reference" href="#peer-plugin" id="id9" name="id9">peer_plugin</a></li>
</ul>
</div>
<p>libtorrent has a plugin interface for implementing extensions to the protocol.
These can be general extensions for transferring metadata or peer exchange
extensions, or it could be used to provide a way to customize the protocol
to fit a particular (closed) network.</p>
<p>In short, the plugin interface makes it possible to:</p>
<ul class="simple">
<li>register extension messages (sent in the extension handshake), see
<a class="reference" href="extension_protocol.html">extensions</a>.</li>
<li>add data and parse data from the extension handshake.</li>
<li>send extension messages and standard bittorrent messages.</li>
<li>override or block the handling of standard bittorrent messages.</li>
</ul>
fixed incorrectly named members of session_status, fixed compilation error in ut_pex, documentation updates
2006-11-28 19:18:37 +01:00
<div class="section">
<h2><a id="a-word-of-caution" name="a-word-of-caution">a word of caution</a></h2>
doc updates and started adding documentation for new plugin interface
2006-11-27 01:04:20 +01:00
<p>Writing your own plugin is a very easy way to introduce serious bugs such as
dead locks and race conditions. Since a plugin has access to internal
structures it is also quite easy to sabotage libtorrent's operation.</p>
<p>All the callbacks in this interface are called with the main libtorrent thread
mutex locked. And they are always called from the libtorrent main thread. In
case portions of your plugin are called from other threads, typically the main
thread, you cannot use any of the member functions on the internal structures
in libtorrent, since those require the mutex to be locked. Futhermore, you would
also need to have a mutex on your own shared data within the plugin, to make
sure it is not accessed at the same time from the libtorrent thread (through a
callback). See <a class="reference" href="http://www.boost.org/doc/html/mutex.html">boost thread's mutex</a>. If you need to send out a message from
another thread, use an internal queue, and do the actual sending in <tt class="docutils literal"><span class="pre">tick()</span></tt>.</p>
</div>
</div>
fixed incorrectly named members of session_status, fixed compilation error in ut_pex, documentation updates
2006-11-28 19:18:37 +01:00
<div class="section">
<h1><a id="plugin-interface" name="plugin-interface">plugin interface</a></h1>
doc updates and started adding documentation for new plugin interface
2006-11-27 01:04:20 +01:00
<p>The plugin interface consists of two base classes that the plugin may
implement. These are called <tt class="docutils literal"><span class="pre">torrent_plugin</span></tt> and <tt class="docutils literal"><span class="pre">peer_plugin</span></tt>. They are
both found in the <tt class="docutils literal"><span class="pre">&lt;libtorrent/extensions.hpp&gt;</span></tt> header.</p>
<p>These plugins are instantiated for each torrent and possibly each peer,
respectively.</p>
</div>
fixed incorrectly named members of session_status, fixed compilation error in ut_pex, documentation updates
2006-11-28 19:18:37 +01:00
<div class="section">
<h1><a id="torrent-plugin" name="torrent-plugin">torrent_plugin</a></h1>
doc updates and started adding documentation for new plugin interface
2006-11-27 01:04:20 +01:00
<p>The synopsis for <tt class="docutils literal"><span class="pre">torrent_plugin</span></tt> follows:</p>
<pre class="literal-block">
struct torrent_plugin
{
virtual ~torrent_plugin();
virtual boost::shared_ptr&lt;peer_plugin&gt; new_connection(peer_connection*);
virtual void on_piece_pass(int index);
virtual void on_piece_failed(int index);
virtual void tick();
virtual bool on_pause();
virtual bool on_resume();
};
</pre>
<p>This is the base class for a torrent_plugin. Your derived class is (if added
as an extension) instantiated for each torrent in the session. The callback
hook functions are defined as follows.</p>
fixed incorrectly named members of session_status, fixed compilation error in ut_pex, documentation updates
2006-11-28 19:18:37 +01:00
<div class="section">
<h2><a id="new-connection" name="new-connection">new_connection()</a></h2>
doc updates and started adding documentation for new plugin interface
2006-11-27 01:04:20 +01:00
<pre class="literal-block">
boost::shared_ptr&lt;peer_plugin&gt; new_connection(peer_connection*);
</pre>
<p>This function is called each time a new peer is connected to the torrent. You
may choose to ignore this by just returning a default constructed
<tt class="docutils literal"><span class="pre">shared_ptr</span></tt> (in which case you don't need to override this member
function).</p>
<p>If you need an extension to the peer connection (which most plugins do) you
are supposed to return an instance of your <tt class="docutils literal"><span class="pre">peer_plugin</span></tt> class. Which in
turn will have its hook functions called on event specific to that peer.</p>
<p>The <tt class="docutils literal"><span class="pre">peer_connection</span></tt> will be valid as long as the <tt class="docutils literal"><span class="pre">shared_ptr</span></tt> is being
held by the torrent object. So, it is generally a good idea to not keep a
<tt class="docutils literal"><span class="pre">shared_ptr</span></tt> to your own peer_plugin. If you want to keep references to it,
use <tt class="docutils literal"><span class="pre">weak_ptr</span></tt>.</p>
<p>If this function throws an exception, the connection will be closed.</p>
</div>
fixed incorrectly named members of session_status, fixed compilation error in ut_pex, documentation updates
2006-11-28 19:18:37 +01:00
<div class="section">
<h2><a id="on-piece-pass-on-piece-fail" name="on-piece-pass-on-piece-fail">on_piece_pass() on_piece_fail()</a></h2>
doc updates and started adding documentation for new plugin interface
2006-11-27 01:04:20 +01:00
<pre class="literal-block">
void on_piece_pass(int index);
void on_piece_failed(int index);
</pre>
<p>These hooks are called when a piece passes the hash check or fails the hash
check, respectively. The <tt class="docutils literal"><span class="pre">index</span></tt> is the piece index that was downloaded.
It is possible to access the list of peers that participated in sending the
piece through the <tt class="docutils literal"><span class="pre">torrent</span></tt> and the <tt class="docutils literal"><span class="pre">piece_picker</span></tt>.</p>
</div>
fixed incorrectly named members of session_status, fixed compilation error in ut_pex, documentation updates
2006-11-28 19:18:37 +01:00
<div class="section">
<h2><a id="tick" name="tick">tick()</a></h2>
doc updates and started adding documentation for new plugin interface
2006-11-27 01:04:20 +01:00
<pre class="literal-block">
void tick();
</pre>
<p>This hook is called approximately once per second. It is a way of making it
easy for plugins to do timed events, for sending messages or whatever.</p>
</div>
fixed incorrectly named members of session_status, fixed compilation error in ut_pex, documentation updates
2006-11-28 19:18:37 +01:00
<div class="section">
<h2><a id="on-pause-on-resume" name="on-pause-on-resume">on_pause() on_resume()</a></h2>
doc updates and started adding documentation for new plugin interface
2006-11-27 01:04:20 +01:00
<pre class="literal-block">
bool on_pause();
bool on_resume();
</pre>
<p>These hooks are called when the torrent is paused and unpaused respectively.
The return value indicates if the event was handled. A return value of
<tt class="docutils literal"><span class="pre">true</span></tt> indicates that it was handled, and no other plugin after this one
will have this hook function called, and the standard handler will also not be
invoked. So, returning true effectively overrides the standard behavior of
pause or unpause.</p>
<p>Note that if you call <tt class="docutils literal"><span class="pre">pause()</span></tt> or <tt class="docutils literal"><span class="pre">resume()</span></tt> on the torrent from your
handler it will recurse back into your handler, so in order to invoke the
standard handler, you have to keep your own state on whether you want standard
behavior or overridden behavior.</p>
</div>
</div>
fixed incorrectly named members of session_status, fixed compilation error in ut_pex, documentation updates
2006-11-28 19:18:37 +01:00
<div class="section">
<h1><a id="peer-plugin" name="peer-plugin">peer_plugin</a></h1>
doc updates and started adding documentation for new plugin interface
2006-11-27 01:04:20 +01:00
<pre class="literal-block">
struct peer_plugin
{
virtual ~peer_plugin();
virtual void add_handshake(entry&amp;);
virtual bool on_handshake();
virtual bool on_extension_handshake(entry const&amp; h);
virtual bool on_choke();
virtual bool on_unchoke();
virtual bool on_interested();
virtual bool on_not_interested();
virtual bool on_have(int index);
virtual bool on_bitfield(std::vector&lt;bool&gt; const&amp; bitfield);
virtual bool on_request(peer_request const&amp; req);
virtual bool on_piece(peer_request const&amp; piece, char const* data);
virtual bool on_cancel(peer_request const&amp; req);
virtual bool on_extended(int length
, int msg, buffer::const_interval body);
virtual bool on_unknown_message(int length, int msg
, buffer::const_interval body);
virtual void on_piece_pass(int index);
virtual void on_piece_failed(int index);
virtual void tick();
virtual bool write_request(peer_request const&amp; r);
};
</pre>
</div>
</div>
</body>
</html>