← Back to branch summary

~ubuntu-branches/ubuntu/oneiric/libtorrent/oneiric

« back to all changes in this revision

Viewing changes to doc/http.xml

  • Committer: Bazaar Package Importer
  • Author(s): Rogério Brito
  • Date: 2011-03-20 01:06:18 UTC
  • mfrom: (1.1.13 upstream) (4.1.9 sid)
  • Revision ID: james.westby@ubuntu.com-20110320010618-g3wyylccqzqko73c
Tags: 0.12.7-5
http://bugs.debian.org/617791
* Use Steinar's "real" patch for IPv6. Addresses #490277, #618275,
  and Closes: #617791.
* Adapt libtorrent-0.12.6-ipv6-07.patch. It FTBFS otherwise.
* Add proper attibution to the IPv6 patch.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/http.xml
 
1
<chapter id="http">
 
2
  <title>Http handler</title>
 
3
 
 
4
 
 
5
<section id="introduction"><title>Introduction</title>
 
6
 
 
7
<para>
 
8
LibTorrent depends on the client to handle http downloads, thus the
 
9
library does not have a dependency on any specific http library. The
 
10
library provides a base class named torrent::Http with virtual member
 
11
functions that the client must implement, and a sigc++ slot which must
 
12
be set to create an instance of the derived torrent::Http class when
 
13
called.  
 
14
</para>
 
15
 
 
16
<para>
 
17
The torrent::Http class and the factory slot related functions can be
 
18
found in the header "torrent/http.h". The http handler should have
 
19
reasonable connection timeouts, be non-blocking and not do reconnects
 
20
on failed downloads.
 
21
</para>
 
22
 
 
23
</section>
 
24
 
 
25
 
 
26
<section id="factory"><title>Factory Slot</title>
 
27
 
 
28
<para>
 
29
The client registers the desired factory slot with the static
 
30
torrent::Http::set_factory member function. Using sigc++ the client
 
31
may bind values to the arguments of their function to avoid depending
 
32
on globals. The factory slot must return a pointer to a new instance
 
33
with the base type torrent::Http, and the caller takes responsibility
 
34
of deleting the object. (Note: consider making the cleanup a slot)
 
35
</para>
 
36
 
 
37
</section>
 
38
 
 
39
 
 
40
<section id="stream"><title>Output Stream</title>
 
41
 
 
42
<para>
 
43
The data downloaded by the http handler is to be written to
 
44
torrent::Http::m_stream which is a pointer to an std::iostream. The
 
45
http handler must not change any of the flags on the stream.
 
46
</para>
 
47
 
 
48
</section>
 
49
 
 
50
 
 
51
<section id="start"><title>Start</title>
 
52
 
 
53
<para>
 
54
Http::start is called by the library when it wishes to initiate a http
 
55
download. Your Http derived class must implement this function. It
 
56
must be non-blocking and thread-safe. This means that if a seperate
 
57
thread is used for downloading then it must not emit any signal while
 
58
the main thread is inside the library.
 
59
</para>
 
60
 
 
61
 
 
62
<section id="close"><title>close</title>
 
63
 
 
64
<para>
 
65
Http::close is used bu the library to stop and close a download. No
 
66
signals may be emited after this. Http::m_data should not be
 
67
cleared. The library may clear the Http::m_data pointer after this.
 
68
</para>
 
69
 
 
70
 
 
71
<section id="signals"><title>Signals</title>
 
72
 
 
73
<para>
 
74
There are two mutually exclusive signals that are called when the
 
75
download has stopped. The signal torrent::Http::m_signalDone is called
 
76
if the download was successful and torrent::Http::m_stream contains
 
77
the complete data. Or if the download was unsuccessful for some
 
78
reason, then torrent::Http::m_signalFailed is called with an error
 
79
message.
 
80
</para>
 
81
 
 
82
 
 
83
</section>
 
84
 
 
85
</chapter>
 
 
b'\\ No newline at end of file'