File: reference-Bdecoding.html

package info (click to toggle)
libtorrent-rasterbar 1.1.13-1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, sid
  • size: 17,248 kB
  • sloc: cpp: 134,519; sh: 4,666; python: 2,591; ansic: 1,754; makefile: 914
file content (386 lines) | stat: -rw-r--r-- 18,301 bytes parent folder | download
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
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.14: http://docutils.sourceforge.net/" />
<title>reference-Bdecoding.rst</title>
<meta name="author" content="Arvid Norberg, arvid&#64;libtorrent.org" />
<meta name=viewport content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="style.css" type="text/css" />
<link rel="stylesheet" type="text/css" href="rst.css" />
<style type="text/css">
/* Hides from IE-mac \*/
* html pre { height: 1%; }
/* End hide from IE-mac */
</style>
</head>
<body>
<div class="document">
    <div id="container">
    <a href="index.html"><table id="header">
    <tr><td id="orange"></td>
    <td id="logo">libtorrent</td></tr>
    </table></a>
    <div id="main">

<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>Arvid Norberg, <a class="last reference external" href="mailto:arvid&#64;libtorrent.org">arvid&#64;libtorrent.org</a></td></tr>
<tr><th class="docinfo-name">Version:</th>
<td>1.1.13</td></tr>
</tbody>
</table>
<p><a class="reference external" href="reference.html">home</a></p>
<div class="section" id="bdecoding">
<h1>Bdecoding</h1>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of contents</p>
<ul class="simple">
<li><a class="reference internal" href="#bdecoding" id="id13">Bdecoding</a><ul>
<li><a class="reference internal" href="#bdecode-node" id="id14">bdecode_node</a></li>
<li><a class="reference internal" href="#print-entry" id="id15">print_entry()</a></li>
<li><a class="reference internal" href="#bdecode" id="id16">bdecode()</a></li>
</ul>
</li>
</ul>
</div>
<a name="bdecode_node"></a><div class="section" id="bdecode-node">
<h2>bdecode_node</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/bdecode.hpp">libtorrent/bdecode.hpp</a>&quot;</p>
<p>Sometimes it's important to get a non-owning reference to the root node (
to be able to copy it as a reference for instance). For that, use the
<a class="reference external" href="reference-Bdecoding.html#non_owning()">non_owning()</a> member function.</p>
<p>There are 5 different types of nodes, see <a class="reference external" href="reference-Core.html#type_t">type_t</a>.</p>
<pre class="literal-block">
struct bdecode_node
{
   friend int <strong>bdecode</strong> (char const* start, char const* end, bdecode_node&amp; ret
      , error_code&amp; ec, int* error_pos, int depth_limit
      , int token_limit);
   <strong>bdecode_node</strong> ();
   <strong>bdecode_node</strong> (bdecode_node const&amp;);
   bdecode_node&amp; <strong>operator=</strong> (bdecode_node const&amp;);
   type_t <strong>type</strong> () const;
   operator <strong>bool</strong> () const;
   bdecode_node <strong>non_owning</strong> () const;
   std::pair&lt;char const*, int&gt; <strong>data_section</strong> () const;
   bdecode_node <strong>list_at</strong> (int i) const;
   std::string <strong>list_string_value_at</strong> (int i
      , char const* default_val = &quot;&quot;) const;
   int <strong>list_size</strong> () const;
   boost::int64_t <strong>list_int_value_at</strong> (int i
      , boost::int64_t default_val = 0) const;
   std::string <strong>dict_find_string_value</strong> (char const* key
      , char const* default_value = &quot;&quot;) const;
   bdecode_node <strong>dict_find_string</strong> (char const* key) const;
   int <strong>dict_size</strong> () const;
   boost::int64_t <strong>dict_find_int_value</strong> (char const* key
      , boost::int64_t default_val = 0) const;
   bdecode_node <strong>dict_find</strong> (std::string key) const;
   bdecode_node <strong>dict_find_list</strong> (char const* key) const;
   bdecode_node <strong>dict_find</strong> (char const* key) const;
   bdecode_node <strong>dict_find_dict</strong> (std::string key) const;
   bdecode_node <strong>dict_find_dict</strong> (char const* key) const;
   std::pair&lt;std::string, bdecode_node&gt; <strong>dict_at</strong> (int i) const;
   bdecode_node <strong>dict_find_int</strong> (char const* key) const;
   boost::int64_t <strong>int_value</strong> () const;
   int <strong>string_length</strong> () const;
   std::string <strong>string_value</strong> () const;
   char const* <strong>string_ptr</strong> () const;
   void <strong>clear</strong> ();
   void <strong>swap</strong> (bdecode_node&amp; n);
   void <strong>reserve</strong> (int tokens);
   void <strong>switch_underlying_buffer</strong> (char const* buf);

   enum type_t
   {
      none_t,
      dict_t,
      list_t,
      string_t,
      int_t,
   };
};
</pre>
<a name="bdecode_node()"></a><div class="section" id="id5">
<h3>bdecode_node()</h3>
<pre class="literal-block">
<strong>bdecode_node</strong> ();
</pre>
<p>creates a default constructed node, it will have the type <tt class="docutils literal">none_t</tt>.</p>
<a name="bdecode_node()"></a>
<a name="operator=()"></a></div>
<div class="section" id="bdecode-node-operator">
<h3>bdecode_node() operator=()</h3>
<pre class="literal-block">
<strong>bdecode_node</strong> (bdecode_node const&amp;);
bdecode_node&amp; <strong>operator=</strong> (bdecode_node const&amp;);
</pre>
<p>For owning nodes, the copy will create a copy of the tree, but the
underlying buffer remains the same.</p>
<a name="type()"></a></div>
<div class="section" id="type">
<h3>type()</h3>
<pre class="literal-block">
type_t <strong>type</strong> () const;
</pre>
<p>the type of this node. See <a class="reference external" href="reference-Core.html#type_t">type_t</a>.</p>
<a name="bool()"></a></div>
<div class="section" id="bool">
<h3>bool()</h3>
<pre class="literal-block">
operator <strong>bool</strong> () const;
</pre>
<p>returns true if <a class="reference external" href="reference-Bencoding.html#type()">type()</a> != none_t.</p>
<a name="non_owning()"></a></div>
<div class="section" id="non-owning">
<h3>non_owning()</h3>
<pre class="literal-block">
bdecode_node <strong>non_owning</strong> () const;
</pre>
<p>return a non-owning reference to this node. This is useful to refer to
the root node without copying it in assignments.</p>
<a name="data_section()"></a></div>
<div class="section" id="data-section">
<h3>data_section()</h3>
<pre class="literal-block">
std::pair&lt;char const*, int&gt; <strong>data_section</strong> () const;
</pre>
<p>returns the buffer and length of the section in the original bencoded
buffer where this node is defined. For a dictionary for instance, this
starts with <tt class="docutils literal">d</tt> and ends with <tt class="docutils literal">e</tt>, and has all the content of the
dictionary in between.</p>
<a name="list_at()"></a>
<a name="list_string_value_at()"></a>
<a name="list_int_value_at()"></a>
<a name="list_size()"></a></div>
<div class="section" id="list-at-list-string-value-at-list-int-value-at-list-size">
<h3>list_at() list_string_value_at() list_int_value_at() list_size()</h3>
<pre class="literal-block">
bdecode_node <strong>list_at</strong> (int i) const;
std::string <strong>list_string_value_at</strong> (int i
      , char const* default_val = &quot;&quot;) const;
int <strong>list_size</strong> () const;
boost::int64_t <strong>list_int_value_at</strong> (int i
      , boost::int64_t default_val = 0) const;
</pre>
<p>functions with the <tt class="docutils literal">list_</tt> prefix operate on lists. These functions are
only valid if <tt class="docutils literal">type()</tt> == <tt class="docutils literal">list_t</tt>. <tt class="docutils literal">list_at()</tt> returns the item
in the list at index <tt class="docutils literal">i</tt>. <tt class="docutils literal">i</tt> may not be greater than or equal to the
size of the list. <tt class="docutils literal">size()</tt> returns the size of the list.</p>
<a name="dict_size()"></a>
<a name="dict_find_dict()"></a>
<a name="dict_find_string()"></a>
<a name="dict_find_int()"></a>
<a name="dict_at()"></a>
<a name="dict_find_list()"></a>
<a name="dict_find_int_value()"></a>
<a name="dict_find()"></a>
<a name="dict_find_string_value()"></a></div>
<div class="section" id="dict-size-dict-find-dict-dict-find-string-dict-find-int-dict-at-dict-find-list-dict-find-int-value-dict-find-dict-find-string-value">
<h3>dict_size() dict_find_dict() dict_find_string() dict_find_int() dict_at() dict_find_list() dict_find_int_value() dict_find() dict_find_string_value()</h3>
<pre class="literal-block">
std::string <strong>dict_find_string_value</strong> (char const* key
      , char const* default_value = &quot;&quot;) const;
bdecode_node <strong>dict_find_string</strong> (char const* key) const;
int <strong>dict_size</strong> () const;
boost::int64_t <strong>dict_find_int_value</strong> (char const* key
      , boost::int64_t default_val = 0) const;
bdecode_node <strong>dict_find</strong> (std::string key) const;
bdecode_node <strong>dict_find_list</strong> (char const* key) const;
bdecode_node <strong>dict_find</strong> (char const* key) const;
bdecode_node <strong>dict_find_dict</strong> (std::string key) const;
bdecode_node <strong>dict_find_dict</strong> (char const* key) const;
std::pair&lt;std::string, bdecode_node&gt; <strong>dict_at</strong> (int i) const;
bdecode_node <strong>dict_find_int</strong> (char const* key) const;
</pre>
<p>Functions with the <tt class="docutils literal">dict_</tt> prefix operates on dictionaries. They are
only valid if <tt class="docutils literal">type()</tt> == <tt class="docutils literal">dict_t</tt>. In case a key you're looking up
contains a 0 byte, you cannot use the null-terminated string overloads,
but have to use <tt class="docutils literal"><span class="pre">std::string</span></tt> instead. <tt class="docutils literal">dict_find_list</tt> will return a
valid <tt class="docutils literal">bdecode_node</tt> if the key is found _and_ it is a list. Otherwise
it will return a default-constructed <a class="reference external" href="reference-Bdecoding.html#bdecode_node">bdecode_node</a>.</p>
<p>Functions with the <tt class="docutils literal">_value</tt> suffix return the value of the node
directly, rather than the nodes. In case the node is not found, or it has
a different type, a default value is returned (which can be specified).</p>
<a name="int_value()"></a></div>
<div class="section" id="int-value">
<h3>int_value()</h3>
<pre class="literal-block">
boost::int64_t <strong>int_value</strong> () const;
</pre>
<p>this function is only valid if <tt class="docutils literal">type()</tt> == <tt class="docutils literal">int_t</tt>. It returns the
value of the integer.</p>
<a name="string_ptr()"></a>
<a name="string_length()"></a>
<a name="string_value()"></a></div>
<div class="section" id="string-ptr-string-length-string-value">
<h3>string_ptr() string_length() string_value()</h3>
<pre class="literal-block">
int <strong>string_length</strong> () const;
std::string <strong>string_value</strong> () const;
char const* <strong>string_ptr</strong> () const;
</pre>
<p>these functions are only valid if <tt class="docutils literal">type()</tt> == <tt class="docutils literal">string_t</tt>. They return
the string values. Note that <tt class="docutils literal">string_ptr()</tt> is <em>not</em> null-terminated.
<tt class="docutils literal">string_length()</tt> returns the number of bytes in the string.</p>
<a name="clear()"></a></div>
<div class="section" id="clear">
<h3>clear()</h3>
<pre class="literal-block">
void <strong>clear</strong> ();
</pre>
<p>resets the <tt class="docutils literal">bdecoded_node</tt> to a default constructed state. If this is
an owning node, the tree is freed and all child nodes are invalidated.</p>
<a name="swap()"></a></div>
<div class="section" id="swap">
<h3>swap()</h3>
<pre class="literal-block">
void <strong>swap</strong> (bdecode_node&amp; n);
</pre>
<p>Swap contents.</p>
<a name="reserve()"></a></div>
<div class="section" id="reserve">
<h3>reserve()</h3>
<pre class="literal-block">
void <strong>reserve</strong> (int tokens);
</pre>
<p>preallocate memory for the specified numbers of tokens. This is
useful if you know approximately how many tokens are in the file
you are about to parse. Doing so will save realloc operations
while parsing. You should only call this on the root node, before
passing it in to <a class="reference external" href="reference-Bencoding.html#bdecode()">bdecode()</a>.</p>
<a name="switch_underlying_buffer()"></a></div>
<div class="section" id="switch-underlying-buffer">
<h3>switch_underlying_buffer()</h3>
<pre class="literal-block">
void <strong>switch_underlying_buffer</strong> (char const* buf);
</pre>
<p>this buffer <em>MUST</em> be identical to the one originally parsed. This
operation is only defined on owning root nodes, i.e. the one passed in to
decode().</p>
<a name="type_t"></a></div>
<div class="section" id="enum-type-t">
<h3>enum type_t</h3>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/bdecode.hpp">libtorrent/bdecode.hpp</a>&quot;</p>
<table border="1" class="docutils">
<colgroup>
<col width="13%" />
<col width="9%" />
<col width="78%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">name</th>
<th class="head">value</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>none_t</td>
<td>0</td>
<td>uninitialized or default constructed. This is also used
to indicate that a node was not found in some cases.</td>
</tr>
<tr><td>dict_t</td>
<td>1</td>
<td>a dictionary node. The <tt class="docutils literal">dict_find_</tt> functions are valid.</td>
</tr>
<tr><td>list_t</td>
<td>2</td>
<td>a list node. The <tt class="docutils literal">list_</tt> functions are valid.</td>
</tr>
<tr><td>string_t</td>
<td>3</td>
<td>a string node, the <tt class="docutils literal">string_</tt> functions are valid.</td>
</tr>
<tr><td>int_t</td>
<td>4</td>
<td>an integer node. The <tt class="docutils literal">int_</tt> functions are valid.</td>
</tr>
</tbody>
</table>
<a name="print_entry()"></a></div>
</div>
<div class="section" id="print-entry">
<h2>print_entry()</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/bdecode.hpp">libtorrent/bdecode.hpp</a>&quot;</p>
<pre class="literal-block">
std::string <strong>print_entry</strong> (bdecode_node const&amp; e
   , bool single_line = false, int indent = 0);
</pre>
<p>print the bencoded structure in a human-readable format to a string
that's returned.</p>
<a name="bdecode()"></a></div>
<div class="section" id="bdecode">
<h2>bdecode()</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/bdecode.hpp">libtorrent/bdecode.hpp</a>&quot;</p>
<pre class="literal-block">
int <strong>bdecode</strong> (char const* start, char const* end, bdecode_node&amp; ret
   , error_code&amp; ec, int* error_pos = 0, int depth_limit = 100
   , int token_limit = 1000000);
</pre>
<p>This function decodes/parses bdecoded data (for example a .torrent file).
The data structure is returned in the <tt class="docutils literal">ret</tt> argument. the buffer to parse
is specified by the <tt class="docutils literal">start</tt> of the buffer as well as the <tt class="docutils literal">end</tt>, i.e. one
byte past the end. If the buffer fails to parse, the function returns a
non-zero value and fills in <tt class="docutils literal">ec</tt> with the error code. The optional
argument <tt class="docutils literal">error_pos</tt>, if set to non-null, will be set to the byte offset
into the buffer where the parse failure occurred.</p>
<p><tt class="docutils literal">depth_limit</tt> specifies the max number of nested lists or dictionaries are
allowed in the data structure. (This affects the stack usage of the
function, be careful not to set it too high).</p>
<p><tt class="docutils literal">token_limit</tt> is the max number of tokens allowed to be parsed from the
buffer. This is simply a sanity check to not have unbounded memory usage.</p>
<p>The resulting <tt class="docutils literal">bdecode_node</tt> is an <em>owning</em> node. That means it will
be holding the whole parsed tree. When iterating lists and dictionaries,
those <tt class="docutils literal">bdecode_node</tt> objects will simply have references to the root or
owning <tt class="docutils literal">bdecode_node</tt>. If the root node is destructed, all other nodes
that refer to anything in that tree become invalid.</p>
<p>However, the underlying buffer passed in to this function (<tt class="docutils literal">start</tt>, <tt class="docutils literal">end</tt>)
must also remain valid while the bdecoded tree is used. The parsed tree
produced by this function does not copy any data out of the buffer, but
simply produces references back into it.</p>
</div>
</div>

    </div>
    </div>
    <div id="gradient"></div>
    <div id="footer">
    <table>
    <tr>
      <td><a href="index.html">home</a></td>
      <td><a href="https://blog.libtorrent.org">blog</a></td>
      <td><a href="utp.html">uTP</a></td>
    </tr>
    <tr>
      <td><a href="https://sourceforge.net/projects/libtorrent/files/libtorrent/">download</a></td>
      <td><a href="reference.html">documentation</a></td>
      <td><a href="dht_store.html">DHT put extension</a></td>
    </tr>
    <tr>
      <td><a href="https://sourceforge.net/projects/libtorrent/files/py-libtorrent/">python bindings</a></td>
      <td><a href="features.html">features</a></td>
      <td><a href="dht_sec.html">DHT security extension</a></td>
    </tr>
    <tr>
      <td><a href="https://sourceforge.net/p/libtorrent/mailman/libtorrent-discuss/">mailing list archive</a></td>
      <td><a href="contributing.html">contributing</a></td>
      <td><a href="streaming.html">streaming</a></td>
    </tr>
    <tr>
      <td><a href="https://github.com/arvidn/libtorrent/issues">report a bug</a></td>
      <td><a href="building.html">building</a></td>
      <td><a href="bittorrent.pdf">bittorrent slides</a></td>
    </tr>
    </table>
    </div>
    <div id="filler"></div>

</div>
</body>
</html>