+
libtorrent manual
+
+
+
+
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.
+
+
+
+
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 to point to your boost build
+installation. Also you have to modify the user_config.jam to reflect the toolsets you have installed.
+(if you're building with gcc, uncomment the line "using gcc ;")
+
You also need to install boost (at least version 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.),
+this is the preferred implementation that should be used in all cases. The file_win.cpp
+have had some problems with failing seeks (I don't know why), so I advise everyone to use
+the other file.
+
+
+
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_32_0). In the windows environment, they should have the typical
+windows format (c:/boost_1_32_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.
+
+
+
+
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.
+
+
+
+
+
+
+| macro |
+description |
+
|---|
+
+
+| NDEBUG |
+If 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_LOGGING |
+If 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_DEBUG |
+This 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, since it will remove the invariant checks within the library.
+
+
+
+
+
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:
+
+
Each class and function is described in this manual.
+
+
+
+
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(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.
+
+
+
+
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().
+
+
+
+
+
+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).
+
+
+
+
+
+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.
+
+
+
+
+
+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.
+
+
+
+
+
+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.
+
+
+
+
+
+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.
+
+
+
+
+
+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.
+
+
+
+
+
+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.
+
+
+
+
+
+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.
+
+
+
+
+
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_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.
+
+
+
+
+
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;
+};
+
+
+
+
+
+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;
+};
+
+
+
+
+
+
+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.
+
+
+
+
+
+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.
+
+
+
+
+
+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;
+};
+
+
+
+
+
+
+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.
+
+
+
+
+
+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.
+
+
+
+
+
+
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;
+
+ int num_complete() const;
+ int num_incomplete() const;
+ int num_downloaded() 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()
+TODO: document how to create a .torrent
+
+
+
+
+boost::filsystem::path save_path() const;
+
+
+
save_path() returns the path that was given to add_torrent() when this torrent
+was started.
+
+
+
+
+
+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.
+
+
+
+
+
+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.
+
+
+
+
+
+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.
+
+
+
+
+
+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.
+
+
+
+
+
+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.
+
+
+
+
+
+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.
+
+
+
+
+
+bool is_seed() const;
+
+
+
Returns true if the torrent is in seed mode (i.e. if it has finished downloading).
+
+
+
+
+
+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.
+
+
+
+
+
+
+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.
+
+
+
+
+
+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.
+
+
+
+
+
+sha1_hash info_hash() const;
+
+
+
info_hash() returns the info-hash for the torrent.
+
+
+
+
+
+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.
+
+
+
+
+
+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:
+
+
+- The torrent handle is invalid.
+- The torrent is checking (or is queued for checking) its storage, it will obviously
+not be ready to write resume data.
+- The torrent hasn't received valid metadata and was started without metadata
+(see libtorrent's metadata from peers extension)
+
+
+
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.
+
+
+
+
+
+
+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.
+
+
+
+
+
+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.
+
+
+
+
+
+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.
+
+
+
+
+
+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.
+
+
+
+
+
+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.
+
+
+
+
+
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_checking |
+The 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_files |
+The torrent has not started its download yet, and is
+currently checking existing files. |
+
+| connecting_to_tracker |
+The torrent has sent a request to the tracker and is
+currently waiting for a response |
+
+| downloading |
+The 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. |
+
+| seeding |
+In 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.
+
+
+
+
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:
+
+
+
+
+
+
+| interesting |
+we are interested in pieces from this peer. |
+
+| choked |
+we have choked this peer. |
+
+| remote_interested
+remote_choked |
+means the same thing but that the peer is interested
+in pieces from us and the peer has choked us. |
+
+| support_extensions |
+means that this peer supports the
+extension protocol. |
+
+| local_connection |
+The 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.
+
+
+
+
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.
+
+
+
+
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.
+
+
+
+
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.
+
+
+
+
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.cpp.
+
+
+
+
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 chars |
+client |
+
|---|
+
+
+| '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.
+
+
+
+
+
+
+
+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.
+
+
+
+
+
+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.
+
+
+
+
+
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:
+
+
+
+
+
+
+| none |
+No alert will ever have this severity level, which
+effectively filters all messages. |
+
+| fatal |
+Fatal errors will have this severity level. Examples can
+be disk full or something else that will make it
+impossible to continue normal execution. |
+
+| critical |
+Signals 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. |
+
+| warning |
+Messages 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. |
+
+| info |
+Events that can be considered normal, but still deserves
+an event. This could be a piece hash that fails. |
+
+| debug |
+This 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:
+
+
+
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;
+};
+
+
+
+
+
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;
+};
+
+
+
+
+
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;
+};
+
+
+
+
+
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;
+};
+
+
+
+
+
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;
+};
+
+
+
+
+
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;
+};
+
+
+
+
+
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.
+
+
+
+
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;
+};
+
+
+
+
+
+
TODO: describe the dispatcher mechanism
+
+
+
+
+
There are a number of exceptions that can be thrown from different places in libtorrent,
+here's a complete list with description.
+
+
+
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();
+};
+
+
+
+
+
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();
+};
+
+
+
+
+
This is thrown by bdecode() if the input data is not a valid bencoding.
+
+struct invalid_encoding: std::exception
+{
+ const char* what() const throw();
+};
+
+
+
+
+
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);
+};
+
+
+
+
+
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();
+};
+
+
+
+
+
+
+
+
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;
+}
+
+
+
+
+
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;
+}
+
+
+
+
+
+
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.
+
+
+
+
+
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.
+
+
+
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. |
+
+
+
+
+
+
+
+
+
+
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.
+
+
+
+
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.
+
+
+
