'\" 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)