.. include:: header.rst

`home`__

__ reference.html

.. contents:: Table of contents
  :depth: 2
  :backlinks: none


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.

In short, the `plugin`__ interface makes it possible to:

* register extension messages (sent in the extension handshake), see
  extensions_.
* add data and parse data from the extension handshake.
* send extension messages and standard bittorrent messages.
* override or block the handling of standard bittorrent messages.
* save and restore state via the `session`__ state
* see all alerts that are posted

a word of caution
-----------------

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.

All the callbacks are always called from the libtorrent network 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 being called from the libtorrent network
thread . Furthermore, you also need to synchronize 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). 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 ``tick()``.

Since the `plugin`__ interface gives you easy access to internal structures, it
is not supported as a stable API. Plugins should be considered specific to a
specific version of libtorrent. Although, in practice the internals mostly
don't change that dramatically.


plugin-interface
----------------

The `plugin`__ interface consists of three base classes that the `plugin`__ may
implement. These are called `plugin`__, `torrent_plugin`__ and `peer_plugin`__.
They are found in the ``<libtorrent/extensions.hpp>`` header.

These plugins are instantiated for each `session`__, torrent and possibly each peer,
respectively.

For plugins that only need per torrent state, it is enough to only implement
``torrent_plugin`` and pass a constructor function or function object to
``session::add_extension()`` or ``torrent_handle::add_extension()`` (if the
torrent has already been started and you want to hook in the extension at
run-time).

The signature of the function is:

.. code:: c++

	std::shared_ptr<torrent_plugin> (*)(torrent_handle const&, client_data_t);

The second argument is the userdata passed to ``session::add_torrent()`` or
``torrent_handle::add_extension()``.

The function should return a ``std::shared_ptr<torrent_plugin>`` which
may or may not be 0. If it is a nullptr, the extension is simply ignored
for this torrent. If it is a valid pointer (to a class inheriting
``torrent_plugin``), it will be associated with this torrent and callbacks
will be made on torrent events.

For more elaborate plugins which require `session`__ wide state, you would
implement ``plugin``, construct an object (in a ``std::shared_ptr``) and pass
it in to ``session::add_extension()``.

custom alerts
-------------

Since plugins are running within internal libtorrent threads, one convenient
way to communicate with the client is to post custom alerts.

The expected interface of any `alert`__, apart from deriving from the `alert`__
base class, looks like this:

.. parsed-literal::

	static const int alert_type = *<unique alert ID>*;
	virtual int type() const { return alert_type; }

	virtual std::string message() const;

	static const alert_category_t static_category = *<bitmask of alert::category_t flags>*;
	virtual alert_category_t category() const { return static_category; }

	virtual char const* what() const { return *<string literal of the name of this alert>*; }

The ``alert_type`` is used for the type-checking in ``alert_cast``. It must
not collide with any other `alert`__. The built-in alerts in libtorrent will
not use `alert`__ type IDs greater than ``user_alert_id``. When defining your
own `alert`__, make sure it's greater than this constant.

``type()`` is the run-time equivalence of the ``alert_type``.

The ``message()`` 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.

``clone()`` is used internally to copy alerts. The suggested implementation
of simply allocating a new instance as a copy of ``*this`` is all that's
expected.

The static category is required for checking whether or not the category
for a specific `alert`__ is enabled or not, without instantiating the `alert`__.
The ``category`` virtual function is the run-time equivalence.

The ``what()`` virtual function may simply be a string literal of the class
name of your `alert`__.

For more information, see the `alert section`_.

.. _`alert section`: reference-Alerts.html

.. raw:: html

	<a name="peer_connection_handle"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+peer_connection_handle&labels=documentation&body=Documentation+under+heading+%22class+peer_connection_handle%22+could+be+improved">report issue</a>]</span>



peer_connection_handle
----------------------

Declared in "`libtorrent/peer_connection_handle.hpp`__"


__ reference-Plugins.html#plugin
__ reference-Plugins.html#plugin
__ reference-Session.html#session
__ reference-Plugins.html#plugin
__ reference-Plugins.html#plugin
__ reference-Plugins.html#plugin
__ reference-Plugins.html#plugin
__ reference-Plugins.html#plugin
__ reference-Plugins.html#plugin
__ reference-Plugins.html#plugin
__ reference-Plugins.html#plugin
__ reference-Plugins.html#torrent_plugin
__ reference-Plugins.html#peer_plugin
__ reference-Session.html#session
__ reference-Session.html#session
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ reference-Alerts.html#alert
__ include/libtorrent/peer_connection_handle.hpp

the `peer_connection_handle`__ class provides a handle to the internal peer
connection object, to be used by plugins. This is a low level interface that
may not be stable across libtorrent versions


__ reference-Plugins.html#peer_connection_handle


.. parsed-literal::
	

	struct peer_connection_handle
	{
	   explicit **peer_connection_handle** (std\:\:weak\_ptr<peer\_connection> impl);
	   connection_type **type** () const;
	   void **add_extension** (std\:\:shared\_ptr<peer\_plugin>);
	   peer_plugin const* **find_plugin** (string\_view type) const;
	   bool **is_seed** () const;
	   bool **upload_only** () const;
	   bool **has_piece** (piece\_index\_t i) const;
	   peer_id const& **pid** () const;
	   bool **is_interesting** () const;
	   bool **is_choked** () const;
	   bool **has_peer_choked** () const;
	   bool **is_peer_interested** () const;
	   void **choke_this_peer** ();
	   void **maybe_unchoke_this_peer** ();
	   void **get_peer_info** (peer\_info& p) const;
	   torrent_handle **associated_torrent** () const;
	   tcp::endpoint **local_endpoint** () const;
	   tcp::endpoint const& **remote** () const;
	   bool **is_connecting** () const;
	   bool **is_outgoing** () const;
	   void **disconnect** (error\_code const& ec, operation\_t op
	      , disconnect\_severity\_t = peer\_connection\_interface\:\:normal);
	   bool **is_disconnecting** () const;
	   bool **ignore_unchoke_slots** () const;
	   bool **on_local_network** () const;
	   bool **failed** () const;
	   void **peer_log** (peer\_log\_alert\:\:direction\_t direction
	      , char const\* event, char const\* fmt = "", ...) const TORRENT\_FORMAT(4,5);
	   bool **should_log** (peer\_log\_alert\:\:direction\_t direction) const;
	   bool **can_disconnect** (error\_code const& ec) const;
	   bool **has_metadata** () const;
	   bool **in_handshake** () const;
	   void **send_buffer** (char const\* begin, int size);
	   time_point **time_of_last_unchoke** () const;
	   std::time_t **last_seen_complete** () const;
	   bool **operator<** (peer\_connection\_handle const& o) const;
	   bool **operator==** (peer\_connection\_handle const& o) const;
	   bool **operator!=** (peer\_connection\_handle const& o) const;
	   std::shared_ptr<peer_connection> **native_handle** () const;
	};

.. raw:: html

	<a name="bt_peer_connection_handle"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+bt_peer_connection_handle&labels=documentation&body=Documentation+under+heading+%22class+bt_peer_connection_handle%22+could+be+improved">report issue</a>]</span>



bt_peer_connection_handle
-------------------------

Declared in "`libtorrent/peer_connection_handle.hpp`__"


__ include/libtorrent/peer_connection_handle.hpp

The `bt_peer_connection_handle`__ provides a handle to the internal bittorrent
peer connection object to plugins. It's low level and may not be a stable API
across libtorrent versions.


__ reference-Plugins.html#bt_peer_connection_handle


.. parsed-literal::
	

	struct bt_peer_connection_handle : peer_connection_handle
	{
	   explicit **bt_peer_connection_handle** (peer\_connection\_handle pc);
	   bool **packet_finished** () const;
	   bool **support_extensions** () const;
	   bool **supports_encryption** () const;
	   void **switch_send_crypto** (std\:\:shared\_ptr<crypto\_plugin> crypto);
	   void **switch_recv_crypto** (std\:\:shared\_ptr<crypto\_plugin> crypto);
	   std::shared_ptr<bt_peer_connection> **native_handle** () const;
	};

.. raw:: html

	<a name="plugin"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+plugin&labels=documentation&body=Documentation+under+heading+%22class+plugin%22+could+be+improved">report issue</a>]</span>



plugin
------

Declared in "`libtorrent/extensions.hpp`__"


__ include/libtorrent/extensions.hpp

this is the base class for a `session`__ `plugin`__. One primary feature
is that it is notified of all torrents that are added to the `session`__,
and can add its own torrent_plugins.


__ reference-Session.html#session
__ reference-Plugins.html#plugin
__ reference-Session.html#session


.. parsed-literal::
	

	struct plugin
	{
	   virtual feature_flags_t **implemented_features** ();
	   virtual std::shared_ptr<torrent_plugin> **new_torrent** (torrent\_handle const&, client\_data\_t);
	   virtual void **added** (session\_handle const&);
	   virtual void **abort** ();
	   virtual bool **on_dht_request** (string\_view */\* query \*/*
	      , udp\:\:endpoint const& */\* source \*/*, bdecode\_node const& */\* message \*/*
	      , entry& */\* response \*/*);
	   virtual void **on_alert** (alert const\*);
	   virtual bool **on_unknown_torrent** (info\_hash\_t const& */\* info\_hash \*/*
	      , peer\_connection\_handle const& */\* pc \*/*, add\_torrent\_params& */\* p \*/*);
	   virtual void **on_tick** ();
	   virtual uint64_t **get_unchoke_priority** (peer\_connection\_handle const& */\* peer \*/*);
	   virtual std::map<std::string, std::string> **save_state** () const;
	   virtual void **load_state** (std\:\:map<std\:\:string, std\:\:string> const&);
	
	   static constexpr feature_flags_t **optimistic_unchoke_feature**  = 1_bit;
	   static constexpr feature_flags_t **tick_feature**  = 2_bit;
	   static constexpr feature_flags_t **dht_request_feature**  = 3_bit;
	   static constexpr feature_flags_t **alert_feature**  = 4_bit;
	};

.. raw:: html

	<a name="implemented_features()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Bimplemented_features%28%29%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Bimplemented_features%28%29%5D%22+could+be+improved">report issue</a>]</span>



implemented_features()
......................

.. parsed-literal::
	
	virtual feature_flags_t **implemented_features** ();
	

This function is expected to return a bitmask indicating which features
this `plugin`__ implements. Some callbacks on this object may not be called
unless the corresponding feature flag is returned here. Note that
callbacks may still be called even if the corresponding feature is not
specified in the return value here. See feature_flags_t for possible
flags to return.


__ reference-Plugins.html#plugin

.. raw:: html

	<a name="new_torrent()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Bnew_torrent%28%29%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Bnew_torrent%28%29%5D%22+could+be+improved">report issue</a>]</span>



new_torrent()
.............

.. parsed-literal::
	
	virtual std::shared_ptr<torrent_plugin> **new_torrent** (torrent\_handle const&, client\_data\_t);
	

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 `client_data_t`__ 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).


__ reference-Session.html#session
__ reference-Add_Torrent.html#client_data_t
__ reference-Add_Torrent.html#add_torrent_params
__ reference-Plugins.html#plugin
__ reference-Plugins.html#torrent_plugin
__ reference-Plugins.html#torrent_plugin

.. raw:: html

	<a name="added()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Badded%28%29%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Badded%28%29%5D%22+could+be+improved">report issue</a>]</span>



added()
.......

.. parsed-literal::
	
	virtual void **added** (session\_handle const&);
	

called when `plugin`__ is added to a `session`__


__ reference-Plugins.html#plugin
__ reference-Session.html#session

.. raw:: html

	<a name="abort()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Babort%28%29%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Babort%28%29%5D%22+could+be+improved">report issue</a>]</span>



abort()
.......

.. parsed-literal::
	
	virtual void **abort** ();
	

called when the `session`__ is aborted
the `plugin`__ should perform any cleanup necessary to allow the session's
destruction (e.g. cancel outstanding async operations)


__ reference-Session.html#session
__ reference-Plugins.html#plugin

.. raw:: html

	<a name="on_dht_request()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Bon_dht_request%28%29%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Bon_dht_request%28%29%5D%22+could+be+improved">report issue</a>]</span>



on_dht_request()
................

.. parsed-literal::
	
	virtual bool **on_dht_request** (string\_view */\* query \*/*
	      , udp\:\:endpoint const& */\* source \*/*, bdecode\_node const& */\* message \*/*
	      , entry& */\* response \*/*);
	

called when a dht request is received.
If your `plugin`__ expects this to be called, make sure to include the flag
``dht_request_feature`` in the return value from `implemented_features()`__.


__ reference-Plugins.html#plugin
__ reference-Plugins.html#implemented_features()

.. raw:: html

	<a name="on_alert()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Bon_alert%28%29%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Bon_alert%28%29%5D%22+could+be+improved">report issue</a>]</span>



on_alert()
..........

.. parsed-literal::
	
	virtual void **on_alert** (alert const\*);
	

called when an `alert`__ is posted alerts that are filtered are not posted.
If your `plugin`__ expects this to be called, make sure to include the flag
``alert_feature`` in the return value from `implemented_features()`__.


__ reference-Alerts.html#alert
__ reference-Plugins.html#plugin
__ reference-Plugins.html#implemented_features()

.. raw:: html

	<a name="on_unknown_torrent()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Bon_unknown_torrent%28%29%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Bon_unknown_torrent%28%29%5D%22+could+be+improved">report issue</a>]</span>



on_unknown_torrent()
....................

.. parsed-literal::
	
	virtual bool **on_unknown_torrent** (info\_hash\_t const& */\* info\_hash \*/*
	      , peer\_connection\_handle const& */\* pc \*/*, add\_torrent\_params& */\* p \*/*);
	

return true if the `add_torrent_params`__ should be added


__ reference-Add_Torrent.html#add_torrent_params

.. raw:: html

	<a name="on_tick()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Bon_tick%28%29%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Bon_tick%28%29%5D%22+could+be+improved">report issue</a>]</span>



on_tick()
.........

.. parsed-literal::
	
	virtual void **on_tick** ();
	

called once per second.
If your `plugin`__ expects this to be called, make sure to include the flag
``tick_feature`` in the return value from `implemented_features()`__.


__ reference-Plugins.html#plugin
__ reference-Plugins.html#implemented_features()

.. raw:: html

	<a name="get_unchoke_priority()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Bget_unchoke_priority%28%29%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Bget_unchoke_priority%28%29%5D%22+could+be+improved">report issue</a>]</span>



get_unchoke_priority()
......................

.. parsed-literal::
	
	virtual uint64_t **get_unchoke_priority** (peer\_connection\_handle const& */\* peer \*/*);
	

called when choosing peers to optimistically unchoke. The return value
indicates the peer's priority for unchoking. Lower return values
correspond to higher priority. Priorities above 2^63-1 are reserved.
If your `plugin`__ has no priority to assign a peer it should return 2^64-1.
If your `plugin`__ expects this to be called, make sure to include the flag
``optimistic_unchoke_feature`` in the return value from `implemented_features()`__.
If multiple plugins implement this function the lowest return value
(i.e. the highest priority) is used.


__ reference-Plugins.html#plugin
__ reference-Plugins.html#plugin
__ reference-Plugins.html#implemented_features()

.. raw:: html

	<a name="load_state()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Bload_state%28%29%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Bload_state%28%29%5D%22+could+be+improved">report issue</a>]</span>



load_state()
............

.. parsed-literal::
	
	virtual void **load_state** (std\:\:map<std\:\:string, std\:\:string> const&);
	

called on startup while loading settings state from the `session_params`__


__ reference-Session.html#session_params

.. raw:: html

	<a name="optimistic_unchoke_feature"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Boptimistic_unchoke_feature%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Boptimistic_unchoke_feature%5D%22+could+be+improved">report issue</a>]</span>


optimistic_unchoke_feature
	include this bit if your `plugin`__ needs to alter the order of the
	optimistic unchoke of peers. i.e. have the on_optimistic_unchoke()
	callback be called.
	

__ reference-Plugins.html#plugin

.. raw:: html

	<a name="tick_feature"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Btick_feature%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Btick_feature%5D%22+could+be+improved">report issue</a>]</span>


tick_feature
	include this bit if your `plugin`__ needs to have `on_tick()`__ called
	

__ reference-Plugins.html#plugin
__ reference-Plugins.html#on_tick()

.. raw:: html

	<a name="dht_request_feature"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Bdht_request_feature%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Bdht_request_feature%5D%22+could+be+improved">report issue</a>]</span>


dht_request_feature
	include this bit if your `plugin`__ needs to have `on_dht_request()`__
	called
	

__ reference-Plugins.html#plugin
__ reference-Plugins.html#on_dht_request()

.. raw:: html

	<a name="alert_feature"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:plugin%3A%3A%5Balert_feature%5D&labels=documentation&body=Documentation+under+heading+%22plugin%3A%3A%5Balert_feature%5D%22+could+be+improved">report issue</a>]</span>


alert_feature
	include this bit if your `plugin`__ needs to have `on_alert()`__
	called
	

__ reference-Plugins.html#plugin
__ reference-Plugins.html#on_alert()

.. raw:: html

	<a name="torrent_plugin"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+torrent_plugin&labels=documentation&body=Documentation+under+heading+%22class+torrent_plugin%22+could+be+improved">report issue</a>]</span>



torrent_plugin
--------------

Declared in "`libtorrent/extensions.hpp`__"


__ include/libtorrent/extensions.hpp

Torrent plugins are associated with a single torrent and have a number
of functions called at certain events. Many of its functions have the
ability to change or override the default libtorrent behavior.




.. parsed-literal::
	

	struct torrent_plugin
	{
	   virtual std::shared_ptr<peer_plugin> **new_connection** (peer\_connection\_handle const&);
	   virtual void **on_piece_pass** (piece\_index\_t);
	   virtual void **on_piece_failed** (piece\_index\_t);
	   virtual void **tick** ();
	   virtual bool **on_resume** ();
	   virtual bool **on_pause** ();
	   virtual void **on_files_checked** ();
	   virtual void **on_state** (torrent\_status\:\:state\_t);
	   virtual void **on_add_peer** (tcp\:\:endpoint const&,
	      peer\_source\_flags\_t, add\_peer\_flags\_t);
	
	   static constexpr add_peer_flags_t **first_time**  = 1_bit;
	   static constexpr add_peer_flags_t **filtered**  = 2_bit;
	};

.. raw:: html

	<a name="new_connection()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_plugin%3A%3A%5Bnew_connection%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_plugin%3A%3A%5Bnew_connection%28%29%5D%22+could+be+improved">report issue</a>]</span>



new_connection()
................

.. parsed-literal::
	
	virtual std::shared_ptr<peer_plugin> **new_connection** (peer\_connection\_handle const&);
	

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_handle`` 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.


__ reference-Plugins.html#peer_plugin
__ reference-Plugins.html#peer_plugin

.. raw:: html

	<a name="on_piece_failed()"></a>
	<a name="on_piece_pass()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_plugin%3A%3A%5Bon_piece_failed%28%29+on_piece_pass%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_plugin%3A%3A%5Bon_piece_failed%28%29+on_piece_pass%28%29%5D%22+could+be+improved">report issue</a>]</span>



on_piece_failed() on_piece_pass()
.................................

.. parsed-literal::
	
	virtual void **on_piece_pass** (piece\_index\_t);
	virtual void **on_piece_failed** (piece\_index\_t);
	

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



.. raw:: html

	<a name="tick()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_plugin%3A%3A%5Btick%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_plugin%3A%3A%5Btick%28%29%5D%22+could+be+improved">report issue</a>]</span>



tick()
......

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="on_resume()"></a>
	<a name="on_pause()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_plugin%3A%3A%5Bon_resume%28%29+on_pause%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_plugin%3A%3A%5Bon_resume%28%29+on_pause%28%29%5D%22+could+be+improved">report issue</a>]</span>



on_resume() on_pause()
......................

.. parsed-literal::
	
	virtual bool **on_resume** ();
	virtual bool **on_pause** ();
	

These hooks are called when the torrent is paused and resumed 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 resume.

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.


__ reference-Plugins.html#plugin

.. raw:: html

	<a name="on_files_checked()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_plugin%3A%3A%5Bon_files_checked%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_plugin%3A%3A%5Bon_files_checked%28%29%5D%22+could+be+improved">report issue</a>]</span>



on_files_checked()
..................

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="on_state()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_plugin%3A%3A%5Bon_state%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_plugin%3A%3A%5Bon_state%28%29%5D%22+could+be+improved">report issue</a>]</span>



on_state()
..........

.. parsed-literal::
	
	virtual void **on_state** (torrent\_status\:\:state\_t);
	

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


__ reference-Torrent_Status.html#state_t

.. raw:: html

	<a name="on_add_peer()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_plugin%3A%3A%5Bon_add_peer%28%29%5D&labels=documentation&body=Documentation+under+heading+%22torrent_plugin%3A%3A%5Bon_add_peer%28%29%5D%22+could+be+improved">report issue</a>]</span>



on_add_peer()
.............

.. parsed-literal::
	
	virtual void **on_add_peer** (tcp\:\:endpoint const&,
	      peer\_source\_flags\_t, add\_peer\_flags\_t);
	

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.



.. raw:: html

	<a name="first_time"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_plugin%3A%3A%5Bfirst_time%5D&labels=documentation&body=Documentation+under+heading+%22torrent_plugin%3A%3A%5Bfirst_time%5D%22+could+be+improved">report issue</a>]</span>


first_time
	this is the first time we see this peer
	


.. raw:: html

	<a name="filtered"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:torrent_plugin%3A%3A%5Bfiltered%5D&labels=documentation&body=Documentation+under+heading+%22torrent_plugin%3A%3A%5Bfiltered%5D%22+could+be+improved">report issue</a>]</span>


filtered
	this peer was not added because it was
	filtered by the IP filter
	


.. raw:: html

	<a name="peer_plugin"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+peer_plugin&labels=documentation&body=Documentation+under+heading+%22class+peer_plugin%22+could+be+improved">report issue</a>]</span>



peer_plugin
-----------

Declared in "`libtorrent/extensions.hpp`__"


__ include/libtorrent/extensions.hpp

peer plugins are associated with a specific peer. A peer could be
both a regular bittorrent peer (``bt_peer_connection``) or one of the
web seed connections (``web_peer_connection`` or ``http_seed_connection``).
In order to only attach to certain peers, make your
torrent_plugin::new_connection only return a `plugin`__ for certain peer
connection types


__ reference-Plugins.html#plugin


.. parsed-literal::
	

	struct peer_plugin
	{
	   virtual string_view **type** () const;
	   virtual void **add_handshake** (entry&);
	   virtual void **on_disconnect** (error\_code const&);
	   virtual void **on_connected** ();
	   virtual bool **on_handshake** (span<char const>);
	   virtual bool **on_extension_handshake** (bdecode\_node const&);
	   virtual bool **on_bitfield** (bitfield const& */\*bitfield\*/*);
	   virtual bool **on_allowed_fast** (piece\_index\_t);
	   virtual bool **on_request** (peer\_request const&);
	   virtual bool **on_choke** ();
	   virtual bool **on_not_interested** ();
	   virtual bool **on_have** (piece\_index\_t);
	   virtual bool **on_interested** ();
	   virtual bool **on_have_all** ();
	   virtual bool **on_have_none** ();
	   virtual bool **on_unchoke** ();
	   virtual bool **on_dont_have** (piece\_index\_t);
	   virtual bool **on_piece** (peer\_request const& */\*piece\*/*
	      , span<char const> */\*buf\*/*);
	   virtual bool **on_reject** (peer\_request const&);
	   virtual bool **on_suggest** (piece\_index\_t);
	   virtual bool **on_cancel** (peer\_request const&);
	   virtual void **sent_have_none** ();
	   virtual void **sent_allow_fast** (piece\_index\_t);
	   virtual void **sent_choke** ();
	   virtual void **sent_cancel** (peer\_request const&);
	   virtual void **sent_request** (peer\_request const&);
	   virtual void **sent_suggest** (piece\_index\_t);
	   virtual void **sent_have_all** ();
	   virtual void **sent_reject_request** (peer\_request const&);
	   virtual void **sent_interested** ();
	   virtual void **sent_not_interested** ();
	   virtual void **sent_unchoke** ();
	   virtual void **sent_have** (piece\_index\_t);
	   virtual void **sent_piece** (peer\_request const&);
	   virtual void **sent_payload** (int */\* bytes \*/*);
	   virtual bool **can_disconnect** (error\_code const& */\*ec\*/*);
	   virtual bool **on_extended** (int */\*length\*/*, int */\*msg\*/*,
	      span<char const> */\*body\*/*);
	   virtual bool **on_unknown_message** (int */\*length\*/*, int */\*msg\*/*,
	      span<char const> */\*body\*/*);
	   virtual void **on_piece_pass** (piece\_index\_t);
	   virtual void **on_piece_failed** (piece\_index\_t);
	   virtual void **tick** ();
	   virtual bool **write_request** (peer\_request const&);
	};

.. raw:: html

	<a name="type()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Btype%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Btype%28%29%5D%22+could+be+improved">report issue</a>]</span>



type()
......

.. parsed-literal::
	
	virtual string_view **type** () const;
	

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


__ reference-Plugins.html#plugin

.. raw:: html

	<a name="add_handshake()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Badd_handshake%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Badd_handshake%28%29%5D%22+could+be+improved">report issue</a>]</span>



add_handshake()
...............

.. parsed-literal::
	
	virtual void **add_handshake** (entry&);
	

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



.. raw:: html

	<a name="on_disconnect()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bon_disconnect%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bon_disconnect%28%29%5D%22+could+be+improved">report issue</a>]</span>



on_disconnect()
...............

.. parsed-literal::
	
	virtual void **on_disconnect** (error\_code const&);
	

called when the peer is being disconnected.



.. raw:: html

	<a name="on_connected()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bon_connected%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bon_connected%28%29%5D%22+could+be+improved">report issue</a>]</span>



on_connected()
..............

.. parsed-literal::
	
	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.


__ reference-Plugins.html#plugin

.. raw:: html

	<a name="on_handshake()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bon_handshake%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bon_handshake%28%29%5D%22+could+be+improved">report issue</a>]</span>



on_handshake()
..............

.. parsed-literal::
	
	virtual bool **on_handshake** (span<char const>);
	

this is called when the initial bittorrent 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



.. raw:: html

	<a name="on_extension_handshake()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bon_extension_handshake%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bon_extension_handshake%28%29%5D%22+could+be+improved">report issue</a>]</span>



on_extension_handshake()
........................

.. parsed-literal::
	
	virtual bool **on_extension_handshake** (bdecode\_node 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


__ reference-Plugins.html#peer_plugin

.. raw:: html

	<a name="on_not_interested()"></a>
	<a name="on_request()"></a>
	<a name="on_have_all()"></a>
	<a name="on_have_none()"></a>
	<a name="on_have()"></a>
	<a name="on_unchoke()"></a>
	<a name="on_allowed_fast()"></a>
	<a name="on_dont_have()"></a>
	<a name="on_bitfield()"></a>
	<a name="on_interested()"></a>
	<a name="on_choke()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bon_not_interested%28%29+on_request%28%29+on_have_all%28%29+on_have_none%28%29+on_have%28%29+on_unchoke%28%29+on_allowed_fast%28%29+on_dont_have%28%29+on_bitfield%28%29+on_interested%28%29+on_choke%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bon_not_interested%28%29+on_request%28%29+on_have_all%28%29+on_have_none%28%29+on_have%28%29+on_unchoke%28%29+on_allowed_fast%28%29+on_dont_have%28%29+on_bitfield%28%29+on_interested%28%29+on_choke%28%29%5D%22+could+be+improved">report issue</a>]</span>



on_not_interested() on_request() on_have_all() on_have_none() on_have() on_unchoke() on_allowed_fast() on_dont_have() on_bitfield() on_interested() on_choke()
..............................................................................................................................................................

.. parsed-literal::
	
	virtual bool **on_bitfield** (bitfield const& */\*bitfield\*/*);
	virtual bool **on_allowed_fast** (piece\_index\_t);
	virtual bool **on_request** (peer\_request const&);
	virtual bool **on_choke** ();
	virtual bool **on_not_interested** ();
	virtual bool **on_have** (piece\_index\_t);
	virtual bool **on_interested** ();
	virtual bool **on_have_all** ();
	virtual bool **on_have_none** ();
	virtual bool **on_unchoke** ();
	virtual bool **on_dont_have** (piece\_index\_t);
	

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


__ reference-Plugins.html#plugin
__ reference-Plugins.html#plugin

.. raw:: html

	<a name="on_piece()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bon_piece%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bon_piece%28%29%5D%22+could+be+improved">report issue</a>]</span>



on_piece()
..........

.. parsed-literal::
	
	virtual bool **on_piece** (peer\_request const& */\*piece\*/*
	      , span<char const> */\*buf\*/*);
	

This function is called when the peer connection is receiving
a piece. ``buf`` points (non-owning pointer) to the data in an
internal immutable disk buffer. The length of the data is specified
in the ``length`` member of the ``piece`` parameter.
returns true to indicate that the piece is handled and the
rest of the logic should be ignored.



.. raw:: html

	<a name="sent_have()"></a>
	<a name="sent_not_interested()"></a>
	<a name="sent_piece()"></a>
	<a name="sent_unchoke()"></a>
	<a name="sent_interested()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bsent_have%28%29+sent_not_interested%28%29+sent_piece%28%29+sent_unchoke%28%29+sent_interested%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bsent_have%28%29+sent_not_interested%28%29+sent_piece%28%29+sent_unchoke%28%29+sent_interested%28%29%5D%22+could+be+improved">report issue</a>]</span>



sent_have() sent_not_interested() sent_piece() sent_unchoke() sent_interested()
...............................................................................

.. parsed-literal::
	
	virtual void **sent_interested** ();
	virtual void **sent_not_interested** ();
	virtual void **sent_unchoke** ();
	virtual void **sent_have** (piece\_index\_t);
	virtual void **sent_piece** (peer\_request const&);
	

called after a choke message has been sent to the peer



.. raw:: html

	<a name="sent_payload()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bsent_payload%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bsent_payload%28%29%5D%22+could+be+improved">report issue</a>]</span>



sent_payload()
..............

.. parsed-literal::
	
	virtual void **sent_payload** (int */\* bytes \*/*);
	

called after piece data has been sent to the peer
this can be used for stats book keeping



.. raw:: html

	<a name="can_disconnect()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bcan_disconnect%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bcan_disconnect%28%29%5D%22+could+be+improved">report issue</a>]</span>



can_disconnect()
................

.. parsed-literal::
	
	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.


__ reference-Plugins.html#plugin

.. raw:: html

	<a name="on_extended()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bon_extended%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bon_extended%28%29%5D%22+could+be+improved">report issue</a>]</span>



on_extended()
.............

.. parsed-literal::
	
	virtual bool **on_extended** (int */\*length\*/*, int */\*msg\*/*,
	      span<char const> */\*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.
thus function may be called more than once per incoming message, but
only the last of the calls will the ``body`` size equal the ``length``.
i.e. Every time another fragment of the message is received, this
function will be called, until finally the whole message has been
received. The purpose of this is to allow early disconnects for invalid
messages and for reporting progress of receiving large messages.


__ reference-Plugins.html#plugin
__ reference-Plugins.html#plugin

.. raw:: html

	<a name="on_unknown_message()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bon_unknown_message%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bon_unknown_message%28%29%5D%22+could+be+improved">report issue</a>]</span>



on_unknown_message()
....................

.. parsed-literal::
	
	virtual bool **on_unknown_message** (int */\*length\*/*, int */\*msg\*/*,
	      span<char const> */\*body\*/*);
	

this is not called for web seeds



.. raw:: html

	<a name="on_piece_failed()"></a>
	<a name="on_piece_pass()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bon_piece_failed%28%29+on_piece_pass%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bon_piece_failed%28%29+on_piece_pass%28%29%5D%22+could+be+improved">report issue</a>]</span>



on_piece_failed() on_piece_pass()
.................................

.. parsed-literal::
	
	virtual void **on_piece_pass** (piece\_index\_t);
	virtual void **on_piece_failed** (piece\_index\_t);
	

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



.. raw:: html

	<a name="tick()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Btick%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Btick%28%29%5D%22+could+be+improved">report issue</a>]</span>



tick()
......

.. parsed-literal::
	
	virtual void **tick** ();
	

called approximately once every second



.. raw:: html

	<a name="write_request()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:peer_plugin%3A%3A%5Bwrite_request%28%29%5D&labels=documentation&body=Documentation+under+heading+%22peer_plugin%3A%3A%5Bwrite_request%28%29%5D%22+could+be+improved">report issue</a>]</span>



write_request()
...............

.. parsed-literal::
	
	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.


__ reference-Plugins.html#plugin

.. raw:: html

	<a name="crypto_plugin"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+crypto_plugin&labels=documentation&body=Documentation+under+heading+%22class+crypto_plugin%22+could+be+improved">report issue</a>]</span>



crypto_plugin
-------------

Declared in "`libtorrent/extensions.hpp`__"


__ include/libtorrent/extensions.hpp





.. parsed-literal::
	

	struct crypto_plugin
	{
	   virtual void **set_outgoing_key** (span<char const> key) = 0;
	   virtual void **set_incoming_key** (span<char const> key) = 0;
	   **encrypt** (span<span<char>> */\*send\_vec\*/*) = 0;
	   virtual std::tuple<int, int, int> **decrypt** (span<span<char>> */\*receive\_vec\*/*) = 0;
	};

.. raw:: html

	<a name="decrypt()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:crypto_plugin%3A%3A%5Bdecrypt%28%29%5D&labels=documentation&body=Documentation+under+heading+%22crypto_plugin%3A%3A%5Bdecrypt%28%29%5D%22+could+be+improved">report issue</a>]</span>



decrypt()
.........

.. parsed-literal::
	
	virtual std::tuple<int, int, int> **decrypt** (span<span<char>> */\*receive\_vec\*/*) = 0;
	

decrypt the provided buffers.
returns is a tuple representing the values
(consume, produce, packet_size)

consume is set to the number of bytes which should be trimmed from the
head of the buffers, default is 0

produce is set to the number of bytes of payload which are now ready to
be sent to the upper layer. default is the number of bytes passed in receive_vec

packet_size is set to the minimum number of bytes which must be read to
advance the next step of decryption. default is 0



.. raw:: html

	<a name="create_ut_metadata_plugin()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:create_ut_metadata_plugin%28%29&labels=documentation&body=Documentation+under+heading+%22create_ut_metadata_plugin%28%29%22+could+be+improved">report issue</a>]</span>



create_ut_metadata_plugin()
---------------------------

Declared in "`libtorrent/extensions/ut_metadata.hpp`__"


__ include/libtorrent/extensions/ut_metadata.hpp

.. parsed-literal::
	
	std::shared_ptr<torrent_plugin> **create_ut_metadata_plugin** (torrent\_handle const&, client\_data\_t);
	

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()`__.


__ reference-Session.html#session
__ reference-Torrent_Handle.html#add_extension()

.. raw:: html

	<a name="create_smart_ban_plugin()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:create_smart_ban_plugin%28%29&labels=documentation&body=Documentation+under+heading+%22create_smart_ban_plugin%28%29%22+could+be+improved">report issue</a>]</span>



create_smart_ban_plugin()
-------------------------

Declared in "`libtorrent/extensions/smart_ban.hpp`__"


__ include/libtorrent/extensions/smart_ban.hpp

.. parsed-literal::
	
	std::shared_ptr<torrent_plugin> **create_smart_ban_plugin** (torrent\_handle const&, client\_data\_t);
	

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()`__.


__ reference-Torrent_Handle.html#add_extension()

.. raw:: html

	<a name="create_ut_pex_plugin()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:create_ut_pex_plugin%28%29&labels=documentation&body=Documentation+under+heading+%22create_ut_pex_plugin%28%29%22+could+be+improved">report issue</a>]</span>



create_ut_pex_plugin()
----------------------

Declared in "`libtorrent/extensions/ut_pex.hpp`__"


__ include/libtorrent/extensions/ut_pex.hpp

.. parsed-literal::
	
	std::shared_ptr<torrent_plugin> **create_ut_pex_plugin** (torrent\_handle const&, client\_data\_t);
	

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()`__.


__ reference-Session.html#session
__ reference-Torrent_Handle.html#add_extension()



.. _`BEP 3`: https://www.bittorrent.org/beps/bep_0003.html
.. _`BEP 17`: https://www.bittorrent.org/beps/bep_0017.html
.. _extensions: manual-ref.html#extensions
.. _`BEP 52`: https://www.bittorrent.org/beps/bep_0052.html
.. _`BEP 19`: https://www.bittorrent.org/beps/bep_0019.html
.. _`BEP 38`: https://www.bittorrent.org/beps/bep_0038.html
.. _`rate based choking`: manual-ref.html#rate-based-choking
.. _`BEP 42`: https://www.bittorrent.org/beps/bep_0042.html
