From 7cf035167bcc4fb4d5d76149666738f45d17cade Mon Sep 17 00:00:00 2001 From: Arvid Norberg Date: Mon, 1 Jul 2013 03:41:36 +0000 Subject: [PATCH] regenerate html --- docs/manual.html | 275 ++++++++++++++++++++++++++++++++++------------- 1 file changed, 200 insertions(+), 75 deletions(-) diff --git a/docs/manual.html b/docs/manual.html index ed2fbeba4..8987dfa93 100644 --- a/docs/manual.html +++ b/docs/manual.html @@ -3,7 +3,7 @@ - + libtorrent API Documentation @@ -248,22 +248,6 @@ class session: public boost::noncopyable session_settings settings() const; void set_pe_settings(pe_settings const& settings); - void set_upload_rate_limit(int bytes_per_second); - int upload_rate_limit() const; - void set_download_rate_limit(int bytes_per_second); - int download_rate_limit() const; - - void set_local_upload_rate_limit(int bytes_per_second); - int local_upload_rate_limit() const; - void set_local_download_rate_limit(int bytes_per_second); - int local_download_rate_limit() const; - - void set_max_uploads(int limit); - void set_max_connections(int limit); - int max_connections() const; - void set_max_half_open_connections(int limit); - int max_half_open_connections() const; - void set_proxy(proxy_settings const& s); proxy_settings proxy() const; @@ -303,9 +287,9 @@ class session: public boost::noncopyable size_t queue_size_limit_); void set_alert_dispatch(boost::function<void(std::auto_ptr<alert>)> const& fun); - feed_handle session::add_feed(feed_settings const& feed); - void session::remove_feed(feed_handle h); - void session::get_feeds(std::vector<feed_handle>& f) const; + feed_handle add_feed(feed_settings const& feed); + void remove_feed(feed_handle h); + void get_feeds(std::vector<feed_handle>& f) const; void add_extension(boost::function< boost::shared_ptr<torrent_plugin>(torrent*)> ext); @@ -529,6 +513,10 @@ until the .torrent file has been downloaded. If there's any error while download 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.

dht_nodes is 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.

If the torrent you are trying to add already exists in the session (is either queued @@ -646,7 +634,7 @@ be taken out of upload-mode, regardless of how it got there. If it's important t manually control when the torrent leaves upload mode, don't make it auto managed.

flag_share_mode 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 -merlely want to improve our share ratio (i.e. increase it). A torrent started in +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 @@ -1172,7 +1160,7 @@ on linux, write to a pipe or an eventfd.

add_feed()

-feed_handle session::add_feed(feed_settings const& feed);
+feed_handle add_feed(feed_settings const& feed);

This adds an RSS feed to the session. The feed will be refreshed @@ -1225,7 +1213,7 @@ see feed_handle.

remove_feed()

-void session::remove_feed(feed_handle h);
+void remove_feed(feed_handle h);

Removes a feed from being watched by the session. When this @@ -1236,7 +1224,7 @@ to any feed.

get_feeds()

-void session::get_feeds(std::vector<feed_handle>& f) const;
+void get_feeds(std::vector<feed_handle>& f) const;

Returns a list of all RSS feeds that are being watched by the session.

@@ -1806,6 +1794,11 @@ returned by orig_files().

If you want to rename the base name of the torrent (for a multifile torrent), you can copy the file_storage (see files() orig_files()), change the name, and then use remap_files().

+

The new_filename can both be a relative path, in which case the file name +is relative to the save_path of the torrent. If the new_filename is +an absolute path (i.e. is_complete(new_filename) == true), then the file +is detached from the save_path of the torrent. In this case the file is +not moved when move_storage_ is invoked.

begin_files() end_files() rbegin_files() rend_files()

@@ -1999,6 +1992,10 @@ struct announce_entry int next_announce_in() const; int min_announce_in() const; + int scrape_incomplete; + int scrape_complete; + int scrape_downloaded; + error_code last_error; std::string message; @@ -2027,6 +2024,12 @@ this tracker. min_announce_in() returns the nu allowed to force another tracker update with this tracker.

If the last time this tracker was contacted failed, last_error is the error code describing what error occurred.

+

scrape_incomplete, scrape_complete and scrape_downloaded are either +-1 or the scrape information this tracker last responded with. incomplete is +the current number of downloaders in the swarm, complete is the current number +of seeds in the swarm and downloaded is the cumulative number of completed +downloads of this torrent, since the beginning of time (from this tracker's point +of view).

If the last time this tracker was contacted, the tracker returned a warning or error message, message contains that message.

fail_limit is the max number of failures to announce to this tracker in @@ -2178,7 +2181,10 @@ struct torrent_handle query_accurate_download_counters = 2, query_last_seen_complete = 4, query_pieces = 8, - query_verified_pieces = 16 + query_verified_pieces = 16, + query_torrent_file = 32, + query_name = 64, + query_save_path = 128, }; torrent_status status(boost::uint32_t flags = 0xffffffff); @@ -2188,8 +2194,6 @@ struct torrent_handle boost::intrusive_ptr<torrent_info> torrent_file() const; bool is_valid() const; - std::string name() const; - enum save_resume_flags_t { flush_disk_cache = 1, save_info_dict = 2 }; void save_resume_data(int flags = 0) const; bool need_save_resume_data() const; @@ -2270,9 +2274,8 @@ struct torrent_handle bool set_metadata(char const* buf, int size) const; - std::string save_path() const; - void move_storage(std::string const& save_path) const; - void move_storage(std::wstring const& save_path) const; + void move_storage(std::string const& save_path, int flags = 0) const; + void move_storage(std::wstring const& save_path, int flags = 0) const; void rename_file(int index, std::string) const; void rename_file(int index, std::wstring) const; storage_interface* get_storage_impl() const; @@ -2435,33 +2438,50 @@ fully downloaded and passed the hash check count. When specifying piece granular the operation is a lot cheaper, since libtorrent already keeps track of this internally and no calculation is required.

-
-

save_path()

-
-
-std::string save_path() const;
-
-
-

save_path() returns the path that was given to async_add_torrent() add_torrent() when this torrent -was started.

-

move_storage()

-void move_storage(std::string const& save_path) const;
-void move_storage(std::wstring const& save_path) const;
+void move_storage(std::string const& save_path, int flags = 0) const;
+void move_storage(std::wstring const& save_path, int flags = 0) const;

Moves the file(s) that this torrent are currently seeding from or downloading to. If the given save_path is not located on the same drive as the original save path, -The files will be copied to the new drive and removed from their original location. +the files will be copied to the new drive and removed from their original location. This will block all other disk IO, and other torrents download and upload rates may drop while copying the file.

Since disk IO is performed in a separate thread, this operation is also asynchronous. Once the operation completes, the storage_moved_alert is generated, with the new path as the message. If the move fails for some reason, storage_moved_failed_alert is generated instead, containing the error message.

+

The flags argument determines the behavior of the copying/moving of the files +in the torrent. They are defined in include/libtorrent/storage.hpp:

+
+
    +
  • always_replace_files = 0
    • +
  • fail_if_exist = 1
    • +
  • dont_replace = 2
    • +
+
+

always_replace_files is the default and replaces any file that exist in both the +source directory and the target directory.

+

fail_if_exist first check to see that none of the copy operations would cause an +overwrite. If it would, it will fail. Otherwise it will proceed as if it was in +always_replace_files mode. Note that there is an inherent race condition here. +If the files in the target directory appear after the check but before the copy +or move completes, they will be overwritten. When failing because of files already +existing in the target path, the error of move_storage_failed_alert is set +to boost::system::errc::file_exists.

+

The intention is that a client may use this as a probe, and if it fails, ask the user +which mode to use. The client may then re-issue the move_storage call with one +of the other modes.

+

dont_replace always takes the existing file in the target directory, if there is +one. The source files will still be removed in that case.

+

Files that have been renamed to have absolute pahts are not moved by this function. +Keep in mind that files that don't belong to the torrent but are stored in the torrent's +directory may be moved as well. This goes for files that have been renamed to +absolute paths that still end up inside the save path.

rename_file()

@@ -2584,17 +2604,6 @@ will throw libtorrent the source mask of this peer. Typically this is one of the source flags in peer_info. i.e. tracker, pex, dht etc.

-
-

name()

-
-
-std::string name() const;
-
-
-

Returns the name of the torrent. i.e. the name from the metadata associated with it. In -case the torrent was started without metadata, and hasn't completely received it yet, -it returns the name given to it when added to the session. See session::add_torrent.

-

set_upload_limit() set_download_limit() upload_limit() download_limit()

@@ -2608,7 +2617,7 @@ int download_limit() const;

set_upload_limit will limit the upload bandwidth used by this particular torrent to the limit you set. It is given as the number of bytes per second the torrent is allowed to upload. set_download_limit works the same way but for download bandwidth instead of upload bandwidth. -Note that setting a higher limit on a torrent then the global limit (session::set_upload_rate_limit) +Note that setting a higher limit on a torrent then the global limit (session_settings::upload_rate_limit) will not override the global rate limit. The torrent can never upload more than the global rate limit.

upload_limit and download_limit will return the current limit setting, for upload and @@ -2907,7 +2916,9 @@ int max_uploads() const;

set_max_uploads() sets the maximum number of peers that's unchoked at the same time on this -torrent. If you set this to -1, there will be no limit.

+torrent. If you set this to -1, there will be no limit. This defaults to infinite. The primary +setting controlling this is the global unchoke slots limit, set by unchoke_slots_limit +in session_settings.

max_uploads() returns the current settings.

@@ -2921,7 +2932,8 @@ int max_connections() const;

set_max_connections() sets the maximum number of connection this torrent will open. If all connections are used up, incoming connections may be refused or poor connections may be closed. This must be at least 2. The default is unlimited number of connections. If -1 is given to the -function, it means unlimited.

+function, it means unlimited. There is also a global limit of the number of connections, set +by connections_limit in session_settings.

max_connections() returns the current settings.

@@ -3028,7 +3040,9 @@ while (outstanding_resume_data > 0) } torrent_handle h = rd->handle; - std::ofstream out((h.save_path() + "/" + h.torrent_file()->name() + ".fastresume").c_str() + torrent_status st = h.status(torrent_handle::query_save_path | torrent_handle::query_name); + std::ofstream out((st.save_path + + "/" + st.name + ".fastresume").c_str() , std::ios_base::binary); out.unsetf(std::ios_base::skipws); bencode(std::ostream_iterator<char>(out), *rd->resume_data); @@ -3107,6 +3121,26 @@ if you're not interested in it (and see performance issues), you can filter them +
  • +
    query_torrent_file
    +

    includes torrent_file, which is all the static information from the .torrent file.

    +
    +
    +
    • +
  • +
    query_name
    +

    includes name, the name of the torrent. This is either derived from the .torrent +file, or from the &dn= magnet link argument or possibly some other source. If the +name of the torrent is not known, this is an empty string.

    +
    +
    +
    • +
  • +
    query_save_path
    +

    includes save_path, the path to the directory the files of the torrent are saved to.

    +
    +
    +
    • @@ -3278,6 +3312,10 @@ struct torrent_status float progress; int progress_ppm; std::string error; + std::string save_path; + std::string name; + + boost::intrusive_ptr<const torrent_info> torrent_file; boost::posix_time::time_duration next_announce; boost::posix_time::time_duration announce_interval; @@ -3451,6 +3489,16 @@ ip, a magnet link for instance).

    error may be set to an error message describing why the torrent was paused, in case it was paused by an error. If the torrent is not paused or if it's paused but not because of an error, this string is empty.

    +

    save_path is the path to the directory where this torrent's files are stored. +It's typically the path as was given to async_add_torrent() add_torrent() when this torrent +was started. This field is only included if the torrent status is queried with +torrent_handle::query_save_path.

    +

    name is the name of the torrent. Typically this is derived from the .torrent file. +In case the torrent was started without metadata, and hasn't completely received it yet, +it returns the name given to it when added to the session. See session::add_torrent. +This field is only included if the torrent status is queried with torrent_handle::query_name.

    +

    torrent_file is set to point to the torrent_info object for this torrent. It's +only included if the torrent status is queried with torrent_handle::query_torrent_file.

    next_announce is the time until the torrent will announce itself to the tracker. And announce_interval is the time the tracker want us to wait until we announce ourself again the next time.

    @@ -4281,7 +4329,7 @@ struct session_settings int write_cache_line_size; int optimistic_disk_retry; - bool disable_hash_check; + bool disable_hash_checks; int max_suggest_pieces; @@ -4294,7 +4342,7 @@ struct session_settings int udp_tracker_token_expiry; bool volatile_read_cache; bool guided_read_cache; - bool default_min_cache_age; + bool default_cache_min_age; int num_optimistic_unchoke_slots; bool no_atime_storage; @@ -4315,6 +4363,7 @@ struct session_settings bool ignore_resume_timestamps; bool no_recheck_incomplete_resume; bool anonymous_mode; + bool force_proxy; int tick_interval; int share_mode_target; @@ -4368,6 +4417,12 @@ struct session_settings bool ban_web_seeds; int max_http_recv_buffer_size; + + bool support_share_mode; + bool support_merkle_torrents; + bool report_redundant_bytes; + std::string handshake_client_version; + bool use_disk_cache_pool; };

    version is automatically set to the libtorrent version you're using @@ -4560,7 +4615,7 @@ reciprocation rate of each peer individually and prefers peers that gives the highest return on investment. It still allocates all upload capacity, but shuffles it around to the best peers first. For this choker to be efficient, you need to set a global upload rate limit -(session::set_upload_rate_limit()). For more information about this +(session_settings::upload_rate_limit). For more information about this choker, see the paper.

    seed_choking_algorithm controls the seeding unchoke behavior. The available @@ -4830,7 +4885,7 @@ 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().

    -

    disable_hash_check controls if downloaded pieces are verified against +

    disable_hash_checks controls if downloaded pieces are verified against the piece hashes in the torrent file or not. The default is false, i.e. to verify all downloaded data. It may be useful to turn this off for performance profiling and simulation scenarios. Do not disable the hash check for regular @@ -4878,7 +4933,7 @@ of a cache line generated by peers to depend on the upload rate you are sending to that peer. The intention is to optimize the RAM usage of the cache, to read ahead further for peers that you're sending faster to.

    -

    default_min_cache_age is the minimum number of seconds any read +

    default_cache_min_age is the minimum number of seconds any read cache line is kept in the cache. This defaults to one second but may be greater if guided_read_cache is enabled. Having a lower bound on the time a cache line stays in the cache is an attempt @@ -4953,13 +5008,15 @@ mode.

    anonymous_mode defaults to false. When set to true, the client tries to hide its identity to a certain degree. The peer-ID will no longer include the client's fingerprint. The user-agent will be reset to an -empty string. Trackers will only be used if they are using a proxy -server. The listen sockets are closed, and incoming connections will +empty string.

    +

    If you're using I2P, it might make sense to enable anonymous mode.

    +

    force_proxy disables any communication that's not going over a proxy. +Enabling this requires a proxy to be configured as well, see set_proxy_settings. +The listen sockets are closed, and incoming connections will only be accepted through a SOCKS5 or I2P proxy (if a peer proxy is set up and -is run on the same machine as the tracker proxy). Since no incoming connections -are accepted, NAT-PMP, UPnP, DHT and local peer discovery are all turned off -when this setting is enabled.

    -

    If you're using I2P, it might make sense to enable anonymous mode as well.

    +is run on the same machine as the tracker proxy). This setting also +disabled peer country lookups, since those are done via DNS lookups that +aren't supported by proxies.

    tick_interval specifies the number of milliseconds between internal ticks. This is the frequency with which bandwidth quota is distributed to peers. It should not be more than one second (i.e. 1000 ms). Setting this @@ -4986,7 +5043,7 @@ quite unthrottled.

    dht_upload_rate_limit sets the rate limit on the DHT. This is specified in bytes per second and defaults to 4000. For busy boxes with lots of torrents that requires more DHT traffic, this should be raised.

    -

    unchoke_slots_limit is the mac number of unchoked peers in the session.

    +

    unchoke_slots_limit is the max number of unchoked peers in the session.

    The number of unchoke slots may be ignored depending on what choking_algorithm is set to.

    half_open_limit sets the maximum number of half-open connections @@ -5115,6 +5172,18 @@ corrupt data are banned.

    RAM buffers when downloading stuff over HTTP. Specifically when specifying a URL to a .torrent file when adding a torrent or when announcing to an HTTP tracker. The default is 2 MiB.

    +

    support_share_mode enables or disables the share mode extension. This is +enabled by default.

    +

    support_merkle_torrents enables or disables the merkle tree torrent support. +This is enabled by default.

    +

    report_redundant_bytes enables or disables reporting redundant bytes to the tracker. +This is enabled by default.

    +

    handshake_client_version is the client name advertized in the peer handshake. If +set to an empty string, the user_agent string is used.

    +

    use_disk_cache_pool enables using a pool allocator for disk cache blocks. This is +disabled by default. Enabling it makes the cache perform better at high throughput. +It also makes the cache less likely and slower at returning memory back to the system +once allocated.

    @@ -5824,6 +5893,7 @@ public: performance_warning = implementation defined, dht_notification = implementation defined, stats_notification = implementation defined, + rss_notification = implementation defined, all_categories = implementation defined }; @@ -5852,6 +5922,10 @@ switch (a->type()) case read_piece_alert::alert_type: { read_piece_alert* p = (read_piece_alert*)a.get(); + if (p->ec) { + // read_piece failed + break; + } // use p break; } @@ -5950,10 +6024,12 @@ is paused and an error state is set and the buffer member of the alert is 0. If successful, buffer points to a buffer containing all the data of the piece. piece is the piece index that was read. size is the number of bytes that was read.

    +

    If the operation fails, ec will indicat what went wrong.

     struct read_piece_alert: torrent_alert
 {
         // ...
+        error_code ec;
         boost::shared_ptr<char> buffer;
         int piece;
         int size;
@@ -6170,8 +6246,9 @@ struct tracker_reply_alert: tracker_alert
         int num_peers;
 };
    -

    The num_peers tells how many peers were returned from the tracker. This is -not necessarily all new peers, some of them may already be connected.

    +

    The num_peers tells how many peers the tracker returned in this response. This is +not expected to be more thant the num_want settings. These are not necessarily +all new peers, some of them may already be connected.

    tracker_warning_alert

    @@ -6605,7 +6682,7 @@ if (h.is_valid()) { entry te = ct.generate(); std::vector<char> buffer; bencode(std::back_inserter(buffer), te); - FILE* f = fopen((to_hex(ti->info_hash().to_string()) + ".torrent").c_str(), "w+"); + FILE* f = fopen((to_hex(ti->info_hash().to_string()) + ".torrent").c_str(), "wb+"); if (f) { fwrite(&buffer[0], 1, buffer.size(), f); fclose(f); @@ -6628,8 +6705,16 @@ struct fastresume_rejected_alert: torrent_alert

    peer_blocked_alert

    -

    This alert is generated when a peer is blocked by the IP filter. The ip member is the -address that was blocked.

    +

    This alert is posted when an incoming peer connection, or a peer that's about to be added +to our peer list, is blocked for some reason. This could be any of:

    + +

    The ip member is the address that was blocked.

     struct peer_blocked_alert: torrent_alert
 {
@@ -6878,6 +6963,23 @@ what went wrong.
 
 
    error is an error code used for when an error occurs on the feed.
    +
    +

    rss_item_alert

    +

    This alert is posted every time a new RSS item (i.e. torrent) is received +from an RSS feed.

    +

    It is only posted if the rss_notifications category is enabled in the +alert mask.

    +
    +struct rss_alert : alert
+{
+        // ...
+        virtual std::string message() const;
+
+        feed_handle handle;
+        feed_item item;
+};
+
    +

    incoming_connection_alert

    The incoming connection alert is posted every time we successfully accept @@ -6961,6 +7063,23 @@ this message was posted. Note that you can map a torrent status to a specific to via its handle member. The receiving end is suggested to have all torrents sorted by the torrent_handle or hashed by it, for efficient updates.

    +
    +

    torrent_update_alert

    +

    When a torrent changes its info-hash, this alert is posted. This only happens in very +specific cases. For instance, when a torrent is downloaded from a URL, the true info +hash is not known immediately. First the .torrent file must be downloaded and parsed.

    +

    Once this download completes, the torrent_update_alert is posted to notify the client +of the info-hash changing.

    +
    +struct torrent_update_alert: torrent_alert
+{
+        // ...
+        sha1_hash old_ih;
+        sha1_hash new_ih;
+};
+
    +

    old_ih and new_ih are the previous and new info-hash for the torrent, respectively.

    +

    alert dispatcher

    @@ -9012,6 +9131,12 @@ the pem file to include in the .torrent file.

    The peer's certificate is located in ./newcert.pem and the certificate's private key in ./newkey.pem.

    + +
    +

    Docutils System Messages

    +
    +

    System Message: ERROR/3 (manual.rst, line 1901); backlink

    +Unknown target name: "move_storage".