From 81384b4f21f97b283775e860fad6ef6c9dea0d16 Mon Sep 17 00:00:00 2001 From: Arvid Norberg Date: Wed, 8 Dec 2010 04:44:20 +0000 Subject: [PATCH] regenerated docs and replaced paypal button --- docs/building.html | 13 ++ docs/client_test.html | 13 ++ docs/contributing.html | 13 ++ docs/dht_extensions.html | 13 ++ docs/examples.html | 13 ++ docs/extension_protocol.html | 13 ++ docs/features.html | 13 ++ docs/index.html | 24 ++- docs/index.rst | 12 +- docs/libtorrent_plugins.html | 13 ++ docs/make_torrent.html | 96 ++++++--- docs/manual.html | 355 +++++++++++++++++++++------------ docs/projects.html | 13 ++ docs/python_binding.html | 13 ++ docs/running_tests.html | 13 ++ docs/template.txt | 13 ++ docs/tuning.html | 13 ++ docs/udp_tracker_protocol.html | 13 ++ docs/utp.html | 13 ++ 19 files changed, 508 insertions(+), 174 deletions(-) diff --git a/docs/building.html b/docs/building.html index 0a020be3f..0d75b9ab5 100644 --- a/docs/building.html +++ b/docs/building.html @@ -2,6 +2,19 @@ + libtorrent manual diff --git a/docs/client_test.html b/docs/client_test.html index 8149e67c0..b723b0d44 100644 --- a/docs/client_test.html +++ b/docs/client_test.html @@ -2,6 +2,19 @@ + client_test example program diff --git a/docs/contributing.html b/docs/contributing.html index 64749656f..e4f6b3cd1 100644 --- a/docs/contributing.html +++ b/docs/contributing.html @@ -2,6 +2,19 @@ + libtorrent manual diff --git a/docs/dht_extensions.html b/docs/dht_extensions.html index a68a7dc03..7d39f5b9a 100644 --- a/docs/dht_extensions.html +++ b/docs/dht_extensions.html @@ -2,6 +2,19 @@ + diff --git a/docs/examples.html b/docs/examples.html index baf23b1f5..334980cc7 100644 --- a/docs/examples.html +++ b/docs/examples.html @@ -2,6 +2,19 @@ + libtorrent Examples diff --git a/docs/extension_protocol.html b/docs/extension_protocol.html index 093f833f8..b411a28ed 100644 --- a/docs/extension_protocol.html +++ b/docs/extension_protocol.html @@ -2,6 +2,19 @@ + diff --git a/docs/features.html b/docs/features.html index 0f64ccdc8..e6aa9abc7 100644 --- a/docs/features.html +++ b/docs/features.html @@ -2,6 +2,19 @@ + libtorrent manual diff --git a/docs/index.html b/docs/index.html index b57122c2e..171577bc8 100644 --- a/docs/index.html +++ b/docs/index.html @@ -2,6 +2,19 @@ + @@ -86,16 +99,7 @@ the library.

+

Feedback

There's a mailing list, general libtorrent discussion.

diff --git a/docs/index.rst b/docs/index.rst index 33b12110c..35f06da1b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -101,17 +101,7 @@ Support the development of libtorrent .. raw:: html -
- - - - - - - -
- + Feedback diff --git a/docs/libtorrent_plugins.html b/docs/libtorrent_plugins.html index ab9586ab4..db2dc6b9e 100644 --- a/docs/libtorrent_plugins.html +++ b/docs/libtorrent_plugins.html @@ -2,6 +2,19 @@ + diff --git a/docs/make_torrent.html b/docs/make_torrent.html index bcbc843eb..e95bb26bb 100644 --- a/docs/make_torrent.html +++ b/docs/make_torrent.html @@ -2,6 +2,19 @@ + creating torrents @@ -44,17 +57,18 @@

Table of contents

-
-

add_file

-
-
-void add_file(file_entry const& e);
-void add_file(fs::path const& p, size_type size);
-
-
-

Adds a file to the file storage. If more files than one are added, -certain restrictions to their paths apply. In a multi-file file -storage (torrent), all files must share the same root directory.

+

If more files than one are added, certain restrictions to their paths apply. +In a multi-file file storage (torrent), all files must share the same root directory.

That is, the first path element of all files must be the same. This shared path element is also set to the name of the torrent. It can be changed by calling set_name.

The built in functions to traverse a directory to add files will make sure this requirement is fulfilled.

+ +
+

file_base() set_file_base()

+
+
+size_type file_base(internal_file_entry const& fe) const;
+void set_file_base(internal_file_entry const& fe, size_type off);
+
+
+

The file base of a file is the offset within the file on the filsystem +where it starts to write. For the most part, this is always 0. It's +possible to map several files (in the torrent) into a single file on +the filesystem by making them all point to the same filename, but with +different file bases, so that they don't overlap. +torrent_info::remap_files can be used to use a new file layout.

+

create_torrent

@@ -304,7 +354,7 @@ struct create_torrent bool priv() const; }; -
+

create_torrent()

diff --git a/docs/manual.html b/docs/manual.html
index 79bce1d05..8075fd1c8 100644
--- a/docs/manual.html
+++ b/docs/manual.html
@@ -2,6 +2,19 @@
 
 
 
+
 
 
 libtorrent API Documentation
@@ -182,118 +195,119 @@
 
  • free functions
 
    • 
-
  • alerts
    • @@ -570,7 +584,7 @@ void save_state(entry& e, boost::uint32_t flags) const; 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.

    +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). These are the possible flags. A flag that's set, means those settings are saved:

    @@ -631,9 +645,9 @@ public:

    add_torrent()

    -typedef storage_interface* (&storage_constructor_type)(
-        file_storage const&, file_storage const*, fs::path const&, file_pool&
-        , std::vector<boost::uint8_t> const&);
+typedef boost::function<storage_interface*(file_storage const&
+        , file_storage const*, std::string const&, file_pool&
+        , std::vector<boost::uint8_t> const&) storage_constructor_type;
 
 struct add_torrent_params
 {
@@ -657,6 +671,7 @@ struct add_torrent_params
         bool upload_mode;
         std::vector<boost::uint8_t> const* file_priorities;
         bool share_mode;
+        std::string trackerid;
 };
 
 torrent_handle add_torrent(add_torrent_params const& params);
@@ -764,6 +779,9 @@ for more info.
    
 a torrent. The semantics are the same as for torrent_handle::prioritize_files().
    
 
    version is filled in by the constructor and should be left untouched. It
 is used for forward binary compatibility.
    
+
    trackerid is 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.

    remove_torrent()

    @@ -1514,18 +1532,18 @@ class torrent_info public: // these constructors throws exceptions on error - torrent_info(sha1_hash const& info_hash); - torrent_info(lazy_entry const& torrent_file); - torrent_info(char const* buffer, int size); - torrent_info(boost::filesystem::path const& filename); - torrent_info(boost::filesystem::wpath const& filename); + torrent_info(sha1_hash const& info_hash, int flags = 0); + torrent_info(lazy_entry const& torrent_file, int flags = 0); + torrent_info(char const* buffer, int size, int flags = 0); + torrent_info(boost::filesystem::path const& filename, int flags = 0); + torrent_info(boost::filesystem::wpath const& filename, int flags = 0); // these constructors sets the error code on error - torrent_info(sha1_hash const& info_hash, error_code& ec); - torrent_info(lazy_entry const& torrent_file, error_code& ec); - torrent_info(char const* buffer, int size, error_code& ec); - torrent_info(fs::path const& filename, error_code& ec); - torrent_info(fs::wpath const& filename, error_code& ec); + torrent_info(sha1_hash const& info_hash, error_code& ec, int flags = 0); + torrent_info(lazy_entry const& torrent_file, error_code& ec, int flags = 0); + torrent_info(char const* buffer, int size, error_code& ec, int flags = 0); + torrent_info(fs::path const& filename, error_code& ec, int flags = 0); + torrent_info(fs::wpath const& filename, error_code& ec, int flags = 0); void add_tracker(std::string const& url, int tier = 0); std::vector<announce_entry> const& trackers() const; @@ -1585,17 +1603,17 @@ public:

    torrent_info()

    -torrent_info(sha1_hash const& info_hash);
-torrent_info(lazy_entry const& torrent_file);
-torrent_info(char const* buffer, int size);
-torrent_info(boost::filesystem::path const& filename);
-torrent_info(boost::filesystem::wpath const& filename);
+torrent_info(sha1_hash const& info_hash, int flags = 0);
+torrent_info(lazy_entry const& torrent_file, int flags = 0);
+torrent_info(char const* buffer, int size, int flags = 0);
+torrent_info(boost::filesystem::path const& filename, int flags = 0);
+torrent_info(boost::filesystem::wpath const& filename, int flags = 0);
 
-torrent_info(sha1_hash const& info_hash, error_code& ec);
-torrent_info(lazy_entry const& torrent_file, error_code& ec);
-torrent_info(char const* buffer, int size, error_code& ec);
-torrent_info(fs::path const& filename, error_code& ec);
-torrent_info(fs::wpath const& filename, error_code& ec);
+torrent_info(sha1_hash const& info_hash, error_code& ec, int flags = 0);
+torrent_info(lazy_entry const& torrent_file, error_code& ec, int flags = 0);
+torrent_info(char const* buffer, int size, error_code& ec, int flags = 0);
+torrent_info(fs::path const& filename, error_code& ec, int flags = 0);
+torrent_info(fs::wpath const& filename, error_code& ec, int flags = 0);

    The constructor that takes an info-hash will initialize the info-hash to the given value, @@ -1605,7 +1623,7 @@ from the swarm.

    The constructor that takes a lazy_entry will create a torrent_info object from the information found in the given torrent_file. The lazy_entry represents a tree node in an bencoded file. To load an ordinary .torrent file -into a lazy_entry, use lazy_bdecode(), see bdecode() bencode().

    +into a lazy_entry, use lazy_bdecode().

    The version that takes a buffer pointer and a size will decode it as a .torrent file and initialize the torrent_info object for you.

    The version that takes a filename will simply load the torrent file and decode it inside @@ -1616,6 +1634,7 @@ will simply set the error code to describe what went wrong and not fully initial torrent_info object. The overloads that do not take the extra error_code parameter will always throw if an error occurs. These overloads are not available when building without exception support.

    +

    The flags argument is currently unused.

    add_tracker()

    @@ -1686,25 +1705,26 @@ reverse_file_iterator rend_files() const;

    This class will need some explanation. First of all, to get a list of all files in the torrent, you can use begin_files(), end_files(), rbegin_files() and rend_files(). These will give you standard vector -iterators with the type file_entry.

    +iterators with the type internal_file_entry, which is an internal type.

    +

    You can resolve it into the public representation of a file (file_entry) +using the file_storage::at function, which takes an index and an iterator;

     struct file_entry
 {
-        boost::filesystem::path path;
+        std::string path;
         size_type offset;
         size_type size;
         size_type file_base;
-        std::string symlink_path;
-        boost::shared_ptr<sha1_hash> filehash;
+        time_t mtime;
+        sha1_hash filehash;
         bool pad_file:1;
         bool hidden_attribute:1;
         bool executable_attribute:1;
         bool symlink_attribute:1;
 };
    -

    The path is the full (relative) path of each file. i.e. if it is a multi-file -torrent, all the files starts with a directory with the same name as torrent_info::name(). -The filenames are encoded with UTF-8.

    +

    The path is the full path of this file. The paths are unicode strings +encoded in UTF-8.

    size is the size of the file (in bytes) and offset is the byte offset of the file within the torrent. i.e. the sum of all the sizes of the files before it in the list.

    @@ -1714,6 +1734,12 @@ if the file. In cases where multiple files are mapped into the same file though, the file_base should be set to an offset so that the different regions do not overlap. This is used when mapping "unselected" files into a so-called part file.

    +

    mtime is the modification time of this file specified in posix time.

    +

    symlink_path is the path which this is a symlink to, or empty if this is +not a symlink. This field is only used if the symlink_attribute is set.

    +

    filehash is a sha-1 hash of the content of the file, or zeroes, if no +file hash was present in the torrent file. It can be used to potentially +find alternative sources for the file.

    pad_file is set to true for files that are not part of the data of the torrent. They are just there to make sure the next file is aligned to a particular byte offset or piece boundry. These files should typically be hidden from an end user. They are @@ -1721,10 +1747,8 @@ not written to disk.

    hidden_attribute is true if the file was marked as hidden (on windows).

    executable_attribute is true if the file was marked as executable (posix)

    symlink_attribute is true if the file was a symlink. If this is the case -the symlink_path specifies the original location where the data for this file -was found.

    -

    filehash is a pointer that is set in case the torrent file included a sha1 hash -for this file. This may be use to look up more sources for this file on other networks.

    +the symlink_index refers to a string which specifies the original location +where the data for this file was found.

    num_files() file_at()

    @@ -3924,6 +3948,7 @@ struct session_settings bool low_prio_disk; int local_service_announce_interval; int dht_announce_interval; + int dht_max_torrents; int udp_tracker_token_expiry; bool volatile_read_cache; @@ -3980,6 +4005,8 @@ struct session_settings bool rate_limit_utp; int listen_queue_size; + + bool announce_double_nat; };

    version is automatically set to the libtorrent version you're using @@ -4459,6 +4486,8 @@ This interval is specified in seconds.

    dht_announce_interval is the number of seconds between announcing torrents to the distributed hash table (DHT). This is specified to be 15 minutes which is its default.

    +

    dht_max_torrents is the max number of torrents we will track +in the DHT.

    udp_tracker_token_expiry is the number of seconds libtorrent will keep UDP tracker connection tokens around for. This is specified to be 60 seconds, and defaults to that. The higher this value is, the @@ -4642,6 +4671,9 @@ be sufficient for any normal client. If this is a high performance server which expects to receive a lot of connections, or used in a simulator or test, it might make sense to raise this number. It will not take affect until listen_on() is called again (or for the first time).

    +

    if announce_double_nat is true, the &ip= argument in tracker requests +(unless otherwise specified) will be set to the intermediate IP address, if the +user is double NATed. If ther user is not double NATed, this option has no affect.

    @@ -5108,6 +5140,44 @@ to automate the identification of clients. It will not be able to identify peers standard encodings. Only Azureus style, Shadow's style and Mainline style. This function is declared in the header <libtorrent/identify_client.hpp>.

    +
    +

    lazy_bdecode()

    +
    +
    +int lazy_bdecode(char const* start, char const* end, lazy_entry& ret
+        , error_code& ec, int* error_pos = 0, int depth_limit = 1000
+        , int item_limit = 1000000);
+
    +
    +

    This function decodes bencoded data.

    +

    Whenever possible, lazy_bdecode() should be preferred over bdecode(). +It is more efficient and more secure. It supports having constraints on the +amount of memory is consumed by the parser.

    +

    lazy refers to the fact that it doesn't copy any actual data out of the +bencoded buffer. It builds a tree of lazy_entry which has pointers into +the bencoded buffer. This makes it very fast and efficient. On top of that, +it is not recursive, which saves a lot of stack space when parsing deeply +nested trees. However, in order to protect against potential attacks, the +depth_limit and item_limit control how many levels deep the tree is +allowed to get. With recursive parser, a few thousand levels would be enough +to exhaust the threads stack and terminate the process. The item_limit +protects against very large structures, not necessarily deep. Each bencoded +item in the structure causes the parser to allocate some amount of memory, +this memory is constant regardless of how much data actually is stored in +the item. One potential attack is to create a bencoded list of hundreds of +thousands empty strings, which would cause the parser to allocate a significant +amount of memory, perhaps more than is available on the machine, and effectively +provide a denial of service. The default item limit is set as a reasonable +upper limit for desktop computers. Very few torrents have more items in them. +The limit corresponds to about 25 MB, which might be a bit much for embedded +systems.

    +

    start and end defines the bencoded buffer to be decoded. ret is +the lazy_entry which is filled in with the whole decoded tree. ec +is a reference to an error_code which is set to describe the error encountered +in case the function fails. error_pos is an optional pointer to an int, +which will be set to the byte offset into the buffer where an error occurred, +in case the function fails.

    +

    bdecode() bencode()

    @@ -5117,6 +5187,7 @@ template<class OutIt> void bencode(OutIt out, const entry& e);

    These functions will encode data to bencoded or decode bencoded data.

    +

    If possible, lazy_bdecode() should be preferred over bdecode().

    The entry class is the internal representation of the bencoded data and it can be used to retrieve information, an entry can also be build by the program and given to bencode() to encode it into the OutIt @@ -6923,6 +6994,30 @@ URL. i.e. it doesn't contain "announce. invalid_tracker_action invalid action field in udp tracker response +190 +expected_string +expected string in bencoded string + +191 +expected_colon +expected colon in bencoded string + +192 +unexpected_eof +unexpected end of file in bencoded string + +193 +expected_value +expected value (list, dict, int or string) in bencoded string + +194 +depth_exceeded +bencoded recursion depth limit exceeded + +195 +item_limit_exceeded +bencoded item count limit exceeded +

    The names of these error codes are declared in then libtorrent::errors namespace.

    diff --git a/docs/projects.html b/docs/projects.html index e82bc8d89..6e74fd684 100644 --- a/docs/projects.html +++ b/docs/projects.html @@ -2,6 +2,19 @@ + projects using libtorrent diff --git a/docs/python_binding.html b/docs/python_binding.html index 3d80b0e85..bb6e0aa3c 100644 --- a/docs/python_binding.html +++ b/docs/python_binding.html @@ -2,6 +2,19 @@ + libtorrent python binding diff --git a/docs/running_tests.html b/docs/running_tests.html index 43d07a129..0b6d250ad 100644 --- a/docs/running_tests.html +++ b/docs/running_tests.html @@ -2,6 +2,19 @@ + libtorrent manual diff --git a/docs/template.txt b/docs/template.txt index 411bb7324..0449f8d1f 100644 --- a/docs/template.txt +++ b/docs/template.txt @@ -1,4 +1,17 @@ %(head_prefix)s + %(head)s diff --git a/docs/tuning.html b/docs/tuning.html index dce4511d4..e33f88fb5 100644 --- a/docs/tuning.html +++ b/docs/tuning.html @@ -2,6 +2,19 @@ + libtorrent manual diff --git a/docs/udp_tracker_protocol.html b/docs/udp_tracker_protocol.html index 8778db217..0f5228553 100644 --- a/docs/udp_tracker_protocol.html +++ b/docs/udp_tracker_protocol.html @@ -2,6 +2,19 @@ + Bittorrent udp-tracker protocol extension diff --git a/docs/utp.html b/docs/utp.html index 4c6ae138c..f691d18a5 100644 --- a/docs/utp.html +++ b/docs/utp.html @@ -2,6 +2,19 @@ + libtorrent manual