premiere
/
premiere-libtorrent
2
2
Fork 1
Code Issues Pull Requests Releases Wiki Activity

updated plugin documentation

This commit is contained in:
Arvid Norberg 2007-11-24 21:13:19 +00:00
parent 463eb47011
commit e931ee54f6
4 changed files with 105 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
docs/libtorrent_plugins.html
View File

@ -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

39
docs/libtorrent_plugins.rst
View File

@ -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

22
docs/manual.html
View File

@ -265,8 +265,10 @@ class session: public boost::noncopyable
boost::intrusive_ptr&lt;torrent_info&gt; const&amp; ti
, boost::filesystem::path const&amp; save_path
, entry const&amp; 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&amp; save_path
, entry const&amp; 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&amp; 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&amp; 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

23
docs/manual.rst
View File

@ -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
, 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_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