From 782a3cfdc61a75547bb8122f6285310b800c996f Mon Sep 17 00:00:00 2001 From: Arvid Norberg Date: Mon, 21 Feb 2005 13:59:24 +0000 Subject: [PATCH] added the ability to get scrape data from the tracker announce reply --- docs/manual.html | 2386 ------------------------ docs/manual.rst | 24 +- include/libtorrent/torrent.hpp | 18 +- include/libtorrent/torrent_handle.hpp | 7 + include/libtorrent/tracker_manager.hpp | 5 +- src/http_tracker_connection.cpp | 26 +- src/session.cpp | 3 +- src/torrent.cpp | 15 +- src/torrent_handle.cpp | 22 + src/udp_tracker_connection.cpp | 12 +- 10 files changed, 116 insertions(+), 2402 deletions(-) diff --git a/docs/manual.html b/docs/manual.html index 07d0be9af..e69de29bb 100755 --- a/docs/manual.html +++ b/docs/manual.html @@ -1,2386 +0,0 @@ - - - - - - -libtorrent manual - - - -
-

libtorrent manual

-
-

Contents

- -
-
-

introduction

-

libtorrent is a C++ library that aims to be a good alternative to all the -other bittorrent implementations around. It is a -library and not a full featured client, although it comes with a working -example client.

-

The main goals of libtorrent are:

-
-
    -
  • to be cpu efficient
    • -
  • to be memory efficient
    • -
  • to be very easy to use
    • -
-
-

libtorrent is not finished. It is an ongoing project (including this documentation). -The current state includes the following features:

-
-
    -
  • multitracker extension support (as described by John Hoffman)
    • -
  • serves multiple torrents on a single port and a single thread
    • -
  • supports http proxies and proxy authentication
    • -
  • gzipped tracker-responses
    • -
  • piece picking on block-level like in Azureus (as opposed to piece-level).
    • -
  • queues torrents for file check, instead of checking all of them in parallel.
    • -
  • uses separate threads for checking files and for main downloader, with a fool-proof -thread-safe library interface. (i.e. There's no way for the user to cause a deadlock).
    • -
  • can limit the upload and download bandwidth usage and the maximum number of unchoked peers
    • -
  • piece-wise, unordered, file allocation
    • -
  • implements fair trade. User settable trade-ratio, must at least be 1:1, -but one can choose to trade 1 for 2 or any other ratio that isn't unfair to the other -party. (i.e. real tit for tat)
    • -
  • fast resume support, a way to get rid of the costly piece check at the start -of a resumed torrent. Saves the storage state, piece_picker state as well as all local -peers in a separate fast-resume file.
    • -
  • supports the extension protocol described by Nolar. See extensions.
    • -
  • supports files > 2 gigabytes.
    • -
  • supports the no_peer_id=1 extension that will ease the load off trackers.
    • -
  • supports the udp-tracker protocol by Olaf van der Spek.
    • -
  • possibility to limit the number of connections.
    • -
  • delays have messages if there's no other outgoing traffic to the peer, and doesn't -send have messages to peers that already has the piece. This saves bandwidth.
    • -
  • does not have any requirements on the piece order in a torrent that it resumes. This -means it can resume a torrent downloaded by any client.
    • -
  • adjusts the length of the request queue depending on download rate.
    • -
  • supports the compact=1 tracker parameter.
    • -
-
-

Functions that are yet to be implemented:

-
-
    -
  • better identification of peers that send bad data
    • -
  • ip-filters
    • -
  • file-level priority
    • -
-
-

libtorrent is portable at least among windows, macosx, and other UNIX-systems. It uses Boost.Thread, -Boost.Filesystem, Boost.Date_time and various other boost libraries as well as zlib.

-

libtorrent has been successfully compiled and tested on:

-
-
    -
  • Windows 2000 vc7.1
    • -
  • Linux x86 GCC 3.0.4, GCC 3.2.3, GCC 3.4.2
    • -
  • MacOS X, GCC 3.3
    • -
  • SunOS 5.8 GCC 3.1
    • -
  • Cygwin GCC 3.3.3
    • -
-
-

Fails on:

-
-
    -
  • GCC 2.95.4 (std::ios_base is missing)
    • -
  • msvc6 sp5
    • -
-
-

libtorrent is released under the BSD-license.

-
-
-

downloading and building

-

To acquire the latest version of libtorrent, you'll have to grab it from CVS. You'll find instructions -on how to do this here (see Anonymous CVS access).

-

The easiest way to build libtorrent is probably to use boost-build. Make sure you install it -correctly by setting the environment variable BOOST_BUILD_PATH and modifying the -user_config.jam to reflect the toolsets you have installed.

-

You also need to install boost 1.31.0.

-

Before you invoke bjam you have to set the environment variable BOOST_ROOT to the -path where you installed boost. This will be used to build and link against the required -boost libraries as well as be used as include path for boost headers.

-

To build you just have to run:

-
-bjam <toolset> link=static
-
-

in the libtorrent directory.

-

If you're building on a platform where dlls share the same heap, you can build libtorrent -as a dll too, by typing link=shared instead of link=static.

-

To build on MacOS X, you need the latest version of boost-build, from the boost cvs.

-

If you're making your own project file, note that there are two versions of the file -abstraction. There's one file_win.cpp which relies on windows file API that supports -files larger than 2 Gigabytes. This does not work in vc6 for some reason, possibly because -it may require windows NT and above. The other file, file.cpp is the default -implementation that simply relies on the standard low level io routines (read, write etc.), -but for some reason this implementation doesn't seem to work on windows.

-
-

cygwin and msvc

-

Note that if you're building on windows using the msvc toolset, you cannot run it -from a cygwin terminal, you'll have to run it from a cmd terminal. The same goes for -cygwin, if you're building with gcc (mingw) you'll have to run it from a cygwin terminal. -Also, make sure the paths are correct in the different environments. In cygwin, the paths -(BOOST_BUILD_PATH and BOOST_ROOT) should be in the typical unix-format (e.g. -/cygdrive/c/boost_1_31_0). In the windows environment, they should have the typical -windows format (c:/boost_1_31_0).

-

If you're building in developer studio, you may have to set the compiler options -"force conformance in for loop scope", "treat wchar_t as built-in type" and -"Enable Run-Time Type Info" to Yes.

-

If you're building in developer studio 6, you will probably have to use the previous -version of boost, boost 1.30.2. And you'll definately have to use at least service -pack 5 (sp5).

-
-
-

release and debug builds

-

The Jamfile can build both a release and debug version of libtorrent. In debug mode, -libtorrent will have pretty expensive invariant checks and asserts built into it. If you -want to disable such checks (you want to do that in a release build) you can see the -table below for which defines you can use to control the build. The Jamfile will define -NDEBUG when it's building a release build.

- ---- - - - - - - - - - - - - - - - - -
macrodescription
NDEBUGIf you define this macro, all asserts, -invariant checks and general debug code will be -removed. This option takes precedence over -other debug settings.
TORRENT_VERBOSE_LOGGINGIf you define this macro, every peer connection -will log its traffic to a log file. -This setting requires a debug build, i.e. -if you set NDEBUG aswell, no logs will be -written.
TORRENT_STORAGE_DEBUGThis will enable extra expensive invariant -checks in the storage, including logging of -piece sorting.
-

If you experience that libtorrent uses unreasonable amounts of cpu, it will definately help to -define NDEBUG.

-
-
-
-

using

-

The interface of libtorrent consists of a few classes. The main class is -the session, it contains the main loop that serves all torrents.

-

The basic usage is as follows:

-
    -

  • conststruct a session

    -
    • -

  • parse .torrent-files and add them to the session (see bdecode() bencode())

    -
    • -
  • -
    main loop (see session)
    -
      -
    • query the torrent_handles for progress (see torrent_handle)
      • -
    • query the session for information
      • -
    • add and remove torrents from the session at run-time
      • -
    -
    -
    -
    • -

  • destruct all torrent_handles

    -
    • -

  • destruct session object

    -
    • -
-

Each class and function is described in this manual.

-
-
-

session

-

The session class has the following synopsis:

-
-class session: public boost::noncopyable
-{
-
-        session(const fingerprint& print = libtorrent::fingerprint("LT", 0, 1, 0, 0));
-
-        session(
-                const fingerprint& print
-                , std::pair<int, int> listen_port_range
-                , const char* listen_interface = 0);
-
-        torrent_handle add_torrent(
-                entry const& e
-                , boost::filesystem::path const& save_path
-                , entry const& resume_data = entry());
-
-        torrent_handle add_torrent(
-                char const* tracker_url
-                , sha1_hash const& info_hash
-                , boost::filesystem::path const& save_path
-                , entry const& resume_data = entry());
-
-        void remove_torrent(torrent_handle const& h);
-
-        void disable_extensions();
-        void enable_extension(peer_connection::extension_index);
-
-        void set_http_settings(const http_settings& settings);
-
-        void set_upload_rate_limit(int bytes_per_second);
-        void set_download_rate_limit(int bytes_per_second);
-        void set_max_uploads(int limit);
-        void set_max_connections(int limit);
-
-        session_status status() const;
-
-        bool is_listening() const;
-        unsigned short listen_port() const;
-        bool listen_on(
-                std::pair<int, int> const& port_range
-                , char const* interface = 0);
-
-
-        std::auto_ptr<alert> pop_alert();
-        void set_severity_level(alert::severity_t s);
-};
-
-

Once it's created, the session object will spawn the main thread that will do all the work. -The main thread will be idle as long it doesn't have any torrents to participate in.

-
-

session()

-
-
-session(const fingerprint& print = libtorrent::fingerprint("LT", 0, 1, 0, 0));
-session(
-        const fingerprint& print
-        , std::pair<int, int> listen_port_range
-        , const char* listen_interface = 0);
-
-
-

If the fingerprint in the first overload is ommited, the client will get a default -fingerprint stating the version of libtorrent. The fingerprint is a short string that will be -used in the peer-id to identify the client and the client's version. For more details see the -fingerprint class. The constructor that only takes a fingerprint will not open a -listen port for the session, to get it running you'll have to call session::listen_on(). -The other constructor, that takes a port range and an interface as well as the fingerprint -will automatically try to listen on a port on the given interface. For more information about -the parameters, see listen_on() function.

-
-
-

~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. All this before the destructor of session -returns. So, it's adviced that any kind of interface (such as windows) are closed before -destructing the sessoin object. Because it can take a few second for it to finish. The -timeout can be set with set_http_settings().

-
-
-

add_torrent()

-
-
-torrent_handle add_torrent(
-        entry const& e
-        , boost::filesystem::path const& save_path
-        , entry const& resume_data = entry());
-torrent_handle add_torrent(
-        char const* tracker_url
-        , sha1_hash const& info_hash
-        , boost::filesystem::path const& save_path
-        , entry const& resume_data = entry());
-
-
-

You add torrents through the add_torrent() function where you give an -object representing the information found in the torrent file and the path where you -want to save the files. The save_path will be prepended to the directory -structure in the torrent-file.

-

If the torrent you are trying to add already exists in the session (is either queued -for checking, being checked or downloading) add_torrent() will throw -duplicate_torrent which derives from std::exception.

-

The optional last 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 -torrent_handle::write_resume_data(). See fast resume.

-

The torrent_handle returned by add_torrent() can be used to retrieve information -about the torrent's progress, its peers etc. It is also used to abort a torrent.

-

The second overload that takes a tracker url and an info-hash instead of metadata (entry) -can be used with torrents where (at least some) peers support the metadata extension. For -the overload to be available, libtorrent must be built with extensions enabled -(TORRENT_ENABLE_EXTENSIONS defined).

-
-
-

remove_torrent()

-
-
-void remove_torrent(torrent_handle const& h);
-
-
-

remove_torrent() will close all peer connections associated with the torrent and tell -the tracker that we've stopped participating in the swarm.

-
-
-

disable_extensions() enable_extension()

-
-
-void disable_extensions();
-void enable_extension(peer_connection::extension_index);
-
-
-

disable_extensions() will disable all extensions available in libtorrent. -enable_extension() will enable a single extension. The available extensions -are enumerated in the peer_connection class. These are the available extensions:

-
-enum extension_index
-{
-        extended_chat_message,
-        extended_metadata_message,
-        extended_peer_exchange_message,
-        extended_listen_port_message,
-        num_supported_extensions
-};
-
-

peer_exchange is not implemented yet

-

By default, all extensions are enabled. -For more information about the extensions, see the extensions section.

-
-
-

set_upload_rate_limit() set_download_rate_limit()

-
-
-void set_upload_rate_limit(int bytes_per_second);
-void set_download_rate_limit(int bytes_per_second);
-
-
-

set_upload_rate_limit() set the maximum number of bytes allowed to be -sent to peers per second. This bandwidth is distributed among all the peers. If -you don't want to limit upload rate, you can set this to -1 (the default). -set_download_rate_limit() works the same way but for download rate instead -of upload rate.

-
-
-

set_max_uploads() set_max_connections()

-
-
-void set_max_uploads(int limit);
-void set_max_connections(int limit);
-
-
-

These functions will set a global limit on the number of unchoked peers (uploads) -and the number of connections opened. The number of connections is set to a hard -minimum of at least two connections per torrent, so if you set a too low -connections limit, and open too many torrents, the limit will not be met. The -number of uploads is at least one per torrent.

-
-
-

status()

-
-
-session_status status() const;
-
-
-

status() returns session wide-statistics and status. The session_status -struct has the following members:

-
-struct session_status
-{
-        bool has_incoming_connections;
-
-        float upload_rate;
-        float download_rate;
-
-        float payload_upload_rate;
-        float payload_download_rate;
-
-        size_type total_download;
-        size_type total_upload;
-
-        size_type total_payload_download;
-        size_type total_payload_upload;
-
-        int num_peers;
-};
-
-

has_incoming_connections is false as long as no incoming connections have been -established on the listening socket. Every time you change the listen port, this will -be reset to false.

-

upload_rate, download_rate, payload_download_rate and payload_upload_rate -are the total download and upload rates accumulated from all torrents. The payload -versions is the payload download only.

-

total_download and total_upload are the total number of bytes downloaded and -uploaded to and from all torrents. total_payload_download and total_payload_upload -are the same thing but where only the payload is considered.

-

num_peers is the total number of peer connections this session have.

-
-
-

is_listening() listen_port() listen_on()

-
-
-bool is_listening() const;
-unsigned short listen_port() const;
-bool listen_on(
-        std::pair<int, int> const& port_range
-        , char const* interface = 0);
-
-
-

is_listening() will tell you wether or not the session has successfully -opened a listening port. If it hasn't, this function will return false, and -then you can use listen_on() to make another try.

-

listen_port() returns the port we ended up listening on. Since you just pass -a port-range to the constructor and to listen_on(), to know which port it -ended up using, you have to ask the session using this function.

-

listen_on() will change the listen port and/or the listen interface. If the -session is already listening on a port, this socket will be closed and a new socket -will be opened with these new settings. The port range is the ports it will try -to listen on, if the first port fails, it will continue trying the next port within -the range and so on. The interface parameter can be left as 0, in that case the -os will decide which interface to listen on, otherwise it should be the ip-address -of the interface you want the listener socket bound to. listen_on() returns true -if it managed to open the socket, and false if it failed. If it fails, it will also -generate an appropriate alert (listen_failed_alert).

-

The interface parameter can also be a hostname that will resolve to the device you -want to listen on.

-
-
-

pop_alert() set_severity_level()

-
-
-std::auto_ptr<alert> pop_alert();
-void set_severity_level(alert::severity_t s);
-
-
-

pop_alert() is used to ask the session if any errors or events has occured. With -set_severity_level() you can filter how serious the event has to be for you to -receive it through pop_alert(). For information, see alerts.

-
-
-
-

entry

-

The entry class represents one node in a bencoded hierarchy. It works as a -variant type, it can be either a list, a dictionary (std::map), an integer -or a string. This is its synopsis:

-
-class entry
-{
-public:
-
-        typedef std::list<std::pair<std::string, entry> > dictionary_type;
-        typedef std::string string_type;
-        typedef std::list<entry> list_type;
-        typedef size_type integer_type;
-
-        enum data_type
-        {
-                int_t,
-                string_t,
-                list_t,
-                dictionary_t,
-                undefined_t
-        };
-
-        data_type type() const;
-
-        entry(const dictionary_type&);
-        entry(const string_type&);
-        entry(const list_type&);
-        entry(const integer_type&);
-
-        entry();
-        entry(data_type t);
-        entry(const entry& e);
-        ~entry();
-
-        void operator=(const entry& e);
-        void operator=(const dictionary_type&);
-        void operator=(const string_type&);
-        void operator=(const list_type&);
-        void operator=(const integer_type&);
-
-        integer_type& integer();
-        integer_type const& integer() const;
-        string_type& string();
-        string_type const& string() const;
-        list_type& list();
-        list_type const& list() const;
-        dictionary_type& dict();
-        dictionary_type const& dict() const;
-
-        // these functions requires that the entry
-        // is a dictionary, otherwise they will throw   
-        entry& operator[](char const* key);
-        entry& operator[](std::string const& key);
-        const entry& operator[](char const* key) const;
-        const entry& operator[](std::string const& key) const;
-        entry* find_key(char const* key);
-        entry const* find_key(char const* key) const;
-        
-        void print(std::ostream& os, int indent = 0) const;
-};
-
-

TODO: finish documentation of entry.

-
-

integer() string() list() dict() type()

-
-
-integer_type& integer();
-integer_type const& integer() const;
-string_type& string();
-string_type const& string() const;
-list_type& list();
-list_type const& list() const;
-dictionary_type& dict();
-dictionary_type const& dict() const;
-
-
-

The integer(), string(), list() and dict() functions -are accessors that return the respecive type. If the entry object isn't of the -type you request, the accessor will throw type_error (which derives from -std::runtime_error). You can ask an entry for its type through the -type() function.

-

The print() function is there for debug purposes only.

-

If you want to create an entry you give it the type you want it to have in its -constructor, and then use one of the non-const accessors to get a reference which you then -can assign the value you want it to have.

-

The typical code to get info from a torrent file will then look like this:

-
-entry torrent_file;
-// ...
-
-const entry::dictionary_type& dict = torrent_file.dict();
-entry::dictionary_type::const_iterator i;
-i = dict.find("announce");
-if (i != dict.end())
-{
-        std::string tracker_url= i->second.string();
-        std::cout << tracker_url << "\n";
-}
-
-

To make it easier to extract information from a torren file, the class torrent_info -exists.

-
-
-
-

torrent_info

-

The torrent_info has the following synopsis:

-
-class torrent_info
-{
-public:
-
-        torrent_info();
-        torrent_info(sha1_hash const& info_hash);
-        torrent_info(entry const& torrent_file);
-
-        entry create_torrent() const;
-        void set_comment(char const* str);
-        void set_piece_size(int size);
-        void set_creator(char const* str);
-        void set_hash(int index, const sha1_hash& h);
-        void add_tracker(std::string const& url, int tier = 0);
-        void add_file(boost::filesystem::path file, size_type size);
-
-        typedef std::vector<file_entry>::const_iterator file_iterator;
-        typedef std::vector<file_entry>::const_reverse_iterator reverse_file_iterator;
-
-        file_iterator begin_files() const;
-        file_iterator end_files() const;
-        reverse_file_iterator rbegin_files() const;
-        reverse_file_iterator rend_files() const;
-
-        int num_files() const;
-        file_entry const& file_at(int index) const;
-
-        std::vector<announce_entry> const& trackers() const;
-
-        size_type total_size() const;
-        size_type piece_length() const;
-        int num_pieces() const;
-        const sha1_hash& info_hash() const;
-        const std::stirng& name() const;
-        const std::string& comment() const;
-
-        boost::optional<boost::posix_time::ptime>
-        creation_date() const;
-
-
-        void print(std::ostream& os) const;
-
-        size_type piece_size(unsigned int index) const;
-        const sha1_hash& hash_for_piece(unsigned int index) const;
-};
-
-
-

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

-
-
-file_iterator begin_files() const;
-file_iterator end_files() const;
-reverse_file_iterator rbegin_files() const;
-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.

-
-struct file_entry
-{
-        boost::filesystem::path path;
-        size_type size;
-};
-
-
-
-

num_files() file_at()

-
-
-int num_files() const;
-const file_entry& file_at(int index) const;
-
-
-

If you need index-access to files you can use the num_files() and file_at() -to access files using indices.

-
-
-

print()

-
-
-void print(std::ostream& os) const;
-
-
-

The print() function is there for debug purposes only. It will print the info from -the torrent file to the given outstream.

-
-
-

trackers()

-
-
-const std::vector<announce_entry>& trackers() const;
-
-
-

The trackers() function will return a sorted vector of announce_entry. -Each announce entry contains a string, which is the tracker url, and a tier index. The -tier index is the high-level priority. No matter which trackers that works or not, the -ones with lower tier will always be tried before the one with higher tier number.

-
-struct announce_entry
-{
-        announce_entry(std::string const& url);
-        std::string url;
-        int tier;
-};
-
-
-
-

total_size() piece_length() piece_size() num_pieces()

-
-
-size_type total_size() const;
-size_type piece_length() const;
-size_type piece_size(unsigned int index) const;
-int num_pieces() const;
-
-
-

total_size(), piece_length() and num_pieces() returns the total -number of bytes the torrent-file represents (all the files in it), the number of byte for -each piece and the total number of pieces, respectively. The difference between -piece_size() and piece_length() is that piece_size() takes -the piece index as argument and gives you the exact size of that piece. It will always -be the same as piece_length() except in the case of the last piece, which may -be smaller.

-
-
-

hash_for_piece() info_hash()

-
-
-size_type piece_size(unsigned int index) const;
-const sha1_hash& hash_for_piece(unsigned int index) const;
-
-
-

hash_for_piece() takes a piece-index and returns the 20-bytes sha1-hash for that -piece and info_hash() returns the 20-bytes sha1-hash for the info-section of the -torrent file. For more information on the sha1_hash, see the big_number class.

-
-
-

name() comment() creation_date()

-
-
-const std::stirng& name() const;
-const std::string& comment() const;
-boost::optional<boost::posix_time::ptime> creation_date() const;
-
-
-

name() returns the name of the torrent.

-

comment() returns the comment associated with the torrent. If there's no comment, -it will return an empty string. creation_date() returns a boost::posix_time::ptime -object, representing the time when this torrent file was created. If there's no timestamp -in the torrent file, this will return a date of january 1:st 1970.

-
-
-
-

torrent_handle

-

You will usually have to store your torrent handles somewhere, since it's the -object through which you retrieve infromation about the torrent and aborts the torrent. -Its declaration looks like this:

-
-struct torrent_handle
-{
-        torrent_handle();
-
-        torrent_status status();
-        void get_download_queue(std::vector<partial_piece_info>& queue);
-        void get_peer_info(std::vector<peer_info>& v);
-        torrent_info const& get_torrent_info();
-        bool is_valid();
-
-        entry write_resume_data();
-        std::vector<char> const& metadata() const;
-        void force_reannounce();
-        void connect_peer(address const& adr) const;
-
-        void set_tracker_login(std::string const& username, std::string const& password);
-
-        std::vector<announce_entry> const& trackers() const;
-        void replace_trackers(std::vector<announce_entry> const&);
-
-        void set_ratio(float ratio);
-        void set_max_uploads(int max_uploads);
-        void set_max_connections(int max_connections);
-        void set_upload_limit(int limit);
-        void set_download_limit(int limit);
-        void use_interface(char const* net_interface);
-
-        void pause();
-        void resume();
-        bool is_paused() const;
-        bool is_seed() const;
-
-        bool has_metadata() const;
-
-        boost::filsystem::path save_path() const;
-        bool move_storage(boost::filesystem::path const& save_path);
-
-        sha1_hash info_hash() const;
-
-        bool operator==(const torrent_handle&) const;
-        bool operator!=(const torrent_handle&) const;
-        bool operator<(const torrent_handle&) const;
-};
-
-

The default constructor will initialize the handle to an invalid state. Which means you cannot -perform any operation on it, unless you first assign it a valid handle. If you try to perform -any operation on an uninitialized handle, it will throw invalid_handle.

-

TODO: document trackers() and replace_trackers()

-
-

save_path()

-
-
-boost::filsystem::path save_path() const;
-
-
-

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

-
-
-

move_storage()

-
-
-bool move_storage(boost::filsystem::path const& save_path);
-
-
-

Moves the file(s) that this torrent are currently seeding from or downloading to. This -operation will only have the desired effect if the given save_path is located on -the same drive as the original save path. If the move operation fails, this function -returns false, otherwise true. Post condition for successful operation is: -save_path() == save_path.

-
-
-

force_reannounce()

-
-
-void force_reannounce();
-
-
-

force_reannounce() will force this torrent to do another tracker request, to receive new -peers. If the torrent is invalid, queued or in checking mode, this functions will throw -invalid_handle.

-
-
-

connect_peer()

-
-
-void connect_peer(address const& adr) const;
-
-
-

connect_peer() is a way to manually connect to peers that one believe is a part of the -torrent. If the peer does not respond, or is not a member of this torrent, it will simply -be disconnected. No harm can be done by using this other than an unnecessary connection -attempt is made. If the torrent is uninitialized or in queued or checking mode, this -will throw invalid_handle.

-
-
-

set_ratio()

-
-
-void set_ratio(float ratio);
-
-
-

set_ratio() sets the desired download / upload ratio. If set to 0, it is considered being -infinite. i.e. the client will always upload as much as it can, no matter how much it gets back -in return. With this setting it will work much like the standard clients.

-

Besides 0, the ratio can be set to any number greater than or equal to 1. It means how much to -attempt to upload in return for each download. e.g. if set to 2, the client will try to upload -2 bytes for every byte received. The default setting for this is 0, which will make it work -as a standard client.

-
-
-

set_upload_limit() set_download_limit()

-
-
-void set_upload_limit(int limit);
-void set_download_limit(int limit);
-
-
-

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) -will not override the global rate limit. The torrent can never upload more than the global rate -limit.

-
-
-

pause() resume() is_paused()

-
-
-void pause();
-void resume();
-bool is_paused() const;
-
-
-

pause(), and resume() will disconnect all peers and reconnect all peers respectively. -When a torrent is paused, it will however remember all share ratios to all peers and remember -all potential (not connected) peers. You can use is_paused() to determine if a torrent -is currently paused. Torrents may be paused automatically if there is a file error (eg. disk full) -or something similar. See file_error_alert.

-
-
-

is_seed()

-
-
-bool is_seed() const;
-
-
-

Returns true if the torrent is in seed mode (i.e. if it has finished downloading).

-

has_metadata()

-
-
-bool has_metadata() const;
-
-
-

Returns true if this torrent has metadata (either it was started from a .torrent file or the -metadata has been downloaded). The only scenario where this can return false is when the torrent -was started torrent-less (i.e. with just an info-hash and tracker ip). Note that if the torrent -doesn't have metadata, the member get_torrent_info() will throw.

-
-
-

set_tracker_login()

-
-
-void set_tracker_login(std::string const& username, std::string const& password);
-
-
-

set_tracker_login() sets a username and password that will be sent along in the HTTP-request -of the tracker announce. Set this if the tracker requires authorization.

-
-
-

use_interface()

-
-
-void use_interface(char const* net_interface);
-
-
-

use_interface() sets the network interface this torrent will use when it opens outgoing -connections. By default, it uses the same interface as the session uses to listen on. The -parameter can be a string containing an ip-address or a hostname.

-
-
-

info_hash()

-
-
-sha1_hash info_hash() const;
-
-
-

info_hash() returns the info-hash for the torrent.

-
-
-

set_max_uploads() set_max_connections()

-
-
-void set_max_uploads(int max_uploads);
-void set_max_connections(int max_connections);
-
-
-

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.

-

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.

-
-
-

write_resume_data()

-
-
-entry write_resume_data();
-
-
-

write_resume_data() generates fast-resume data and returns it as an entry. This entry -is suitable for being bencoded. For more information about how fast-resume works, see fast resume.

-

There are three cases where this function will just return an empty entry:

-
-
    -
  1. The torrent handle is invalid.
    2. -
  2. The torrent is checking (or is queued for checking) its storage, it will obviously -not be ready to write resume data.
    3. -
  3. The torrent hasn't received valid metadata and was started without metadata -(see libtorrent's metadata from peers extension)
    4. -
-
-

Note that by the time this function returns, the resume data may already be invalid if the torrent -is still downloading! The recommended practice is to first pause the torrent, then generate the -fast resume data, and then close it down.

-
-
-

metadata()

-
-
-std::vector<char> const& metadata() const;
-
-
-

metadata() will return a reference to a buffer containing the exact info part of the -.torrent file. This buffer will be valid as long as the torrent is still running. When hashed, -it will produce the same hash as the info-hash.

-
-
-

status()

-
-
-torrent_status status();
-
-
-

status() will return a structure with information about the status of this -torrent. If the torrent_handle is invalid, it will throw invalid_handle exception. -See torrent_status.

-
-
-

get_download_queue()

-
-
-void get_download_queue(std::vector<partial_piece_info>& queue);
-
-
-

get_download_queue() takes a non-const reference to a vector which it will fill with -information about pieces that are partially downloaded or not downloaded at all but partially -requested. The entry in the vector (partial_piece_info) looks like this:

-
-struct partial_piece_info
-{
-        enum { max_blocks_per_piece };
-        int piece_index;
-        int blocks_in_piece;
-        std::bitset<max_blocks_per_piece> requested_blocks;
-        std::bitset<max_blocks_per_piece> finished_blocks;
-        peer_id peer[max_blocks_per_piece];
-        int num_downloads[max_blocks_per_piece];
-};
-
-

piece_index is the index of the piece in question. blocks_in_piece is the -number of blocks in this particular piece. This number will be the same for most pieces, but -the last piece may have fewer blocks than the standard pieces.

-

requested_blocks is a bitset with one bit per block in the piece. If a bit is set, it -means that that block has been requested, but not necessarily fully downloaded yet. To know -from whom the block has been requested, have a look in the peer array. The bit-index -in the requested_blocks and finished_blocks correspons to the array-index into -peers and num_downloads. The array of peers is contains the id of the -peer the piece was requested from. If a piece hasn't been requested (the bit in -requested_blocks is not set) the peer array entry will be undefined.

-

The finished_blocks is a bitset where each bit says if the block is fully downloaded -or not. And the num_downloads array says how many times that block has been downloaded. -When a piece fails a hash verification, single blocks may be redownloaded to see if the hash teast -may pass then.

-
-
-

get_peer_info()

-
-
-void get_peer_info(std::vector<peer_info>&);
-
-
-

get_peer_info() takes a reference to a vector that will be cleared and filled -with one entry for each peer connected to this torrent, given the handle is valid. If the -torrent_handle is invalid, it will throw invalid_handle exception. Each entry in -the vector contains information about that particular peer. See peer_info.

-
-
-

get_torrent_info()

-
-
-torrent_info const& get_torrent_info();
-
-
-

Returns a const reference to the torrent_info object associated with this torrent. -This reference is valid as long as the torrent_handle is valid, no longer. If the -torrent_handle is invalid or if it doesn't have any metadata, invalid_handle -exception will be thrown. The torrent may be in a state without metadata only if -it was started without a .torrent file, i.e. by using the libtorrent extension of -just supplying a tracker and info-hash.

-
-
-

is_valid()

-
-
-bool is_valid() const;
-
-
-

Returns true if this handle refers to a valid torrent and false if it hasn't been initialized -or if the torrent it refers to has been aborted. Note that a handle may become invalid after -it has been added to the session. Usually this is because the storage for the torrent is -somehow invalid or if the filenames are not allowed (and hence cannot be opened/created) on -your filesystem. If such an error occurs, a file_error_alert is generated and all handles -that refers to that torrent will become invalid.

-
-
-
-

torrent_status

-

It contains the following fields:

-
-struct torrent_status
-{
-        enum state_t
-        {
-                queued_for_checking,
-                checking_files,
-                connecting_to_tracker,
-                downloading,
-                seeding
-        };
-
-        state_t state;
-        bool paused;
-        float progress;
-        boost::posix_time::time_duration next_announce;
-        boost::posix_time::time_duration announce_interval;
-
-        std::string current_tracker;
-
-        size_type total_download;
-        size_type total_upload;
-
-        size_type total_payload_download;
-        size_type total_payload_upload;
-
-        size_type total_failed_bytes;
-
-        float download_rate;
-        float upload_rate;
-
-        float download_payload_rate;
-        float upload_payload_rate;
-
-        int num_peers;
-
-        const std::vector<bool>* pieces;
-        size_type total_done;
-
-        int num_seeds;
-        float distributed_copies;
-
-        int block_size;
-};
-
-

progress is a value in the range [0, 1], that represents the progress of the -torrent's current task. It may be checking files or downloading. The torrent's -current task is in the state member, it will be one of the following:

- ---- - - - - - - - - - - - - - - - - - -
queued_for_checkingThe torrent is in the queue for being checked. But there -currently is another torrent that are being checked. -This torrent will wait for its turn.
checking_filesThe torrent has not started its download yet, and is -currently checking existing files.
connecting_to_trackerThe torrent has sent a request to the tracker and is -currently waiting for a response
downloadingThe torrent is being downloaded. This is the state -most torrents will be in most of the time. The progress -meter will tell how much of the files that has been -downloaded.
seedingIn this state the torrent has finished downloading and -is a pure seeder.
-

paused is set to true if the torrent is paused and false otherwise.

-

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.

-

current_tracker is the URL of the last working tracker. If no tracker request has -been successful yet, it's set to an empty string.

-

total_download and total_upload is the number of bytes downloaded and -uploaded to all peers, accumulated, this session only.

-

total_payload_download and total_payload_upload counts the amount of bytes -send and received this session, but only the actual oayload data (i.e the interesting -data), these counters ignore any protocol overhead.

-

total_failed_bytes is the number of bytes that has been downloaded and that -has failed the piece hash test. In other words, this is just how much crap that -has been downloaded.

-

pieces is the bitmask that represents which pieces we have (set to true) and -the pieces we don't have. It's a pointer and may be set to 0 if the torrent isn't -downloading or seeding.

-

download_rate and upload_rate are the total rates for all peers for this -torrent. These will usually have better precision than summing the rates from -all peers. The rates are given as the number of bytes per second. The -download_payload_rate and upload_payload_rate respectively is the -total transfer rate of payload only, not counting protocol chatter. This might -be slightly smaller than the other rates, but if projected over a long time -(e.g. when calculating ETA:s) the difference may be noticable.

-

num_peers is the number of peers this torrent currently is connected to.

-

total_done is the total number of bytes of the file(s) that we have. All -this does not necessarily has to be downloaded during this session (that's -total_download_payload).

-

num_seeds is the number of peers that are seeding that this client is -currently connected to.

-

distributed_copies is the number of distributed copies of the torrent. -Note that one copy may be spread out among many peers. The integer part -tells how many copies there are currently of the rarest piece(s) among the -peers this client is connected to. The fractional part tells the share of -pieces that have more copies than the rarest piece(s). For example: 2.5 would -mean that the rarest pieces have only 2 copies among the peers this torrent is -connected to, and that 50% of all the pieces have more than two copies.

-

block_size is the size of a block, in bytes. A block is a sub piece, it -is the number of bytes that each piece request asks for and the number of -bytes that each bit in the partial_piece_info's bitset represents -(see get_download_queue()). This is typically 16 kB, but it may be -larger if the pieces are larger.

-
-
-

peer_info

-

It contains the following fields:

-
-struct peer_info
-{
-        enum
-        {
-                interesting = 0x1,
-                choked = 0x2,
-                remote_interested = 0x4,
-                remote_choked = 0x8,
-                supports_extensions = 0x10,
-                local_connection = 0x20
-        };
-        unsigned int flags;
-        address ip;
-        float up_speed;
-        float down_speed;
-        size_type total_download;
-        size_type total_upload;
-        peer_id id;
-        std::vector<bool> pieces;
-        bool seed;
-        int upload_limit;
-        int upload_ceiling;
-
-        size_type load_balancing;
-
-        int download_queue_length;
-        int upload_queue_length;
-
-        int downloading_piece_index;
-        int downloading_block_index;
-        int downloading_progress;
-        int downloading_total;
-};
-
-

The flags attribute tells you in which state the peer is. It is set to -any combination of the enums above. The following table describes each flag:

- ---- - - - - - - - - - - - - - - - - - -
interestingwe are interested in pieces from this peer.
chokedwe have choked this peer.
remote_interested -remote_chokedmeans the same thing but that the peer is interested -in pieces from us and the peer has choked us.
support_extensionsmeans that this peer supports the -extension protocol.
local_connectionThe connection was initiated by us, the peer has a -listen port open, and that port is the same is in the -address of this peer. If this flag is not set, this -peer connection was opened by this peer connecting to -us.
-

The ip field is the IP-address to this peer. Its type is a wrapper around the -actual address and the port number. See address class.

-

up_speed and down_speed is the current upload and download speed -we have to and from this peer. These figures are updated aproximately once every second.

-

total_download and total_upload are the total number of bytes downloaded -from and uploaded to this peer. These numbers do not include the protocol chatter, but only -the payload data.

-

id is the peer's id as used in the bit torrent protocol. This id can be used to -extract 'fingerprints' from the peer. Sometimes it can tell you which client the peer -is using. See identify_client()_

-

pieces is a vector of booleans that has as many entries as there are pieces -in the torrent. Each boolean tells you if the peer has that piece (if it's set to true) -or if the peer miss that piece (set to false).

-

seed is true if this peer is a seed.

-

upload_limit is the number of bytes per second we are allowed to send to this -peer every second. It may be -1 if there's no limit. The upload limits of all peers -should sum up to the upload limit set by session::set_upload_limit.

-

upload_ceiling is the current maximum allowed upload rate given the cownload -rate and share ratio. If the global upload rate is inlimited, the upload_limit -for every peer will be the same as their upload_ceiling.

-

load_balancing is a measurment of the balancing of free download (that we get) -and free upload that we give. Every peer gets a certain amount of free upload, but -this member says how much extra free upload this peer has got. If it is a negative -number it means that this was a peer from which we have got this amount of free -download.

-

download_queue_length is the number of piece-requests we have sent to this peer -that hasn't been answered with a piece yet.

-

upload_queue_length is the number of piece-requests we have received from this peer -that we haven't answered with a piece yet.

-

You can know which piece, and which part of that piece, that is currently being -downloaded from a specific peer by looking at the next four members. -downloading_piece_index is the index of the piece that is currently being downloaded. -This may be set to -1 if there's currently no piece downloading from this peer. If it is ->= 0, the other three members are valid. downloading_block_index is the index of the -block (or sub-piece) that is being downloaded. downloading_progress is the number -of bytes of this block we have received from the peer, and downloading_total is -the total number of bytes in this block.

-
-
-

address

-

The address class represents a name of a network endpoint (usually referred to as -IP-address) and a port number. This is the same thing as a sockaddr_in would contain. -Its declaration looks like this:

-
-class address
-{
-public:
-        address();
-        address(unsigned char a
-                , unsigned char b
-                , unsigned char c
-                , unsigned char d
-                , unsigned short  port);
-        address(unsigned int addr, unsigned short port);
-        address(const std::string& addr, unsigned short port);
-        address(const address& a);
-        ~address();
-
-        std::string as_string() const;
-        unsigned int ip() const;
-        unsigned short port() const;
-
-        bool operator<(const address& a) const;
-        bool operator!=(const address& a) const;
-        bool operator==(const address& a) const;
-};
-
-

It is less-than comparable to make it possible to use it as a key in a map. as_string() may block -while it does the DNS lookup, it returns a string that points to the address represented by the object.

-

ip() will return the 32-bit ip-address as an integer. port() returns the port number.

-
-
-

http_settings

-

You have some control over tracker requests through the http_settings object. You -create it and fill it with your settings and then use session::set_http_settings() -to apply them. You have control over proxy and authorization settings and also the user-agent -that will be sent to the tracker. The user-agent is a good way to identify your client.

-
-struct http_settings
-{
-        http_settings();
-        std::string proxy_ip;
-        int proxy_port;
-        std::string proxy_login;
-        std::string proxy_password;
-        std::string user_agent;
-        int tracker_timeout;
-        int tracker_maximum_response_length;
-};
-
-

proxy_ip may be a hostname or ip to a http proxy to use. If this is -an empty string, no http proxy will be used.

-

proxy_port is the port on which the http proxy listens. If proxy_ip -is empty, this will be ignored.

-

proxy_login should be the login username for the http proxy, if this -empty, the http proxy will be trid to be used without authentication.

-

proxy_password the password string for the http proxy.

-

user_agent this is the client identification to the tracker. It will -be followed by the string "(libtorrent)" to identify that this library -is being used. This should be set to your client's name and version number.

-

tracker_timeout is the number of seconds the tracker connection will -wait until it considers the tracker to have timed-out. Default value is 10 -seconds.

-

tracker_maximum_response_length is the maximum number of bytes in a -tracker response. If a response size passes this number it will be rejected -and the connection will be closed. On gzipped responses this size is measured -on the uncompressed data. So, if you get 20 bytes of gzip response that'll -expand to 2 megs, it will be interrupted before the entire response has been -uncompressed (given your limit is lower than 2 megs). Default limit is -1 megabyte.

-
-
-

big_number

-

Both the peer_id and sha1_hash types are typedefs of the class -big_number. It represents 20 bytes of data. Its synopsis follows:

-
-class big_number
-{
-public:
-        bool operator==(const big_number& n) const;
-        bool operator!=(const big_number& n) const;
-        bool operator<(const big_number& n) const;
-
-        const unsigned char* begin() const;
-        const unsigned char* end() const;
-
-        unsigned char* begin();
-        unsigned char* end();
-};
-
-

The iterators gives you access to individual bytes.

-
-
-

hasher

-

This class creates sha1-hashes. Its declaration looks like this:

-
-class hasher
-{
-public:
-        hasher();
-
-        void update(const char* data, unsigned int len);
-        sha1_hash final();
-        void reset();
-};
-
-

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.

-

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.c.

-
-
-

fingerprint

-

The fingerprint class represents information about a client and its version. It is used -to encode this information into the client's peer id.

-

This is the class declaration:

-
-struct fingerprint
-{
-        fingerprint(const char* id_string, int major, int minor, int revision, int tag);
-
-        std::string to_string() const;
-
-        char id[2];
-        char major_version;
-        char minor_version;
-        char revision_version;
-        char tag_version;
-
-};
-
-

The constructor takes a char const* that should point to a string constant containing -exactly two characters. These are the characters that should be unique for your client. Make -sure not to clash with anybody else. Here are some taken id's:

- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
id charsclient
'AZ'Azureus
'LT'libtorrent (default)
'BX'BittorrentX
'MT'Moonlight Torrent
'TS'Torrent Storm
'SS'Swarm Scope
'XT'Xan Torrent
-

The major, minor, revision and tag parameters are used to identify the -version of your client. All these numbers must be within the range [0, 9].

-

to_string() will generate the actual string put in the peer-id, and return it.

-
-
-

free functions

-
-

identify_client()

-
-
-std::string identify_client(peer_id const& id);
-
-
-

This function is declared in the header <libtorrent/identify_client.hpp>. 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.

-
-
-

bdecode() bencode()

-
-
-template<class InIt> entry bdecode(InIt start, InIt end);
-template<class OutIt> void bencode(OutIt out, const entry& e);
-
-
-

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

-

The entry class is the internal representation of the bencoded data -and it can be used to retreive information, an entry can also be build by -the program and given to bencode() to encode it into the OutIt -iterator.

-

The OutIt and InIt are iterators -(InputIterator_ and OutputIterator_ respectively). They -are templates and are usually instantiated as ostream_iterator_, -back_insert_iterator_ or istream_iterator_. These -functions will assume that the iterator refers to a character -(char). So, if you want to encode entry e into a buffer -in memory, you can do it like this:

-
-std::vector<char> buffer;
-bencode(std::back_insert_iterator<std::vector<char> >(buf), e);
-
-

If you want to decode a torrent file from a buffer in memory, you can do it like this:

-
-std::vector<char> buffer;
-// ...
-entry e = bdecode(buf.begin(), buf.end());
-
-

Or, if you have a raw char buffer:

-
-const char* buf;
-// ...
-entry e = bdecode(buf, buf + data_size);
-
-

Now we just need to know how to retrieve information from the entry.

-

If bdecode() encounters invalid encoded data in the range given to it -it will throw invalid_encoding.

-
-
-
-

alerts

-

The pop_alert() function on session is the interface for retrieving -alerts, warnings, messages and errors from libtorrent. If there hasn't -occured any errors (matching your severity level) pop_alert() will -return a zero pointer. If there has been some error, it will return a pointer -to an alert object describing it. You can then use the alert object and query -it for information about the error or message. To retrieve any alerts, you have -to select a severity level using session::set_severity_level(). It defaults to -alert::none, which means that you don't get any messages at all, ever. -You have the following levels to select among:

- ---- - - - - - - - - - - - - - - - - - - - - -
noneNo alert will ever have this severity level, which -effectively filters all messages.
fatalFatal errors will have this severity level. Examples can -be disk full or something else that will make it -impossible to continue normal execution.
criticalSignals errors that requires user interaction or -messages that almost never should be ignored. For -example, a chat message received from another peer is -announced as severity critical.
warningMessages with the warning severity can be a tracker that -times out or responds with invalid data. It will be -retried automatically, and the possible next tracker in -a multitracker sequence will be tried. It does not -require any user interaction.
infoEvents that can be considered normal, but still deserves -an event. This could be a piece hash that fails.
debugThis will include alot of debug events that can be used -both for debugging libtorrent but also when debugging -other clients that are connected to libtorrent. It will -report strange behaviors among the connected peers.
-

When setting a severity level, you will receive messages of that severity and all -messages that are more sever. If you set alert::none (the default) you will not recieve -any events at all.

-

When you set a severuty level other than none, you have the responsibility to call -pop_alert() from time to time. If you don't do that, the alert queue will just grow.

-

When you get an alert, you can use typeid() or dynamic_cast<> to get more detailed -information on exactly which type it is. i.e. what kind of error it is. You can also use a -dispatcher mechanism that's available in libtorrent.

-

All alert types are defined in the <libtorrent/alert_types.hpp> header file.

-

The alert class is the base class that specific messages are derived from. This -is its synopsis:

-
-class alert
-{
-public:
-
-        enum severity_t { debug, info, warning, critital, fatal, none };
-
-        alert(severity_t severity, const std::string& msg);
-        virtual ~alert();
-
-        std::string const& msg() const;
-        severity_t severity() const;
-
-        virtual std::auto_ptr<alert> clone() const = 0;
-};
-
-

This means that all alerts have at least a string describing it. They also -have a severity level that can be used to sort them or present them to the -user in different ways.

-

The specific alerts, that all derives from alert, are:

-
-

listen_failed_alert

-

This alert is generated when none of the ports, given in the port range, to -session can be opened for listening. This alert is generated as severity -level fatal.

-
-struct listen_failed_alert: alert
-{
-        listen_failed_alert(const std::string& msg);
-        virtual std::auto_ptr<alert> clone() const;
-};
-
-
-
-

file_error_alert

-

If the storage fails to read or write files that it needs access to, this alert is -generated and the torrent is paused. It is generated as severity level fatal.

-
-struct file_error_alert: alert
-{
-        file_error_alert(
-                const torrent_handle& h
-                , const std::string& msg);
-                
-        virtual std::auto_ptr<alert> clone() const;
-
-        torrent_handle handle;
-};
-
-
-
-

tracker_alert

-

This alert is generated on tracker time outs, premature disconnects, invalid response or -a HTTP response other than "200 OK". From the alert you can get the handle to the torrent -the tracker belongs to. This alert is generated as severity level warning.

-

The times_in_row member says how many times in a row this tracker has failed.

-
-struct tracker_alert: alert
-{
-        tracker_alert(const torrent_handle& h, int times
-                , const std::string& msg);
-        virtual std::auto_ptr<alert> clone() const;
-
-        torrent_handle handle;
-        int times_in_row;
-};
-
-
-
-

hash_failed_alert

-

This alert is generated when a finished piece fails its hash check. You can get the handle -to the torrent which got the failed piece and the index of the piece itself from the alert. -This alert is generated as severity level info.

-
-struct hash_failed_alert: alert
-{
-        hash_failed_alert(
-                const torrent_handle& h
-                , int index
-                , const std::string& msg);
-
-        virtual std::auto_ptr<alert> clone() const;
-
-        torrent_handle handle;
-        int piece_index;
-};
-
-
-
-

peer_ban_alert

-

This alert is generated when a peer is banned because it has sent too many corrupt pieces -to us. It is generated at severity level info. The handle member is a torrent_handle -to the torrent that this peer was a member of.

-
-struct peer_ban_alert: alert
-{
-        peer_ban_alert(
-                address const& pip
-                , torrent_handle h
-                , const std::string& msg);
-
-        virtual std::auto_ptr<alert> clone() const;
-
-        address ip;
-        torrent_handle handle;
-};
-
-
-
-

peer_error_alert

-

This alert is generated when a peer sends invalid data over the peer-peer protocol. The peer -will be disconnected, but you get its ip address from the alert, to identify it. This alert -is generated as severity level debug.

-
-struct peer_error_alert: alert
-{
-        peer_error_alert(
-                address const& pip
-                , peer_id const& pid
-                , const std::string& msg);
-
-        virtual std::auto_ptr<alert> clone() const;
-
-        address ip;
-        peer_id id;
-};
-
-
-
-

invalid_request_alert

-

This is a debug alert that is generated by an incoming invalid piece request. The handle -is a handle to the torrent the peer is a member of. ìp is the address of the peer and the -request is the actual incoming request from the peer. The alert is generated as severity level -debug.

-
-struct invalid_request_alert: alert
-{
-        invalid_request_alert(
-                peer_request const& r
-                , torrent_handle const& h
-                , address const& send
-                , peer_id const& pid
-                , std::string const& msg);
-
-        virtual std::auto_ptr<alert> clone() const;
-
-        torrent_handle handle;
-        address ip;
-        peer_request request;
-        peer_id id;
-};
-
-
-struct peer_request
-{
-        int piece;
-        int start;
-        int length;
-        bool operator==(peer_request const& r) const;
-};
-
-

The peer_request contains the values the client sent in its request message. piece is -the index of the piece it want data from, start is the offset within the piece where the data -should be read, and length is the amount of data it wants.

-
-
-

torrent_finished_alert

-

This alert is generated when a torrent switches from being a downloader to a seed. -It will only be generated once per torrent. It contains a torrent_handle to the -torrent in question. This alert is generated as severity level info.

-
-struct torrent_finished_alert: alert
-{
-        torrent_finished_alert(
-                const torrent_handle& h
-                , const std::string& msg);
-
-        virtual std::auto_ptr<alert> clone() const;
-
-        torrent_handle handle;
-};
-
-
-
-

metadata_received_alert

-

This alert is generated when the metadata has been completely received and the torrent -can start downloading. It is not generated on torrents that are started with metadata, but -only those that needs to download it from peers (when utilizing the libtorrent extension). -It is generated at severity level info.

-
-struct metadata_received_alert: alert
-{
-        metadata_received_alert(
-                const torrent_handle& h
-                , const std::string& msg);
-                
-        virtual std::auto_ptr<alert> clone() const;
-
-        torrent_handle handle;
-};
-
- -
-
-

dispatcher

-

TODO: describe the dispatcher mechanism

-
-
-
-

exceptions

-

There are a number of exceptions that can be thrown from different places in libtorrent, -here's a complete list with description.

-
-

invalid_handle

-

This exception is thrown when querying information from a torrent_handle that hasn't -been initialized or that has become invalid.

-
-struct invalid_handle: std::exception
-{
-        const char* what() const throw();
-};
-
-
-
-

duplicate_torrent

-

This is thrown by add_torrent() if the torrent already has been added to -the session.

-
-struct duplicate_torrent: std::exception
-{
-        const char* what() const throw();
-};
-
-
-
-

invalid_encoding

-

This is thrown by bdecode() if the input data is not a valid bencoding.

-
-struct invalid_encoding: std::exception
-{
-        const char* what() const throw();
-};
-
-
-
-

type_error

-

This is thrown from the accessors of entry if the data type of the entry doesn't -match the type you want to extract from it.

-
-struct type_error: std::runtime_error
-{
-        type_error(const char* error);
-};
-
-
-
-

invalid_torrent_file

-

This exception is thrown from the constructor of torrent_info if the given bencoded information -doesn't meet the requirements on what information has to be present in a torrent file.

-
-struct invalid_torrent_file: std::exception
-{
-        const char* what() const throw();
-};
-
-
-
-
-

examples

-
-

dump_torrent

-

This is an example of a program that will take a torrent-file as a parameter and -print information about it to std out:

-
-#include <iostream>
-#include <fstream>
-#include <iterator>
-#include <exception>
-#include <iomanip>
-
-#include "libtorrent/entry.hpp"
-#include "libtorrent/bencode.hpp"
-#include "libtorrent/torrent_info.hpp"
-
-
-int main(int argc, char* argv[])
-{
-        using namespace libtorrent;
-
-        if (argc != 2)
-        {
-                std::cerr << "usage: dump_torrent torrent-file\n";
-                return 1;
-        }
-
-        try
-        {
-                std::ifstream in(argv[1], std::ios_base::binary);
-                in.unsetf(std::ios_base::skipws);
-                entry e = bdecode(std::istream_iterator<char>(in), std::istream_iterator<char>());
-                torrent_info t(e);
-
-                // print info about torrent
-                std::cout << "\n\n----- torrent file info -----\n\n";
-                std::cout << "trackers:\n";
-                for (std::vector<announce_entry>::const_iterator i = t.trackers().begin();
-                        i != t.trackers().end();
-                        ++i)
-                {
-                        std::cout << i->tier << ": " << i->url << "\n";
-                }
-
-                std::cout << "number of pieces: " << t.num_pieces() << "\n";
-                std::cout << "piece length: " << t.piece_length() << "\n";
-                std::cout << "files:\n";
-                for (torrent_info::file_iterator i = t.begin_files();
-                        i != t.end_files();
-                        ++i)
-                {
-                        std::cout << "  " << std::setw(11) << i->size
-                        << "  " << i->path << " " << i->filename << "\n";
-                }
-                
-        }
-        catch (std::exception& e)
-        {
-                std::cout << e.what() << "\n";
-        }
-
-        return 0;
-}
-
-
-
-

simple client

-

This is a simple client. It doesn't have much output to keep it simple:

-
-#include <iostream>
-#include <fstream>
-#include <iterator>
-#include <exception>
-
-#include <boost/format.hpp>
-#include <boost/date_time/posix_time/posix_time.hpp>
-
-#include "libtorrent/entry.hpp"
-#include "libtorrent/bencode.hpp"
-#include "libtorrent/session.hpp"
-#include "libtorrent/http_settings.hpp"
-
-int main(int argc, char* argv[])
-{
-        using namespace libtorrent;
-
-        if (argc != 2)
-        {
-                std::cerr << "usage: ./simple_cient torrent-file\n"
-                        "to stop the client, press return.\n";
-                return 1;
-        }
-
-        try
-        {
-                session s;
-                s.listen_on(std::make_pair(6881, 6889));
-
-                std::ifstream in(argv[1], std::ios_base::binary);
-                in.unsetf(std::ios_base::skipws);
-                entry e = bdecode(std::istream_iterator<char>(in), std::istream_iterator<char>());
-                s.add_torrent(e, "");
-                        
-                // wait for the user to end
-                char a;
-                std::cin.unsetf(std::ios_base::skipws);
-                std::cin >> a;
-        }
-        catch (std::exception& e)
-        {
-                std::cout << e.what() << "\n";
-        }
-        return 0;
-}
-
-
-
-
-

fast resume

-

The fast resume mechanism is a way to remember which pieces are downloaded and where they -are put between sessions. You can generate fast resume data by calling -torrent_handle::write_resume_data() on torrent_handle. You can then save this data -to disk and use it when resuming the torrent. libtorrent will not check the piece hashes -then, and rely on the information given in the fast-resume data. The fast-resume data -also contains information about which blocks, in the unfinished pieces, were downloaded, -so it will not have to start from scratch on the partially downloaded pieces.

-

To use the fast-resume data you simply give it to add_torrent(), and it -will skip the time consuming checks. It may have to do the checking anyway, if the -fast-resume data is corrupt or doesn't fit the storage for that torrent, then it will -not trust the fast-resume data and just do the checking.

-
-

file format

-

The file format is a bencoded dictionary containing the following fields:

- ---- - - - - - - - - - - - - - - - - - - - - - - - -
file-formatstring: "libtorrent resume file"
file-versioninteger: 1
info-hashstring, the info hash of the torrent this data is saved for.
blocks per pieceinteger, the number of blocks per piece. Must be: piece_size -/ (16 * 1024). Clamped to be within the range [1, 256]. It -is the number of blocks per (normal sized) piece. Usually -each block is 16 * 1024 bytes in size. But if piece size is -greater than 4 megabytes, the block size will increase.
slots

list of integers. The list mappes slots ti piece indices. It -tells which piece is on which slot. If piece index is -2 it -means it is free, that there's no piece there. If it is -1, -means the slot isn't allocated on disk yet. The pieces have -to meet the following requirement:

-

If there's a slot at the position of the piece index, -the piece must be located in that slot.

-
peers

list of dictionaries. Each dictionary has the following -layout:

- ---- - - - - - - - - -
ipstring, the ip address of the peer.
portinteger, the listen port of the peer
-

These are the local peers we were connected to when this -fast-resume data was saved.

-
unfinished

list of dictionaries. Each dictionary represents an -piece, and has the following layout:

- ---- - - - - - - - - - - - -
pieceinteger, the index of the piece this entry -refers to.
bitmaskstring, a binary bitmask representing the -blocks that have been downloaded in this -piece.
adler32The adler32 checksum of the data in the -blocks specified by bitmask.
-
-
-
-
-

extensions

-

These extensions all operates within the extension protocol. The -name of the extension is the name used in the extension-list packets, -and the payload is the data in the extended message (not counting the -length-prefix, message-id nor extension-id).

-

Note that since this protocol relies on one of the reserved bits in the -handshake, it may be incompatible with future versions of the mainline -bittorrent client.

-

These are the extensions that are currently implemented.

-
-

chat messages

-

Extension name: "chat"

-

The payload in the packet is a bencoded dictionary with any -combination of the following entries:

-
- ---- - - - - - - - - -
"msg"This is a string that contains a message that -should be displayed to the user.
"ctrl"This is a control string that can tell a client that -it is ignored (to make the user aware of that) and -it can also tell a client that it is no longer ignored. -These notifications are encoded as the strings: -"ignored" and "not ignored". -Any unrecognized strings should be ignored.
-
-
-
-

metadata from peers

-

Extension name: "metadata"

-

The point with this extension is that you don't have to distribute the -metadata (.torrent-file) separately. The metadata can be distributed -through the bittorrent swarm. The only thing you need to download such -a torrent is the tracker url and the info-hash of the torrent.

-

It works by assuming that the initial seeder has the metadata and that -the metadata will propagate through the network as more peers join.

-

There are three kinds of messages in the metadata extension. These packets -are put as payload to the extension message. The three packets are:

-
-
    -
  • request metadata
    • -
  • metadata
    • -
  • don't have metadata
    • -
-
-

request metadata:

-
- ----- - - - - - - - - - - - - - - - - - - - - -
sizenamedescription
uint8_tmsg_typeDetermines the kind of message this is -0 means 'request metadata'
uint8_tstartThe start of the metadata block that -is requested. It is given in 256:ths -of the total size of the metadata, -since the requesting client don't know -the size of the metadata.
uint8_tsizeThe size of the metadata block that is -requested. This is also given in -256:ths of the total size of the -metadata. The size is given as size-1. -That means that if this field is set -0, the request wants one 256:th of the -metadata.
-
-

metadata:

-
- ----- - - - - - - - - - - - - - - - - - - - - - - - - -
sizenamedescription
uint8_tmsg_type1 means 'metadata'
int32_ttotal_sizeThe total size of the metadata, given -in number of bytes.
int32_toffsetThe offset of where the metadata block -in this message belongs in the final -metadata. This is given in bytes.
uint8_t[]metadataThe actual metadata block. The size of -this part is given implicit by the -length prefix in the bittorrent -protocol packet.
-
-

Don't have metadata:

-
- ----- - - - - - - - - - - - - -
sizenamedescription
uint8_tmsg_type2 means 'I don't have metadata'. -This message is sent as a reply to a -metadata request if the the client -doesn't have any metadata.
-
-

The current implementation of this extension in libtorrent is experimental, -and not optimal in any way.

-
-
-
-

filename checks

-

Boost.Filesystem will by default check all its paths to make sure they conform -to filename requirements on many platforms. If you don't want this check, you can -set it to either only check for native filesystem requirements or turn it off -alltogether. You can use:

-
-boost::filesystem::path::default_name_check(boost::filesystem::native);
-
-

for example. For more information, see the Boost.Filesystem docs.

-
-
-

acknowledgements

-

Written by Arvid Norberg. Copyright (c) 2003

-

Contributions by Magnus Jonsson and Daniel Wallin

-

Thanks to Reimond Retz for bugfixes, suggestions and testing

-

Thanks to University of Umeå for providing development and -test hardware.

-

Project is hosted by sourceforge.

-

sf_logo

-
-
- - diff --git a/docs/manual.rst b/docs/manual.rst index 9e0b755c3..7fde18a5e 100755 --- a/docs/manual.rst +++ b/docs/manual.rst @@ -189,7 +189,7 @@ The basic usage is as follows: * query the torrent_handles for progress (see torrent_handle_) * query the session for information * add and remove torrents from the session at run-time -* destruct all torrent_handles +* save resume data for all torrent_handles (optional) * destruct session object Each class and function is described in this manual. @@ -799,6 +799,10 @@ Its declaration looks like this:: bool is_paused() const; bool is_seed() const; + int num_complete() const; + int num_incomplete() const; + int num_downloaded() const; + bool has_metadata() const; boost::filsystem::path save_path() const; @@ -924,7 +928,25 @@ is_seed() Returns true if the torrent is in seed mode (i.e. if it has finished downloading). +num_complete() num_incomplete() num_downloaded() +------------------------------------------------ + + :: + + int num_complete() const; + int num_incomplete() const; + int num_downloaded() const; + +These members returns the optional scrape data returned by the tracker in the announce response. +If the tracker did not return any scrape data the return value of these functions are -1. Note +that in some cases the tracker can return some scrape data, so there is no guarantee that all +functions returns -1 just because one of them do. ``num_complete()`` is the total number of +seeds in the swarm. ``num_incomplete()`` is the number of downloaders in the swarm and +``num_downloaded()`` is the number of times this torrent has been downloaded. + + has_metadata() +-------------- :: diff --git a/include/libtorrent/torrent.hpp b/include/libtorrent/torrent.hpp index 38754e05d..34948602e 100755 --- a/include/libtorrent/torrent.hpp +++ b/include/libtorrent/torrent.hpp @@ -150,6 +150,15 @@ namespace libtorrent float ratio() const { return m_ratio; } + int num_complete() const + { return m_complete; } + + int num_incomplete() const + { return m_incomplete; } + + int num_downloaded() const + { return m_downloaded; } + // -------------------------------------------- // PEER MANAGEMENT @@ -192,7 +201,8 @@ namespace libtorrent // (either http_tracker_connection or udp_tracker_connection) // when this torrent got a response from its tracker request // or when a failure occured - virtual void tracker_response(std::vector& e, int interval); + virtual void tracker_response(std::vector& e, int interval + , int complete, int incomplete, int downloaded); virtual void tracker_request_timed_out(); virtual void tracker_request_error(int response_code, const std::string& str); @@ -393,6 +403,12 @@ namespace libtorrent // from the tracker int m_duration; + // the scrape data from the tracker response, this + // is optional and may be -1. + int m_complete; + int m_incomplete; + int m_downloaded; + std::map m_connections; // this is the upload and download statistics for the whole torrent. diff --git a/include/libtorrent/torrent_handle.hpp b/include/libtorrent/torrent_handle.hpp index c6574c044..64069cc51 100755 --- a/include/libtorrent/torrent_handle.hpp +++ b/include/libtorrent/torrent_handle.hpp @@ -197,6 +197,13 @@ namespace libtorrent void pause(); void resume(); + // interface for requesting tracker scrape data + // from tha last tracker announce response + // (optional, only sent by some trackers) + int num_complete() const; + int num_incomplete() const; + int num_downloaded() const; + // set the interface to bind outgoing connections // to. void use_interface(const char* net_interface); diff --git a/include/libtorrent/tracker_manager.hpp b/include/libtorrent/tracker_manager.hpp index 69f868dba..d92923581 100755 --- a/include/libtorrent/tracker_manager.hpp +++ b/include/libtorrent/tracker_manager.hpp @@ -104,7 +104,10 @@ namespace libtorrent virtual ~request_callback() {} virtual void tracker_response( std::vector& peers - , int interval) = 0; + , int interval + , int complete + , int incomplete + , int downloaded) = 0; virtual void tracker_request_timed_out() = 0; virtual void tracker_request_error( int response_code diff --git a/src/http_tracker_connection.cpp b/src/http_tracker_connection.cpp index d3fddda06..df9578937 100755 --- a/src/http_tracker_connection.cpp +++ b/src/http_tracker_connection.cpp @@ -542,7 +542,7 @@ namespace libtorrent return ret; } - void http_tracker_connection::parse(const entry& e) + void http_tracker_connection::parse(entry const& e) { if (!has_requester()) return; @@ -553,13 +553,13 @@ namespace libtorrent try { - const entry& failure = e["failure reason"]; + entry const& failure = e["failure reason"]; if (has_requester()) requester().tracker_request_error( m_code, failure.string().c_str()); return; } - catch (const type_error&) {} + catch (type_error const&) {} int interval = (int)e["interval"].integer(); @@ -587,7 +587,7 @@ namespace libtorrent } else { - const entry::list_type& l = e["peers"].list(); + entry::list_type const& l = e["peers"].list(); for(entry::list_type::const_iterator i = l.begin(); i != l.end(); ++i) { peer_entry p = extract_peer_info(*i); @@ -595,7 +595,23 @@ namespace libtorrent } } - requester().tracker_response(peer_list, interval); + // look for optional crape info + int complete = -1; + int incomplete = -1; + int downloaded = -1; + try + { + entry const& f = e["files"]; + entry const& sd = f[std::string(m_req.info_hash.begin() + , m_req.info_hash.end())]; + complete = sd["complete"].integer(); + incomplete = sd["incomplete"].integer(); + downloaded = sd["downloaded"].integer(); + } + catch(type_error& e) {} + + requester().tracker_response(peer_list, interval, complete + , incomplete, downloaded); } catch(type_error& e) { diff --git a/src/session.cpp b/src/session.cpp index 7f332180e..d9122f29f 100755 --- a/src/session.cpp +++ b/src/session.cpp @@ -132,8 +132,7 @@ namespace libtorrent { namespace detail if (!t->abort) { boost::mutex::scoped_lock l(m_ses.m_mutex); - m_ses.m_torrents.insert( - std::make_pair(t->info_hash, t->torrent_ptr)).first; + m_ses.m_torrents.insert(std::make_pair(t->info_hash, t->torrent_ptr)); m_torrents.pop_front(); if (t->torrent_ptr->is_seed() && m_ses.m_alerts.should_post(alert::info)) { diff --git a/src/torrent.cpp b/src/torrent.cpp index feaf97db9..26c8eae40 100755 --- a/src/torrent.cpp +++ b/src/torrent.cpp @@ -160,6 +160,9 @@ namespace libtorrent , m_storage(0) , m_next_request(second_clock::universal_time()) , m_duration(1800) + , m_complete(-1) + , m_incomplete(-1) + , m_downloaded(-1) , m_policy() , m_ses(ses) , m_picker(0) @@ -203,6 +206,9 @@ namespace libtorrent , m_storage(0) , m_next_request(second_clock::universal_time()) , m_duration(1800) + , m_complete(-1) + , m_incomplete(-1) + , m_downloaded(-1) , m_policy() , m_ses(ses) , m_picker(0) @@ -271,7 +277,10 @@ namespace libtorrent void torrent::tracker_response( std::vector& peer_list - , int interval) + , int interval + , int complete + , int incomplete + , int downloaded) { m_failed_trackers = 0; // less than 5 minutes announce intervals @@ -294,6 +303,10 @@ namespace libtorrent m_next_request = second_clock::universal_time() + boost::posix_time::seconds(m_duration); } + if (complete >= 0) m_complete = complete; + if (incomplete >= 0) m_incomplete = incomplete; + if (downloaded >= 0) m_downloaded = downloaded; + // connect to random peers from the list std::random_shuffle(peer_list.begin(), peer_list.end()); diff --git a/src/torrent_handle.cpp b/src/torrent_handle.cpp index 6c90efe61..3b16b0b62 100755 --- a/src/torrent_handle.cpp +++ b/src/torrent_handle.cpp @@ -271,6 +271,28 @@ namespace libtorrent , bind(&torrent::resume, _1)); } + + int torrent_handle::num_complete() const + { + INVARIANT_CHECK; + return call_member(m_ses, m_chk, m_info_hash + , bind(&torrent::num_complete, _1)); + } + + int torrent_handle::num_incomplete() const + { + INVARIANT_CHECK; + return call_member(m_ses, m_chk, m_info_hash + , bind(&torrent::num_incomplete, _1)); + } + + int torrent_handle::num_downloaded() const + { + INVARIANT_CHECK; + return call_member(m_ses, m_chk, m_info_hash + , bind(&torrent::num_downloaded, _1)); + } + void torrent_handle::set_tracker_login(std::string const& name, std::string const& password) { INVARIANT_CHECK; diff --git a/src/udp_tracker_connection.cpp b/src/udp_tracker_connection.cpp index d4ad54fe1..aa76efd6b 100755 --- a/src/udp_tracker_connection.cpp +++ b/src/udp_tracker_connection.cpp @@ -241,18 +241,20 @@ namespace libtorrent } if (action != announce) return false; - if (len < 12) + if (len < 24) { #ifndef NDEBUG if (has_requester()) requester().debug_log("udp_tracker_connection: " - "got a message with size < 12, ignoring"); + "got a message with size < 24, ignoring"); #endif return false; } int interval = detail::read_int32(buf); - int num_peers = (len - 12) / 6; - if ((len - 12) % 6 != 0) + int incomplete = detail::read_int32(buf); + int complete = detail::read_int32(buf); + int num_peers = (len - 24) / 6; + if ((len - 24) % 6 != 0) { if (has_requester()) requester().tracker_request_error(-1, "invalid tracker response"); @@ -276,7 +278,7 @@ namespace libtorrent peer_list.push_back(e); } - requester().tracker_response(peer_list, interval); + requester().tracker_response(peer_list, interval, complete, incomplete, -1); return true; }