components/library/libtorrent/libtorrent.3

   1 '\" t
   2 .TH "LIBTORRENT" "3" "03 Jun 2009" "SunOS 5.11"
   3
   4 .SH NAME
   5 libtorrent \- a BitTorrent library
   6 .sp
   7 .SH DESCRIPTION
   8 .sp
   9 .LP
  10 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.
  11 .sp
  12 Torrent State
  13 .RS +4
  14 .TP
  15 .ie t \(bu
  16 .el o
  17 Closed
  18 .sp
  19 This is the initial state of a download. When switching to this mode,
  20 all tracker requests are closed and the bitfield of completed
  21 chunks is cleared. File paths can only be changed in this state.
  22 Functions for getting information on bitfields, chunk count and
  23 various others will return size 0 in this state.
  24 .sp
  25 .nf
  26 torrent::Download::is_open() == false;
  27 torrent::Download::is_active() == false;
  28 torrent::Download::is_tracker_busy() == false;
  29 .fi
  30 .RE
  31 .RS +4
  32 .TP
  33 .ie t \(bu
  34 .el o
  35 Open
  36 .sp
  37 This is the state after a successfull call to torrent::Download::open().
  38 This  function  throws torrent::local_error if the download could not be
  39 opened. All files in the download have been created  and are open. The
  40 initial hash check must be done to get a valid bitfield of completed chunks.
  41 .sp
  42 .nf
  43 torrent::Download::is_open() == true;
  44 torrent::Download::is_active() == false;
  45 .fi
  46 .RE
  47 .RS +4
  48 .TP
  49 .ie t \(bu
  50 .el o
  51 Active
  52 .sp
  53 A  download  is  active  after   calling   torrent::Download::start().
  54 Only downloads that are in an open state and has a valid bitfield of
  55 completed chunks can be activated.
  56 .sp
  57 .nf
  58 torrent::Download::is_open() == true;
  59 torrent::Download::is_active() == true;
  60 torrent::Download::is_hash_checked() == true;
  61 .fi
  62
  63 A tracker request will be made when torrent::Download::stop()  is
  64 called  on an active download. It is not required to wait for the
  65 tracker  request  to   finish   before   calling   torrent::Down
  66 load::close(),  but  it  is  recommened so the tracker knows this
  67 client is not available.File
  68 .RE
  69
  70 .TP
  71 Paths
  72 .sp
  73 The paths of files in a  Download  consists  of two parts, the
  74 root directory and the paths of each file. The file paths are
  75 read from the torrent file and  the files usually reside in the
  76 root directory. The root directory is by default "./" for single
  77 file torrents and  "./[torrent_name]/" for multifile torrents.
  78 .sp
  79 .nf
  80 // Get and set the root directory.
  81 std::string    torrent::Download::get_root_dir();
  82 void           torrent::Download::set_root_dir(const std::string& dir);
  83
  84 // Get the torrent::Entry class for each file in the download.
  85 torrent::Entry torrent::Download::get_entry(uint32_t index);
  86 uint32_t       torrent::Download::get_entry_size();
  87
  88 typedef std::list<std::string> torrent::Entry::Path;
  89
  90 // Get and set the file path.
  91 std::string    torrent::Entry::get_path();
  92 const Path&    torrent::Entry::get_path_list();
  93 void           torrent::Entry::set_path_list(const Path& l);
  94 .fi
  95 .sp
  96 The  modifications  can  only  be done while the download is in a
  97 closed state. Modifying the file paths will not change the  "info
  98 hash" part of the bencoded torrent associated with the download.
  99
 100 .TP
 101 Http handler Introduction
 102 .sp
 103 LibTorrent depends on the client to handle http downloads, thus
 104 the  library does  not have a dependency on any specific http library.
 105 The library provides a base class named torrent::Http with virtual
 106 member  functions  that the client must implement, and a sigc++ slot
 107 which must be set to create  an  instance  of  the  derived  tor
 108 rent::Http  class  when  called.
 109
 110 The torrent::Http class and the factory slot related functions can
 111 be found in the  header  "torrent/http.h".
 112 The http handler should have reasonable connection timeouts, be
 113 nonblocking and not do reconnects on  failed  downloads.
 114
 115 .TP
 116 Factory Slot
 117 .sp
 118 The client registers the desired factory slot with the static
 119 torrent::Http::set_factory member function. Using
 120 sigc++ the client may bind values to the arguments of their func
 121 tion to avoid depending on globals. The factory slot must  return
 122 a pointer to a new instance with the base type torrent::Http, and
 123 the caller takes responsibility of deleting  the  object.  (Note:
 124 consider  making  the cleanup a slot)
 125
 126 .TP
 127 Output Stream
 128 .sp
 129 The data downloaded  by the http handler is to be written to
 130 torrent::Http::m_stream which is a pointer to an std::iostream.
 131 The http handler must not change any of the flags on the stream.
 132
 133 StartHttp::start is called by the library when it wishes to initiate a
 134 http download. Your Http derived class must implement this  func
 135 tion. It must be nonblocking and threadsafe. This means that if
 136 a seperate thread is used for downloading then it must  not  emit
 137 any  signal  while  the  main  thread is inside the library.
 138
 139 closeHttp::close is used by the library to stop and close a  download.
 140 No signals may be emited after this. Http::m_data should not be
 141 cleared. The library may clear the Http::m_data pointer after
 142 this.
 143
 144 .TP
 145 Signals
 146 .sp
 147 There  are  two mutually exclusive signals that are
 148 called when the download has stopped. The signal tor
 149 rent::Http::m_signalDone is called if the download was successful
 150 and torrent::Http::m_stream contains the complete data. Or if the
 151 download was unsuccessful for some reason, then tor
 152 rent::Http::m_signalFailed is called with an error message.
 153 .SH SEE ALSO
 154 .sp
 155 .LP
 156 \fBrtorrent\fR(1)