forked from premiere/premiere-libtorrent
190 lines
9.6 KiB
HTML
190 lines
9.6 KiB
HTML
<?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" />
|
|
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
|
|
<title></title>
|
|
<meta name="author" content="Arvid Norberg, arvid@rasterbar.com" />
|
|
<link rel="stylesheet" href="style.css" type="text/css" />
|
|
</head>
|
|
<body>
|
|
<div class="document">
|
|
|
|
<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@rasterbar.com">arvid@rasterbar.com</a></td></tr>
|
|
</tbody>
|
|
</table>
|
|
<div class="section">
|
|
<h1><a id="libtorrent-plugins" name="libtorrent-plugins">libtorrent plugins</a></h1>
|
|
<div class="contents topic" id="table-of-contents">
|
|
<p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
|
|
<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>
|
|
<div class="section">
|
|
<h2><a id="a-word-of-caution" name="a-word-of-caution">a word of caution</a></h2>
|
|
<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>
|
|
<div class="section">
|
|
<h1><a id="plugin-interface" name="plugin-interface">plugin interface</a></h1>
|
|
<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"><libtorrent/extensions.hpp></span></tt> header.</p>
|
|
<p>These plugins are instantiated for each torrent and possibly each peer,
|
|
respectively.</p>
|
|
</div>
|
|
<div class="section">
|
|
<h1><a id="torrent-plugin" name="torrent-plugin">torrent_plugin</a></h1>
|
|
<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<peer_plugin> 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>
|
|
<div class="section">
|
|
<h2><a id="new-connection" name="new-connection">new_connection()</a></h2>
|
|
<pre class="literal-block">
|
|
boost::shared_ptr<peer_plugin> 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>
|
|
<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>
|
|
<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>
|
|
<div class="section">
|
|
<h2><a id="tick" name="tick">tick()</a></h2>
|
|
<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>
|
|
<div class="section">
|
|
<h2><a id="on-pause-on-resume" name="on-pause-on-resume">on_pause() on_resume()</a></h2>
|
|
<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>
|
|
<div class="section">
|
|
<h1><a id="peer-plugin" name="peer-plugin">peer_plugin</a></h1>
|
|
<pre class="literal-block">
|
|
struct peer_plugin
|
|
{
|
|
virtual ~peer_plugin();
|
|
|
|
virtual void add_handshake(entry&);
|
|
virtual bool on_handshake();
|
|
virtual bool on_extension_handshake(entry const& 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<bool> const& bitfield);
|
|
virtual bool on_request(peer_request const& req);
|
|
virtual bool on_piece(peer_request const& piece, char const* data);
|
|
virtual bool on_cancel(peer_request const& 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& r);
|
|
};
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html>
|