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