From 382d582407f24c059797ac7a205439f259a20859 Mon Sep 17 00:00:00 2001 From: Arvid Norberg Date: Wed, 27 Nov 2013 20:09:44 +0000 Subject: [PATCH] more documentation --- include/libtorrent/disk_buffer_holder.hpp | 21 +++++++++++++++++++ include/libtorrent/error_code.hpp | 4 ++++ include/libtorrent/lazy_entry.hpp | 24 ++++++++++++++++++++-- include/libtorrent/session.hpp | 14 ++++++++++++- include/libtorrent/utf8.hpp | 25 +++++++++++++++++++++-- src/utf8.cpp | 4 ++-- 6 files changed, 85 insertions(+), 7 deletions(-) diff --git a/include/libtorrent/disk_buffer_holder.hpp b/include/libtorrent/disk_buffer_holder.hpp index a19c8c8c0..7f599762e 100644 --- a/include/libtorrent/disk_buffer_holder.hpp +++ b/include/libtorrent/disk_buffer_holder.hpp @@ -53,12 +53,31 @@ namespace libtorrent // this buffer has been released, ``buffer()`` will return 0. struct TORRENT_EXPORT disk_buffer_holder { + // internal disk_buffer_holder(aux::session_impl& ses, char* buf); + + // construct a buffer holder that will free the held buffer + // using a disk buffer pool directly (there's only one + // disk_buffer_pool per session) disk_buffer_holder(disk_buffer_pool& disk_pool, char* buf); + + // frees any unreleased disk buffer held by this object ~disk_buffer_holder(); + + // return the held disk buffer and clear it from the + // holder. The responsibility to free it is passed on + // to the caller char* release(); + + // return a pointer to the held buffer char* get() const { return m_buf; } + + // set the holder object to hold the specified buffer + // (or NULL by default). If it's already holding a + // disk buffer, it will first be freed. void reset(char* buf = 0); + + // swap pointers of two disk buffer holders. void swap(disk_buffer_holder& h) { TORRENT_ASSERT(&h.m_disk_pool == &m_disk_pool); @@ -66,6 +85,8 @@ namespace libtorrent } typedef char* (disk_buffer_holder::*unspecified_bool_type)(); + + // internal operator unspecified_bool_type() const { return m_buf == 0? 0: &disk_buffer_holder::release; } diff --git a/include/libtorrent/error_code.hpp b/include/libtorrent/error_code.hpp index dc816afea..463f8beda 100644 --- a/include/libtorrent/error_code.hpp +++ b/include/libtorrent/error_code.hpp @@ -507,7 +507,11 @@ namespace libtorrent { return boost::system::error_condition(ev, *this); } }; + // return the instance of the libtorrent_error_category which + // maps libtorrent error codes to human readable error messages. TORRENT_EXPORT boost::system::error_category& get_libtorrent_category(); + + // returns the error_category for HTTP errors TORRENT_EXPORT boost::system::error_category& get_http_category(); namespace errors diff --git a/include/libtorrent/lazy_entry.hpp b/include/libtorrent/lazy_entry.hpp index 347805124..b26002eb0 100644 --- a/include/libtorrent/lazy_entry.hpp +++ b/include/libtorrent/lazy_entry.hpp @@ -140,6 +140,7 @@ namespace libtorrent none_t, dict_t, list_t, string_t, int_t }; + // internal lazy_entry() : m_begin(0), m_len(0), m_size(0), m_capacity(0), m_type(none_t) { m_data.start = 0; } @@ -239,6 +240,12 @@ namespace libtorrent boost::int64_t dict_find_int_value(char const* name, boost::int64_t default_val = 0) const; lazy_entry const* dict_find_int(char const* name) const; + // these functions require that ``this`` is a dictionary. + // (this->type() == dict_t). They look for an element with the + // specified name in the dictionary. ``dict_find_dict`` only + // finds dictionaries and ``dict_find_list`` only finds lists. + // if no key with the corresponding value of the right type is + // found, NULL is returned. lazy_entry const* dict_find_dict(char const* name) const; lazy_entry const* dict_find_list(char const* name) const; @@ -246,7 +253,8 @@ namespace libtorrent // position ``i`` from the dictionary. std::pair dict_at(int i) const; - // if this is a dictionary, return the number of items in it + // requires that ``this`` is a dictionary. return the + // number of items in it int dict_size() const { TORRENT_ASSERT(m_type == dict_t); @@ -266,7 +274,8 @@ namespace libtorrent // internal lazy_entry* list_append(); - // if this is a list, return the item at index ``i``. + // requires that ``this`` is a list. return + // the item at index ``i``. lazy_entry* list_at(int i) { TORRENT_ASSERT(m_type == list_t); @@ -276,8 +285,19 @@ namespace libtorrent lazy_entry const* list_at(int i) const { return const_cast(this)->list_at(i); } + // these functions require ``this`` to have the type list. + // (this->type() == list_t). ``list_string_value_at`` returns + // the string at index ``i``. ``list_pstr_at`` + // returns a pascal_string of the string value at index ``i``. + // if the element at ``i`` is not a string, an empty string + // is returned. std::string list_string_value_at(int i) const; pascal_string list_pstr_at(int i) const; + + // this function require ``this`` to have the type list. + // (this->type() == list_t). returns the integer value at + // index ``i``. If the element at ``i`` is not an integer + // ``default_val`` is returned, which defaults to 0. boost::int64_t list_int_value_at(int i, boost::int64_t default_val = 0) const; // if this is a list, return the number of items in it. diff --git a/include/libtorrent/session.hpp b/include/libtorrent/session.hpp index 5b616d500..6469f8cb0 100644 --- a/include/libtorrent/session.hpp +++ b/include/libtorrent/session.hpp @@ -556,11 +556,23 @@ namespace libtorrent void set_ip_filter(ip_filter const& f); ip_filter get_ip_filter() const; + // apply port_filter ``f`` to incoming and outgoing peers. + // a port filter will reject making outgoing peer connections + // to certain remote ports. The main intention is to be able + // to avoid triggering certain anti-virus software by connecting + // to SMTP, FTP ports. void set_port_filter(port_filter const& f); + + // sets and gets the raw peer ID used by libtorrent. When anonymous + // mode is set the peer ID is randomized per peer anyway. void set_peer_id(peer_id const& pid); - void set_key(int key); peer_id id() const; + // sets the key sent to trackers. If it's not set, it is initialized + // by libtorrent. The key may be used by the tracker to identify the + // peer potentially across you changing your IP. + void set_key(int key); + // ``is_listening()`` will tell you whether or not the session has successfully // opened a listening port. If it hasn't, this function will return false, and diff --git a/include/libtorrent/utf8.hpp b/include/libtorrent/utf8.hpp index 6270391b9..480ecbaeb 100644 --- a/include/libtorrent/utf8.hpp +++ b/include/libtorrent/utf8.hpp @@ -44,8 +44,29 @@ POSSIBILITY OF SUCH DAMAGE. namespace libtorrent { - TORRENT_EXPORT int utf8_wchar(const std::string &utf8, std::wstring &wide); - TORRENT_EXPORT int wchar_utf8(const std::wstring &wide, std::string &utf8); + enum utf8_conv_result_t + { + // conversion successful + conversion_oK, + + // partial character in source, but hit end + source_exhausted, + + // insuff. room in target for conversion + target_exhausted, + + // source sequence is illegal/malformed + source_illegal + }; + + // ``utf8_wchar`` converts a UTF-8 string (``utf8``) to a wide character + // string (``wide``). ``wchar_utf8`` converts a wide character string + // (``wide``) to a UTF-8 string (``utf8``). The return value is one of + // the enumeration values from utf8_conv_result_t. + TORRENT_EXPORT utf8_conv_result_t utf8_wchar( + const std::string &utf8, std::wstring &wide); + TORRENT_EXPORT utf8_conv_result_t wchar_utf8( + const std::wstring &wide, std::string &utf8); } #endif // !BOOST_NO_STD_WSTRING diff --git a/src/utf8.cpp b/src/utf8.cpp index a7c64e0f3..6c37c103f 100644 --- a/src/utf8.cpp +++ b/src/utf8.cpp @@ -40,7 +40,7 @@ POSSIBILITY OF SUCH DAMAGE. namespace libtorrent { - int utf8_wchar(const std::string &utf8, std::wstring &wide) + utf8_conv_result_t utf8_wchar(const std::string &utf8, std::wstring &wide) { // allocate space for worst-case wide.resize(utf8.size()); @@ -69,7 +69,7 @@ namespace libtorrent } } - int wchar_utf8(const std::wstring &wide, std::string &utf8) + utf8_conv_result_t wchar_utf8(const std::wstring &wide, std::string &utf8) { // allocate space for worst-case utf8.resize(wide.size() * 6);