diff --git a/docs/building.html b/docs/building.html index 6972da71a..483396657 100644 --- a/docs/building.html +++ b/docs/building.html @@ -657,10 +657,6 @@ when link=shared is set). If this is defined, the support for trackerless torrents will be disabled. -TORRENT_DHT_VERBOSE_LOGGING -This will enable verbose logging of the DHT -protocol traffic. - TORRENT_DISABLE_ENCRYPTION This will disable any encryption support and the dependencies of a crypto library. diff --git a/docs/index.html b/docs/index.html index 5c9ad46d2..2e17a18f8 100644 --- a/docs/index.html +++ b/docs/index.html @@ -46,7 +46,7 @@

@@ -121,16 +121,15 @@ to the author of the library by including the libtorrent license in your software or documentation.

It is however greatly appreciated if additional features are contributed back to the open source project. Patches can be emailed to the mailing -list or posted to the bug tracker.

+list or posted to the bug tracker.

Acknowledgements

-

Written by Arvid Norberg. Copyright © 2003-2014

+

Written by Arvid Norberg. Copyright © 2003-2015

Contributions by Magnus Jonsson, Daniel Wallin and Cory Nelson

Thanks to Reimond Retz for bugfixes, suggestions and testing

Thanks to Umeå University for providing development and test hardware.

-

Project is hosted by sourceforge.

-

sf_logo

+

Project is hosted by github.

diff --git a/docs/reference-Session.html b/docs/reference-Session.html deleted file mode 100644 index ad6adc542..000000000 --- a/docs/reference-Session.html +++ /dev/null @@ -1,1482 +0,0 @@ - - - - - - -Session - - - - - - - -
-
- - - - -
-

Session

- --- - - - - - -
Author:Arvid Norberg, arvid@libtorrent.org
Version:1.1.0
- -
-

add_torrent_params

-

Declared in "libtorrent/add_torrent_params.hpp"

-

The add_torrent_params is a parameter pack for adding torrents to a -session. The key fields when adding a torrent are:

-
    -
  • ti - when you have a .torrent file
  • -
  • url - when you have a magnet link or http URL to the .torrent file
  • -
  • info_hash - when all you have is an info-hash (this is similar to a -magnet link)
  • -
-

one of those fields need to be set. Another mandatory field is -save_path. The add_torrent_params object is passed into one of the -session::add_torrent() overloads or session::async_add_torrent().

-

If you only specify the info-hash, the torrent file will be downloaded -from peers, which requires them to support the metadata extension. For -the metadata extension to work, libtorrent must be built with extensions -enabled (TORRENT_DISABLE_EXTENSIONS must not be defined). It also -takes an optional name argument. This may be left empty in case no -name should be assigned to the torrent. In case it's not, the name is -used for the torrent as long as it doesn't have metadata. See -torrent_handle::name.

-
-struct add_torrent_params
-{
-   add_torrent_params (storage_constructor_type sc = default_storage_constructor);
-
-   enum flags_t
-   {
-      flag_seed_mode,
-      flag_override_resume_data,
-      flag_upload_mode,
-      flag_share_mode,
-      flag_apply_ip_filter,
-      flag_paused,
-      flag_auto_managed,
-      flag_duplicate_is_error,
-      flag_merge_resume_trackers,
-      flag_update_subscribe,
-      flag_super_seeding,
-      flag_sequential_download,
-      flag_use_resume_save_path,
-      flag_pinned,
-      | flag_auto_managed | flag_paused | flag_apply_ip_filter,
-   };
-
-   int version;
-   boost::shared_ptr<torrent_info> ti;
-   std::vector<std::string> trackers;
-   std::vector<std::string> url_seeds;
-   std::vector<std::pair<std::string, int> > dht_nodes;
-   std::string name;
-   std::string save_path;
-   std::vector<char> resume_data;
-   storage_mode_t storage_mode;
-   storage_constructor_type storage;
-   void* userdata;
-   std::vector<boost::uint8_t> file_priorities;
-   std::string trackerid;
-   std::string url;
-   std::string uuid;
-   std::string source_feed_url;
-   boost::uint64_t flags;
-   sha1_hash info_hash;
-   int max_uploads;
-   int max_connections;
-   int upload_limit;
-   int download_limit;
-};
-
-
-

add_torrent_params()

-
-add_torrent_params (storage_constructor_type sc = default_storage_constructor);
-
-

The constructor can be used to initialize the storage constructor, -which determines the storage mechanism for the downloaded or seeding -data for the torrent. For more information, see the storage field.

-
-
-

enum flags_t

-

Declared in "libtorrent/add_torrent_params.hpp"

- ----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
namevaluedescription
flag_seed_mode1

If flag_seed_mode is set, libtorrent will assume that all files -are present for this torrent and that they all match the hashes in -the torrent file. Each time a peer requests to download a block, -the piece is verified against the hash, unless it has been verified -already. If a hash fails, the torrent will automatically leave the -seed mode and recheck all the files. The use case for this mode is -if a torrent is created and seeded, or if the user already know -that the files are complete, this is a way to avoid the initial -file checks, and significantly reduce the startup time.

-

Setting flag_seed_mode on a torrent without metadata (a -.torrent file) is a no-op and will be ignored.

-

If resume data is passed in with this torrent, the seed mode saved -in there will override the seed mode you set here.

-
flag_override_resume_data2If flag_override_resume_data is set, flags set for this torrent -in this add_torrent_params object will take precedence over -whatever states are saved in the resume data. For instance, the -paused, auto_managed, sequential_download, seed_mode, -super_seeding, max_uploads, max_connections, -upload_limit and download_limit are all affected by this -flag. The intention of this flag is to have any field in -add_torrent_params configuring the torrent override the corresponding -configuration from the resume file, with the one exception of save -resume data, which has its own flag (for historic reasons).
flag_upload_mode4

If flag_upload_mode is set, the torrent will be initialized in -upload-mode, which means it will not make any piece requests. This -state is typically entered on disk I/O errors, and if the torrent -is also auto managed, it will be taken out of this state -periodically. This mode can be used to avoid race conditions when -adjusting priorities of pieces before allowing the torrent to start -downloading.

-

If the torrent is auto-managed (flag_auto_managed), the torrent -will eventually be taken out of upload-mode, regardless of how it -got there. If it's important to manually control when the torrent -leaves upload mode, don't make it auto managed.

-
flag_share_mode8

determines if the torrent should be added in share mode or not. -Share mode indicates that we are not interested in downloading the -torrent, but merley want to improve our share ratio (i.e. increase -it). A torrent started in share mode will do its best to never -download more than it uploads to the swarm. If the swarm does not -have enough demand for upload capacity, the torrent will not -download anything. This mode is intended to be safe to add any -number of torrents to, without manual screening, without the risk -of downloading more than is uploaded.

-

A torrent in share mode sets the priority to all pieces to 0, -except for the pieces that are downloaded, when pieces are decided -to be downloaded. This affects the progress bar, which might be set -to "100% finished" most of the time. Do not change file or piece -priorities for torrents in share mode, it will make it not work.

-

The share mode has one setting, the share ratio target, see -session_settings::share_mode_target for more info.

-
flag_apply_ip_filter16determines if the IP filter should apply to this torrent or not. By -default all torrents are subject to filtering by the IP filter -(i.e. this flag is set by default). This is useful if certain -torrents needs to be excempt for some reason, being an auto-update -torrent for instance.
flag_paused32specifies whether or not the torrent is to be started in a paused -state. I.e. it won't connect to the tracker or any of the peers -until it's resumed. This is typically a good way of avoiding race -conditions when setting configuration options on torrents before -starting them.
flag_auto_managed64

If the torrent is auto-managed (flag_auto_managed), the torrent -may be resumed at any point, regardless of how it paused. If it's -important to manually control when the torrent is paused and -resumed, don't make it auto managed.

-

If flag_auto_managed is set, the torrent will be queued, -started and seeded automatically by libtorrent. When this is set, -the torrent should also be started as paused. The default queue -order is the order the torrents were added. They are all downloaded -in that order. For more details, see queuing.

-

If you pass in resume data, the auto_managed state of the torrent -when the resume data was saved will override the auto_managed state -you pass in here. You can override this by setting -override_resume_data.

-
flag_duplicate_is_error128 
flag_merge_resume_trackers256defaults to off and specifies whether tracker URLs loaded from -resume data should be added to the trackers in the torrent or -replace the trackers.
flag_update_subscribe512on by default and means that this torrent will be part of state -updates when calling post_torrent_updates().
flag_super_seeding1024sets the torrent into super seeding mode. If the torrent is not a -seed, this flag has no effect. It has the same effect as calling -torrent_handle::super_seeding(true) on the torrent handle -immediately after adding it.
flag_sequential_download2048sets the sequential download state for the torrent. It has the same -effect as calling torrent_handle::sequential_download(true) on -the torrent handle immediately after adding it.
flag_use_resume_save_path4096if this flag is set, the save path from the resume data file, if -present, is honored. This defaults to not being set, in which -case the save_path specified in add_torrent_params is always used.
flag_pinned8192indicates that this torrent should never be unloaded from RAM, even -if unloading torrents are allowed in general. Setting this makes -the torrent exempt from loading/unloading management.
-
flag_auto_managed | flag_paused | flag_apply_ip_filter
-
-
8194 
-
-
version
-
filled in by the constructor and should be left untouched. It is used -for forward binary compatibility.
-
-
-
ti
-
torrent_info object with the torrent to add. Unless the url or -info_hash is set, this is required to be initiazlied.
-
-
-
trackers
-
If the torrent doesn't have a tracker, but relies on the DHT to find -peers, the trackers can specify tracker URLs for the torrent.
-
-
-
url_seeds
-
url seeds to be added to the torrent (BEP 17).
-
- -
-
dht_nodes name
-
a list of hostname and port pairs, representing DHT nodes to be added -to the session (if DHT is enabled). The hostname may be an IP address.
-
-
-
save_path
-

the path where the torrent is or will be stored. Note that this may -alos be stored in resume data. If you want the save path saved in -the resume data to be used, you need to set the -flag_use_resume_save_path flag.

-
-

Note

-

On windows this path (and other paths) are interpreted as UNC -paths. This means they must use backslashes as directory separators -and may not contain the special directories "." or "..".

-
-
-
-
-
resume_data
-
The optional parameter, resume_data can be given if up to date -fast-resume data is available. The fast-resume data can be acquired -from a running torrent by calling save_resume_data() on -torrent_handle. See fast resume. The vector that is passed in -will be swapped into the running torrent instance with -std::vector::swap().
-
-
-
storage_mode
-
One of the values from storage_mode_t. For more information, see -storage allocation.
-
-
-
storage
-
can be used to customize how the data is stored. The default storage -will simply write the data to the files it belongs to, but it could be -overridden to save everything to a single file at a specific location -or encrypt the content on disk for instance. For more information -about the storage_interface that needs to be implemented for a custom -storage, see storage_interface.
-
-
-
userdata
-
The userdata parameter is optional and will be passed on to the -extension constructor functions, if any (see add_extension()).
-
-
-
file_priorities
-
can be set to control the initial file priorities when adding a -torrent. The semantics are the same as for -torrent_handle::prioritize_files().
-
-
-
trackerid
-
the default tracker id to be used when announcing to trackers. By -default this is empty, and no tracker ID is used, since this is an -optional argument. If a tracker returns a tracker ID, that ID is used -instead of this.
-
-
-
url
-

If you specify a url, the torrent will be set in -downloading_metadata state until the .torrent file has been -downloaded. If there's any error while downloading, the torrent will -be stopped and the torrent error state (torrent_status::error) -will indicate what went wrong. The url may refer to a magnet link -or a regular http URL.

-

If it refers to an HTTP URL, the info-hash for the added torrent will -not be the true info-hash of the .torrent. Instead a placeholder, -unique, info-hash is used which is later updated once the .torrent -file has been downloaded.

-

Once the info-hash change happens, a torrent_update_alert is posted.

-
-
-
-
uuid
-
if uuid is specified, it is used to find duplicates. If another -torrent is already running with the same UUID as the one being added, -it will be considered a duplicate. This is mainly useful for RSS feed -items which has UUIDs specified.
-
-
-
source_feed_url
-
should point to the URL of the RSS feed this torrent comes from, if it -comes from an RSS feed.
-
-
-
flags
-
flags controlling aspects of this torrent and how it's added. See -flags_t for details.
-
-
-
info_hash
-
set this to the info hash of the torrent to add in case the info-hash -is the only known property of the torrent. i.e. you don't have a -.torrent file nor a magnet link.
-
- - - -
-
max_uploads max_connections upload_limit download_limit
-

max_uploads, max_connections, upload_limit, -download_limit correspond to the set_max_uploads(), -set_max_connections(), set_upload_limit() and -set_download_limit() functions on torrent_handle. These values let -you initialize these settings when the torrent is added, instead of -calling these functions immediately following adding it.

-

-1 means unlimited on these settings just like their counterpart -functions on torrent_handle

-
-
-
-
-
-

cache_status

-

Declared in "libtorrent/disk_io_thread.hpp"

-

this struct holds a number of statistics counters -relevant for the disk io thread and disk cache.

-
-struct cache_status
-{
-   cache_status ();
-
-   std::vector<cached_piece_info> pieces;
-};
-
-
-

cache_status()

-
-cache_status ();
-
-

initializes all counters to 0

-
-
-
-

stats_metric

-

Declared in "libtorrent/session.hpp"

-

describes one statistics metric from the session. For more information, -see the session statistics section.

-
-struct stats_metric
-{
-   char const* name;
-   int value_index;
-   int type;
-};
-
-
-
-

session_proxy

-

Declared in "libtorrent/session.hpp"

-

this is a holder for the internal session implementation object. Once the -session destruction is explicitly initiated, this holder is used to -synchronize the completion of the shutdown. The lifetime of this object -may outlive session, causing the session destructor to not block. The -session_proxy destructor will block however, until the underlying session -is done shutting down.

-
-class session_proxy
-{
-   session_proxy ();
-};
-
-
-

session_proxy()

-
-session_proxy ();
-
-

default constructor, does not refer to any session -implementation object.

-
-
-
-

session

-

Declared in "libtorrent/session.hpp"

-

The session holds all state that spans multiple torrents. Among other -things it runs the network loop and manages all torrents. Once it's -created, the session object will spawn the main thread that will do all -the work. The main thread will be idle as long it doesn't have any -torrents to participate in.

-

You have some control over session configuration through the -session::apply_settings() member function. To change one or more -configuration options, create a settings_pack. object and fill it with -the settings to be set and pass it in to session::apply_settings().

-

see apply_settings().

-
-class session: public boost::noncopyable
-{
-   session (fingerprint const& print = fingerprint("LT"
-      , LIBTORRENT_VERSION_MAJOR, LIBTORRENT_VERSION_MINOR, 0, 0)
-      , int flags = start_default_features | add_default_plugins
-      , boost::uint32_t alert_mask = alert::error_notification);
-   session (fingerprint const& print
-      , std::pair<int, int> listen_port_range
-      , char const* listen_interface = "0.0.0.0"
-      , int flags = start_default_features | add_default_plugins
-      , int alert_mask = alert::error_notification);
-   session (settings_pack const& pack
-      , int flags = start_default_features | add_default_plugins);
-   ~session ();
-   void load_state (lazy_entry const& e);
-   void save_state (entry& e, boost::uint32_t flags = 0xffffffff) const;
-   void refresh_torrent_status (std::vector<torrent_status>* ret
-      , boost::uint32_t flags = 0) const;
-   void get_torrent_status (std::vector<torrent_status>* ret
-      , boost::function<bool(torrent_status const&)> const& pred
-      , boost::uint32_t flags = 0) const;
-   void post_torrent_updates (boost::uint32_t flags = 0xffffffff);
-   void post_session_stats ();
-   void post_dht_stats ();
-   torrent_handle find_torrent (sha1_hash const& info_hash) const;
-   std::vector<torrent_handle> get_torrents () const;
-   void async_add_torrent (add_torrent_params const& params);
-   torrent_handle add_torrent (add_torrent_params const& params, error_code& ec);
-   torrent_handle add_torrent (add_torrent_params const& params);
-   session_proxy abort ();
-   void resume ();
-   void pause ();
-   bool is_paused () const;
-   void set_load_function (user_load_function_t fun);
-   void get_cache_info (cache_status* ret, torrent_handle h = torrent_handle(), int flags = 0) const;
-   feed_handle add_feed (feed_settings const& feed);
-   void remove_feed (feed_handle h);
-   void get_feeds (std::vector<feed_handle>& f) const;
-   bool is_dht_running () const;
-   void set_dht_settings (dht_settings const& settings);
-   void add_dht_router (std::pair<std::string, int> const& node);
-   void add_dht_node (std::pair<std::string, int> const& node);
-   void dht_get_item (sha1_hash const& target);
-   void dht_get_item (boost::array<char, 32> key
-      , std::string salt = std::string());
-   sha1_hash dht_put_item (entry data);
-   void dht_put_item (boost::array<char, 32> key
-      , boost::function<void(entry&, boost::array<char,64>&
-      , boost::uint64_t&, std::string const&)> cb
-      , std::string salt = std::string());
-   void add_extension (boost::function<boost::shared_ptr<torrent_plugin>(
-      torrent*, void*)> ext);
-   void add_extension (boost::shared_ptr<plugin> ext);
-   ip_filter get_ip_filter () const;
-   void set_ip_filter (ip_filter const& f);
-   void set_port_filter (port_filter const& f);
-   peer_id id () const;
-   void set_key (int key);
-   bool is_listening () const;
-   unsigned short listen_port () const;
-   unsigned short ssl_listen_port () const;
-   void set_peer_class_filter (ip_filter const& f);
-   void set_peer_class_type_filter (peer_class_type_filter const& f);
-   int create_peer_class (char const* name);
-   void delete_peer_class (int cid);
-   peer_class_info get_peer_class (int cid);
-   void set_peer_class (int cid, peer_class_info const& pci);
-   void remove_torrent (const torrent_handle& h, int options = 0);
-   aux::session_settings get_settings () const;
-   void apply_settings (settings_pack const& s);
-   void pop_alerts (std::deque<alert*>* alerts);
-   std::auto_ptr<alert> pop_alert ();
-   alert const* wait_for_alert (time_duration max_wait);
-   void set_alert_dispatch (boost::function<void(std::auto_ptr<alert>)> const& fun);
-   void delete_port_mapping (int handle);
-   int add_port_mapping (protocol_type t, int external_port, int local_port);
-
-   enum save_state_flags_t
-   {
-      save_settings,
-      save_dht_settings,
-      save_dht_state,
-      save_encryption_settings,
-      save_feeds,
-   };
-
-   enum options_t
-   {
-      delete_files,
-   };
-
-   enum session_flags_t
-   {
-      add_default_plugins,
-      start_default_features,
-   };
-
-   enum protocol_type
-   {
-      udp,
-      tcp,
-   };
-};
-
-
-

~session()

-
-~session ();
-
-

The destructor of session will notify all trackers that our torrents -have been shut down. If some trackers are down, they will time out. -All this before the destructor of session returns. So, it's advised -that any kind of interface (such as windows) are closed before -destructing the session object. Because it can take a few second for -it to finish. The timeout can be set with apply_settings().

- -
-
-

load_state() save_state()

-
-void load_state (lazy_entry const& e);
-void save_state (entry& e, boost::uint32_t flags = 0xffffffff) const;
-
-

loads and saves all session settings, including dht_settings, -encryption settings and proxy settings. save_state writes all keys -to the entry that's passed in, which needs to either not be -initialized, or initialized as a dictionary.

-

load_state expects a lazy_entry which can be built from a bencoded -buffer with lazy_bdecode().

-

The flags arguments passed in to save_state can be used to -filter which parts of the session state to save. By default, all state -is saved (except for the individual torrents). see save_state_flags_t

- -
-
-

get_torrent_status() refresh_torrent_status()

-
-void refresh_torrent_status (std::vector<torrent_status>* ret
-      , boost::uint32_t flags = 0) const;
-void get_torrent_status (std::vector<torrent_status>* ret
-      , boost::function<bool(torrent_status const&)> const& pred
-      , boost::uint32_t flags = 0) const;
-
-
-

Note

-

these calls are potentially expensive and won't scale well with -lots of torrents. If you're concerned about performance, consider -using post_torrent_updates() instead.

-
-

get_torrent_status returns a vector of the torrent_status for -every torrent which satisfies pred, which is a predicate function -which determines if a torrent should be included in the returned set -or not. Returning true means it should be included and false means -excluded. The flags argument is the same as to -torrent_handle::status(). Since pred is guaranteed to be -called for every torrent, it may be used to count the number of -torrents of different categories as well.

-

refresh_torrent_status takes a vector of torrent_status structs -(for instance the same vector that was returned by -get_torrent_status() ) and refreshes the status based on the -handle member. It is possible to use this function by first -setting up a vector of default constructed torrent_status objects, -only initializing the handle member, in order to request the -torrent status for multiple torrents in a single call. This can save a -significant amount of time if you have a lot of torrents.

-

Any torrent_status object whose handle member is not referring to -a valid torrent are ignored.

-
-
-

post_torrent_updates()

-
-void post_torrent_updates (boost::uint32_t flags = 0xffffffff);
-
-

This functions instructs the session to post the state_update_alert, -containing the status of all torrents whose state changed since the -last time this function was called.

-

Only torrents who has the state subscription flag set will be -included. This flag is on by default. See add_torrent_params. -the flags argument is the same as for torrent_handle::status(). -see torrent_handle::status_flags_t.

-
-
-

post_session_stats()

-
-void post_session_stats ();
-
-

This function will post a session_stats_alert object, containing a -snapshot of the performance counters from the internals of libtorrent. -To interpret these counters, query the session via -session_stats_metrics().

-

For more information, see the session statistics section.

-
-
-

post_dht_stats()

-
-void post_dht_stats ();
-
-

This will cause a dht_stats_alert to be posted.

- -
-
-

find_torrent() get_torrents()

-
-torrent_handle find_torrent (sha1_hash const& info_hash) const;
-std::vector<torrent_handle> get_torrents () const;
-
-

find_torrent() looks for a torrent with the given info-hash. In -case there is such a torrent in the session, a torrent_handle to that -torrent is returned. In case the torrent cannot be found, an invalid -torrent_handle is returned.

-

See torrent_handle::is_valid() to know if the torrent was found or -not.

-

get_torrents() returns a vector of torrent_handles to all the -torrents currently in the session.

- -
-
-

add_torrent() async_add_torrent()

-
-void async_add_torrent (add_torrent_params const& params);
-torrent_handle add_torrent (add_torrent_params const& params, error_code& ec);
-torrent_handle add_torrent (add_torrent_params const& params);
-
-

You add torrents through the add_torrent() function where you give an -object with all the parameters. The add_torrent() overloads will block -until the torrent has been added (or failed to be added) and returns -an error code and a torrent_handle. In order to add torrents more -efficiently, consider using async_add_torrent() which returns -immediately, without waiting for the torrent to add. Notification of -the torrent being added is sent as add_torrent_alert.

-

The overload that does not take an error_code throws an exception on -error and is not available when building without exception support. -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.

-

If the torrent you are trying to add already exists in the session (is -either queued for checking, being checked or downloading) -add_torrent() will throw libtorrent_exception which derives from -std::exception unless duplicate_is_error is set to false. In that -case, add_torrent() will return the handle to the existing torrent.

-

all torrent_handles must be destructed before the session is destructed!

-
-
-

abort()

-
-session_proxy abort ();
-
-

In case you want to destruct the session asynchrounously, you can -request a session destruction proxy. If you don't do this, the -destructor of the session object will block while the trackers are -contacted. If you keep one session_proxy to the session when -destructing it, the destructor will not block, but start to close down -the session, the destructor of the proxy will then synchronize the -threads. So, the destruction of the session is performed from the -session destructor call until the session_proxy destructor -call. The session_proxy does not have any operations on it (since -the session is being closed down, no operations are allowed on it). -The only valid operation is calling the destructor:

-
-class session_proxy
-{
-public:
-        session_proxy();
-        ~session_proxy()
-};
-
- - -
-
-

pause() resume() is_paused()

-
-void resume ();
-void pause ();
-bool is_paused () const;
-
-

Pausing the session has the same effect as pausing every torrent in -it, except that torrents will not be resumed by the auto-manage -mechanism. Resuming will restore the torrents to their previous paused -state. i.e. the session pause state is separate from the torrent pause -state. A torrent is inactive if it is paused or if the session is -paused.

-
-
-

set_load_function()

-
-void set_load_function (user_load_function_t fun);
-
-

This function enables dynamic loading of torrent files. When a -torrent is unloaded but needs to be availabe in memory, this function -is called from within the libtorrent network thread. From within -this thread, you can not use any of the public APIs of libtorrent -itself. The the info-hash of the torrent is passed in to the function -and it is expected to fill in the passed in vector<char> with the -.torrent file corresponding to it.

-

If there is an error loading the torrent file, the error_code -(ec) should be set to reflect the error. In such case, the torrent -itself is stopped and set to an error state with the corresponding -error code.

-

Given that the function is called from the internal network thread of -libtorrent, it's important to not stall. libtorrent will not be able -to send nor receive any data until the function call returns.

-

The signature of the function to pass in is:

-
-void fun(sha1_hash const& info_hash, std::vector<char>& buf, error_code& ec);
-
-
-
-

get_cache_info()

-
-void get_cache_info (cache_status* ret, torrent_handle h = torrent_handle(), int flags = 0) const;
-
-

Fills in the cache_status struct with information about the given torrent. -If flags is session::disk_cache_no_pieces the cache_status::pieces field -will not be set. This may significantly reduce the cost of this call.

-
-
-

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.

-

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.

-
-
-

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.

- -
-
-

is_dht_running() set_dht_settings()

-
-bool is_dht_running () const;
-void set_dht_settings (dht_settings const& settings);
-
-

set_dht_settings sets some parameters availavle to the dht node. -See dht_settings for more information.

-

is_dht_running() returns true if the DHT support has been started -and false -otherwise.

-

get_dht_settings() returns the current settings

- -
-
-

add_dht_router() add_dht_node()

-
-void add_dht_router (std::pair<std::string, int> const& node);
-void add_dht_node (std::pair<std::string, int> const& node);
-
-

add_dht_node takes a host name and port pair. That endpoint will be -pinged, and if a valid DHT reply is received, the node will be added to -the routing table.

-

add_dht_router adds the given endpoint to a list of DHT router -nodes. If a search is ever made while the routing table is empty, -those nodes will be used as backups. Nodes in the router node list -will also never be added to the regular routing table, which -effectively means they are only used for bootstrapping, to keep the -load off them.

-

An example routing node that you could typically add is -router.bittorrent.com.

-
-
-

dht_get_item()

-
-void dht_get_item (sha1_hash const& target);
-
-

query the DHT for an immutable item at the target hash. -the result is posted as a dht_immutable_item_alert.

-
-
-

dht_get_item()

-
-void dht_get_item (boost::array<char, 32> key
-      , std::string salt = std::string());
-
-

query the DHT for a mutable item under the public key key. -this is an ed25519 key. salt is optional and may be left -as an empty string if no salt is to be used. -if the item is found in the DHT, a dht_mutable_item_alert is -posted.

-
-
-

dht_put_item()

-
-sha1_hash dht_put_item (entry data);
-
-

store the given bencoded data as an immutable item in the DHT. -the returned hash is the key that is to be used to look the item -up agan. It's just the sha-1 hash of the bencoded form of the -structure.

-
-
-

dht_put_item()

-
-void dht_put_item (boost::array<char, 32> key
-      , boost::function<void(entry&, boost::array<char,64>&
-      , boost::uint64_t&, std::string const&)> cb
-      , std::string salt = std::string());
-
-

store a mutable item. The key is the public key the blob is -to be stored under. The optional salt argument is a string that -is to be mixed in with the key when determining where in the DHT -the value is to be stored. The callback function is called from within -the libtorrent network thread once we've found where to store the blob, -possibly with the current value stored under the key. -The values passed to the callback functions are:

-
-
entry& value
-
the current value stored under the key (may be empty). Also expected -to be set to the value to be stored by the function.
-
boost::array<char,64>& signature
-
the signature authenticating the current value. This may be zeroes -if there is currently no value stored. The functon is expected to -fill in this buffer with the signature of the new value to store. -To generate the signature, you may want to use the -sign_mutable_item function.
-
boost::uint64_t& seq
-
current sequence number. May be zero if there is no current value. -The function is expected to set this to the new sequence number of -the value that is to be stored. Sequence numbers must be monotonically -increasing. Attempting to overwrite a value with a lower or equal -sequence number will fail, even if the signature is correct.
-
std::string const& salt
-
this is the salt that was used for this put call.
-
-

Since the callback function cb is called from within libtorrent, -it is critical to not perform any blocking operations. Ideally not -even locking a mutex. Pass any data required for this function along -with the function object's context and make the function entirely -self-contained. The only reason data blobs' values are computed -via a function instead of just passing in the new value is to avoid -race conditions. If you want to update the value in the DHT, you -must first retrieve it, then modify it, then write it back. The way -the DHT works, it is natural to always do a lookup before storing and -calling the callback in between is convenient.

-
-
-

add_extension()

-
-void add_extension (boost::function<boost::shared_ptr<torrent_plugin>(
-      torrent*, void*)> ext);
-void add_extension (boost::shared_ptr<plugin> 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);
-
- -
-
-

get_ip_filter() set_ip_filter()

-
-ip_filter get_ip_filter () const;
-void set_ip_filter (ip_filter const& f);
-
-

Sets a filter that will be used to reject and accept incoming as well -as outgoing connections based on their originating ip address. The -default filter will allow connections to any ip address. To build a -set of rules for which addresses are accepted and not, see ip_filter.

-

Each time a peer is blocked because of the IP filter, a -peer_blocked_alert is generated. get_ip_filter() Returns the -ip_filter currently in the session. See ip_filter.

-
-
-

set_port_filter()

-
-void set_port_filter (port_filter const& f);
-
-

apply port_filter f to incoming and outgoing peers. a port filter -will reject making outgoing peer connections to certain remote ports. -The main intention is to be able to avoid triggering certain -anti-virus software by connecting to SMTP, FTP ports.

-
-
-

id()

-
-peer_id id () const;
-
-

returns the raw peer ID used by libtorrent. When anonymous mode is set -the peer ID is randomized per peer.

-
-
-

set_key()

-
-void set_key (int key);
-
-

sets the key sent to trackers. If it's not set, it is initialized -by libtorrent. The key may be used by the tracker to identify the -peer potentially across you changing your IP.

- - -
-
-

listen_port() ssl_listen_port() is_listening()

-
-bool is_listening () const;
-unsigned short listen_port () const;
-unsigned short ssl_listen_port () 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 set a new -settings_pack::listen_interfaces to try another interface and port to -bind to.

-

listen_port() returns the port we ended up listening on. If the -port specified in settings_pack::listen_interfaces failed, libtorrent -will try to bind to the next port, and so on. If it fails -settings_pack::max_retry_port_bind times, it will bind to port 0 -(meaning the OS picks the port). The only way to know which port it -ended up binding to is to ask for it by calling listen_port().

-

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.

-
-
-

set_peer_class_filter()

-
-void set_peer_class_filter (ip_filter const& f);
-
-

Sets the peer class filter for this session. All new peer connections -will take this into account and be added to the peer classes specified -by this filter, based on the peer's IP address.

-

The ip-filter essentially maps an IP -> uint32. Each bit in that 32 -bit integer represents a peer class. The least significant bit -represents class 0, the next bit class 1 and so on.

-

For more info, see ip_filter.

-

For example, to make all peers in the range 200.1.1.0 - 200.1.255.255 -belong to their own peer class, apply the following filter:

-
-ip_filter f;
-int my_class = ses.create_peer_class("200.1.x.x IP range");
-f.add_rule(address_v4::from_string("200.1.1.0")
-        , address_v4::from_string("200.1.255.255")
-        , 1 << my_class);
-ses.set_peer_class_filter(f);
-
-

This setting only applies to new connections, it won't affect existing -peer connections.

-

This function is limited to only peer class 0-31, since there are only -32 bits in the IP range mapping. Only the set bits matter; no peer -class will be removed from a peer as a result of this call, peer -classes are only added.

-

The peer_class argument cannot be greater than 31. The bitmasks -representing peer classes in the peer_class_filter are 32 bits.

-

For more information, see peer classes.

-
-
-

set_peer_class_type_filter()

-
-void set_peer_class_type_filter (peer_class_type_filter const& f);
-
-

Sets and gets the peer class type filter. This is controls automatic -peer class assignments to peers based on what kind of socket it is.

-

It does not only support assigning peer classes, it also supports -removing peer classes based on socket type.

-

The order of these rules being applied are:

-
    -
  1. peer-class IP filter
  2. -
  3. peer-class type filter, removing classes
  4. -
  5. peer-class type filter, adding classes
  6. -
-

For more information, see peer classes. -TODO: add get_peer_class_type_filter() as well

-
-
-

create_peer_class()

-
-int create_peer_class (char const* name);
-
-

Creates a new peer class (see peer classes) with the given name. The -returned integer is the new peer class' identifier. Peer classes may -have the same name, so each invocation of this function creates a new -class and returns a unique identifier.

-

Identifiers are assigned from low numbers to higher. So if you plan on -using certain peer classes in a call to set_peer_class_filter(), -make sure to create those early on, to get low identifiers.

-

For more information on peer classes, see peer classes.

-
-
-

delete_peer_class()

-
-void delete_peer_class (int cid);
-
-

This call dereferences the reference count of the specified peer -class. When creating a peer class it's automatically referenced by 1. -If you want to recycle a peer class, you may call this function. You -may only call this function once per peer class you create. -Calling it more than once for the same class will lead to memory -corruption.

-

Since peer classes are reference counted, this function will not -remove the peer class if it's still assigned to torrents or peers. It -will however remove it once the last peer and torrent drops their -references to it.

-

There is no need to call this function for custom peer classes. All -peer classes will be properly destructed when the session object -destructs.

-

For more information on peer classes, see peer classes.

- -
-
-

get_peer_class() set_peer_class()

-
-peer_class_info get_peer_class (int cid);
-void set_peer_class (int cid, peer_class_info const& pci);
-
-

These functions queries information from a peer class and updates the -configuration of a peer class, respectively.

-

cid must refer to an existing peer class. If it does not, the -return value of get_peer_class() is undefined.

-

set_peer_class() sets all the information in the -peer_class_info object in the specified peer class. There is no -option to only update a single property.

-

A peer or torrent balonging to more than one class, the highest -priority among any of its classes is the one that is taken into -account.

-

For more information, see peer classes.

-
-
-

remove_torrent()

-
-void remove_torrent (const torrent_handle& h, int options = 0);
-
-

remove_torrent() will close all peer connections associated with -the torrent and tell the tracker that we've stopped participating in -the swarm. This operation cannot fail. When it completes, you will -receive a torrent_removed_alert.

-

The optional second argument options can be used to delete all the -files downloaded by this torrent. To do so, pass in the value -session::delete_files. The removal of the torrent is asyncronous, -there is no guarantee that adding the same torrent immediately after -it was removed will not throw a libtorrent_exception exception. Once -the torrent is deleted, a torrent_deleted_alert is posted.

- -
-
-

get_settings() apply_settings()

-
-aux::session_settings get_settings () const;
-void apply_settings (settings_pack const& s);
-
-

Applies the settings specified by the settings_pack s. This is an -asynchronous operation that will return immediately and actually apply -the settings to the main thread of libtorrent some time later.

- - -
-
-

pop_alert() pop_alerts() wait_for_alert()

-
-void pop_alerts (std::deque<alert*>* alerts);
-std::auto_ptr<alert> pop_alert ();
-alert const* wait_for_alert (time_duration max_wait);
-
-

pop_alert() is used to ask the session if any errors or events has -occurred. With settings_pack::alert_mask you can filter which alerts -to receive through pop_alert(). For information about the alert -categories, see alerts.

-

pop_alerts() pops all pending alerts in a single call. In high -performance environments with a very high alert churn rate, this can -save significant amount of time compared to popping alerts one at a -time. Each call requires one round-trip to the network thread. If -alerts are produced in a higher rate than they can be popped (when -popped one at a time) it's easy to get stuck in an infinite loop, -trying to drain the alert queue. Popping the entire queue at once -avoids this problem.

-

However, the pop_alerts function comes with significantly more -responsibility. You pass in an empty std::dequeue<alert*> to it. -If it's not empty, all elements in it will be deleted and then -cleared. All currently pending alerts are returned by being swapped -into the passed in container. The responsibility of deleting the -alerts is transferred to the caller. This means you need to call -delete for each item in the returned dequeue. It's probably a good -idea to delete the alerts as you handle them, to save one extra pass -over the dequeue.

-

Alternatively, you can pass in the same container the next time you -call pop_alerts.

-

wait_for_alert blocks until an alert is available, or for no more -than max_wait time. If wait_for_alert returns because of the -time-out, and no alerts are available, it returns 0. If at least one -alert was generated, a pointer to that alert is returned. The alert is -not popped, any subsequent calls to wait_for_alert will return the -same pointer until the alert is popped by calling pop_alert. This -is useful for leaving any alert dispatching mechanism independent of -this blocking call, the dispatcher can be called and it can pop the -alert independently.

-
-

Note

-

Although these functions are all thread-safe, popping alerts from -multiple separate threads may introduce race conditions in that -the thread issuing an asynchronous operation may not be the one -receiving the alert with the result.

-
-

In the python binding, wait_for_alert takes the number of -milliseconds to wait as an integer.

-

To control the max number of alerts that's queued by the session, see -session_settings::alert_queue_size.

-

save_resume_data_alert and save_resume_data_failed_alert are always -posted, regardelss of the alert mask.

-
-
-

set_alert_dispatch()

-
-void set_alert_dispatch (boost::function<void(std::auto_ptr<alert>)> const& fun);
-
-

This sets a function to be called (from within libtorrent's netowrk -thread) every time an alert is posted. Since the function (fun) is -run in libtorrent's internal thread, it may not call any of -libtorrent's external API functions. Doing so results in a dead lock.

-

The main intention with this function is to support integration with -platform-dependent message queues or signalling systems. For instance, -on windows, one could post a message to an HNWD or on linux, write to -a pipe or an eventfd.

- -
-
-

add_port_mapping() delete_port_mapping()

-
-void delete_port_mapping (int handle);
-int add_port_mapping (protocol_type t, int external_port, int local_port);
-
-

add_port_mapping adds a port forwarding on UPnP and/or NAT-PMP, -whichever is enabled. The return value is a handle referring to the -port mapping that was just created. Pass it to delete_port_mapping() -to remove it.

-
-
-

enum save_state_flags_t

-

Declared in "libtorrent/session.hpp"

- ----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
namevaluedescription
save_settings1saves settings (i.e. the session_settings)
save_dht_settings2saves dht_settings
save_dht_state4saves dht state such as nodes and node-id, possibly accelerating -joining the DHT if provided at next session startup.
save_encryption_settings32save pe_settings
save_feeds128saves RSS feeds
-
-
-

enum options_t

-

Declared in "libtorrent/session.hpp"

- ----- - - - - - - - - - - - - -
namevaluedescription
delete_files1delete the files belonging to the torrent from disk.
-
-
-

enum session_flags_t

-

Declared in "libtorrent/session.hpp"

- ----- - - - - - - - - - - - - - - - - -
namevaluedescription
add_default_plugins1this will add common extensions like ut_pex, ut_metadata, lt_tex -smart_ban and possibly others.
start_default_features2this will start features like DHT, local service discovery, UPnP -and NAT-PMP.
-
-
-

enum protocol_type

-

Declared in "libtorrent/session.hpp"

- ----- - - - - - - - - - - - - - - - - -
namevaluedescription
udp1 
tcp2 
-
-
-

find_metric_idx()

-

Declared in "libtorrent/session.hpp"

-
-int find_metric_idx (char const* name);
-
-

given a name of a metric, this function returns the counter index of it, -or -1 if it could not be found. The counter index is the index into the -values array returned by session_stats_alert.

-
-
-

session_stats_metrics()

-

Declared in "libtorrent/session.hpp"

-
-std::vector<stats_metric> session_stats_metrics ();
-
-

This free function returns the list of available metrics exposed by -libtorrent's statistics API. Each metric has a name and a value index. -The value index is the index into the array in session_stats_alert where -this metric's value can be found when the session stats is sampled (by -calling post_session_stats()).

-
-
- -
-
-
- -
- - - - diff --git a/docs/settings.rst b/docs/settings.rst index b95e6f6d1..a1483056c 100644 --- a/docs/settings.rst +++ b/docs/settings.rst @@ -1828,7 +1828,7 @@ disconnected. +------------------------------+------+------------+ | name | type | default | +==============================+======+============+ -| send_buffer_low_watermark | int | 512 | +| send_buffer_low_watermark | int | 10 * 1024 | +------------------------------+------+------------+ | send_buffer_watermark | int | 500 * 1024 | +------------------------------+------+------------+ @@ -2296,28 +2296,6 @@ It defaults to 3 pieces, which means that when seeding, any peer we've sent more than this number of pieces to will be unchoked in favour of a choked peer. -.. _max_sparse_regions: - -.. raw:: html - - - -+--------------------+------+---------+ -| name | type | default | -+====================+======+=========+ -| max_sparse_regions | int | 0 | -+--------------------+------+---------+ - -``max_sparse_regions`` is a limit of the number of *sparse regions* -in a torrent. A sparse region is defined as a hole of pieces we -have not yet downloaded, in between pieces that have been -downloaded. This is used as a hack for windows vista which has a -bug where you cannot write files with more than a certain number of -sparse regions. This limit is not hard, it will be exceeded. Once -it's exceeded, pieces that will maintain or decrease the number of -sparse regions are prioritized. To disable this functionality, set -this to 0. It defaults to 0 on all platforms except windows. - .. _max_rejects: .. raw:: html @@ -2762,7 +2740,7 @@ replace existing ones. +=====================+======+=========+ | utp_target_delay | int | 100 | +---------------------+------+---------+ -| utp_gain_factor | int | 1500 | +| utp_gain_factor | int | 3000 | +---------------------+------+---------+ | utp_min_timeout | int | 500 | +---------------------+------+---------+ @@ -2770,7 +2748,7 @@ replace existing ones. +---------------------+------+---------+ | utp_fin_resends | int | 2 | +---------------------+------+---------+ -| utp_num_resends | int | 6 | +| utp_num_resends | int | 3 | +---------------------+------+---------+ | utp_connect_timeout | int | 3000 | +---------------------+------+---------+ @@ -2902,8 +2880,7 @@ fill up to this level. +-------------------+------+------------------+ ``max_metadata_size`` is the maximum allowed size (in bytes) to be -received by the metadata extension, i.e. magnet links. It defaults -to 1 MiB. +received by the metadata extension, i.e. magnet links. .. _hashing_threads: @@ -3184,6 +3161,17 @@ kinds of alerts to receive control the settings for incoming and outgoing connections respectively. see enc_policy enum for the available options. +Keep in mind that protocol encryption degrades performance in +several respects: +1. It prevents "zero copy" disk buffers being sent to peers, since + each peer needs to mutate the data (i.e. encrypt it) the data + must be copied per peer connection rather than sending the same + buffer to multiple peers. +2. The encryption itself requires more CPU than plain bittorrent + protocol. The highest cost is the Diffie Hellman exchange on + connection setup. +3. The encryption handshake adds several round-trips to the +connection setup, and delays transferring data. .. _allowed_enc_level: diff --git a/docs/todo.html b/docs/todo.html index d58db29c9..4fca92ff2 100644 --- a/docs/todo.html +++ b/docs/todo.html @@ -22,12 +22,63 @@

libtorrent todo-list

0 urgent -6 important -52 relevant +12 important +58 relevant 9 feasible -164 notes -
relevance 3../src/file.cpp:481find out what error code is reported when the filesystem does not support hard links.