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:
+
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)
+- 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.
+
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);
+ add_torrent_params (storage_constructor_type sc = default_storage_constructor);
enum flags_t
{
@@ -132,20 +135,20 @@ struct add_torrent_params
add_torrent_params()
-**add_torrent_params** (storage_constructor_type sc = default_storage_constructor);
+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.
+
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"
-
-
-
+
+
+
| name |
@@ -156,84 +159,99 @@ information, see the storage field.
|---|
| flag_seed_mode |
1 |
-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.
+ | 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_data |
2 |
-If flag_override_resume_data is set, the paused and auto_managed
-state of the torrent are not loaded from the resume data, but the states requested
-by the flags in add_torrent_params will override them.
-If you pass in resume data, the paused state of the torrent when the resume data
-was saved will override the paused state you pass in here. You can override this
-by setting flag_override_resume_data.
+ | If flag_override_resume_data is set, the paused and
+auto_managed state of the torrent are not loaded from the
+resume data, but the states requested by the flags in
+add_torrent_params will override them.
+If you pass in resume data, the paused state of the torrent when
+the resume data was saved will override the paused state you pass
+in here. You can override this by setting
+flag_override_resume_data.
|
| flag_upload_mode |
4 |
-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.
+ | 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_mode |
8 |
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
+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.
+The share mode has one setting, the share ratio target, see
+session_settings::share_mode_target for more info.
|
| flag_apply_ip_filter |
16 |
determines 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. |
+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_paused |
32 |
specifies 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. |
+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_managed |
64 |
-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.
+ | 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_error |
@@ -243,7 +261,8 @@ by setting override_resume_data.
| flag_merge_resume_trackers |
256 |
defaults to off and specifies whether tracker URLs loaded from
-resume data should be added to the trackers in the torrent or replace the trackers. |
+resume data should be added to the trackers in the torrent or
+replace the trackers.
| flag_update_subscribe |
512 |
@@ -252,16 +271,16 @@ updates when calling torrent_handle::super_seeding(true) on the torrent handle immediately
-after adding it.
+sets 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_download |
2048 |
-sets 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. |
+sets 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. |
@@ -272,13 +291,13 @@ 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.
+- 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.
+- 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
@@ -288,62 +307,71 @@ is set, this is required to be initiazlied.
- dht_nodes name save_path
-- 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.
+- 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.
- 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().
+- 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.
+- 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.
+- 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()).
+- 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().
+- 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.
+- 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.
+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.
+- 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
@@ -352,7 +380,8 @@ if it comes from an RSS feed.
- flags
-- flags controlling aspects of this torrent and how it's added. See flags_t for details.
+- flags controlling aspects of this torrent and how it's added. See
+flags_t for details.
- info_hash
@@ -365,14 +394,14 @@ is the only known property of the torrent. i.e. you don't have a
- 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
+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
@@ -385,7 +414,7 @@ relevant for the disk io thread and disk cache.
struct cache_status
{
- **cache_status** ();
+ cache_status ();
size_type blocks_written;
size_type writes;
@@ -415,7 +444,7 @@ struct cache_status
cache_status()
-**cache_status** ();
+cache_status ();
initializes all counters to 0
@@ -531,13 +560,13 @@ is done shutting down.
class session_proxy
{
- **session_proxy** ();
+ session_proxy ();
};
session_proxy()
-**session_proxy** ();
+session_proxy ();
default constructor, does not refer to any session
implementation object.
@@ -554,18 +583,18 @@ torrents to participate in.
class session: public boost::noncopyable
{
- **session** (fingerprint const& print = fingerprint("LT"
+ 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
TORRENT_LOGPATH_ARG_DEFAULT);
- **session** (fingerprint const& print
+ 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
TORRENT_LOGPATH_ARG_DEFAULT);
- **~session** ();
+ ~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
@@ -684,12 +713,12 @@ class session: public boost::noncopyable
session()
-**session** (fingerprint const& print = fingerprint("LT"
+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
TORRENT_LOGPATH_ARG_DEFAULT);
-**session** (fingerprint const& print
+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
@@ -711,12 +740,12 @@ nat-pmp) and default plugins (ut_metadata, ut_pex and smart_ban). The
default is to start those things. If you do not want them to start,
pass 0 as the flags parameter.
The alert_mask is the same mask that you would send to
-set_alert_mask().
+set_alert_mask().
-
+
~session()
-**~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.
@@ -998,7 +1027,7 @@ 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
@@ -1020,7 +1049,7 @@ 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
@@ -1210,7 +1239,7 @@ 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).
+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
@@ -1288,13 +1317,13 @@ void set_proxy (proxy_settings const& s);
proxy_settings proxy () const;
These functions sets and queries the proxy settings to be used for the
-session.
+
session.
For more information on what settings are available for proxies, see
proxy_settings. If the session is not in anonymous mode, proxies that
aren't working or fail, will automatically be disabled and packets
will flow without using any proxy. If you want to enforce using a
proxy, even when the proxy doesn't work, enable anonymous_mode in
-session_settings.
+
session_settings.
diff --git a/docs/reference-Settings.html b/docs/reference-Settings.html
index 7d77601c8..7b759e6fa 100644
--- a/docs/reference-Settings.html
+++ b/docs/reference-Settings.html
@@ -55,10 +55,10 @@
@@ -69,7 +69,7 @@ direct certain traffic to a proxy.
struct proxy_settings
{
- **proxy_settings** ();
+ proxy_settings ();
std::string hostname;
std::string username;
@@ -83,7 +83,7 @@ struct proxy_settings
proxy_settings()
-**proxy_settings** ();
+proxy_settings ();
defaults constructs proxy settings, initializing it to the default
settings.
@@ -131,9 +131,9 @@ session::get_settings() to get the current settings.
struct session_settings
{
- **session_settings** (std::string const& user_agent = "libtorrent/"
+ session_settings (std::string const& user_agent = "libtorrent/"
LIBTORRENT_VERSION);
- **~session_settings** ();
+ ~session_settings ();
enum io_buffer_mode_t
{
@@ -336,9 +336,9 @@ struct session_settings
~session_settings() session_settings()
-**session_settings** (std::string const& user_agent = "libtorrent/"
+session_settings (std::string const& user_agent = "libtorrent/"
LIBTORRENT_VERSION);
-**~session_settings** ();
+~session_settings ();
initializes the session_settings to the default settings.
@@ -1179,7 +1179,7 @@ until libtorrent will take it out of the upload mode, to test if the
error condition has been fixed.
libtorrent will only do this automatically for auto managed torrents.
You can explicitly take a torrent out of upload only mode using
-set_upload_mode().
+set_upload_mode().
@@ -1744,7 +1744,7 @@ socket on the same port as the TCP socket.
struct dht_settings
{
- **dht_settings** ();
+ dht_settings ();
int max_peers_reply;
int search_branching;
@@ -1761,10 +1761,10 @@ struct dht_settings
bool ignore_dark_internet;
};
-
+
dht_settings()
-**dht_settings** ();
+dht_settings ();
initialized dht_settings to the default values
@@ -1859,7 +1859,7 @@ to peer protocol encryption.
struct pe_settings
{
- **pe_settings** ();
+ pe_settings ();
enum enc_policy
{
@@ -1881,10 +1881,10 @@ struct pe_settings
bool prefer_rc4;
};
-
+
pe_settings()
-**pe_settings** ();
+pe_settings ();
initializes the encryption settings with the default vaues
diff --git a/docs/reference-Time.html b/docs/reference-Time.html
index 29e6d7780..43d44ab45 100644
--- a/docs/reference-Time.html
+++ b/docs/reference-Time.html
@@ -55,8 +55,8 @@
This section contains fundamental time types used internally by
@@ -68,7 +68,7 @@ in time.
and they can only be constructed via one of the construction functions
that take a well defined time unit (seconds, minutes, etc.). They can
only be turned into well defined time units by the accessor functions
-(total_microseconds(), etc.).
+(
total_microseconds(), etc.).
Note
In a future version of libtorrent, these types will be replaced
diff --git a/docs/reference-Utility.html b/docs/reference-Utility.html
index db5c560b7..8f12a9b47 100644
--- a/docs/reference-Utility.html
+++ b/docs/reference-Utility.html
@@ -67,12 +67,12 @@ in a heap allocated or borrowed array.
struct bitfield
{
- **bitfield** (int bits);
- **bitfield** (bitfield const& rhs);
- **bitfield** (bitfield&& rhs);
- **bitfield** (int bits, bool val);
- **bitfield** ();
- **bitfield** (char const* b, int bits);
+ bitfield (int bits);
+ bitfield (bitfield const& rhs);
+ bitfield (bitfield&& rhs);
+ bitfield (int bits, bool val);
+ bitfield ();
+ bitfield (char const* b, int bits);
void borrow_bytes (char* b, int bits);
void assign (char const* b, int bits);
bool get_bit (int index) const;
@@ -90,12 +90,12 @@ struct bitfield
bitfield()
-**bitfield** (int bits);
-**bitfield** (bitfield const& rhs);
-**bitfield** (bitfield&& rhs);
-**bitfield** (int bits, bool val);
-**bitfield** ();
-**bitfield** (char const* b, int bits);
+bitfield (int bits);
+bitfield (bitfield const& rhs);
+bitfield (bitfield&& rhs);
+bitfield (int bits, bool val);
+bitfield ();
+bitfield (char const* b, int bits);
constructs a new bitfield. The default constructor creates an empty
bitfield. bits is the size of the bitfield (specified in bits).
@@ -196,7 +196,7 @@ peer IDs, node IDs etc.
class sha1_hash
{
- **sha1_hash** ();
+ sha1_hash ();
static sha1_hash max ();
static sha1_hash min ();
explicit sha1_hash (char const* s);
@@ -230,7 +230,7 @@ class sha1_hash
sha1_hash()
-**sha1_hash** ();
+sha1_hash ();
constructs an all-sero sha1-hash
diff --git a/include/libtorrent/add_torrent_params.hpp b/include/libtorrent/add_torrent_params.hpp
index 7e4c3e77b..e5c2cd353 100644
--- a/include/libtorrent/add_torrent_params.hpp
+++ b/include/libtorrent/add_torrent_params.hpp
@@ -51,29 +51,32 @@ namespace libtorrent
class torrent;
struct torrent_plugin;
- // The add_torrent_params is a parameter pack for adding torrents to a session.
- // The key fields when adding a torrent are:
+ // 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)
+ // * 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()``.
+ // 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``.
+ // 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 TORRENT_EXPORT add_torrent_params
{
- // 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.
+ // 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.
add_torrent_params(storage_constructor_type sc = default_storage_constructor)
: version(LIBTORRENT_VERSION_NUM)
#ifndef TORRENT_NO_DEPRECATE
@@ -127,102 +130,118 @@ namespace libtorrent
// values for the ``flags`` field
enum flags_t
{
- // 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.
+ // 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.
+ // 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.
+ // If resume data is passed in with this torrent, the seed mode saved
+ // in there will override the seed mode you set here.
flag_seed_mode = 0x001,
- // If ``flag_override_resume_data`` is set, the ``paused`` and ``auto_managed``
- // state of the torrent are not loaded from the resume data, but the states requested
- // by the flags in ``add_torrent_params`` will override them.
+ // If ``flag_override_resume_data`` is set, the ``paused`` and
+ // ``auto_managed`` state of the torrent are not loaded from the
+ // resume data, but the states requested by the flags in
+ // ``add_torrent_params`` will override them.
//
- // If you pass in resume data, the paused state of the torrent when the resume data
- // was saved will override the paused state you pass in here. You can override this
- // by setting ``flag_override_resume_data``.
+ // If you pass in resume data, the paused state of the torrent when
+ // the resume data was saved will override the paused state you pass
+ // in here. You can override this by setting
+ // ``flag_override_resume_data``.
flag_override_resume_data = 0x002,
- // 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 ``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.
+ // 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_upload_mode = 0x004,
// 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.
+ // 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
+ // 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.
+ // The share mode has one setting, the share ratio target, see
+ // ``session_settings::share_mode_target`` for more info.
flag_share_mode = 0x008,
// determines 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.
+ // 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_apply_ip_filter = 0x010,
// specifies 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.
+ // 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_paused = 0x020,
- // 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 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 ``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``.
+ // 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_auto_managed = 0x040,
flag_duplicate_is_error = 0x080,
// defaults to off and specifies whether tracker URLs loaded from
- // resume data should be added to the trackers in the torrent or replace the trackers.
+ // resume data should be added to the trackers in the torrent or
+ // replace the trackers.
flag_merge_resume_trackers = 0x100,
// on by default and means that this torrent will be part of state
// updates when calling post_torrent_updates().
flag_update_subscribe = 0x200,
- // sets 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.
+ // sets 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_super_seeding = 0x400,
- // sets 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.
+ // sets 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_sequential_download = 0x800,
// internal
@@ -236,87 +255,97 @@ namespace libtorrent
// is used for forward binary compatibility.
int version;
- // torrent_info object with the torrent to add. Unless the url or info_hash
- // is set, this is required to be initiazlied.
+ // torrent_info object with the torrent to add. Unless the url or
+ // info_hash is set, this is required to be initiazlied.
boost::intrusive_ptr ti;
#ifndef TORRENT_NO_DEPRECATE
char const* tracker_url;
#endif
- // 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.
+ // 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.
std::vector trackers;
// url seeds to be added to the torrent (`BEP 17`_).
std::vector url_seeds;
- // 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.
+ // 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.
std::vector > dht_nodes;
std::string name;
std::string save_path;
- // 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()``.
+ // 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()``.
std::vector resume_data;
- // One of the values from storage_mode_t. For more information, see storage-allocation_.
+ // One of the values from storage_mode_t. For more information, see
+ // storage-allocation_.
storage_mode_t storage_mode;
- // 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.
+ // 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.
storage_constructor_type storage;
- // The ``userdata`` parameter is optional and will be passed on to the extension
- // constructor functions, if any (see `add_extension()`_).
+ // The ``userdata`` parameter is optional and will be passed on to the
+ // extension constructor functions, if any (see `add_extension()`_).
void* userdata;
- // can be set to control the initial file priorities when adding
- // a torrent. The semantics are the same as for ``torrent_handle::prioritize_files()``.
+ // can be set to control the initial file priorities when adding a
+ // torrent. The semantics are the same as for
+ // ``torrent_handle::prioritize_files()``.
std::vector file_priorities;
- // torrent extension construction functions can be added to this
- // vector to have them be added immediately when the torrent is
- // constructed. This may be desired over the torrent_handle::add_extension()
- // in order to avoid race conditions. For instance it may be important
- // to have the plugin catch events that happen very early on after
- // the torrent is created.
+ // torrent extension construction functions can be added to this vector
+ // to have them be added immediately when the torrent is constructed.
+ // This may be desired over the torrent_handle::add_extension() in order
+ // to avoid race conditions. For instance it may be important to have the
+ // plugin catch events that happen very early on after the torrent is
+ // created.
std::vector(torrent*, void*)> >
extensions;
- // 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.
+ // 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.
std::string trackerid;
- // 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 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.
+ // 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.
std::string url;
- // 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.
+ // 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.
std::string uuid;
// should point to the URL of the RSS feed this torrent comes from,
// if it comes from an RSS feed.
std::string source_feed_url;
- // flags controlling aspects of this torrent and how it's added. See flags_t for details.
+ // flags controlling aspects of this torrent and how it's added. See
+ // flags_t for details.
boost::uint64_t flags;
// set this to the info hash of the torrent to add in case the info-hash
@@ -324,15 +353,15 @@ namespace libtorrent
// .torrent file nor a magnet link.
sha1_hash info_hash;
- // ``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.
+ // ``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
+ // -1 means unlimited on these settings just like their counterpart
+ // functions on torrent_handle
int max_uploads;
int max_connections;
int upload_limit;
diff --git a/include/libtorrent/alert.hpp b/include/libtorrent/alert.hpp
index 5fb9c81d5..34bbaecc4 100644
--- a/include/libtorrent/alert.hpp
+++ b/include/libtorrent/alert.hpp
@@ -49,24 +49,22 @@ POSSIBILITY OF SUCH DAMAGE.
// OVERVIEW
//
-// The pop_alert() function on session is the interface for retrieving
-// alerts, warnings, messages and errors from libtorrent. If no alerts have
-// been posted by libtorrent pop_alert() will return a default initialized
-// ``std::auto_ptr`` object. If there is an alert in libtorrent's queue, the alert
-// from the front of the queue is popped and returned.
-// You can then use the alert object and query
+// The pop_alerts() function on session is the main interface for retrieving
+// alerts (warnings, messages and errors from libtorrent). If no alerts have
+// been posted by libtorrent pop_alert() will return an empty list.
//
-// By default, only errors are reported. set_alert_mask() can be
-// used to specify which kinds of events should be reported. The alert mask
-// is comprised by bits from the category_t enum.
+// By default, only errors are reported. set_alert_mask() can be used to
+// specify which kinds of events should be reported. The alert mask is
+// comprised by bits from the category_t enum.
//
-// Every alert belongs to one or more category. There is a small cost involved in posting alerts. Only
-// alerts that belong to an enabled category are posted. Setting the alert bitmask to 0 will disable
-// all alerts (except those that are non-discardable).
+// Every alert belongs to one or more category. There is a small cost involved
+// in posting alerts. Only alerts that belong to an enabled category are
+// posted. Setting the alert bitmask to 0 will disable all alerts (except those
+// that are non-discardable).
//
// There are other alert base classes that some alerts derive from, all the
-// alerts that are generated for a specific torrent are derived from torrent_alert,
-// and tracker events derive from tracker_alert.
+// alerts that are generated for a specific torrent are derived from
+// torrent_alert, and tracker events derive from tracker_alert.
//
#ifdef _MSC_VER
diff --git a/include/libtorrent/bitfield.hpp b/include/libtorrent/bitfield.hpp
index a72ef2dc8..eff90b715 100644
--- a/include/libtorrent/bitfield.hpp
+++ b/include/libtorrent/bitfield.hpp
@@ -48,7 +48,7 @@ namespace libtorrent
{
// constructs a new bitfield. The default constructor creates an empty
// bitfield. ``bits`` is the size of the bitfield (specified in bits).
- // `` val`` is the value to initialize the bits to. If not specified
+ // ``val`` is the value to initialize the bits to. If not specified
// all bits are initialized to 0.
//
// The constructor taking a pointer ``b`` and ``bits`` copies a bitfield
diff --git a/include/libtorrent/identify_client.hpp b/include/libtorrent/identify_client.hpp
index 0c0b6a39a..ed8492b50 100644
--- a/include/libtorrent/identify_client.hpp
+++ b/include/libtorrent/identify_client.hpp
@@ -50,17 +50,18 @@ POSSIBILITY OF SUCH DAMAGE.
namespace libtorrent
{
- // This function is declared in the header ````. It can can be used
- // to extract a string describing a client version from its peer-id. It will recognize most clients
- // that have this kind of identification in the peer-id.
+ // This function can can be used to extract a string describing a client
+ // version from its peer-id. It will recognize most clients that have this
+ // kind of identification in the peer-id.
TORRENT_EXPORT std::string identify_client(const peer_id& p);
- // Returns an optional fingerprint if any can be identified from the peer id. This can be used
- // to automate the identification of clients. It will not be able to identify peers with non-
- // standard encodings. Only Azureus style, Shadow's style and Mainline style. This function is
- // declared in the header ````.
+ // Returns an optional fingerprint if any can be identified from the peer
+ // id. This can be used to automate the identification of clients. It will
+ // not be able to identify peers with non- standard encodings. Only Azureus
+ // style, Shadow's style and Mainline style.
TORRENT_EXPORT boost::optional client_fingerprint(peer_id const& p);
}
#endif // TORRENT_IDENTIFY_CLIENT_HPP_INCLUDED
+
diff --git a/include/libtorrent/storage.hpp b/include/libtorrent/storage.hpp
index 567a97495..d7d7a4d8c 100644
--- a/include/libtorrent/storage.hpp
+++ b/include/libtorrent/storage.hpp
@@ -66,9 +66,21 @@ POSSIBILITY OF SUCH DAMAGE.
// OVERVIEW
//
-// This is an example storage implementation that stores all pieces in a ``std::map``,
-// i.e. in RAM. It's not necessarily very useful in practice, but illustrates the
-// basics of implementing a custom storage.
+// libtorrent provides a customization point for storage of data. By default,
+// (``default_storage``) downloaded files are saved to disk according with the
+// general conventions of bittorrent clients, mimicing the original file layout
+// when the torrent was created. The libtorrent user may define a custom
+// storage to store piece data in a different way.
+//
+// A custom storage implementation must derive from and implement the
+// storage_interface. You must also provide a function that constructs the
+// custom storage object and provide this function to the add_torrent() call
+// via add_torrent_params. Either passed in to the constructor or by setting
+// the add_torrent_params::storage field.
+//
+// This is an example storage implementation that stores all pieces in a
+// ``std::map``, i.e. in RAM. It's not necessarily very useful in practice, but
+// illustrates the basics of implementing a custom storage.
//
//::
//
@@ -166,16 +178,16 @@ namespace libtorrent
// The storage interface is a pure virtual class that can be implemented to
// customize how and where data for a torrent is stored. The default storage
- // implementation uses regular files in the filesystem, mapping the files in the
- // torrent in the way one would assume a torrent is saved to disk. Implementing
- // your own storage interface makes it possible to store all data in RAM, or in
- // some optimized order on disk (the order the pieces are received for instance),
- // or saving multifile torrents in a single file in order to be able to take
- // advantage of optimized disk-I/O.
+ // implementation uses regular files in the filesystem, mapping the files in
+ // the torrent in the way one would assume a torrent is saved to disk.
+ // Implementing your own storage interface makes it possible to store all
+ // data in RAM, or in some optimized order on disk (the order the pieces are
+ // received for instance), or saving multifile torrents in a single file in
+ // order to be able to take advantage of optimized disk-I/O.
//
- // It is also possible to write a thin class that uses the default storage but
- // modifies some particular behavior, for instance encrypting the data before
- // it's written to disk, and decrypting it when it's read again.
+ // It is also possible to write a thin class that uses the default storage
+ // but modifies some particular behavior, for instance encrypting the data
+ // before it's written to disk, and decrypting it when it's read again.
//
// The storage interface is based on slots, each slot is 'piece_size' number
// of bytes. All access is done by writing and reading whole or partial
@@ -183,9 +195,10 @@ namespace libtorrent
// does not necessarily correspond to the piece with the same index (in
// compact allocation mode it won't).
//
- // libtorrent comes with two built-in storage implementations; ``default_storage``
- // and ``disabled_storage``. Their constructor functions are called default_storage_constructor()
- // and ``disabled_storage_constructor`` respectively. The disabled storage does
+ // libtorrent comes with two built-in storage implementations;
+ // ``default_storage`` and ``disabled_storage``. Their constructor functions
+ // are called default_storage_constructor() and
+ // ``disabled_storage_constructor`` respectively. The disabled storage does
// just what it sounds like. It throws away data that's written, and it
// reads garbage. It's useful mostly for benchmarking and profiling purpose.
//
@@ -195,50 +208,54 @@ namespace libtorrent
storage_interface(): m_disk_pool(0), m_settings(0) {}
- // This function is called when the storage is to be initialized. The default storage
- // will create directories and empty files at this point. If ``allocate_files`` is true,
- // it will also ``ftruncate`` all files to their target size.
+ // This function is called when the storage is to be initialized. The
+ // default storage will create directories and empty files at this point.
+ // If ``allocate_files`` is true, it will also ``ftruncate`` all files to
+ // their target size.
//
// Returning ``true`` indicates an error occurred.
virtual bool initialize(bool allocate_files) = 0;
- // This function is called when first checking (or re-checking) the storage for a torrent.
- // It should return true if any of the files that is used in this storage exists on disk.
- // If so, the storage will be checked for existing pieces before starting the download.
+ // This function is called when first checking (or re-checking) the
+ // storage for a torrent. It should return true if any of the files that
+ // is used in this storage exists on disk. If so, the storage will be
+ // checked for existing pieces before starting the download.
virtual bool has_any_file() = 0;
// change the priorities of files.
virtual void set_file_priority(std::vector const& prio) = 0;
- // These functions should read or write the data in or to the given ``slot`` at the given ``offset``.
- // It should read or write ``num_bufs`` buffers sequentially, where the size of each buffer
- // is specified in the buffer array ``bufs``. The file::iovec_t type has the following members::
+ // These functions should read or write the data in or to the given
+ // ``slot`` at the given ``offset``. It should read or write ``num_bufs``
+ // buffers sequentially, where the size of each buffer is specified in
+ // the buffer array ``bufs``. The file::iovec_t type has the following
+ // members::
//
- // struct iovec_t
- // {
- // void* iov_base;
- // size_t iov_len;
- // };
+ // struct iovec_t { void* iov_base; size_t iov_len; };
//
- // The return value is the number of bytes actually read or written, or -1 on failure. If
- // it returns -1, the error code is expected to be set to
+ // The return value is the number of bytes actually read or written, or
+ // -1 on failure. If it returns -1, the error code is expected to be set
+ // to
//
- // Every buffer in ``bufs`` can be assumed to be page aligned and be of a page aligned size,
- // except for the last buffer of the torrent. The allocated buffer can be assumed to fit a
- // fully page aligned number of bytes though. This is useful when reading and writing the
- // last piece of a file in unbuffered mode.
+ // Every buffer in ``bufs`` can be assumed to be page aligned and be of a
+ // page aligned size, except for the last buffer of the torrent. The
+ // allocated buffer can be assumed to fit a fully page aligned number of
+ // bytes though. This is useful when reading and writing the last piece
+ // of a file in unbuffered mode.
//
- // The ``offset`` is aligned to 16 kiB boundries *most of the time*, but there are rare
- // exceptions when it's not. Specifically if the read cache is disabled/or full and a
- // client requests unaligned data, or the file itself is not aligned in the torrent.
- // Most clients request aligned data.
+ // The ``offset`` is aligned to 16 kiB boundries *most of the time*, but
+ // there are rare exceptions when it's not. Specifically if the read
+ // cache is disabled/or full and a client requests unaligned data, or the
+ // file itself is not aligned in the torrent. Most clients request
+ // aligned data.
virtual int readv(file::iovec_t const* bufs, int slot, int offset, int num_bufs, int flags = file::random_access);
virtual int writev(file::iovec_t const* bufs, int slot, int offset, int num_bufs, int flags = file::random_access);
- // This function is called when a read job is queued. It gives the storage wrapper an
- // opportunity to hint the operating system about this coming read. For instance, the
- // storage may call ``posix_fadvise(POSIX_FADV_WILLNEED)`` or ``fcntl(F_RDADVISE)``.
+ // This function is called when a read job is queued. It gives the
+ // storage wrapper an opportunity to hint the operating system about this
+ // coming read. For instance, the storage may call
+ // ``posix_fadvise(POSIX_FADV_WILLNEED)`` or ``fcntl(F_RDADVISE)``.
virtual void hint_read(int, int, int) {}
// negative return value indicates an error
@@ -251,17 +268,18 @@ namespace libtorrent
// byte at offset ``offset`` in slot ``slot``.
virtual size_type physical_offset(int slot, int offset) = 0;
- // This function is optional. It is supposed to return the first piece, starting at
- // ``start`` that is fully contained within a data-region on disk (i.e. non-sparse
- // region). The purpose of this is to skip parts of files that can be known to contain
- // zeros when checking files.
+ // This function is optional. It is supposed to return the first piece,
+ // starting at ``start`` that is fully contained within a data-region on
+ // disk (i.e. non-sparse region). The purpose of this is to skip parts of
+ // files that can be known to contain zeros when checking files.
virtual int sparse_end(int start) const { return start; }
- // This function should move all the files belonging to the storage to the new save_path.
- // The default storage moves the single file or the directory of the torrent.
+ // This function should move all the files belonging to the storage to
+ // the new save_path. The default storage moves the single file or the
+ // directory of the torrent.
//
- // Before moving the files, any open file handles may have to be closed, like
- // ``release_files()``.
+ // Before moving the files, any open file handles may have to be closed,
+ // like ``release_files()``.
//
// returns one of:
// | no_error = 0
@@ -295,9 +313,10 @@ namespace libtorrent
// Returning ``true`` indicates an error occurred.
virtual bool move_slot(int src_slot, int dst_slot) = 0;
- // This function should swap the data in ``slot1`` and ``slot2``. The default
- // storage uses a scratch buffer to read the data into, then moving the other
- // slot and finally writing back the temporary slot's data
+ // This function should swap the data in ``slot1`` and ``slot2``. The
+ // default storage uses a scratch buffer to read the data into, then
+ // moving the other slot and finally writing back the temporary slot's
+ // data
//
// This is only used in compact mode.
//
@@ -305,8 +324,8 @@ namespace libtorrent
virtual bool swap_slots(int slot1, int slot2) = 0;
// This function should do a 3-way swap, or shift of the slots. ``slot1``
- // should move to ``slot2``, which should be moved to ``slot3`` which in turn
- // should be moved to ``slot1``.
+ // should move to ``slot2``, which should be moved to ``slot3`` which in
+ // turn should be moved to ``slot1``.
//
// This is only used in compact mode.
//
@@ -324,12 +343,13 @@ namespace libtorrent
// ``true`` should be returned.
virtual bool rename_file(int index, std::string const& new_filename) = 0;
- // This function should delete all files and directories belonging to this storage.
+ // This function should delete all files and directories belonging to
+ // this storage.
//
// Returning ``true`` indicates an error occurred.
//
- // The ``disk_buffer_pool`` is used to allocate and free disk buffers. It has the
- // following members::
+ // The ``disk_buffer_pool`` is used to allocate and free disk buffers. It
+ // has the following members::
//
// struct disk_buffer_pool : boost::noncopyable
// {
@@ -347,13 +367,13 @@ namespace libtorrent
#ifndef TORRENT_NO_DEPRECATE
// This function is called each time a file is completely downloaded. The
- // storage implementation can perform last operations on a file. The file will
- // not be opened for writing after this.
+ // storage implementation can perform last operations on a file. The file
+ // will not be opened for writing after this.
//
// ``index`` is the index of the file that completed.
//
- // On windows the default storage implementation clears the sparse file flag
- // on the specified file.
+ // On windows the default storage implementation clears the sparse file
+ // flag on the specified file.
virtual void finalize_file(int) {}
#endif
@@ -389,9 +409,9 @@ namespace libtorrent
session_settings* m_settings;
};
- // The default implementation of storage_interface. Behaves as a normal bittorrent client.
- // It is possible to derive from this class in order to override some of its behavior, when
- // implementing a custom storage.
+ // The default implementation of storage_interface. Behaves as a normal
+ // bittorrent client. It is possible to derive from this class in order to
+ // override some of its behavior, when implementing a custom storage.
class TORRENT_EXPORT default_storage : public storage_interface, boost::noncopyable
{
public: