diff --git a/docs/index.html b/docs/index.html index 9c4fd6128..f1aecc5b1 100755 --- a/docs/index.html +++ b/docs/index.html @@ -4,13 +4,12 @@ -libtorrent -
-

libtorrent

- +
+

logo.png

+
@@ -28,7 +27,7 @@

libtorrent is a C++ library that aims to be a good alternative to all the -other bittorrent implementations around. It is a +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:

diff --git a/docs/index.rst b/docs/index.rst index 76949fe2d..95f80ef4e 100755 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,8 +1,8 @@ -========== -libtorrent -========== +.. image:: logo.png +.. class:: menu + =================== ============== ============== =========== =============== `sourceforge page`_ documentation_ `report bugs`_ screenshot_ `mailing list`_ =================== ============== ============== =========== =============== @@ -14,12 +14,10 @@ libtorrent .. _mailing list: http://lists.sourceforge.net/lists/listinfo/libtorrent-discuss libtorrent is a C++ library that aims to be a good alternative to all the -`other bittorrent implementations`__ around. It is a +other bittorrent implementations around. It is a library and not a full featured client, although it comes with a working example client. -__ links.html - The main goals of libtorrent are: * to be cpu efficient diff --git a/docs/manual.html b/docs/manual.html index 41f5d0fe5..83fae92e4 100755 --- a/docs/manual.html +++ b/docs/manual.html @@ -13,63 +13,63 @@

Contents

-

introduction

+

introduction

libtorrent is a C++ library that aims to be a good alternative to all the -other bittorrent implementations around. It is a +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:

@@ -132,7 +132,7 @@ boost.filesystem, boost.date_time and various other boost libraries as well as z

libtorrent is released under the BSD-license.

-

building

+

building

Whwn building in release mode you need to define NDEBUG in order to avoid all asserts and invariant checks within libtorrent. Developer studio does this by default.

@@ -167,7 +167,7 @@ loop scope" and "treat wchar_t as built-in type" to Yes.

TODO: more detailed build instructions.

-

using

+

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:

@@ -194,7 +194,7 @@ the session, it contains the m

Each class and function is described in this manual.

-

session

+

session

The session class has the following synopsis:

 class session: public boost::noncopyable
@@ -255,7 +255,7 @@ change in the future to give more control of the listen-port.

 
For information about the pop_alert() function, see alerts.
-

parsing torrent files

+

parsing torrent files

The torrent files are bencoded. There are two functions in libtorrent that can encode and decode bencoded data. They are:

@@ -294,7 +294,7 @@ entry e = bdecode(buf, buf + data_size);
 it will throw invalid_encoding.
-

entry

+

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:

@@ -375,7 +375,7 @@ if (i != dict.end()) exists.

-

torrent_info

+

torrent_info

The torrent_info has the following synopsis:

 class torrent_info
@@ -462,7 +462,7 @@ object, representing the time when this torrent file was created. If there's no
 in the torrent file, this will return a date of january 1:st 1970.
-

torrent_handle

+

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:

@@ -520,7 +520,7 @@ torrent. If you set this to -1, there will be no limit.

is suitable for being bencoded. For more information about how fast-resume works, see fast resume. It may throw invalid_handle if the torrent handle is invalid.

-

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. It contains the following fields:

@@ -609,7 +609,7 @@ all peers. The rates are given as the number of bytes per second.

total_done is the total number of bytes of the file(s) that we have.

-

get_download_queue()

+

get_download_queue()

get_download_queue() takes a non-const reference to a vector which it will fill 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:

@@ -641,7 +641,7 @@ When a piece fails a hash verification, single blocks may be redownloaded to see may pass then.

-

get_peer_info()

+

get_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 @@ -750,19 +750,19 @@ of bytes of this block we have received from the peer, and < the total number of bytes in this block.

-

get_torrent_info()

+

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, invalid_handle exception will be thrown.

-

is_valid()

+

is_valid()

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.

-

address

+

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:

@@ -795,7 +795,7 @@ while it does the DNS lookup, it returns a string that points to the address rep

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

-

http_settings

+

http_settings

You have some control over tracker requests through the http_settings object. You create it and fill it with your settings and the use session::set_http_settings() to apply them. You have control over proxy and authorization settings and also the user-agent @@ -835,7 +835,7 @@ uncompressed (given your limit is lower than 2 megs). Default limit is 1 megabyte.

-

big_number

+

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:

@@ -856,7 +856,7 @@ public:
 
The iterators gives you access to individual bytes.
-

hasher

+

hasher

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

 class hasher
@@ -880,7 +880,7 @@ call reset() to reinitialize i
 For more info, see src/sha1.c.
-

fingerprint

+

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:

@@ -931,7 +931,7 @@ sure not to clash with anybody else. Here are some taken id's:

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.

-

identify_client

+

identify_client

There's a function, in the header libtorrent/identify_client.hpp, that can be used to extract a string describing a client version from its peer-id. It has the following declaration:

@@ -942,7 +942,7 @@ std::string identify_client(const peer_id& id);
-

alerts

+

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 @@ -1023,7 +1023,7 @@ have a severity leve 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:

-

tracker_alert

+

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.

@@ -1038,7 +1038,7 @@ struct tracker_alert: alert
-

hash_failed_alert

+

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.

@@ -1058,7 +1058,7 @@ struct hash_failed_alert: alert
-

peer_error_alert

+

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 peer-id from the alert. This alert is generated as severity level debug.

@@ -1073,7 +1073,7 @@ struct peer_error_alert: alert
-

invalid_request_alert

+

invalid_request_alert

Thie is a debug alert that is generated by an incoming invalid piece request.

 struct invalid_request_alert: alert
@@ -1093,7 +1093,7 @@ struct invalid_request_alert: alert
-

chat_message_alert

+

chat_message_alert

This alert is generated when you receive a chat message from another peer. Chat messages are supported as an extension ("chat"). It is generated as severity level critical, even though it doesn't necessarily require any user intervention, it's high priority @@ -1115,16 +1115,16 @@ struct chat_message_alert: alert

-

dispatcher

+

dispatcher

TODO: describe the dispatcher mechanism

-

exceptions

+

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

+

invalid_handle

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

@@ -1135,7 +1135,7 @@ struct invalid_handle: std::exception
-

duplicate_torrent

+

duplicate_torrent

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

@@ -1146,7 +1146,7 @@ struct duplicate_torrent: std::exception
-

invalid_encoding

+

invalid_encoding

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

 struct invalid_encoding: std::exception
@@ -1156,7 +1156,7 @@ struct invalid_encoding: std::exception
-

type_error

+

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.

@@ -1167,7 +1167,7 @@ struct type_error: std::runtime_error
-

invalid_torrent_file

+

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.

@@ -1179,9 +1179,9 @@ struct invalid_torrent_file: std::exception
-

examples

+

examples

-

dump_torrent

+

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:

@@ -1245,7 +1245,7 @@ int main(int argc, char* argv[])
-

simple client

+

simple client

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

 #include <iostream>
@@ -1297,7 +1297,7 @@ int main(int argc, char* argv[])
-

fast resume

+

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 @@ -1310,7 +1310,7 @@ will skip the time consuming checks. It may have to do the checking anyway, if t 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

+

file format

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

@@ -1392,7 +1392,7 @@ piece.
-

extensions

+

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 @@ -1418,7 +1418,7 @@ with future versions of bittorrent.

+- - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+ -->
-

Aknowledgements

+

Aknowledgements

Written by Arvid Norberg and Daniel Wallin. Copyright (c) 2003

Contributions by Magnus Jonsson

Thanks to Reimond Retz for bugfixes, suggestions and testing

diff --git a/docs/manual.rst b/docs/manual.rst index 50e251c57..fc4321e46 100755 --- a/docs/manual.rst +++ b/docs/manual.rst @@ -8,12 +8,10 @@ introduction ============ libtorrent is a C++ library that aims to be a good alternative to all the -`other bittorrent implementations`__ around. It is a +other bittorrent implementations around. It is a library and not a full featured client, although it comes with a working example client. -__ links.html - The main goals of libtorrent are: * to be cpu efficient diff --git a/docs/style.css b/docs/style.css index f2dd9c0ef..97e8539ed 100755 --- a/docs/style.css +++ b/docs/style.css @@ -55,24 +55,54 @@ ol font-family: Georgia, "Times New Roman", Times, serif } -a +a:link { font-weight: bold; color: #003366; text-decoration: none; } +a:visited +{ + font-weight: bold; + color: #003366; + text-decoration: none; +} + + table { - border: 1px solid black + border: 1px solid black; + border-collapse: collapse; } +table td +{ + padding: 6px; +} + +table th +{ + border: 3px solid black; + padding: 6px; +} + +table.menu +{ + border-style: none; +} + +table.menu td +{ + padding-left: 15px; + padding-right: 15px; + padding-top: 7px; + padding-bottom: 7px; +} + + td { border: 1px solid black } -a:hover -{ - color: #8080FF; -} diff --git a/include/libtorrent/alert_types.hpp b/include/libtorrent/alert_types.hpp new file mode 100755 index 000000000..d68ff889b --- /dev/null +++ b/include/libtorrent/alert_types.hpp @@ -0,0 +1,144 @@ +/* + +Copyright (c) 2003, Arvid Norberg +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions +are met: + + * Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in + the documentation and/or other materials provided with the distribution. + * Neither the name of the author nor the names of its + contributors may be used to endorse or promote products derived + from this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +POSSIBILITY OF SUCH DAMAGE. + +*/ + +#ifndef TORRENT_ALERT_TYPES_HPP_INCLUDED +#define TORRENT_ALERT_TYPES_HPP_INCLUDED + +#include "libtorrent/alert.hpp" +#include "libtorrent/torrent_handle.hpp" + +namespace libtorrent +{ + struct tracker_alert: alert + { + tracker_alert(const torrent_handle& h + , const std::string& msg) + : alert(alert::warning, msg) + , handle(h) + {} + + virtual std::auto_ptr clone() const + { return std::auto_ptr(new tracker_alert(*this)); } + + torrent_handle handle; + }; + + struct hash_failed_alert: alert + { + hash_failed_alert( + const torrent_handle& h + , int index + , const std::string& msg) + : alert(alert::info, msg) + , handle(h) + , piece_index(index) + {} + + virtual std::auto_ptr clone() const + { return std::auto_ptr(new hash_failed_alert(*this)); } + + torrent_handle handle; + int piece_index; + }; + + struct peer_error_alert: alert + { + peer_error_alert(const peer_id& pid, const std::string& msg) + : alert(alert::debug, msg) + , id(pid) + {} + + virtual std::auto_ptr clone() const + { return std::auto_ptr(new peer_error_alert(*this)); } + + peer_id id; + }; + + struct chat_message_alert: alert + { + chat_message_alert( + const torrent_handle& h + , const peer_id& send + , const std::string& msg) + : alert(alert::critical, msg) + , handle(h) + , sender(send) + {} + + virtual std::auto_ptr clone() const + { return std::auto_ptr(new chat_message_alert(*this)); } + + torrent_handle handle; + peer_id sender; + }; + + struct invalid_request_alert: alert + { + invalid_request_alert( + const peer_request& r + , const torrent_handle& h + , const peer_id& send + , const std::string& msg) + : alert(alert::debug, msg) + , handle(h) + , sender(send) + , request(r) + {} + + virtual std::auto_ptr clone() const + { return std::auto_ptr(new invalid_request_alert(*this)); } + + torrent_handle handle; + peer_id sender; + peer_request request; + }; + + // TODO: document + struct torrent_finished_alert: alert + { + torrent_finished_alert( + const torrent_handle& h + , const std::string& msg) + : alert(alert::warning, msg) + , handle(h) + {} + + virtual std::auto_ptr clone() const + { return std::auto_ptr(new torrent_finished_alert(*this)); } + + torrent_handle handle; + }; + +} + + +#endif diff --git a/include/libtorrent/peer_connection.hpp b/include/libtorrent/peer_connection.hpp index 8573024a9..8be58a53b 100755 --- a/include/libtorrent/peer_connection.hpp +++ b/include/libtorrent/peer_connection.hpp @@ -150,45 +150,6 @@ namespace libtorrent int full_block_bytes; }; - struct chat_message_alert: alert - { - chat_message_alert( - const torrent_handle& h - , const peer_id& send - , const std::string& msg) - : alert(alert::critical, msg) - , handle(h) - , sender(send) - {} - - virtual std::auto_ptr clone() const - { return std::auto_ptr(new chat_message_alert(*this)); } - - torrent_handle handle; - peer_id sender; - }; - - struct invalid_request_alert: alert - { - invalid_request_alert( - const peer_request& r - , const torrent_handle& h - , const peer_id& send - , const std::string& msg) - : alert(alert::debug, msg) - , handle(h) - , sender(send) - , request(r) - {} - - virtual std::auto_ptr clone() const - { return std::auto_ptr(new invalid_request_alert(*this)); } - - torrent_handle handle; - peer_id sender; - peer_request request; - }; - class peer_connection: public boost::noncopyable { public: diff --git a/include/libtorrent/session.hpp b/include/libtorrent/session.hpp index 84b7ff680..5be27e5ad 100755 --- a/include/libtorrent/session.hpp +++ b/include/libtorrent/session.hpp @@ -67,19 +67,6 @@ POSSIBILITY OF SUCH DAMAGE. namespace libtorrent { - struct peer_error_alert: alert - { - peer_error_alert(const peer_id& pid, const std::string& msg) - : alert(alert::debug, msg) - , id(pid) - {} - - virtual std::auto_ptr clone() const - { return std::auto_ptr(new peer_error_alert(*this)); } - - peer_id id; - }; - namespace detail { // workaround for microsofts diff --git a/include/libtorrent/torrent.hpp b/include/libtorrent/torrent.hpp index 99c349100..97c422ea3 100755 --- a/include/libtorrent/torrent.hpp +++ b/include/libtorrent/torrent.hpp @@ -63,37 +63,6 @@ namespace libtorrent std::string escape_string(const char* str, int len); std::string unescape_string(std::string const& s); - struct tracker_alert: alert - { - tracker_alert(const torrent_handle& h - , const std::string& msg) - : alert(alert::warning, msg) - , handle(h) - {} - - virtual std::auto_ptr clone() const - { return std::auto_ptr(new tracker_alert(*this)); } - - torrent_handle handle; - }; - - struct hash_failed_alert: alert - { - hash_failed_alert( - const torrent_handle& h - , int index - , const std::string& msg) - : alert(alert::info, msg) - , handle(h) - , piece_index(index) - {} - - virtual std::auto_ptr clone() const - { return std::auto_ptr(new hash_failed_alert(*this)); } - - torrent_handle handle; - int piece_index; - }; namespace detail { diff --git a/include/libtorrent/torrent_handle.hpp b/include/libtorrent/torrent_handle.hpp index 2e298d752..ed9df36e3 100755 --- a/include/libtorrent/torrent_handle.hpp +++ b/include/libtorrent/torrent_handle.hpp @@ -62,6 +62,7 @@ namespace libtorrent { return "invalid torrent handle used"; } }; + // TODO: put torrent_info in its own header struct torrent_status { torrent_status() diff --git a/src/peer_connection.cpp b/src/peer_connection.cpp index dea77a3e6..b21c71e64 100755 --- a/src/peer_connection.cpp +++ b/src/peer_connection.cpp @@ -40,6 +40,7 @@ POSSIBILITY OF SUCH DAMAGE. #include "libtorrent/identify_client.hpp" #include "libtorrent/entry.hpp" #include "libtorrent/bencode.hpp" +#include "libtorrent/alert_types.hpp" #if defined(_MSC_VER) #define for if (false) {} else for @@ -704,7 +705,12 @@ namespace libtorrent if (!was_seed && is_seed()) { assert(verified); - // TODO: post torrent_finished_alert + if (m_torrent->alerts().should_post(alert::warning)) + { + m_torrent->alerts().post_alert(torrent_finished_alert( + m_torrent->get_handle() + , "torrent is finished downloading")); + } } } diff --git a/src/policy.cpp b/src/policy.cpp index 637f30714..1b964999b 100755 --- a/src/policy.cpp +++ b/src/policy.cpp @@ -38,10 +38,7 @@ POSSIBILITY OF SUCH DAMAGE. #include "libtorrent/torrent.hpp" #include "libtorrent/socket.hpp" #include "libtorrent/peer_connection.hpp" - -// TODO: move all alerts to a single header -// session.hpp is included just for the peer_error_alert -#include "libtorrent/session.hpp" +#include "libtorrent/alert_types.hpp" #if defined(_MSC_VER) && _MSC_VER < 1300 # define for if (false) {} else for diff --git a/src/session.cpp b/src/session.cpp index dad23eb80..4a21e93ce 100755 --- a/src/session.cpp +++ b/src/session.cpp @@ -55,6 +55,7 @@ POSSIBILITY OF SUCH DAMAGE. #include "libtorrent/session.hpp" #include "libtorrent/fingerprint.hpp" #include "libtorrent/entry.hpp" +#include "libtorrent/alert_types.hpp" #if defined(_MSC_VER) && _MSC_VER < 1300 namespace std diff --git a/src/torrent.cpp b/src/torrent.cpp index 29268188e..10871f4cb 100755 --- a/src/torrent.cpp +++ b/src/torrent.cpp @@ -53,6 +53,7 @@ POSSIBILITY OF SUCH DAMAGE. #include "libtorrent/peer_id.hpp" #include "libtorrent/alert.hpp" #include "libtorrent/identify_client.hpp" +#include "libtorrent/alert_types.hpp" #if defined(_MSC_VER) && _MSC_VER < 1300 namespace std