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

moved documentation form manual.rst to headers

This commit is contained in:
Arvid Norberg 2013-07-25 07:07:09 +00:00
parent b0f73427d7
commit 26fd67e808
3 changed files with 167 additions and 274 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

253
docs/manual.rst
View File

@ -93,259 +93,6 @@ For documentation on these types, please refer to the `asio documentation`_.
.. _`asio documentation`: http://asio.sourceforge.net/asio-0.3.8/doc/asio/reference.html
is_listening() listen_port() listen_on()
----------------------------------------
::
bool is_listening() const;
unsigned short listen_port() const;
enum {
listen_reuse_address = 1,
listen_no_system_port = 2
};
void listen_on(
std::pair<int, int> const& port_range
, error_code& ec
, char const* interface = 0
, int flags = 0);
``is_listening()`` will tell you whether or not the session has successfully
opened a listening port. If it hasn't, this function will return false, and
then you can use ``listen_on()`` to make another attempt.
``listen_port()`` returns the port we ended up listening on. Since you just pass
a port-range to the constructor and to ``listen_on()``, to know which port it
ended up using, you have to ask the session using this function.
``listen_on()`` will change the listen port and/or the listen interface. If the
session is already listening on a port, this socket will be closed and a new socket
will be opened with these new settings. The port range is the ports it will try
to listen on, if the first port fails, it will continue trying the next port within
the range and so on. The interface parameter can be left as 0, in that case the
os will decide which interface to listen on, otherwise it should be the ip-address
of the interface you want the listener socket bound to. ``listen_on()`` returns the
error code of the operation in ``ec``. If this indicates success, the session is
listening on a port within the specified range. If it fails, it will also
generate an appropriate alert (listen_failed_alert_).
If all ports in the specified range fails to be opened for listening, libtorrent will
try to use port 0 (which tells the operating system to pick a port that's free). If
that still fails you may see a listen_failed_alert_ with port 0 even if you didn't
ask to listen on it.
It is possible to prevent libtorrent from binding to port 0 by passing in the flag
``session::no_system_port`` in the ``flags`` argument.
The interface parameter can also be a hostname that will resolve to the device you
want to listen on. If you don't specify an interface, libtorrent may attempt to
listen on multiple interfaces (typically 0.0.0.0 and ::). This means that if your
IPv6 interface doesn't work, you may still see a listen_failed_alert_, even though
the IPv4 port succeeded.
The ``flags`` parameter can either be 0 or ``session::listen_reuse_address``, which
will set the reuse address socket option on the listen socket(s). By default, the
listen socket does not use reuse address. If you're running a service that needs
to run on a specific port no matter if it's in use, set this flag.
If you're also starting the DHT, it is a good idea to do that after you've called
``listen_on()``, since the default listen port for the DHT is the same as the tcp
listen socket. If you start the DHT first, it will assume the tcp port is free and
open the udp socket on that port, then later, when ``listen_on()`` is called, it
may turn out that the tcp port is in use. That results in the DHT and the bittorrent
socket listening on different ports. If the DHT is active when ``listen_on`` is
called, the udp port will be rebound to the new port, if it was configured to use
the same port as the tcp socket, and if the listen_on call failed to bind to the
same port that the udp uses.
If you want the OS to pick a port for you, pass in 0 as both first and second.
The reason why it's a good idea to run the DHT and the bittorrent socket on the same
port is because that is an assumption that may be used to increase performance. One
way to accelerate the connecting of peers on windows may be to first ping all peers
with a DHT ping packet, and connect to those that responds first. On windows one
can only connect to a few peers at a time because of a built in limitation (in XP
Service pack 2).
add_feed()
----------
::
feed_handle add_feed(feed_settings const& feed);
This adds an RSS feed to the session. The feed will be refreshed
regularly and optionally add all torrents from the feed, as they
appear. The feed is defined by the ``feed_settings`` object::
struct feed_settings
{
feed_settings();
std::string url;
bool auto_download;
bool auto_map_handles;
int default_ttl;
add_torrent_params add_args;
};
By default ``auto_download`` is true, which means all torrents in
the feed will be downloaded. Set this to false in order to manually
add torrents to the session. You may react to the rss_alert_ when
a feed has been updated to poll it for the new items in the feed
when adding torrents manually. When torrents are added automatically,
an add_torrent_alert_ is posted which includes the torrent handle
as well as the error code if it failed to be added. You may also call
``session::get_torrents()`` to get the handles to the new torrents.
Before adding the feed, you must set the ``url`` field to the
feed's url. It may point to an RSS or an atom feed.
``auto_map_handles`` defaults to true and determines whether or
not to set the ``handle`` field in the ``feed_item``, returned
as the feed status. If auto-download is enabled, this setting
is ignored. If auto-download is not set, setting this to false
will save one pass through all the feed items trying to find
corresponding torrents in the session.
The ``default_ttl`` is the default interval for refreshing a feed.
This may be overridden by the feed itself (by specifying the ``<ttl>``
tag) and defaults to 30 minutes. The field specifies the number of
minutes between refreshes.
If torrents are added automatically, you may want to set the
``add_args`` to appropriate values for download directory etc.
This object is used as a template for adding torrents from feeds,
but some torrent specific fields will be overridden by the
individual torrent being added. For more information on the
``add_torrent_params``, see `async_add_torrent() add_torrent()`_.
The returned feed_handle_ is a handle which is used to interact
with the feed, things like forcing a refresh or querying for
information about the items in the feed. For more information,
see feed_handle_.
remove_feed()
-------------
::
void remove_feed(feed_handle h);
Removes a feed from being watched by the session. When this
call returns, the feed handle is invalid and won't refer
to any feed.
get_feeds()
-----------
::
void get_feeds(std::vector<feed_handle>& f) const;
Returns a list of all RSS feeds that are being watched by the session.
add_extension()
---------------
::
void add_extension(boost::function<
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
``boost::shared_ptr<torrent_plugin>``. To write custom plugins, see
`libtorrent plugins`_. For the typical bittorrent client all of these
extensions should be added. The main plugins implemented in libtorrent are:
metadata extension
Allows peers to download the metadata (.torren files) from the swarm
directly. Makes it possible to join a swarm with just a tracker and
info-hash.
::
#include <libtorrent/extensions/metadata_transfer.hpp>
ses.add_extension(&libtorrent::create_metadata_plugin);
uTorrent metadata
Same as ``metadata extension`` but compatible with uTorrent.
::
#include <libtorrent/extensions/ut_metadata.hpp>
ses.add_extension(&libtorrent::create_ut_metadata_plugin);
uTorrent peer exchange
Exchanges peers between clients.
::
#include <libtorrent/extensions/ut_pex.hpp>
ses.add_extension(&libtorrent::create_ut_pex_plugin);
smart ban plugin
A plugin that, with a small overhead, can ban peers
that sends bad data with very high accuracy. Should
eliminate most problems on poisoned torrents.
::
#include <libtorrent/extensions/smart_ban.hpp>
ses.add_extension(&libtorrent::create_smart_ban_plugin);
.. _`libtorrent plugins`: libtorrent_plugins.html
set_settings() set_pe_settings()
--------------------------------
::
void set_settings(session_settings const& settings);
void set_pe_settings(pe_settings const& settings);
Sets the session settings and the packet encryption settings respectively.
See session_settings_ and pe_settings_ for more information on available
options.
set_proxy() proxy()
-------------------
::
void set_proxy(proxy_settings const& s);
proxy_setting proxy() const;
These functions sets and queries the proxy settings to be used for the session.
For more information on what settings are available for proxies, see
`proxy_settings`_.
set_i2p_proxy() i2p_proxy()
---------------------------
::
void set_i2p_proxy(proxy_settings const&);
proxy_settings const& i2p_proxy();
``set_i2p_proxy`` sets the i2p_ proxy, and tries to open a persistant
connection to it. The only used fields in the proxy settings structs
are ``hostname`` and ``port``.
``i2p_proxy`` returns the current i2p proxy in use.
.. _i2p: http://www.i2p2.de
entry
=====

29
include/libtorrent/rss.hpp
View File

@ -81,17 +81,36 @@ namespace libtorrent
std::string url;
// automatically add torrents to session from
// By default ``auto_download`` is true, which means all torrents in
// the feed will be downloaded. Set this to false in order to manually
// add torrents to the session. You may react to the rss_alert_ when
// a feed has been updated to poll it for the new items in the feed
// when adding torrents manually. When torrents are added automatically,
// an add_torrent_alert_ is posted which includes the torrent handle
// as well as the error code if it failed to be added. You may also call
// ``session::get_torrents()`` to get the handles to the new torrents.
bool auto_download;
// automatically find existing torrents and set
// the torrent_handle in the feed item
// ``auto_map_handles`` defaults to true and determines whether or
// not to set the ``handle`` field in the ``feed_item``, returned
// as the feed status. If auto-download is enabled, this setting
// is ignored. If auto-download is not set, setting this to false
// will save one pass through all the feed items trying to find
// corresponding torrents in the session.
bool auto_map_handles;
// in minutes
// The ``default_ttl`` is the default interval for refreshing a feed.
// This may be overridden by the feed itself (by specifying the ``<ttl>``
// tag) and defaults to 30 minutes. The field specifies the number of
// minutes between refreshes.
int default_ttl;
// used when adding torrents
// If torrents are added automatically, you may want to set the
// ``add_args`` to appropriate values for download directory etc.
// This object is used as a template for adding torrents from feeds,
// but some torrent specific fields will be overridden by the
// individual torrent being added. For more information on the
// ``add_torrent_params``, see `async_add_torrent() add_torrent()`_.
add_torrent_params add_args;
};

159
include/libtorrent/session.hpp
View File

@ -239,7 +239,7 @@ namespace libtorrent
// was called.
//
// Only torrents who has the state subscription flag set will be included. This flag
// is on by default. See ``add_torrent_params`` under `async_add_torrent() add_torrent()`_
// is on by default. See add_torrent_params_.
void post_torrent_updates();
io_service& get_io_service();
@ -359,8 +359,24 @@ namespace libtorrent
void get_cache_info(sha1_hash const& ih
, std::vector<cached_piece_info>& ret) const;
// This adds an RSS feed to the session. The feed will be refreshed
// regularly and optionally add all torrents from the feed, as they
// appear.
//
// Before adding the feed, you must set the ``url`` field to the
// feed's url. It may point to an RSS or an atom feed.
// The returned feed_handle_ is a handle which is used to interact
// with the feed, things like forcing a refresh or querying for
// information about the items in the feed. For more information,
// see feed_handle_.
feed_handle add_feed(feed_settings const& feed);
// Removes a feed from being watched by the session. When this
// call returns, the feed handle is invalid and won't refer
// to any feed.
void remove_feed(feed_handle h);
// Returns a list of all RSS feeds that are being watched by the session.
void get_feeds(std::vector<feed_handle>& f) const;
// starts/stops UPnP, NATPMP or LSD port mappers
@ -428,11 +444,50 @@ namespace libtorrent
void start_dht(entry const& startup_state) TORRENT_DEPRECATED;
#endif
#ifndef TORRENT_DISABLE_ENCRYPTION
void set_pe_settings(pe_settings const& settings);
pe_settings get_pe_settings() const;
#endif
// 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
// ``boost::shared_ptr<torrent_plugin>``. To write custom plugins, see
// `libtorrent plugins`_. For the typical bittorrent client all of these
// extensions should be added. The main plugins implemented in libtorrent are:
//
// metadata extension
// Allows peers to download the metadata (.torren files) from the swarm
// directly. Makes it possible to join a swarm with just a tracker and
// info-hash.
//
// ::
//
// #include <libtorrent/extensions/metadata_transfer.hpp>
// ses.add_extension(&libtorrent::create_metadata_plugin);
//
// uTorrent metadata
// Same as ``metadata extension`` but compatible with uTorrent.
//
// ::
//
// #include <libtorrent/extensions/ut_metadata.hpp>
// ses.add_extension(&libtorrent::create_ut_metadata_plugin);
//
// uTorrent peer exchange
// Exchanges peers between clients.
//
// ::
//
// #include <libtorrent/extensions/ut_pex.hpp>
// ses.add_extension(&libtorrent::create_ut_pex_plugin);
//
// smart ban plugin
// A plugin that, with a small overhead, can ban peers
// that sends bad data with very high accuracy. Should
// eliminate most problems on poisoned torrents.
//
// ::
//
// #include <libtorrent/extensions/smart_ban.hpp>
// ses.add_extension(&libtorrent::create_smart_ban_plugin);
//
//
// .. _`libtorrent plugins`: libtorrent_plugins.html
void add_extension(boost::function<boost::shared_ptr<torrent_plugin>(torrent*, void*)> ext);
void add_extension(boost::shared_ptr<plugin> ext);
@ -482,7 +537,70 @@ namespace libtorrent
void set_key(int key);
peer_id id() const;
bool is_listening() const;
// ``is_listening()`` will tell you whether or not the session has successfully
// opened a listening port. If it hasn't, this function will return false, and
// then you can use ``listen_on()`` to make another attempt.
//
// ``listen_port()`` returns the port we ended up listening on. Since you just pass
// a port-range to the constructor and to ``listen_on()``, to know which port it
// ended up using, you have to ask the session using this function.
//
// ``listen_on()`` will change the listen port and/or the listen interface. If the
// session is already listening on a port, this socket will be closed and a new socket
// will be opened with these new settings. The port range is the ports it will try
// to listen on, if the first port fails, it will continue trying the next port within
// the range and so on. The interface parameter can be left as 0, in that case the
// os will decide which interface to listen on, otherwise it should be the ip-address
// of the interface you want the listener socket bound to. ``listen_on()`` returns the
// error code of the operation in ``ec``. If this indicates success, the session is
// listening on a port within the specified range. If it fails, it will also
// generate an appropriate alert (listen_failed_alert_).
//
// If all ports in the specified range fails to be opened for listening, libtorrent will
// try to use port 0 (which tells the operating system to pick a port that's free). If
// that still fails you may see a listen_failed_alert_ with port 0 even if you didn't
// ask to listen on it.
//
// It is possible to prevent libtorrent from binding to port 0 by passing in the flag
// ``session::no_system_port`` in the ``flags`` argument.
//
// The interface parameter can also be a hostname that will resolve to the device you
// want to listen on. If you don't specify an interface, libtorrent may attempt to
// listen on multiple interfaces (typically 0.0.0.0 and ::). This means that if your
// IPv6 interface doesn't work, you may still see a listen_failed_alert_, even though
// the IPv4 port succeeded.
//
// The ``flags`` parameter can either be 0 or ``session::listen_reuse_address``, which
// will set the reuse address socket option on the listen socket(s). By default, the
// listen socket does not use reuse address. If you're running a service that needs
// to run on a specific port no matter if it's in use, set this flag.
//
// If you're also starting the DHT, it is a good idea to do that after you've called
// ``listen_on()``, since the default listen port for the DHT is the same as the tcp
// listen socket. If you start the DHT first, it will assume the tcp port is free and
// open the udp socket on that port, then later, when ``listen_on()`` is called, it
// may turn out that the tcp port is in use. That results in the DHT and the bittorrent
// socket listening on different ports. If the DHT is active when ``listen_on`` is
// called, the udp port will be rebound to the new port, if it was configured to use
// the same port as the tcp socket, and if the listen_on call failed to bind to the
// same port that the udp uses.
//
// If you want the OS to pick a port for you, pass in 0 as both first and second.
//
// The reason why it's a good idea to run the DHT and the bittorrent socket on the same
// port is because that is an assumption that may be used to increase performance. One
// way to accelerate the connecting of peers on windows may be to first ping all peers
// with a DHT ping packet, and connect to those that responds first. On windows one
// can only connect to a few peers at a time because of a built in limitation (in XP
// Service pack 2).
void listen_on(
std::pair<int, int> const& port_range
, error_code& ec
, const char* net_interface = 0
, int flags = 0);
unsigned short listen_port() const;
// if the listen port failed in some way
// you can retry to listen on another port-
@ -513,15 +631,6 @@ namespace libtorrent
, int flags = 0) TORRENT_DEPRECATED;
#endif
void listen_on(
std::pair<int, int> const& port_range
, error_code& ec
, const char* net_interface = 0
, int flags = 0);
// returns the port we ended up listening on
unsigned short listen_port() const;
enum options_t
{
none = 0,
@ -543,9 +652,20 @@ namespace libtorrent
// is posted.
void remove_torrent(const torrent_handle& h, int options = none);
// Sets the session settings and the packet encryption settings respectively.
// See session_settings_ and pe_settings_ for more information on available
// options.
void set_settings(session_settings const& s);
session_settings settings() const;
#ifndef TORRENT_DISABLE_ENCRYPTION
void set_pe_settings(pe_settings const& settings);
pe_settings get_pe_settings() const;
#endif
// These functions sets and queries the proxy settings to be used for the session.
//
// For more information on what settings are available for proxies, see
// `proxy_settings`_.
void set_proxy(proxy_settings const& s);
proxy_settings proxy() const;
@ -586,6 +706,13 @@ namespace libtorrent
#endif // TORRENT_NO_DEPRECATE
#if TORRENT_USE_I2P
// ``set_i2p_proxy`` sets the i2p_ proxy, and tries to open a persistant
// connection to it. The only used fields in the proxy settings structs
// are ``hostname`` and ``port``.
//
// ``i2p_proxy`` returns the current i2p proxy in use.
//
// .. _i2p: http://www.i2p2.de
void set_i2p_proxy(proxy_settings const& s);
proxy_settings i2p_proxy() const;
#endif