From e931ee54f6b6c2671c98d3957c83e0fd208d9a89 Mon Sep 17 00:00:00 2001 From: Arvid Norberg Date: Sat, 24 Nov 2007 21:13:19 +0000 Subject: [PATCH] updated plugin documentation --- docs/libtorrent_plugins.html | 36 ++++++++++++++++++++++++++++++++- docs/libtorrent_plugins.rst | 39 ++++++++++++++++++++++++++++++++++++ docs/manual.html | 22 +++++++++++++------- docs/manual.rst | 23 ++++++++++++++------- 4 files changed, 105 insertions(+), 15 deletions(-) diff --git a/docs/libtorrent_plugins.html b/docs/libtorrent_plugins.html index 0209a72a6..90a367ecc 100644 --- a/docs/libtorrent_plugins.html +++ b/docs/libtorrent_plugins.html @@ -34,9 +34,10 @@
  • on_piece_pass() on_piece_fail()
  • tick()
  • on_pause() on_resume()
    • +
  • on_files_checked()
    • -
  • peer_plugin
    • +
  • peer_plugin

    • libtorrent has a plugin interface for implementing extensions to the protocol. @@ -74,6 +75,22 @@ implement. These are called torre both found in the <libtorrent/extensions.hpp> header.

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

    +

    This is done by passing in a 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:

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

    The first argument is the internal torrent object, the second argument +is the userdata passed to session::add_torrent() or +torrent_handle::add_extension().

    +

    The function should return a boost::shared_ptr<torrent_plugin> 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 +torrent_plugin), it will be associated with this torrent and callbacks +will be made on torrent events.

    torrent_plugin

    @@ -91,6 +108,8 @@ struct torrent_plugin virtual bool on_pause(); virtual bool on_resume(); + + virtual void on_files_checked(); };

    This is the base class for a torrent_plugin. Your derived class is (if added @@ -150,6 +169,16 @@ 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()

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

    +

    peer_plugin

    @@ -168,9 +197,14 @@ struct peer_plugin virtual bool on_not_interested(); virtual bool on_have(int index); virtual bool on_bitfield(std::vector<bool> const& bitfield); + virtual bool on_have_all(); + virtual bool on_have_none(); + virtual bool on_allowed_fast(int index); virtual bool on_request(peer_request const& req); virtual bool on_piece(peer_request const& piece, char const* data); virtual bool on_cancel(peer_request const& req); + virtual bool on_reject(peer_request const& req); + virtual bool on_suggest(int index); virtual bool on_extended(int length , int msg, buffer::const_interval body); virtual bool on_unknown_message(int length, int msg diff --git a/docs/libtorrent_plugins.rst b/docs/libtorrent_plugins.rst index d6dc8360d..839f3917b 100644 --- a/docs/libtorrent_plugins.rst +++ b/docs/libtorrent_plugins.rst @@ -50,6 +50,25 @@ both found in the ```` header. These plugins are instantiated for each torrent and possibly each peer, respectively. +This is done by passing in a 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:: + + boost::shared_ptr (*)(torrent*, void*); + +The first argument is the internal torrent object, the second argument +is the userdata passed to ``session::add_torrent()`` or +``torrent_handle::add_extension()``. + +The function should return a ``boost::shared_ptr`` 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 +``torrent_plugin``), it will be associated with this torrent and callbacks +will be made on torrent events. + torrent_plugin ============== @@ -68,6 +87,8 @@ The synopsis for ``torrent_plugin`` follows:: virtual bool on_pause(); virtual bool on_resume(); + + virtual void on_files_checked(); }; This is the base class for a torrent_plugin. Your derived class is (if added @@ -142,6 +163,19 @@ 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() +------------------ + +:: + + 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. + peer_plugin =========== @@ -162,9 +196,14 @@ peer_plugin virtual bool on_not_interested(); virtual bool on_have(int index); virtual bool on_bitfield(std::vector const& bitfield); + virtual bool on_have_all(); + virtual bool on_have_none(); + virtual bool on_allowed_fast(int index); virtual bool on_request(peer_request const& req); virtual bool on_piece(peer_request const& piece, char const* data); virtual bool on_cancel(peer_request const& req); + virtual bool on_reject(peer_request const& req); + virtual bool on_suggest(int index); virtual bool on_extended(int length , int msg, buffer::const_interval body); virtual bool on_unknown_message(int length, int msg diff --git a/docs/manual.html b/docs/manual.html index f861a8787..9040e2349 100644 --- a/docs/manual.html +++ b/docs/manual.html @@ -265,8 +265,10 @@ class session: public boost::noncopyable boost::intrusive_ptr<torrent_info> const& ti , boost::filesystem::path const& save_path , entry const& resume_data = entry() - , bool compact_mode = true - , bool paused = false); + , storage_mode_t storage_mode = storage_mode_sparse + , bool paused = false + , storage_constructor_type sc = default_storage_constructor + , void* userdata = 0); torrent_handle add_torrent( char const* tracker_url @@ -274,8 +276,10 @@ class session: public boost::noncopyable , char const* name , boost::filesystem::path const& save_path , entry const& resume_data = entry() - , bool compact_mode = true - , bool paused = true); + , storage_mode_t storage_mode = storage_mode_sparse + , bool paused = false + , storage_constructor_type sc = default_storage_constructor + , void* userdata = 0); session_proxy abort(); @@ -406,7 +410,8 @@ torrent_handle add_torrent( , entry const& resume_data = entry() , storage_mode_t storage_mode = storage_mode_sparse , bool paused = false - , storage_constructor_type sc = default_storage_constructor); + , storage_constructor_type sc = default_storage_constructor + , void* userdata = 0); torrent_handle add_torrent( char const* tracker_url @@ -416,7 +421,8 @@ torrent_handle add_torrent( , entry const& resume_data = entry() , storage_mode_t storage_mode = storage_mode_sparse , bool paused = false - , storage_constructor_type sc = default_storage_constructor); + , storage_constructor_type sc = default_storage_constructor + , void* userdata = 0);

    You add torrents through the add_torrent() function where you give an @@ -456,6 +462,8 @@ content on disk for instance. For more information about the storage_interface.

    The torrent_handle returned by add_torrent() can be used to retrieve information about the torrent's progress, its peers etc. It is also used to abort a torrent.

    +

    The userdata parameter is optional and will be passed on to the extension +constructor functions, if any (see add_extension()).

    The second overload that takes a tracker url and an info-hash instead of metadata (torrent_info) can be used with torrents where (at least some) peers support the metadata extension. For the overload to be available, libtorrent must be built @@ -692,7 +700,7 @@ receive it through pop_alert() 

     void add_extension(boost::function<
-        boost::shared_ptr<torrent_plugin>(torrent*)> ext);
+        boost::shared_ptr<torrent_plugin>(torrent*, void*)> ext);

    This function adds an extension to this session. The argument is a function diff --git a/docs/manual.rst b/docs/manual.rst index 32b0f98a6..73e1dadc4 100644 --- a/docs/manual.rst +++ b/docs/manual.rst @@ -79,8 +79,10 @@ The ``session`` class has the following synopsis:: boost::intrusive_ptr const& ti , boost::filesystem::path const& save_path , entry const& resume_data = entry() - , bool compact_mode = true - , bool paused = false); + , storage_mode_t storage_mode = storage_mode_sparse + , bool paused = false + , storage_constructor_type sc = default_storage_constructor + , void* userdata = 0); torrent_handle add_torrent( char const* tracker_url @@ -88,8 +90,10 @@ The ``session`` class has the following synopsis:: , char const* name , boost::filesystem::path const& save_path , entry const& resume_data = entry() - , bool compact_mode = true - , bool paused = true); + , storage_mode_t storage_mode = storage_mode_sparse + , bool paused = false + , storage_constructor_type sc = default_storage_constructor + , void* userdata = 0); session_proxy abort(); @@ -225,7 +229,8 @@ add_torrent() , entry const& resume_data = entry() , storage_mode_t storage_mode = storage_mode_sparse , bool paused = false - , storage_constructor_type sc = default_storage_constructor); + , storage_constructor_type sc = default_storage_constructor + , void* userdata = 0); torrent_handle add_torrent( char const* tracker_url @@ -235,7 +240,8 @@ add_torrent() , entry const& resume_data = entry() , storage_mode_t storage_mode = storage_mode_sparse , bool paused = false - , storage_constructor_type sc = default_storage_constructor); + , storage_constructor_type sc = default_storage_constructor + , void* userdata = 0); You add torrents through the ``add_torrent()`` function where you give an object representing the information found in the torrent file and the path where you @@ -283,6 +289,9 @@ that needs to be implemented for a custom storage, see `storage_interface`_. The torrent_handle_ returned by ``add_torrent()`` can be used to retrieve information about the torrent's progress, its peers etc. It is also used to abort a torrent. +The ``userdata`` parameter is optional and will be passed on to the extension +constructor functions, if any (see `add_extension()`_). + The second overload that takes a tracker url and an info-hash instead of metadata (``torrent_info``) can be used with torrents where (at least some) peers support the metadata extension. For the overload to be available, libtorrent must be built @@ -544,7 +553,7 @@ add_extension() :: void add_extension(boost::function< - boost::shared_ptr(torrent*)> ext); + boost::shared_ptr(torrent*, void*)> ext); This function adds an extension to this session. The argument is a function object that is called with a ``torrent*`` and which should return a