1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
|
<chapter id="http">
<title>Http handler</title>
<section id="introduction"><title>Introduction</title>
<para>
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 torrent::Http class when
called.
</para>
<para>
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 non-blocking and not do reconnects
on failed downloads.
</para>
</section>
<section id="factory"><title>Factory Slot</title>
<para>
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 function 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)
</para>
</section>
<section id="stream"><title>Output Stream</title>
<para>
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.
</para>
</section>
<section id="start"><title>Start</title>
<para>
Http::start is called by the library when it wishes to initiate a http
download. Your Http derived class must implement this function. It
must be non-blocking and thread-safe. 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.
</para>
<section id="close"><title>close</title>
<para>
Http::close is used bu 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.
</para>
<section id="signals"><title>Signals</title>
<para>
There are two mutually exclusive signals that are called when the
download has stopped. The signal torrent::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 torrent::Http::m_signalFailed is called with an error
message.
</para>
</section>
</chapter>
|
