<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>
<li>save and restore state via the <aclass="reference external"href="reference-Session.html#session">session</a> state</li>
<li>see all alerts that are posted</li>
</ul>
<divclass="section"id="a-word-of-caution">
<h2>a word of caution</h2>
<p>Writing your own <aclass="reference external"href="reference-Plugins.html#plugin">plugin</a> is a very easy way to introduce serious bugs such as
dead locks and race conditions. Since a <aclass="reference external"href="reference-Plugins.html#plugin">plugin</a> 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 network thread. In
case portions of your <aclass="reference external"href="reference-Plugins.html#plugin">plugin</a> 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 <aclass="reference external"href="reference-Plugins.html#plugin">plugin</a>, to make
sure it is not accessed at the same time from the libtorrent thread (through a
callback). See <aclass="reference external"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, it is advised to use an internal queue, and do the actual
sending in <ttclass="docutils literal">tick()</tt>.</p>
<p>Since the <aclass="reference external"href="reference-Plugins.html#plugin">plugin</a> interface gives you easy access to internal structures, it
is not supported as a stable API. Plugins should be considered spcific to a
specific version of libtorrent. Although, in practice the internals mostly
don't change that dramatically.</p>
</div>
</div>
<divclass="section"id="plugin-interface">
<h1>plugin-interface</h1>
<p>The <aclass="reference external"href="reference-Plugins.html#plugin">plugin</a> interface consists of three base classes that the <aclass="reference external"href="reference-Plugins.html#plugin">plugin</a> may
implement. These are called <aclass="reference external"href="reference-Plugins.html#plugin">plugin</a>, <aclass="reference external"href="reference-Plugins.html#torrent_plugin">torrent_plugin</a> and <aclass="reference external"href="reference-Plugins.html#peer_plugin">peer_plugin</a>.
They are found in the <ttclass="docutils literal"><libtorrent/extensions.hpp></tt> header.</p>
<p>These plugins are instantiated for each <aclass="reference external"href="reference-Session.html#session">session</a>, torrent and possibly each peer,
respectively.</p>
<p>For plugins that only need per torrent state, it is enough to only implement
<ttclass="docutils literal">torrent_plugin</tt> and pass a constructor function or function object to
<ttclass="docutils literal"><spanclass="pre">session::add_extension()</span></tt> or <ttclass="docutils literal"><spanclass="pre">torrent_handle::add_extension()</span></tt> (if the
torrent has already been started and you want to hook in the extension at
<p>The function should return a <ttclass="docutils literal"><spanclass="pre">boost::shared_ptr<torrent_plugin></span></tt> which
may or may not be 0. If it is a null pointer, the extension is simply ignored
for this torrent. If it is a valid pointer (to a class inheriting
<ttclass="docutils literal">torrent_plugin</tt>), it will be associated with this torrent and callbacks
will be made on torrent events.</p>
<p>For more elaborate plugins which require <aclass="reference external"href="reference-Session.html#session">session</a> wide state, you would
implement <ttclass="docutils literal">plugin</tt>, construct an object (in a <ttclass="docutils literal"><spanclass="pre">boost::shared_ptr</span></tt>) and pass
it in to <ttclass="docutils literal"><spanclass="pre">session::add_extension()</span></tt>.</p>
</div>
<divclass="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 <aclass="reference external"href="reference-Alerts.html#alert">alert</a>, apart from deriving from the <aclass="reference external"href="reference-Alerts.html#alert">alert</a>
base class, looks like this:</p>
<preclass="literal-block">
const static int alert_type = <em><unique alert ID></em>;
const static int static_category = <em><bitmask of alert::category_t flags></em>;
virtual int category() const { return static_category; }
virtual char const* what() const { return <em><string literal of the name of this alert></em>; }
</pre>
<p>The <ttclass="docutils literal">alert_type</tt> is used for the type-checking in <ttclass="docutils literal">alert_cast</tt>. It must
not collide with any other <aclass="reference external"href="reference-Alerts.html#alert">alert</a>. The built-in alerts in libtorrent will
not use <aclass="reference external"href="reference-Alerts.html#alert">alert</a> type IDs greater than <ttclass="docutils literal">user_alert_id</tt>. When defining your
own <aclass="reference external"href="reference-Alerts.html#alert">alert</a>, make sure it's greater than this constant.</p>
<p><ttclass="docutils literal">type()</tt> is the run-time equivalence of the <ttclass="docutils literal">alert_type</tt>.</p>
<p>The <ttclass="docutils literal">message()</tt> virtual function is expected to construct a useful
string representation of the <aclass="reference external"href="reference-Alerts.html#alert">alert</a> and the event or data it represents.
Something convenient to put in a log file for instance.</p>
<p><ttclass="docutils literal">clone()</tt> is used internally to copy alerts. The suggested implementation
of simply allocating a new instance as a copy of <ttclass="docutils literal">*this</tt> is all that's
expected.</p>
<p>The static category is required for checking wether or not the category
for a specific <aclass="reference external"href="reference-Alerts.html#alert">alert</a> is enabled or not, without instantiating the <aclass="reference external"href="reference-Alerts.html#alert">alert</a>.
The <ttclass="docutils literal">category</tt> virtual function is the run-time equivalence.</p>
<p>The <ttclass="docutils literal">what()</tt> virtual function may simply be a string literal of the class
name of your <aclass="reference external"href="reference-Alerts.html#alert">alert</a>.</p>
<p>For more information, see the <aclass="reference external"href="reference-Alerts.html">alert section</a>.</p>
<p>Declared in "<aclass="reference external"href="../include/libtorrent/extensions.hpp">libtorrent/extensions.hpp</a>"</p>
<p>this is the base class for a <aclass="reference external"href="reference-Session.html#session">session</a><aclass="reference external"href="reference-Plugins.html#plugin">plugin</a>. One primary feature
is that it is notified of all torrents that are added to the <aclass="reference external"href="reference-Session.html#session">session</a>,
<p>this is called by the <aclass="reference external"href="reference-Session.html#session">session</a> every time a new torrent is added.
The <ttclass="docutils literal">torrent*</tt> points to the internal torrent object created
for the new torrent. The <ttclass="docutils literal">void*</tt> is the userdata pointer as
passed in via <aclass="reference external"href="reference-Session.html#add_torrent_params">add_torrent_params</a>.</p>
<p>If the <aclass="reference external"href="reference-Plugins.html#plugin">plugin</a> returns a <aclass="reference external"href="reference-Plugins.html#torrent_plugin">torrent_plugin</a> instance, it will be added
to the new torrent. Otherwise, return an empty shared_ptr to a
<aclass="reference external"href="reference-Plugins.html#torrent_plugin">torrent_plugin</a> (the default).</p>
<p>called when <aclass="reference external"href="reference-Plugins.html#plugin">plugin</a> is added to a <aclass="reference external"href="reference-Session.html#session">session</a></p>
<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
<ttclass="docutils literal">shared_ptr</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 <aclass="reference external"href="reference-Plugins.html#peer_plugin">peer_plugin</a> class. Which in
turn will have its hook functions called on event specific to that peer.</p>
<p>The <ttclass="docutils literal">peer_connection</tt> will be valid as long as the <ttclass="docutils literal">shared_ptr</tt> is being
held by the torrent object. So, it is generally a good idea to not keep a
<ttclass="docutils literal">shared_ptr</tt> to your own <aclass="reference external"href="reference-Plugins.html#peer_plugin">peer_plugin</a>. If you want to keep references to it,
use <ttclass="docutils literal">weak_ptr</tt>.</p>
<p>If this function throws an exception, the connection will be closed.</p>
<p>These hooks are called when a piece passes the hash check or fails the hash
check, respectively. The <ttclass="docutils literal">index</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 <ttclass="docutils literal">torrent</tt> and the <ttclass="docutils literal">piece_picker</tt>.</p>
<aname="tick()"></a></div>
<divclass="section"id="tick">
<h3>tick()</h3>
<preclass="literal-block">
virtual void <strong>tick</strong> ();
</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>
<aname="on_resume()"></a>
<aname="on_pause()"></a></div>
<divclass="section"id="on-resume-on-pause">
<h3>on_resume() on_pause()</h3>
<preclass="literal-block">
virtual bool <strong>on_resume</strong> ();
virtual bool <strong>on_pause</strong> ();
</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
<ttclass="docutils literal">true</tt> indicates that it was handled, and no other <aclass="reference external"href="reference-Plugins.html#plugin">plugin</a> 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 <ttclass="docutils literal">pause()</tt> or <ttclass="docutils literal">resume()</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
<p>Declared in "<aclass="reference external"href="../include/libtorrent/extensions/lt_trackers.hpp">libtorrent/extensions/lt_trackers.hpp</a>"</p>
<p>constructor function for the trackers exchange extension. This can
either be passed in the add_torrent_params::extensions field, or
via <aclass="reference external"href="reference-Core.html#add_extension()">torrent_handle::add_extension()</a>.</p>
<aname="create_smart_ban_plugin()"></a></div>
<divclass="section"id="create-smart-ban-plugin">
<h3>create_smart_ban_plugin()</h3>
<p>Declared in "<aclass="reference external"href="../include/libtorrent/extensions/smart_ban.hpp">libtorrent/extensions/smart_ban.hpp</a>"</p>
<p>Declared in "<aclass="reference external"href="../include/libtorrent/extensions/ut_metadata.hpp">libtorrent/extensions/ut_metadata.hpp</a>"</p>
