From 72e6069dcf967501c08e3dda6ce1357f26879738 Mon Sep 17 00:00:00 2001 From: Arvid Norberg Date: Wed, 25 Apr 2007 23:38:25 +0000 Subject: [PATCH] added proxy documentation --- docs/manual.rst | 136 +++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 110 insertions(+), 26 deletions(-) diff --git a/docs/manual.rst b/docs/manual.rst index c761d4cf7..991387192 100644 --- a/docs/manual.rst +++ b/docs/manual.rst @@ -103,6 +103,14 @@ The ``session`` class has the following synopsis:: void set_max_connections(int limit); void set_max_half_open_connections(int limit); + void set_peer_proxy(proxy_settings const& s); + void set_web_seed_proxy(proxy_settings const& s); + void set_tracker_proxy(proxy_settings const& s); + + proxy_settings const& peer_proxy() const; + proxy_settings const& web_seed_proxy() const; + proxy_settings const& tracker_proxy() const; + int num_uploads() const; int num_connections() const; @@ -504,6 +512,37 @@ e.g. .. _`libtorrent plugins`: libtorrent_plugins.html +set_peer_proxy() set_web_seed_proxy() set_tracker_proxy() set_dht_proxy() +------------------------------------------------------------------------- + + :: + + void set_peer_proxy(proxy_settings const& s); + void set_web_seed_proxy(proxy_settings const& s); + void set_tracker_proxy(proxy_settings const& s); + void set_dht_proxy(proxy_settings const& s); + +The ``set_dht_proxy`` is not available when DHT is disabled. These functions +sets the proxy settings for different kinds of connections, bittorrent peers, +web seeds, trackers and the DHT traffic. + +``set_peer_proxy`` affects regular bittorrent peers. ``set_web_seed_proxy`` +affects only web seeds. see `HTTP seeding`_. + + +peer_proxy() web_seed_proxy() tracker_proxy() dht_proxy() +--------------------------------------------------------- + + :: + + proxy_settings const& peer_proxy() const; + proxy_settings const& web_seed_proxy() const; + proxy_settings const& tracker_proxy() const; + proxy_settings const& dht_proxy() const; + +The ``dht_proxy`` is not available when DHT is disabled. + + start_dht() stop_dht() set_dht_settings() dht_state() ----------------------------------------------------- @@ -1279,17 +1318,17 @@ first algorithm is effectively active for all pieces. You may however change the priority of individual pieces. There are 8 different priority levels: -0. piece is not downloaded at all -1. normal priority. Download order is dependent on availability -2. higher than normal priority. Pieces are preferred over pieces with - the same availability, but not over pieces with lower availability -3. pieces are as likely to be picked as partial pieces. -4. pieces are preferred over partial pieces, but not over pieces with - lower availability -5. *currently the same as 4* -6. piece is as likely to be picked as any piece with availability 1 -7. maximum priority, availability is disregarded, the piece is preferred - over any other piece with lower priority + 0. piece is not downloaded at all + 1. normal priority. Download order is dependent on availability + 2. higher than normal priority. Pieces are preferred over pieces with + the same availability, but not over pieces with lower availability + 3. pieces are as likely to be picked as partial pieces. + 4. pieces are preferred over partial pieces, but not over pieces with + lower availability + 5. *currently the same as 4* + 6. piece is as likely to be picked as any piece with availability 1 + 7. maximum priority, availability is disregarded, the piece is preferred + over any other piece with lower priority The exact definitions of these priorities are implementation details, and subject to change. The interface guarantees that higher number means higher @@ -2100,10 +2139,6 @@ that will be sent to the tracker. The user-agent is a good way to identify your struct session_settings { session_settings(); - std::string proxy_ip; - int proxy_port; - std::string proxy_login; - std::string proxy_password; std::string user_agent; int tracker_completion_timeout; int tracker_receive_timeout; @@ -2124,17 +2159,6 @@ that will be sent to the tracker. The user-agent is a good way to identify your bool use_dht_as_fallback; }; -``proxy_ip`` may be a hostname or ip to a http proxy to use. If this is -an empty string, no http proxy will be used. - -``proxy_port`` is the port on which the http proxy listens. If ``proxy_ip`` -is empty, this will be ignored. - -``proxy_login`` should be the login username for the http proxy, if this -empty, the http proxy will be tried to be used without authentication. - -``proxy_password`` the password string for the http proxy. - ``user_agent`` this is the client identification to the tracker. The recommended format of this string is: "ClientName/ClientVersion libtorrent/libtorrentVersion". @@ -2227,6 +2251,66 @@ the peer fails, the time is multiplied by fail counter. all trackers in its tracker list has failed. Either by an explicit error message or a time out. +proxy_settings +============== + +The ``proxy_settings`` structs contains the information needed to +direct certain traffic to a proxy. + + :: + + struct TORRENT_EXPORT proxy_settings + { + proxy_settings(); + + std::string hostname; + int port; + + std::string username; + std::string password; + + enum proxy_type + { + none, + socks5, + socks5_pw, + http, + http_pw + }; + + proxy_type type; + }; + +``hostname`` is the name or IP of the proxy server. ``port`` is the +port number the proxy listens to. If required, ``username`` and ``password`` +can be set to authenticate with the proxy. + +The ``type`` tells libtorrent what kind of proxy server it is. The following +options are available: + + * ``none`` - This is the default, no proxy server is used, all other fields + are ignored. + + * ``socks5`` - The server is assumed to be a SOCKS5 server (`RFC 1928`_) that + does not require any authentication. The username and password are ignored. + + * ``socks5_pw`` - The server is assumed to be a SOCKS5 server that supports + plain text username and password authentication (`RFC 1929`_). The username + and password specified may be sent to the proxy if it requires. + + * ``http`` - The server is assumed to be an HTTP proxy. If the transport used + for the connection is non-HTTP, the server is assumed to support the + CONNECT method. i.e. for web seeds and HTTP trackers, a plain proxy will + suffice. The proxy is assumed to not require authorization. The username + and password will not be used. + + * ``http_pw`` - The server is assumed to be an HTTP proxy that requires + user authorization. The username and password will be sent to the proxy. + + +_`RFC 1928`: http://www.faqs.org/rfcs/rfc1928.html +_`RFC 1929`: http://www.faqs.org/rfcs/rfc1929.html + ip_filter =========