← Back to branch summary

~ubuntu-branches/debian/wheezy/libtorrent/wheezy

« back to all changes in this revision

Viewing changes to doc/torrent.xml

  • Committer: Bazaar Package Importer
  • Author(s): Rogério Brito
  • Date: 2011-03-09 20:04:41 UTC
  • mfrom: (1.3.4 upstream) (7.1.5 sid)
  • Revision ID: james.westby@ubuntu.com-20110309200441-ffi9aaqdyd72d8xl
Tags: 0.12.7-4
* Steal patch from upstream's bug tracking system to enable IPv6.
* Refresh patches to apply cleanly.
* This should, hopefully, be a good step towards addressing #490277.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/torrent.xml
 
1
<chapter id="torrent">
 
2
  <title>Torrent</title>
 
3
 
 
4
<section id="state"><title>State</title>
 
5
 
 
6
<section id="closed"><title>Closed</title>
 
7
 
 
8
<para>
 
9
This is the initial state of a download. When switching to this mode,
 
10
all tracker requests are closed and the bitfield of completed chunks
 
11
is cleared. File paths can only be changed in this state. Functions
 
12
for getting information on bitfields, chunk count and various others
 
13
will return size 0 in this state. (TODO: Check which)
 
14
</para>
 
15
 
 
16
<para>
 
17
<blockquote>
 
18
<programlisting>
 
19
torrent::Download::is_open() == false;
 
20
torrent::Download::is_active() == false;
 
21
torrent::Download::is_tracker_busy() == false;
 
22
</programlisting>
 
23
</blockquote>
 
24
</para>
 
25
 
 
26
</section>
 
27
 
 
28
<section id="open"> <title>Open</title>
 
29
 
 
30
<para>
 
31
This is the state after a successfull call to
 
32
torrent::Download::open(). This function throws torrent::local_error
 
33
if the download could not be opened. All files in the download have
 
34
been created and are open. The initial hash check must be done to get
 
35
a valid bitfield of completed chunks.
 
36
</para>
 
37
 
 
38
<para>
 
39
<blockquote>
 
40
<programlisting>
 
41
torrent::Download::is_open() == true;
 
42
torrent::Download::is_active() == false;
 
43
</programlisting>
 
44
</blockquote>
 
45
</para>
 
46
 
 
47
</section>
 
48
 
 
49
<section id="active"> <title>Active</title>
 
50
 
 
51
<para>
 
52
A download is active after calling torrent::Download::start(). Only
 
53
downloads that are in an open state and has a valid bitfield of
 
54
completed chunks can be activated.
 
55
</para>
 
56
 
 
57
<para>
 
58
<blockquote>
 
59
<programlisting>
 
60
torrent::Download::is_open() == true;
 
61
torrent::Download::is_active() == true;
 
62
torrent::Download::is_hash_checked() == true;
 
63
</programlisting>
 
64
</blockquote>
 
65
</para>
 
66
 
 
67
<para>
 
68
A tracker request will be made when torrent::Download::stop() is
 
69
called on an active download. It is not required to wait for the
 
70
tracker request to finish before calling torrent::Download::close(),
 
71
but it is recommened so the tracker knows this client is not available.
 
72
</para>
 
73
 
 
74
</section>
 
75
</section>
 
76
 
 
77
 
 
78
<section id="file-paths">
 
79
<title>File Paths</title>
 
80
 
 
81
<para>
 
82
The paths of files in a Download consists of two parts, the
 
83
root directory and the paths of each file. The file paths are read
 
84
from the torrent file and the files usually reside in the root
 
85
directory. The root directory is by default "./" for single file
 
86
torrents and "./[torrent_name]/" for multi-file torrents.
 
87
</para>
 
88
 
 
89
 
 
90
<para>
 
91
<blockquote>
 
92
<programlisting>
 
93
// Get and set the root directory.
 
94
std::string    torrent::Download::get_root_dir();
 
95
void           torrent::Download::set_root_dir(const std::string& dir);
 
96
 
 
97
// Get the torrent::Entry class for each file in the download.
 
98
torrent::Entry torrent::Download::get_entry(uint32_t index);
 
99
uint32_t       torrent::Download::get_entry_size();
 
100
 
 
101
typedef std::list&lt;std::string> torrent::Entry::Path;
 
102
 
 
103
// Get and set the file path.
 
104
std::string    torrent::Entry::get_path();
 
105
const Path&    torrent::Entry::get_path_list();
 
106
 
 
107
void           torrent::Entry::set_path_list(const Path& l);
 
108
</programlisting>
 
109
</blockquote>
 
110
</para>
 
111
 
 
112
 
 
113
<para>
 
114
The modifications can only be done while the download is in a
 
115
closed state. Modifying the file paths will not change the "info hash"
 
116
part of the bencode'd torrent associated with the download. (TODO:
 
117
When exporting, save root directory and file paths to another section
 
118
of the torrent)
 
119
</para>
 
120
 
 
121
</section>
 
122
 
 
123
</chapter>
 
 
b'\\ No newline at end of file'