new_torrent()

virtual boost::shared_ptr<torrent_plugin> new_torrent (torrent*, void*);

this is called by the session every time a new torrent is added. The torrent* points to the internal torrent object created for the new torrent. The void* is the userdata pointer as passed in via add_torrent_params.

If the plugin returns a torrent_plugin instance, it will be added to the new torrent. Otherwise, return an empty shared_ptr to a torrent_plugin (the default).

added()

virtual void added (aux::session_impl*);

called when plugin is added to a session

on_alert()

virtual void on_alert (alert const*);

called when an alert is posted alerts that are filtered are not posted

on_tick()

virtual void on_tick ();

called once per second

on_optimistic_unchoke()

virtual bool on_optimistic_unchoke (std::vector<policy::peer*>& /* peers */);

called when choosing peers to optimisticly unchoke peer's will be unchoked in the order they appear in the given vector which is initiallity sorted by when they were last optimistically unchoked. if the plugin returns true then the ordering provided will be used and no other plugin will be allowed to change it.

save_state()

virtual void save_state (entry&) const;

called when saving settings state

load_state()

virtual void load_state (lazy_entry const&);

called when loading settings state

new_connection()

virtual boost::shared_ptr<peer_plugin> new_connection (peer_connection*);

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 shared_ptr (in which case you don't need to override this member function).

If you need an extension to the peer connection (which most plugins do) you are supposed to return an instance of your peer_plugin class. Which in turn will have its hook functions called on event specific to that peer.

The peer_connection will be valid as long as the shared_ptr is being held by the torrent object. So, it is generally a good idea to not keep a shared_ptr to your own peer_plugin. If you want to keep references to it, use weak_ptr.

If this function throws an exception, the connection will be closed.

on_piece_failed() on_piece_pass()

virtual void on_piece_pass (int /*index*/);
virtual void on_piece_failed (int /*index*/);

These hooks are called when a piece passes the hash check or fails the hash check, respectively. The index is the piece index that was downloaded. It is possible to access the list of peers that participated in sending the piece through the torrent and the piece_picker.

tick()

virtual void tick ();

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.

on_resume() on_pause()

virtual bool on_resume ();
virtual bool on_pause ();

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 true 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.

Note that if you call pause() or resume() 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.

on_files_checked()

virtual void on_files_checked ();

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.

i.e. This function is always called when the torrent is in a state where it can start downloading.

on_state()

virtual void on_state (int /*s*/);

called when the torrent changes state the state is one of torrent_status::state_t enum members

on_add_peer()

virtual void on_add_peer (tcp::endpoint const&,
      int /*src*/, int /*flags*/);

called every time a new peer is added to the peer list. This is before the peer is connected to. For flags, see torrent_plugin::flags_t. The source argument refers to the source where we learned about this peer from. It's a bitmask, because many sources may have told us about the same peer. For peer source flags, see peer_info::peer_source_flags.

type()

virtual char const* type () const;

This function is expected to return the name of the plugin.

add_handshake()

virtual void add_handshake (entry&);

can add entries to the extension handshake this is not called for web seeds

on_disconnect()

virtual void on_disconnect (error_code const& /*ec*/);

called when the peer is being disconnected.

on_connected()

virtual void on_connected ();

called when the peer is successfully connected. Note that incoming connections will have been connected by the time the peer plugin is attached to it, and won't have this hook called.

on_handshake()

virtual bool on_handshake (char const* /*reserved_bits*/);

this is called when the initial BT handshake is received. Returning false means that the other end doesn't support this extension and will remove it from the list of plugins. this is not called for web seeds

on_extension_handshake()

virtual bool on_extension_handshake (lazy_entry const&);

called when the extension handshake from the other end is received if this returns false, it means that this extension isn't supported by this peer. It will result in this peer_plugin being removed from the peer_connection and destructed. this is not called for web seeds

on_bitfield() on_have_none() on_suggest() on_unchoke() on_cancel() on_have() on_choke() on_piece() on_request() on_reject() on_not_interested() on_interested() on_allowed_fast() on_have_all() on_dont_have()

virtual bool on_have (int /*index*/);
virtual bool on_bitfield (bitfield const& /*bitfield*/);
virtual bool on_have_all ();
virtual bool on_reject (peer_request const&);
virtual bool on_request (peer_request const&);
virtual bool on_unchoke ();
virtual bool on_interested ();
virtual bool on_allowed_fast (int /*index*/);
virtual bool on_have_none ();
virtual bool on_choke ();
virtual bool on_not_interested ();
virtual bool on_piece (peer_request const& /*piece*/
      , disk_buffer_holder& /*data*/);
virtual bool on_suggest (int /*index*/);
virtual bool on_cancel (peer_request const&);
virtual bool on_dont_have (int /*index*/);

returning true from any of the message handlers indicates that the plugin has handeled the message. it will break the plugin chain traversing and not let anyone else handle the message, including the default handler.

sent_unchoke()

virtual void sent_unchoke ();

called after a choke message has been sent to the peer

can_disconnect()

virtual bool can_disconnect (error_code const& /*ec*/);

called when libtorrent think this peer should be disconnected. if the plugin returns false, the peer will not be disconnected.

on_extended()

virtual bool on_extended (int /*length*/, int /*msg*/,
      buffer::const_interval /*body*/);

called when an extended message is received. If returning true, the message is not processed by any other plugin and if false is returned the next plugin in the chain will receive it to be able to handle it this is not called for web seeds

on_unknown_message()

virtual bool on_unknown_message (int /*length*/, int /*msg*/,
      buffer::const_interval /*body*/);

this is not called for web seeds

on_piece_failed() on_piece_pass()

virtual void on_piece_pass (int /*index*/);
virtual void on_piece_failed (int /*index*/);

called when a piece that this peer participated in either fails or passes the hash_check

tick()

virtual void tick ();

called aproximately once every second

write_request()

virtual bool write_request (peer_request const&);

called each time a request message is to be sent. If true is returned, the original request message won't be sent and no other plugin will have this function called.

create_lt_trackers_plugin()

Declared in "libtorrent/extensions/lt_trackers.hpp"

boost::shared_ptr<torrent_plugin> create_lt_trackers_plugin (torrent*, void*);

constructor function for the trackers exchange extension. This can either be passed in the add_torrent_params::extensions field, or via torrent_handle::add_extension().

create_smart_ban_plugin()

Declared in "libtorrent/extensions/smart_ban.hpp"

boost::shared_ptr<torrent_plugin> create_smart_ban_plugin (torrent*, void*);

constructor function for the smart ban extension. The extension keeps track of the data peers have sent us for failing pieces and once the piece completes and passes the hash check bans the peers that turned out to have sent corrupt data. This function can either be passed in the add_torrent_params::extensions field, or via torrent_handle::add_extension().

create_ut_metadata_plugin()

Declared in "libtorrent/extensions/ut_metadata.hpp"

boost::shared_ptr<torrent_plugin> create_ut_metadata_plugin (torrent*, void*);

constructor function for the ut_metadata extension. The ut_metadata extension allows peers to request the .torrent file (or more specifically the 'info'-dictionary of the .torrent file) from each other. This is the main building block in making magnet links work. This extension is enabled by default unless explicitly disabled in the session constructor.

This can either be passed in the add_torrent_params::extensions field, or via torrent_handle::add_extension().

create_ut_pex_plugin()

Declared in "libtorrent/extensions/ut_pex.hpp"

boost::shared_ptr<torrent_plugin> create_ut_pex_plugin (torrent*, void*);

constructor function for the ut_pex extension. The ut_pex extension allows peers to gossip about their connections, allowing the swarm stay well connected and peers aware of more peers in the swarm. This extension is enabled by default unless explicitly disabled in the session constructor.

This can either be passed in the add_torrent_params::extensions field, or via torrent_handle::add_extension().