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 >
2012-01-14 17:04:25 +01:00
< meta http-equiv = "Content-Type" content = "text/html; charset=utf-8" / >
2013-01-21 20:13:24 +01:00
< meta name = "generator" content = "Docutils 0.8.1: http://docutils.sourceforge.net/" / >
2012-01-14 17:04:25 +01:00
< title > < / title >
< meta name = "author" content = "Arvid Norberg, arvid@rasterbar.com" / >
< link rel = "stylesheet" type = "text/css" href = "../../css/base.css" / >
< link rel = "stylesheet" type = "text/css" href = "../../css/rst.css" / >
2010-12-08 05:44:20 +01:00
< script type = "text/javascript" >
/* < ![CDATA[ */
(function() {
var s = document.createElement('script'), t = document.getElementsByTagName('script')[0];
s.type = 'text/javascript';
s.async = true;
s.src = 'http://api.flattr.com/js/0.6/load.js?mode=auto';
t.parentNode.insertBefore(s, t);
})();
/* ]]> */
< / script >
2006-11-27 01:04:20 +01:00
< link rel = "stylesheet" href = "style.css" type = "text/css" / >
2008-10-17 05:23:30 +02:00
< style type = "text/css" >
/* Hides from IE-mac \*/
* html pre { height: 1%; }
/* End hide from IE-mac */
< / style >
2006-11-27 01:04:20 +01:00
< / head >
< body >
< div class = "document" >
2008-10-17 05:23:30 +02:00
< div id = "container" >
< div id = "headerNav" >
< ul >
< li class = "first" > < a href = "/" > Home< / a > < / li >
< li > < a href = "../../products.html" > Products< / a > < / li >
< li > < a href = "../../contact.html" > Contact< / a > < / li >
< / ul >
< / div >
< div id = "header" >
< h1 > < span > Rasterbar Software< / span > < / h1 >
< h2 > < span > Software developement and consulting< / span > < / h2 >
< / div >
< div id = "main" >
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 >
2009-03-21 05:36:46 +01:00
< td > Arvid Norberg, < a class = "last reference external" href = "mailto:arvid@rasterbar.com" > arvid@ rasterbar.com< / a > < / td > < / tr >
2006-11-27 01:04:20 +01:00
< / tbody >
< / table >
2008-10-17 05:23:30 +02:00
< div class = "section" id = "libtorrent-plugins" >
< h1 > libtorrent plugins< / h1 >
< div class = "contents topic" id = "contents" >
< p class = "topic-title first" > Contents< / p >
2006-11-27 01:04:20 +01:00
< ul class = "simple" >
2012-02-12 11:11:14 +01:00
< 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 = "id2" > a word of caution< / a > < / li >
2006-11-27 01:04:20 +01:00
< / ul >
< / li >
2012-02-12 11:11:14 +01:00
< li > < a class = "reference internal" href = "#plugin-interface" id = "id3" > plugin interface< / a > < / li >
< li > < a class = "reference internal" href = "#plugin" id = "id4" > plugin< / a > < / li >
< li > < a class = "reference internal" href = "#torrent-plugin" id = "id5" > torrent_plugin< / a > < ul >
< 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 = "id7" > on_piece_pass() on_piece_fail()< / 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 = "id9" > on_pause() on_resume()< / a > < / li >
< li > < a class = "reference internal" href = "#on-files-checked" id = "id10" > on_files_checked()< / a > < / li >
< li > < a class = "reference internal" href = "#on-add-peer" id = "id11" > on_add_peer()< / a > < / li >
2006-11-27 01:04:20 +01:00
< / ul >
< / li >
2012-02-12 11:11:14 +01:00
< li > < a class = "reference internal" href = "#peer-plugin" id = "id12" > peer_plugin< / 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 >
2006-11-27 01:04:20 +01:00
< / 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
2009-03-21 05:36:46 +01:00
< a class = "reference external" href = "extension_protocol.html" > extensions< / a > .< / li >
2006-11-27 01:04:20 +01:00
< 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 >
2011-02-01 10:48:28 +01:00
< li > save and restore state via the session state< / li >
< li > see all alerts that are posted< / li >
2006-11-27 01:04:20 +01:00
< / ul >
2008-10-17 05:23:30 +02:00
< div class = "section" id = "a-word-of-caution" >
< h2 > a word of caution< / h2 >
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
2011-02-01 10:48:28 +01:00
mutex locked. And they are always called from the libtorrent network thread. In
2006-11-27 01:04:20 +01:00
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
2009-03-21 05:36:46 +01:00
callback). See < a class = "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
2011-02-01 10:48:28 +01:00
another thread, it is advised to use an internal queue, and do the actual
2013-01-21 20:13:24 +01:00
sending in < tt class = "docutils literal" > tick()< / tt > .< / p >
2011-02-01 10:48:28 +01:00
< p > Since the plugin 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 >
2006-11-27 01:04:20 +01:00
< / div >
< / div >
2008-10-17 05:23:30 +02:00
< div class = "section" id = "plugin-interface" >
< h1 > plugin interface< / h1 >
2011-02-01 10:48:28 +01:00
< p > The plugin interface consists of three base classes that the plugin may
2013-01-21 20:13:24 +01:00
implement. These are called < tt class = "docutils literal" > plugin< / tt > , < tt class = "docutils literal" > torrent_plugin< / tt > and < tt class = "docutils literal" > peer_plugin< / tt > .
They are found in the < tt class = "docutils literal" > < libtorrent/extensions.hpp> < / tt > header.< / p >
2011-02-01 10:48:28 +01:00
< p > These plugins are instantiated for each session, torrent and possibly each peer,
2006-11-27 01:04:20 +01:00
respectively.< / p >
2011-02-01 10:48:28 +01:00
< p > For plugins that only need per torrent state, it is enough to only implement
2013-01-21 20:13:24 +01:00
< tt class = "docutils literal" > torrent_plugin< / tt > and pass a constructor function or function object to
2007-11-24 22:13:19 +01:00
< tt class = "docutils literal" > < span class = "pre" > session::add_extension()< / span > < / tt > or < tt class = "docutils literal" > < span class = "pre" > torrent_handle::add_extension()< / span > < / tt > (if the
torrent has already been started and you want to hook in the extension at
run-time).< / p >
< p > The signature of the function is:< / p >
< pre class = "literal-block" >
boost::shared_ptr< torrent_plugin> (*)(torrent*, void*);
< / pre >
< p > The first argument is the internal torrent object, the second argument
is the userdata passed to < tt class = "docutils literal" > < span class = "pre" > session::add_torrent()< / span > < / tt > or
< tt class = "docutils literal" > < span class = "pre" > torrent_handle::add_extension()< / span > < / tt > .< / p >
< p > The function should return a < tt class = "docutils literal" > < span class = "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
2013-01-21 20:13:24 +01:00
< tt class = "docutils literal" > torrent_plugin< / tt > ), it will be associated with this torrent and callbacks
2007-11-24 22:13:19 +01:00
will be made on torrent events.< / p >
2011-02-01 10:48:28 +01:00
< p > For more elaborate plugins which require session wide state, you would
2013-01-21 20:13:24 +01:00
implement < tt class = "docutils literal" > plugin< / tt > , construct an object (in a < tt class = "docutils literal" > < span class = "pre" > boost::shared_ptr< / span > < / tt > ) and pass
2011-02-01 10:48:28 +01:00
it in to < tt class = "docutils literal" > < span class = "pre" > session::add_extension()< / span > < / tt > .< / p >
< / div >
< div class = "section" id = "plugin" >
< h1 > plugin< / h1 >
< pre class = "literal-block" >
struct plugin
{
virtual ~plugin();
virtual boost::shared_ptr< torrent_plugin> new_torrent(torrent* t, void* user);
virtual void added(boost::weak_ptr< aux::session_impl> s);
virtual void on_alert(alert const* a);
virtual void on_tick();
virtual void save_state(entry& ent) const;
virtual void load_state(lazy_entry const& ent);
};
< / pre >
2006-11-27 01:04:20 +01:00
< / div >
2008-10-17 05:23:30 +02:00
< div class = "section" id = "torrent-plugin" >
< h1 > torrent_plugin< / h1 >
2013-01-21 20:13:24 +01:00
< p > The synopsis for < tt class = "docutils literal" > torrent_plugin< / tt > follows:< / p >
2006-11-27 01:04:20 +01:00
< 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();
2007-11-24 22:13:19 +01:00
virtual void on_files_checked();
2011-05-24 01:50:55 +02:00
virtual void on_state(int s);
enum flags_t {
first_time = 1,
filtered = 2
};
virtual void on_add_peer(tcp::endpoint const& ip
, int src, int flags);
2006-11-27 01:04:20 +01:00
};
< / 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 >
2008-10-17 05:23:30 +02:00
< div class = "section" id = "new-connection" >
< h2 > new_connection()< / h2 >
2006-11-27 01:04:20 +01:00
< 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
2013-01-21 20:13:24 +01:00
< tt class = "docutils literal" > shared_ptr< / tt > (in which case you don't need to override this member
2006-11-27 01:04:20 +01:00
function).< / p >
< p > If you need an extension to the peer connection (which most plugins do) you
2013-01-21 20:13:24 +01:00
are supposed to return an instance of your < tt class = "docutils literal" > peer_plugin< / tt > class. Which in
2006-11-27 01:04:20 +01:00
turn will have its hook functions called on event specific to that peer.< / p >
2013-01-21 20:13:24 +01:00
< p > The < tt class = "docutils literal" > peer_connection< / tt > will be valid as long as the < tt class = "docutils literal" > shared_ptr< / tt > is being
2006-11-27 01:04:20 +01:00
held by the torrent object. So, it is generally a good idea to not keep a
2013-01-21 20:13:24 +01:00
< tt class = "docutils literal" > shared_ptr< / tt > to your own peer_plugin. If you want to keep references to it,
use < tt class = "docutils literal" > weak_ptr< / tt > .< / p >
2006-11-27 01:04:20 +01:00
< p > If this function throws an exception, the connection will be closed.< / p >
< / div >
2008-10-17 05:23:30 +02:00
< div class = "section" id = "on-piece-pass-on-piece-fail" >
< h2 > on_piece_pass() on_piece_fail()< / h2 >
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
2013-01-21 20:13:24 +01:00
check, respectively. The < tt class = "docutils literal" > index< / tt > is the piece index that was downloaded.
2006-11-27 01:04:20 +01:00
It is possible to access the list of peers that participated in sending the
2013-01-21 20:13:24 +01:00
piece through the < tt class = "docutils literal" > torrent< / tt > and the < tt class = "docutils literal" > piece_picker< / tt > .< / p >
2006-11-27 01:04:20 +01:00
< / div >
2008-10-17 05:23:30 +02:00
< div class = "section" id = "tick" >
< h2 > tick()< / h2 >
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 >
2008-10-17 05:23:30 +02:00
< div class = "section" id = "on-pause-on-resume" >
< h2 > on_pause() on_resume()< / h2 >
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
2013-01-21 20:13:24 +01:00
< tt class = "docutils literal" > true< / tt > indicates that it was handled, and no other plugin after this one
2006-11-27 01:04:20 +01:00
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 >
2013-01-21 20:13:24 +01:00
< p > Note that if you call < tt class = "docutils literal" > pause()< / tt > or < tt class = "docutils literal" > resume()< / tt > on the torrent from your
2006-11-27 01:04:20 +01:00
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 >
2008-10-17 05:23:30 +02:00
< div class = "section" id = "on-files-checked" >
< h2 > on_files_checked()< / h2 >
2007-11-24 22:13:19 +01:00
< pre class = "literal-block" >
void on_files_checked();
< / pre >
< p > This function is called when the initial files of the torrent have been
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
can start downloading.< / p >
< / div >
2012-02-12 11:11:14 +01:00
< div class = "section" id = "on-add-peer" >
< h2 > on_add_peer()< / h2 >
2011-05-24 01:50:55 +02:00
< pre class = "literal-block" >
enum flags_t {
first_time = 1,
filtered = 2
};
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 >
2013-01-21 20:13:24 +01:00
< p > < tt class = "docutils literal" > src< / tt > is a bitmask of < tt class = "docutils literal" > < span class = "pre" > peer_info::peer_source_flags< / span > < / tt > :< / p >
2011-05-24 01:50:55 +02:00
< pre class = "literal-block" >
enum peer_source_flags
{
tracker = 0x1,
dht = 0x2,
pex = 0x4,
lsd = 0x8,
resume_data = 0x10,
incoming = 0x20
};
< / pre >
2013-01-21 20:13:24 +01:00
< p > < tt class = "docutils literal" > flags< / tt > is a bitmask of:< / p >
2011-05-24 01:50:55 +02:00
< pre class = "literal-block" >
enum flags_t {
first_time = 1,
filtered = 2
};
< / pre >
2013-01-21 20:13:24 +01:00
< p > If the < tt class = "docutils literal" > filtered< / tt > flag is set, it means the peer wasn't added to the
2011-05-24 01:50:55 +02:00
peer list because of and IP filter, port filter, reserved ports filter.< / p >
< / div >
2006-11-27 01:04:20 +01:00
< / div >
2008-10-17 05:23:30 +02:00
< div class = "section" id = "peer-plugin" >
< h1 > peer_plugin< / h1 >
2006-11-27 01:04:20 +01:00
< pre class = "literal-block" >
struct peer_plugin
{
virtual ~peer_plugin();
virtual void add_handshake(entry& );
2008-05-15 18:18:27 +02:00
virtual bool on_handshake(char const* reserved_bits);
2008-07-06 14:22:56 +02:00
virtual bool on_extension_handshake(lazy_entry const& h);
2006-11-27 01:04:20 +01:00
virtual bool on_choke();
virtual bool on_unchoke();
virtual bool on_interested();
virtual bool on_not_interested();
virtual bool on_have(int index);
2008-05-29 05:37:19 +02:00
virtual bool on_bitfield(bitfield const& bits);
2007-11-24 22:13:19 +01:00
virtual bool on_have_all();
virtual bool on_have_none();
virtual bool on_allowed_fast(int index);
2006-11-27 01:04:20 +01:00
virtual bool on_request(peer_request const& req);
2008-04-10 12:03:23 +02:00
virtual bool on_piece(peer_request const& piece, disk_buffer_holder& buffer);
2006-11-27 01:04:20 +01:00
virtual bool on_cancel(peer_request const& req);
2007-11-24 22:13:19 +01:00
virtual bool on_reject(peer_request const& req);
virtual bool on_suggest(int index);
2006-11-27 01:04:20 +01:00
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 >
2008-10-17 05:23:30 +02:00
< div class = "section" id = "disk-buffer-holder" >
< h1 > disk_buffer_holder< / h1 >
2008-04-10 12:03:23 +02:00
< pre class = "literal-block" >
struct disk_buffer_holder
{
disk_buffer_holder(aux::session_impl& s, char* b);
~disk_buffer_holder();
char* release();
char* buffer();
};
< / pre >
2013-01-21 20:13:24 +01:00
< p > The disk buffer holder acts like a < tt class = "docutils literal" > scoped_ptr< / tt > that frees a disk buffer
when it's destructed, unless it's released. < tt class = "docutils literal" > release< / tt > returns the disk
2008-04-10 12:03:23 +02:00
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 >
2013-01-21 20:13:24 +01:00
< p > < tt class = "docutils literal" > buffer()< / tt > returns the pointer without transferring responsibility. If
this buffer has been released, < tt class = "docutils literal" > buffer()< / tt > will return 0.< / p >
2012-02-12 11:11:14 +01:00
< / 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 >
2013-01-21 20:13:24 +01:00
< p > The expected interface of any alert, apart from deriving from the < tt class = "docutils literal" > alert< / tt >
2012-02-12 11:11:14 +01:00
base class, looks like this:< / p >
< pre class = "literal-block" >
const static int alert_type = < em > < unique alert ID> < / em > ;
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 = < 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 >
2013-01-21 20:13:24 +01:00
< p > The < tt class = "docutils literal" > alert_type< / tt > is used for the type-checking in < tt class = "docutils literal" > alert_cast< / tt > . It must not collide with
2012-02-12 11:11:14 +01:00
any other alert. The built-in alerts in libtorrent will not use alert type IDs greater than
2013-01-21 20:13:24 +01:00
< tt class = "docutils literal" > user_alert_id< / tt > . When defining your own alert, make sure it's greater than this constant.< / p >
< p > < tt class = "docutils literal" > type()< / tt > is the run-time equivalence of the < tt class = "docutils literal" > alert_type< / tt > .< / p >
< p > The < tt class = "docutils literal" > message()< / tt > virtual function is expected to construct a useful string representation
2012-02-12 11:11:14 +01:00
of the alert and the event or data it represents. Something convenient to put in a log file
for instance.< / p >
2013-01-21 20:13:24 +01:00
< p > < tt class = "docutils literal" > clone()< / tt > is used internally to copy alerts. The suggested implementation of simply
allocating a new instance as a copy of < tt class = "docutils literal" > *this< / tt > is all that's expected.< / p >
2012-02-12 11:11:14 +01:00
< p > The static category is required for checking wether or not the category for a specific alert
2013-01-21 20:13:24 +01:00
is enabled or not, without instantiating the alert. The < tt class = "docutils literal" > category< / tt > virtual function is
2012-02-12 11:11:14 +01:00
the run-time equivalence.< / p >
2013-01-21 20:13:24 +01:00
< p > The < tt class = "docutils literal" > what()< / tt > virtual function may simply be a string literal of the class name of
2012-02-12 11:11:14 +01:00
your alert.< / p >
< p > For more information, see the alert section in the < a class = "reference external" href = "manual.html" > main manual< / a > .< / p >
2008-04-10 12:03:23 +02:00
< / div >
2008-10-17 05:23:30 +02:00
< / div >
< div id = "footer" >
< span > Copyright © 2005 Rasterbar Software.< / span >
< / div >
< / div >
< script src = "http://www.google-analytics.com/urchin.js" type = "text/javascript" >
< / script >
< script type = "text/javascript" >
_uacct = "UA-1599045-1";
urchinTracker();
< / script >
2006-11-27 01:04:20 +01:00
< / div >
< / body >
< / html >
