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
<p>The plugin interface consists of three base classes that the plugin may
implement. These are called <ttclass="docutils literal"><spanclass="pre">plugin</span></tt>, <ttclass="docutils literal"><spanclass="pre">torrent_plugin</span></tt> and <ttclass="docutils literal"><spanclass="pre">peer_plugin</span></tt>.
They are found in the <ttclass="docutils literal"><spanclass="pre"><libtorrent/extensions.hpp></span></tt> header.</p>
<p>These plugins are instantiated for each session, torrent and possibly each peer,
<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>For more elaborate plugins which require session wide state, you would
implement <ttclass="docutils literal"><spanclass="pre">plugin</span></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>
<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"><spanclass="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 <ttclass="docutils literal"><spanclass="pre">peer_plugin</span></tt> class. Which in
turn will have its hook functions called on event specific to that peer.</p>
<p>The <ttclass="docutils literal"><spanclass="pre">peer_connection</span></tt> will be valid as long as the <ttclass="docutils literal"><spanclass="pre">shared_ptr</span></tt> is being
held by the torrent object. So, it is generally a good idea to not keep a
<ttclass="docutils literal"><spanclass="pre">shared_ptr</span></tt> to your own peer_plugin. If you want to keep references to it,
use <ttclass="docutils literal"><spanclass="pre">weak_ptr</span></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"><spanclass="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 <ttclass="docutils literal"><spanclass="pre">torrent</span></tt> and the <ttclass="docutils literal"><spanclass="pre">piece_picker</span></tt>.</p>
<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"><spanclass="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 <ttclass="docutils literal"><spanclass="pre">pause()</span></tt> or <ttclass="docutils literal"><spanclass="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
virtual void on_add_peer(tcp::endpoint const& ip
, int src, int flags);
</pre>
<p>This function is called whenever we hear about a peer from any peer source,
such as the tracker, PEX, DHT or Local peer discovery.</p>
<p><ttclass="docutils literal"><spanclass="pre">src</span></tt> is a bitmask of <ttclass="docutils literal"><spanclass="pre">peer_info::peer_source_flags</span></tt>:</p>
<preclass="literal-block">
enum peer_source_flags
{
tracker = 0x1,
dht = 0x2,
pex = 0x4,
lsd = 0x8,
resume_data = 0x10,
incoming = 0x20
};
</pre>
<p><ttclass="docutils literal"><spanclass="pre">flags</span></tt> is a bitmask of:</p>
<preclass="literal-block">
enum flags_t {
first_time = 1,
filtered = 2
};
</pre>
<p>If the <ttclass="docutils literal"><spanclass="pre">filtered</span></tt> flag is set, it means the peer wasn't added to the
peer list because of and IP filter, port filter, reserved ports filter.</p>
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"><spanclass="pre">alert_type</span></tt> is used for the type-checking in <ttclass="docutils literal"><spanclass="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
<ttclass="docutils literal"><spanclass="pre">user_alert_id</span></tt>. When defining your own alert, make sure it's greater than this constant.</p>
<p><ttclass="docutils literal"><spanclass="pre">type()</span></tt> is the run-time equivalence of the <ttclass="docutils literal"><spanclass="pre">alert_type</span></tt>.</p>
<p>The <ttclass="docutils literal"><spanclass="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><ttclass="docutils literal"><spanclass="pre">clone()</span></tt> is used internally to copy alerts. The suggested implementation of simply
allocating a new instance as a copy of <ttclass="docutils literal"><spanclass="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 <ttclass="docutils literal"><spanclass="pre">category</span></tt> virtual function is
the run-time equivalence.</p>
<p>The <ttclass="docutils literal"><spanclass="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 <aclass="reference external"href="manual.html">main manual</a>.</p>
