From 46f309f8b9e9e0bf3649c8f379a0030669df1579 Mon Sep 17 00:00:00 2001 From: Arvid Norberg Date: Mon, 12 May 2014 06:28:47 +0000 Subject: [PATCH] update and regenerate documentation --- AUTHORS | 12 ++-- docs/building.html | 2 +- docs/client_test.html | 2 +- docs/contributing.html | 2 +- docs/dht_extensions.html | 2 +- docs/dht_sec.html | 2 +- docs/dht_store.html | 2 +- docs/examples.html | 2 +- docs/extension_protocol.html | 2 +- docs/features.html | 2 +- docs/hacking.html | 2 +- docs/projects.html | 2 +- docs/python_binding.html | 2 +- docs/reference-Bencoding.html | 20 ++++-- docs/reference-Core.html | 116 +++++++++++++++++++++++++++------ docs/reference.html | 2 + docs/todo.html | 115 +++++++++++++++++++++++--------- docs/troubleshooting.html | 2 +- docs/tuning.html | 2 +- docs/udp_tracker_protocol.html | 2 +- docs/utp.html | 2 +- 21 files changed, 217 insertions(+), 80 deletions(-) diff --git a/AUTHORS b/AUTHORS index 5a3d84e12..6c82ec790 100644 --- a/AUTHORS +++ b/AUTHORS @@ -1,11 +1,11 @@ - -Written by Arvid Norberg. Copyright (c) 2003-2007 - -Lots of testing, suggestions and contributions by: -Massaroddel -Tianhao Qiu. +Written by Arvid Norberg. Copyright (c) 2003-2014 Contributions by: +Ajax16384 +Steven Siloti +Thomas Fischer +Massaroddel +Tianhao Qiu. Shyam Magnus Jonsson Daniel Wallin diff --git a/docs/building.html b/docs/building.html index dc66bd43c..39b4cad99 100644 --- a/docs/building.html +++ b/docs/building.html @@ -3,7 +3,7 @@ - + libtorrent manual diff --git a/docs/client_test.html b/docs/client_test.html index fa8432a9f..37f13bf31 100644 --- a/docs/client_test.html +++ b/docs/client_test.html @@ -3,7 +3,7 @@ - + client_test example program diff --git a/docs/contributing.html b/docs/contributing.html index 311242c77..876b7b0a7 100644 --- a/docs/contributing.html +++ b/docs/contributing.html @@ -3,7 +3,7 @@ - + libtorrent manual diff --git a/docs/dht_extensions.html b/docs/dht_extensions.html index 95ded2db6..82dd107a4 100644 --- a/docs/dht_extensions.html +++ b/docs/dht_extensions.html @@ -3,7 +3,7 @@ - + diff --git a/docs/dht_sec.html b/docs/dht_sec.html index 7a429b3dc..b13d7611a 100644 --- a/docs/dht_sec.html +++ b/docs/dht_sec.html @@ -3,7 +3,7 @@ - + BitTorrent DHT security extension diff --git a/docs/dht_store.html b/docs/dht_store.html index 485ebde3f..4a825f285 100644 --- a/docs/dht_store.html +++ b/docs/dht_store.html @@ -3,7 +3,7 @@ - + BitTorrent extension for arbitrary DHT store diff --git a/docs/examples.html b/docs/examples.html index d14e8b532..ff7de0014 100644 --- a/docs/examples.html +++ b/docs/examples.html @@ -3,7 +3,7 @@ - + libtorrent Examples diff --git a/docs/extension_protocol.html b/docs/extension_protocol.html index 858ca2713..d3d6bf4d0 100644 --- a/docs/extension_protocol.html +++ b/docs/extension_protocol.html @@ -3,7 +3,7 @@ - + diff --git a/docs/features.html b/docs/features.html index d08afd024..60a319bb1 100644 --- a/docs/features.html +++ b/docs/features.html @@ -3,7 +3,7 @@ - + libtorrent manual diff --git a/docs/hacking.html b/docs/hacking.html index a31d3229b..30aa2b929 100644 --- a/docs/hacking.html +++ b/docs/hacking.html @@ -3,7 +3,7 @@ - + libtorrent hacking diff --git a/docs/projects.html b/docs/projects.html index 25010b801..36eb691df 100644 --- a/docs/projects.html +++ b/docs/projects.html @@ -3,7 +3,7 @@ - + projects using libtorrent diff --git a/docs/python_binding.html b/docs/python_binding.html index 4dea95ade..1a4f6cd3f 100644 --- a/docs/python_binding.html +++ b/docs/python_binding.html @@ -3,7 +3,7 @@ - + libtorrent python binding diff --git a/docs/reference-Bencoding.html b/docs/reference-Bencoding.html index 6e9bdc071..93da5034d 100644 --- a/docs/reference-Bencoding.html +++ b/docs/reference-Bencoding.html @@ -55,11 +55,11 @@

Table of contents

Bencoding is a common representation in bittorrent used for @@ -768,6 +768,16 @@ is a reference to an error_code which is set t 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.

+ +
+

print_entry()

+

Declared in "libtorrent/lazy_entry.hpp"

+
+std::string print_entry (lazy_entry const& e
+   , bool single_line = false, int indent = 0);
+
+

print the bencoded structure in a human-readable format to a stting +that's returned.

diff --git a/docs/reference-Core.html b/docs/reference-Core.html index b310a91b1..bbee35336 100644 --- a/docs/reference-Core.html +++ b/docs/reference-Core.html @@ -55,15 +55,16 @@

Table of contents

@@ -133,6 +134,68 @@ disk buffer, it will first be freed.

void swap (disk_buffer_holder& h);

swap pointers of two disk buffer holders.

+
+ +
+

hasher

+

Declared in "libtorrent/hasher.hpp"

+

this is a SHA-1 hash class.

+

You use it by first instantiating it, then call update() to feed it +with data. i.e. you don't have to keep the entire buffer of which you want to +create the hash in memory. You can feed the hasher parts of it at a time. When +You have fed the hasher with all the data, you call final() and it +will return the sha1-hash of the data.

+

The constructor that takes a char const* and an integer will construct the +sha1 context and feed it the data passed in.

+

If you want to reuse the hasher object once you have created a hash, you have to +call reset() to reinitialize it.

+

The sha1-algorithm used was implemented by Steve Reid and released as public domain. +For more info, see src/sha1.cpp.

+
+class hasher
+{
+   hasher ();
+   hasher (const char* data, int len);
+   hasher& operator= (hasher const& h);
+   hasher (hasher const& h);
+   hasher& update (std::string const& data);
+   hasher& update (const char* data, int len);
+   sha1_hash final ();
+   void reset ();
+   ~hasher ();
+};
+
+
+

hasher()

+
+hasher (const char* data, int len);
+
+

this is the same as default constructing followed by a call to +update(data, len).

+
+
+

update()

+
+hasher& update (std::string const& data);
+hasher& update (const char* data, int len);
+
+

append the following bytes to what is being hashed

+
+
+

final()

+
+sha1_hash final ();
+
+

returns the SHA-1 digest of the buffers previously passed to +update() and the hasher constructor.

+
+
+

reset()

+
+void reset ();
+
+

restore the hasher state to be as if the hasher has just been +default constructed.

@@ -1049,6 +1112,9 @@ struct torrent_handle , std::string const& private_key , std::string const& dh_params , std::string const& passphrase = ""); + void set_ssl_certificate_buffer (std::string const& certificate + , std::string const& private_key + , std::string const& dh_params); storage_interface* get_storage_impl () const; boost::intrusive_ptr<torrent_info const> torrent_file () const; void use_interface (const char* net_interface) const; @@ -1124,7 +1190,7 @@ struct torrent_handle }; }; -
+

torrent_handle()

 torrent_handle ();
@@ -1668,18 +1734,26 @@ for the peers of this torrent. It defaults to false. If it is set to
 true, the peer_info structure for the peers in this torrent will have
 their country member set. See peer_info for more information on
 how to interpret this field.

+
-
-

set_ssl_certificate()

+
+

set_ssl_certificate_buffer() set_ssl_certificate()

 void set_ssl_certificate (std::string const& certificate
       , std::string const& private_key
       , std::string const& dh_params
       , std::string const& passphrase = "");
+void set_ssl_certificate_buffer (std::string const& certificate
+      , std::string const& private_key
+      , std::string const& dh_params);

For SSL torrents, use this to specify a path to a .pem file to use as this client's certificate. The certificate must be signed by the certificate in the .torrent file to be valid.

+

The set_ssl_certificate_buffer() overload takes the actual certificate, +private key and DH params as strings, rather than paths to files. This +overload is only available when libtorrent is built against boost +1.54 or later.

cert is a path to the (signed) certificate in .pem format corresponding to this torrent.

private_key is a path to the private key for the specified @@ -2317,7 +2391,7 @@ struct torrent_status sha1_hash info_hash; }; -

+

operator==()

 bool operator== (torrent_status const& st) const;
@@ -2325,7 +2399,7 @@ bool operator== (torrent_status const& st) const;
 
compres if the torrent status objects come from the same torrent. i.e.
 only the torrent_handle field is compared.
-
+

enum state_t

Declared in "libtorrent/torrent_handle.hpp"

@@ -2875,7 +2949,7 @@ 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.

-
+

reset()

 void reset ();
@@ -3091,7 +3165,7 @@ class torrent_info : public intrusive_ptr_base<torrent_info>
    bool is_merkle_torrent () const;
 };
-
+

torrent_info()

 torrent_info (std::string const& filename, int flags = 0);
@@ -3123,7 +3197,7 @@ always throw if an error occurs. These overloads are not available when building
 exception support.

 
The flags argument is currently unused.
-
+

~torrent_info()

 ~torrent_info ();
@@ -3148,7 +3222,7 @@ names. Filename may be chaged using file_storage object, see the separate document on how
 to create torrents.
-
+

rename_file()

 void rename_file (int index, std::string const& new_filename);
@@ -3233,7 +3307,7 @@ the piece index as argument and gives you the exact size of that piece. It will
 be the same as piece_length() except in the case of the last piece, which may
 be smaller.
-
+

info_hash()

 const sha1_hash& info_hash () const;
@@ -3280,7 +3354,7 @@ std::string ssl_cert () const;
 torrent. Otherwise returns an empty string. The certificate is
 the the public certificate in x509 format.
-
+

is_valid()

 bool is_valid () const;
@@ -3393,7 +3467,7 @@ lazy_entry const* info (char const* key) const;
 It can be used to access extension values put in the .torrent file. If the specified
 key cannot be found, it returns NULL.
-
+

swap()

 void swap (torrent_info& ti);
diff --git a/docs/reference.html b/docs/reference.html
index 4760db30f..e08a16f4a 100644
--- a/docs/reference.html
+++ b/docs/reference.html
@@ -56,6 +56,7 @@
 
Core

 

 
disk_buffer_holder

+
hasher

 
peer_info

 
peer_request

 
block_info

@@ -113,6 +114,7 @@
 
bencode()

 
operator<<()

 
lazy_bdecode()

+
print_entry()
diff --git a/docs/todo.html b/docs/todo.html index 79bdc3b17..9186c452e 100644 --- a/docs/todo.html +++ b/docs/todo.html @@ -24,7 +24,7 @@ 2 important 6 relevant 13 feasible -45 notes +46 notes
relevance 4../src/session_impl.cpp:666in order to support SSL over uTP, the utp_socket manager either needs to be able to receive packets on multiple ports, or we need to peek into the first few bytes the payload stream of a socket to determine whether or not it's an SSL connection. (The former is simpler but won't do as well with NATs)
relevance 3../src/torrent.cpp:6111if peer is a really good peer, maybe we shouldn't disconnect it
relevance 3../src/torrent.cpp:6151if peer is a really good peer, maybe we shouldn't disconnect it
relevance 2../src/policy.cpp:155this could be optimized if SSE 4.2 is available. It could also be optimized given that we have a fixed length
relevance 1../src/torrent.cpp:5372save the send_stats state instead of throwing them away it may pose an issue when downgrading though
relevance 1../src/torrent.cpp:5412save the send_stats state instead of throwing them away it may pose an issue when downgrading though
relevance 1../src/torrent.cpp:6279should disconnect all peers that have the pieces we have not just seeds. It would be pretty expensive to check all pieces for all peers though
relevance 1../src/torrent.cpp:6319should disconnect all peers that have the pieces we have not just seeds. It would be pretty expensive to check all pieces for all peers though
relevance 0../src/file.cpp:1400is there any way to pre-fetch data from a file on windows?
relevance 0../src/file.cpp:1404is there any way to pre-fetch data from a file on windows?
relevance 0../src/torrent.cpp:5105make this more generic to not just work if files have been renamed, but also if they have been merged into a single file for instance maybe use the same format as .torrent files and reuse some code from torrent_info The mapped_files needs to be read both in the network thread and in the disk thread, since they both have their own mapped files structures which are kept in sync
relevance 0../src/torrent.cpp:5145make this more generic to not just work if files have been renamed, but also if they have been merged into a single file for instance maybe use the same format as .torrent files and reuse some code from torrent_info The mapped_files needs to be read both in the network thread and in the disk thread, since they both have their own mapped files structures which are kept in sync
relevance 0../src/torrent.cpp:5281if this is a merkle torrent and we can't restore the tree, we need to wipe all the bits in the have array, but not necessarily we might want to do a full check to see if we have all the pieces. This is low priority since almost no one uses merkle torrents
relevance 0../src/torrent.cpp:5429make this more generic to not just work if files have been renamed, but also if they have been merged into a single file for instance. using file_base
relevance 0../src/torrent.cpp:5469make this more generic to not just work if files have been renamed, but also if they have been merged into a single file for instance. using file_base
relevance 0../src/torrent.cpp:8005go through the pieces we have and count the total number of downloaders we have. Only count peers that are interested in us since some peers might not send have messages for pieces we have it num_interested == 0, we need to pick a new piece
relevance 0../src/udp_tracker_connection.cpp:550it would be more efficient to not use a string here. however, the problem is that some trackers will respond with actual strings. For example i2p trackers
relevance 0../src/udp_socket.cpp:292it would be nice to detect this on posix systems also
relevance 0../src/udp_tracker_connection.cpp:550it would be more efficient to not use a string here. however, the problem is that some trackers will respond with actual strings. For example i2p trackers
relevance 0../src/upnp.cpp:65listen_interface is not used. It's meant to bind the broadcast socket
relevance 0../src/upnp.cpp:65listen_interface is not used. It's meant to bind the broadcast socket
relevance 0../src/utp_stream.cpp:1606this loop may not be very efficient
relevance 0../src/utp_stream.cpp:1606this loop may not be very efficient
relevance 0../src/kademlia/dht_tracker.cpp:428ideally this function would be called when the put completes
relevance 0../src/kademlia/dht_tracker.cpp:428ideally this function would be called when the put completes
relevance 0../src/kademlia/routing_table.cpp:293instad of refreshing a bucket by using find_nodes, ping each node periodically
relevance 0../include/libtorrent/config.hpp:327Make this count Unicode characters instead of bytes on windows
relevance 0../include/libtorrent/config.hpp:327Make this count Unicode characters instead of bytes on windows
relevance 0../include/libtorrent/peer_connection.hpp:725make this private
relevance 0../include/libtorrent/peer_connection.hpp:725make this private
relevance 0../include/libtorrent/peer_connection.hpp:806make these private as well
relevance 0../include/libtorrent/peer_connection.hpp:806make these private as well
relevance 0../include/libtorrent/proxy_base.hpp:166it would be nice to remember the bind port and bind once we know where the proxy is m_sock.bind(endpoint, ec);
relevance 0../include/libtorrent/proxy_base.hpp:166it would be nice to remember the bind port and bind once we know where the proxy is m_sock.bind(endpoint, ec);
relevance 0../include/libtorrent/stat.hpp:113this is 4 bytes of padding!
relevance 0../include/libtorrent/stat.hpp:113this is 4 bytes of padding!
relevance 0../include/libtorrent/torrent.hpp:1333there's space for another bit here
relevance 0../include/libtorrent/torrent.hpp:1336there's space for another bit here
relevance 0../include/libtorrent/torrent_info.hpp:123include the number of peers received from this tracker, at last announce
relevance 0../include/libtorrent/torrent_info.hpp:123include the number of peers received from this tracker, at last announce
relevance 0../include/libtorrent/upnp.hpp:108support using the windows API for UPnP operations as well
relevance 0../include/libtorrent/upnp.hpp:108support using the windows API for UPnP operations as well
relevance 0../include/libtorrent/utp_stream.hpp:378implement blocking write. Low priority since it's not used (yet)
relevance 0../include/libtorrent/utp_stream.hpp:378implement blocking write. Low priority since it's not used (yet)
relevance 0../include/libtorrent/kademlia/item.hpp:61since this is a public function, it should probably be moved out of this header and into one with other public functions.
relevance 0../include/libtorrent/kademlia/item.hpp:61since this is a public function, it should probably be moved out of this header and into one with other public functions.