'\" t
|
.TH "LIBTORRENT" "3" "03 Jun 2009" "SunOS 5.11"
|
|
.SH NAME
|
libtorrent \- a BitTorrent library
|
.sp
|
.SH DESCRIPTION
|
.sp
|
.LP
|
LibTorrent is a BitTorrent library written in C++ for *nix, with a focus on high performance and good code. The library differentiates itself from other implementations by transfering directly from file pages to the network stack. On high-bandwidth connections it is able to seed at 3 times the speed of the official client.
|
.sp
|
Torrent State
|
.RS +4
|
.TP
|
.ie t \(bu
|
.el o
|
Closed
|
.sp
|
This is the initial state of a download. When switching to this mode,
|
all tracker requests are closed and the bitfield of completed
|
chunks is cleared. File paths can only be changed in this state.
|
Functions for getting information on bitfields, chunk count and
|
various others will return size 0 in this state.
|
.sp
|
.nf
|
torrent::Download::is_open() == false;
|
torrent::Download::is_active() == false;
|
torrent::Download::is_tracker_busy() == false;
|
.fi
|
.RE
|
.RS +4
|
.TP
|
.ie t \(bu
|
.el o
|
Open
|
.sp
|
This is the state after a successfull call to torrent::Download::open().
|
This function throws torrent::local_error if the download could not be
|
opened. All files in the download have been created and are open. The
|
initial hash check must be done to get a valid bitfield of completed chunks.
|
.sp
|
.nf
|
torrent::Download::is_open() == true;
|
torrent::Download::is_active() == false;
|
.fi
|
.RE
|
.RS +4
|
.TP
|
.ie t \(bu
|
.el o
|
Active
|
.sp
|
A download is active after calling torrent::Download::start().
|
Only downloads that are in an open state and has a valid bitfield of
|
completed chunks can be activated.
|
.sp
|
.nf
|
torrent::Download::is_open() == true;
|
torrent::Download::is_active() == true;
|
torrent::Download::is_hash_checked() == true;
|
.fi
|
|
A tracker request will be made when torrent::Download::stop() is
|
called on an active download. It is not required to wait for the
|
tracker request to finish before calling torrent::Down
|
load::close(), but it is recommened so the tracker knows this
|
client is not available.File
|
.RE
|
|
.TP
|
Paths
|
.sp
|
The paths of files in a Download consists of two parts, the
|
root directory and the paths of each file. The file paths are
|
read from the torrent file and the files usually reside in the
|
root directory. The root directory is by default "./" for single
|
file torrents and "./[torrent_name]/" for multifile torrents.
|
.sp
|
.nf
|
// Get and set the root directory.
|
std::string torrent::Download::get_root_dir();
|
void torrent::Download::set_root_dir(const std::string& dir);
|
|
// Get the torrent::Entry class for each file in the download.
|
torrent::Entry torrent::Download::get_entry(uint32_t index);
|
uint32_t torrent::Download::get_entry_size();
|
|
typedef std::list<std::string> torrent::Entry::Path;
|
|
// Get and set the file path.
|
std::string torrent::Entry::get_path();
|
const Path& torrent::Entry::get_path_list();
|
void torrent::Entry::set_path_list(const Path& l);
|
.fi
|
.sp
|
The modifications can only be done while the download is in a
|
closed state. Modifying the file paths will not change the "info
|
hash" part of the bencoded torrent associated with the download.
|
|
.TP
|
Http handler Introduction
|
.sp
|
LibTorrent depends on the client to handle http downloads, thus
|
the library does not have a dependency on any specific http library.
|
The library provides a base class named torrent::Http with virtual
|
member functions that the client must implement, and a sigc++ slot
|
which must be set to create an instance of the derived tor
|
rent::Http class when called.
|
|
The torrent::Http class and the factory slot related functions can
|
be found in the header "torrent/http.h".
|
The http handler should have reasonable connection timeouts, be
|
nonblocking and not do reconnects on failed downloads.
|
|
.TP
|
Factory Slot
|
.sp
|
The client registers the desired factory slot with the static
|
torrent::Http::set_factory member function. Using
|
sigc++ the client may bind values to the arguments of their func
|
tion to avoid depending on globals. The factory slot must return
|
a pointer to a new instance with the base type torrent::Http, and
|
the caller takes responsibility of deleting the object. (Note:
|
consider making the cleanup a slot)
|
|
.TP
|
Output Stream
|
.sp
|
The data downloaded by the http handler is to be written to
|
torrent::Http::m_stream which is a pointer to an std::iostream.
|
The http handler must not change any of the flags on the stream.
|
|
StartHttp::start is called by the library when it wishes to initiate a
|
http download. Your Http derived class must implement this func
|
tion. It must be nonblocking and threadsafe. This means that if
|
a seperate thread is used for downloading then it must not emit
|
any signal while the main thread is inside the library.
|
|
closeHttp::close is used by the library to stop and close a download.
|
No signals may be emited after this. Http::m_data should not be
|
cleared. The library may clear the Http::m_data pointer after
|
this.
|
|
.TP
|
Signals
|
.sp
|
There are two mutually exclusive signals that are
|
called when the download has stopped. The signal tor
|
rent::Http::m_signalDone is called if the download was successful
|
and torrent::Http::m_stream contains the complete data. Or if the
|
download was unsuccessful for some reason, then tor
|
rent::Http::m_signalFailed is called with an error message.
|
.SH SEE ALSO
|
.sp
|
.LP
|
\fBrtorrent\fR(1)
|