diff --git a/docs/manual.rst b/docs/manual.rst index 31c7ce585..cd1c9a14f 100644 --- a/docs/manual.rst +++ b/docs/manual.rst @@ -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 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 ```` -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& 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*, 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``. 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 - ses.add_extension(&libtorrent::create_metadata_plugin); - -uTorrent metadata - Same as ``metadata extension`` but compatible with uTorrent. - -:: - - #include - ses.add_extension(&libtorrent::create_ut_metadata_plugin); - -uTorrent peer exchange - Exchanges peers between clients. - -:: - - #include - 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 - 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 ===== diff --git a/include/libtorrent/rss.hpp b/include/libtorrent/rss.hpp index ea375eca3..d7670470f 100644 --- a/include/libtorrent/rss.hpp +++ b/include/libtorrent/rss.hpp @@ -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 ```` + // 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; }; diff --git a/include/libtorrent/session.hpp b/include/libtorrent/session.hpp index 98c2767de..2cf18560f 100644 --- a/include/libtorrent/session.hpp +++ b/include/libtorrent/session.hpp @@ -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& 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& 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``. 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 + // ses.add_extension(&libtorrent::create_metadata_plugin); + // + // uTorrent metadata + // Same as ``metadata extension`` but compatible with uTorrent. + // + // :: + // + // #include + // ses.add_extension(&libtorrent::create_ut_metadata_plugin); + // + // uTorrent peer exchange + // Exchanges peers between clients. + // + // :: + // + // #include + // 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 + // ses.add_extension(&libtorrent::create_smart_ban_plugin); + // + // + // .. _`libtorrent plugins`: libtorrent_plugins.html void add_extension(boost::function(torrent*, void*)> ext); void add_extension(boost::shared_ptr 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 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 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