15824630 SUNBT7206173 Need to update swig to a version that supports lua 5.2.
'\" 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)