updated plugin documentation

docs/libtorrent_plugins.html

@@ -34,9 +34,10 @@
 <li><a class="reference" href="#on-piece-pass-on-piece-fail" id="id6" name="id6">on_piece_pass() on_piece_fail()</a></li>
 <li><a class="reference" href="#tick" id="id7" name="id7">tick()</a></li>
 <li><a class="reference" href="#on-pause-on-resume" id="id8" name="id8">on_pause() on_resume()</a></li>
+<li><a class="reference" href="#on-files-checked" id="id9" name="id9">on_files_checked()</a></li>
 </ul>
 </li>
-<li><a class="reference" href="#peer-plugin" id="id9" name="id9">peer_plugin</a></li>
+<li><a class="reference" href="#peer-plugin" id="id10" name="id10">peer_plugin</a></li>
 </ul>
 </div>
 <p>libtorrent has a plugin interface for implementing extensions to the protocol.
@@ -74,6 +75,22 @@ implement. These are called <tt class="docutils literal"><span class="pre">torre
 both found in the <tt class="docutils literal"><span class="pre">&lt;libtorrent/extensions.hpp&gt;</span></tt> header.</p>
 <p>These plugins are instantiated for each torrent and possibly each peer,
 respectively.</p>
+<p>This is done by passing in a function or function object to
+<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&lt;torrent_plugin&gt; (*)(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&lt;torrent_plugin&gt;</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
+<tt class="docutils literal"><span class="pre">torrent_plugin</span></tt>), it will be associated with this torrent and callbacks
+will be made on torrent events.</p>
 </div>
 <div class="section">
 <h1><a id="torrent-plugin" name="torrent-plugin">torrent_plugin</a></h1>
@@ -91,6 +108,8 @@ struct torrent_plugin
 
         virtual bool on_pause();
         virtual bool on_resume();
+
+        virtual void on_files_checked();
 };
 </pre>
 <p>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.</p>
 </div>
+<div class="section">
+<h2><a id="on-files-checked" name="on-files-checked">on_files_checked()</a></h2>
+<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>
 </div>
 <div class="section">
 <h1><a id="peer-plugin" name="peer-plugin">peer_plugin</a></h1>
@@ -168,9 +197,14 @@ struct peer_plugin
         virtual bool on_not_interested();
         virtual bool on_have(int index);
         virtual bool on_bitfield(std::vector&lt;bool&gt; const&amp; 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&amp; req);
         virtual bool on_piece(peer_request const&amp; piece, char const* data);
         virtual bool on_cancel(peer_request const&amp; req);
+        virtual bool on_reject(peer_request const&amp; 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

docs/libtorrent_plugins.rst

@@ -50,6 +50,25 @@ 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
 ==============
@@ -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<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

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
+                , storage_mode_t storage_mode = storage_mode_sparse
-                , bool paused = false);
+                , 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
+                , storage_mode_t storage_mode = storage_mode_sparse
-                , bool paused = true);
+                , 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);
 </pre>
 </blockquote>
 <p>You add torrents through the <tt class="docutils literal"><span class="pre">add_torrent()</span></tt> function where you give an
@@ -456,6 +462,8 @@ content on disk for instance. For more information about the <tt class="docutils
 that needs to be implemented for a custom storage, see <a class="reference" href="#storage-interface">storage_interface</a>.</p>
 <p>The <a class="reference" href="#torrent-handle">torrent_handle</a> returned by <tt class="docutils literal"><span class="pre">add_torrent()</span></tt> can be used to retrieve information
 about the torrent's progress, its peers etc. It is also used to abort a torrent.</p>
+<p>The <tt class="docutils literal"><span class="pre">userdata</span></tt> parameter is optional and will be passed on to the extension
+constructor functions, if any (see <a class="reference" href="#add-extension">add_extension()</a>).</p>
 <p>The second overload that takes a tracker url and an info-hash instead of metadata
 (<tt class="docutils literal"><span class="pre">torrent_info</span></tt>) 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 <tt class="docutils literal"><span class="pre">pop_alert()</s
 <blockquote>
 <pre class="literal-block">
 void add_extension(boost::function&lt;
-        boost::shared_ptr&lt;torrent_plugin&gt;(torrent*)&gt; ext);
+        boost::shared_ptr&lt;torrent_plugin&gt;(torrent*, void*)&gt; ext);
 </pre>
 </blockquote>
 <p>This function adds an extension to this session. The argument is a function

docs/manual.rst

@@ -79,8 +79,10 @@ The ``session`` class has the following synopsis::
 			boost::intrusive_ptr<torrent_info> const& ti
 			, boost::filesystem::path const& save_path
 			, entry const& resume_data = entry()
-			, bool compact_mode = true
+			, storage_mode_t storage_mode = storage_mode_sparse
-			, bool paused = false);
+			, 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
+			, storage_mode_t storage_mode = storage_mode_sparse
-			, bool paused = true);
+			, 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_plugin>(torrent*)> ext);
+			boost::shared_ptr<torrent_plugin>(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