File: tutorial.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 (479 lines) | stat: -rw-r--r-- 60,191 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
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
<?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>libtorrent manual</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" id="libtorrent-manual">
    <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">
<h1 class="title">libtorrent manual</h1>
<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>
<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="#tutorial" id="id2">tutorial</a><ul>
<li><a class="reference internal" href="#alert-masks" id="id3">alert masks</a></li>
<li><a class="reference internal" href="#session-destruction" id="id4">session destruction</a></li>
<li><a class="reference internal" href="#asynchronous-operations" id="id5">asynchronous operations</a></li>
<li><a class="reference internal" href="#torrent-status-updates" id="id6">torrent_status_updates</a></li>
<li><a class="reference internal" href="#resuming-torrents" id="id7">resuming torrents</a></li>
<li><a class="reference internal" href="#example" id="id8">example</a></li>
<li><a class="reference internal" href="#torrent-files" id="id9">torrent files</a></li>
<li><a class="reference internal" href="#bencoding" id="id10">bencoding</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="tutorial">
<h1>tutorial</h1>
<p>The fundamental feature of starting and downloading torrents in libtorrent is
achieved by creating a <em>session</em>, which provides the context and a container for
torrents. This is done with via the <a class="reference external" href="reference-Core.html#session">session</a> class, most of its interface is
documented under <a class="reference external" href="reference-Core.html#session_handle">session_handle</a> though.</p>
<p>To add a torrent to the session, you fill in an <a class="reference external" href="reference-Core.html#add_torrent_params">add_torrent_params</a> object and
pass it either to <a class="reference external" href="reference-Core.html#add_torrent()">add_torrent()</a> or <a class="reference external" href="reference-Core.html#add_torrent()">async_add_torrent()</a>.</p>
<p><tt class="docutils literal">add_torrent()</tt> is a blocking call which returns a <a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a>.</p>
<p>For example:</p>
<pre class="code c++ literal-block">
<span class="comment preproc">#include</span> <span class="comment preprocfile">&lt;libtorrent/session.hpp&gt;</span><span class="comment preproc">
#include</span> <span class="comment preprocfile">&lt;libtorrent/add_torrent_params.hpp&gt;</span><span class="comment preproc">
#include</span> <span class="comment preprocfile">&lt;libtorrent/torrent_handle.hpp&gt;</span><span class="comment preproc">
#include</span> <span class="comment preprocfile">&lt;libtorrent/magnet_uri.hpp&gt;</span><span class="comment preproc">
</span>
<span class="keyword">namespace</span> <span class="name">lt</span> <span class="operator">=</span> <span class="name">libtorrent</span><span class="punctuation">;</span>
<span class="keyword type">int</span> <span class="name function">main</span><span class="punctuation">(</span><span class="keyword type">int</span> <span class="name">argc</span><span class="punctuation">,</span> <span class="keyword type">char</span> <span class="keyword">const</span><span class="operator">*</span> <span class="name">argv</span><span class="punctuation">[])</span>
<span class="punctuation">{</span>
        <span class="keyword">if</span> <span class="punctuation">(</span><span class="name">argc</span> <span class="operator">!=</span> <span class="literal number integer">2</span><span class="punctuation">)</span> <span class="punctuation">{</span>
                <span class="name">fprintf</span><span class="punctuation">(</span><span class="name">stderr</span><span class="punctuation">,</span> <span class="literal string">&quot;usage: %s &lt;magnet-url&gt;</span><span class="literal string escape">\n</span><span class="literal string">&quot;</span><span class="punctuation">);</span>
                <span class="keyword">return</span> <span class="literal number integer">1</span><span class="punctuation">;</span>
        <span class="punctuation">}</span>
        <span class="name">lt</span><span class="operator">::</span><span class="name">session</span> <span class="name">ses</span><span class="punctuation">;</span>

        <span class="name">lt</span><span class="operator">::</span><span class="name">add_torrent_params</span> <span class="name">atp</span><span class="punctuation">;</span>
        <span class="name">lt</span><span class="operator">::</span><span class="name">error_code</span> <span class="name">ec</span><span class="punctuation">;</span>
        <span class="name">lt</span><span class="operator">::</span><span class="name">parse_magnet_uri</span><span class="punctuation">(</span><span class="name">argv</span><span class="punctuation">[</span><span class="literal number integer">1</span><span class="punctuation">],</span> <span class="name">atp</span><span class="punctuation">,</span> <span class="name">ec</span><span class="punctuation">);</span>
        <span class="name">atp</span><span class="punctuation">.</span><span class="name">save_path</span> <span class="operator">=</span> <span class="literal string">&quot;.&quot;</span><span class="punctuation">;</span> <span class="comment single">// save in current dir
</span>        <span class="name">lt</span><span class="operator">::</span><span class="name">torrent_handle</span> <span class="name">h</span> <span class="operator">=</span> <span class="name">ses</span><span class="punctuation">.</span><span class="name">add_torrent</span><span class="punctuation">(</span><span class="name">atp</span><span class="punctuation">);</span>

        <span class="comment single">// ...
</span><span class="punctuation">}</span>
</pre>
<p>Once you have a <a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a>, you can affect it as well as querying status.
First, let's extend the example to print out messages from the bittorrent engine
about progress and events happening under the hood. libtorrent has a mechanism
referred to as <em>alerts</em> to communicate back information to the client application.</p>
<p>Clients can poll a session for new alerts via the <a class="reference external" href="reference-Core.html#pop_alerts()">pop_alerts()</a> call. This
function fills in a vector of alert pointers with all new alerts since the last
call to this function. The pointers are owned by the session object at will
become invalidated by the next call to <a class="reference external" href="reference-Core.html#pop_alerts()">pop_alerts()</a>.</p>
<p>The alerts form a class hierarchy with <a class="reference external" href="reference-Alerts.html#alert">alert</a> as the root class. Each specific
kind of alert may include additional state, specific to the kind of message. All
alerts implement a message() function that prints out pertinent information
of the alert message. This can be convenient for simply logging events.</p>
<p>For programatically react to certain events, use <a class="reference external" href="reference-Alerts.html#alert_cast()">alert_cast&lt;&gt;</a> to attempt
a down cast of an alert object to a more specific type.</p>
<p>In order to print out events from libtorrent as well as exiting when the torrent
completes downloading, we can poll the session for alerts periodically and print
them out, as well as listening for the <a class="reference external" href="reference-Alerts.html#torrent-finished-alert">torrent_finished_alert</a>, which is posted
when a torrent completes.</p>
<pre class="code c++ literal-block">
<span class="comment preproc">#include</span> <span class="comment preprocfile">&lt;iostream&gt;</span><span class="comment preproc">
#include</span> <span class="comment preprocfile">&lt;thread&gt;</span><span class="comment preproc">
#include</span> <span class="comment preprocfile">&lt;chrono&gt;</span><span class="comment preproc">
</span>
<span class="comment preproc">#include</span> <span class="comment preprocfile">&lt;libtorrent/session.hpp&gt;</span><span class="comment preproc">
#include</span> <span class="comment preprocfile">&lt;libtorrent/add_torrent_params.hpp&gt;</span><span class="comment preproc">
#include</span> <span class="comment preprocfile">&lt;libtorrent/torrent_handle.hpp&gt;</span><span class="comment preproc">
#include</span> <span class="comment preprocfile">&lt;libtorrent/alert_types.hpp&gt;</span><span class="comment preproc">
#include</span> <span class="comment preprocfile">&lt;libtorrent/magnet_uri.hpp&gt;</span><span class="comment preproc">
#include</span> <span class="comment preprocfile">&lt;libtorrent/error_code.hpp&gt;</span><span class="comment preproc">
</span>
<span class="keyword type">int</span> <span class="name function">main</span><span class="punctuation">(</span><span class="keyword type">int</span> <span class="name">argc</span><span class="punctuation">,</span> <span class="keyword type">char</span> <span class="keyword">const</span><span class="operator">*</span> <span class="name">argv</span><span class="punctuation">[])</span>
<span class="punctuation">{</span>
  <span class="keyword">if</span> <span class="punctuation">(</span><span class="name">argc</span> <span class="operator">!=</span> <span class="literal number integer">2</span><span class="punctuation">)</span> <span class="punctuation">{</span>
    <span class="name">std</span><span class="operator">::</span><span class="name">cerr</span> <span class="operator">&lt;&lt;</span> <span class="literal string">&quot;usage: &quot;</span> <span class="operator">&lt;&lt;</span> <span class="name">argv</span><span class="punctuation">[</span><span class="literal number integer">0</span><span class="punctuation">]</span> <span class="operator">&lt;&lt;</span> <span class="literal string">&quot; &lt;magnet-url&gt;&quot;</span> <span class="operator">&lt;&lt;</span> <span class="name">std</span><span class="operator">::</span><span class="name">endl</span><span class="punctuation">;</span>
    <span class="keyword">return</span> <span class="literal number integer">1</span><span class="punctuation">;</span>
  <span class="punctuation">}</span>
  <span class="name">lt</span><span class="operator">::</span><span class="name">settings_pack</span> <span class="name">p</span><span class="punctuation">;</span>
  <span class="name">p</span><span class="punctuation">.</span><span class="name">set_int</span><span class="punctuation">(</span><span class="name">lt</span><span class="operator">::</span><span class="name">settings_pack</span><span class="operator">::</span><span class="name">alert_mask</span><span class="punctuation">,</span> <span class="name">lt</span><span class="operator">::</span><span class="name">alert</span><span class="operator">::</span><span class="name">status_notification</span>
    <span class="operator">|</span> <span class="name">lt</span><span class="operator">::</span><span class="name">alert</span><span class="operator">::</span><span class="name">error_notification</span><span class="punctuation">);</span>
  <span class="name">lt</span><span class="operator">::</span><span class="name">session</span> <span class="name">ses</span><span class="punctuation">(</span><span class="name">p</span><span class="punctuation">);</span>

  <span class="name">lt</span><span class="operator">::</span><span class="name">add_torrent_params</span> <span class="name">atp</span><span class="punctuation">;</span>
  <span class="name">lt</span><span class="operator">::</span><span class="name">error_code</span> <span class="name">ec</span><span class="punctuation">;</span>
  <span class="name">lt</span><span class="operator">::</span><span class="name">parse_magnet_uri</span><span class="punctuation">(</span><span class="name">argv</span><span class="punctuation">[</span><span class="literal number integer">1</span><span class="punctuation">],</span> <span class="name">atp</span><span class="punctuation">,</span> <span class="name">ec</span><span class="punctuation">);</span>
  <span class="keyword">if</span> <span class="punctuation">(</span><span class="name">ec</span><span class="punctuation">)</span> <span class="punctuation">{</span>
    <span class="name">std</span><span class="operator">::</span><span class="name">cerr</span> <span class="operator">&lt;&lt;</span> <span class="literal string">&quot;invalid magnet URI: &quot;</span> <span class="operator">&lt;&lt;</span> <span class="name">ec</span><span class="punctuation">.</span><span class="name">message</span><span class="punctuation">()</span> <span class="operator">&lt;&lt;</span> <span class="name">std</span><span class="operator">::</span><span class="name">endl</span><span class="punctuation">;</span>
    <span class="keyword">return</span> <span class="literal number integer">1</span><span class="punctuation">;</span>
  <span class="punctuation">}</span>
  <span class="name">atp</span><span class="punctuation">.</span><span class="name">save_path</span> <span class="operator">=</span> <span class="literal string">&quot;.&quot;</span><span class="punctuation">;</span> <span class="comment single">// save in current dir
</span>  <span class="name">lt</span><span class="operator">::</span><span class="name">torrent_handle</span> <span class="name">h</span> <span class="operator">=</span> <span class="name">ses</span><span class="punctuation">.</span><span class="name">add_torrent</span><span class="punctuation">(</span><span class="name">atp</span><span class="punctuation">);</span>

  <span class="keyword">for</span> <span class="punctuation">(;;)</span> <span class="punctuation">{</span>
    <span class="name">std</span><span class="operator">::</span><span class="name">vector</span><span class="operator">&lt;</span><span class="name">lt</span><span class="operator">::</span><span class="name">alert</span><span class="operator">*&gt;</span> <span class="name">alerts</span><span class="punctuation">;</span>
    <span class="name">ses</span><span class="punctuation">.</span><span class="name">pop_alerts</span><span class="punctuation">(</span><span class="operator">&amp;</span><span class="name">alerts</span><span class="punctuation">);</span>

    <span class="keyword">for</span> <span class="punctuation">(</span><span class="name">lt</span><span class="operator">::</span><span class="name">alert</span> <span class="keyword">const</span><span class="operator">*</span> <span class="name label">a</span> <span class="punctuation">:</span> <span class="name">alerts</span><span class="punctuation">)</span> <span class="punctuation">{</span>
      <span class="name">std</span><span class="operator">::</span><span class="name">cout</span> <span class="operator">&lt;&lt;</span> <span class="name">a</span><span class="operator">-&gt;</span><span class="name">message</span><span class="punctuation">()</span> <span class="operator">&lt;&lt;</span> <span class="name">std</span><span class="operator">::</span><span class="name">endl</span><span class="punctuation">;</span>
      <span class="comment single">// if we receive the finished alert or an error, we're done
</span>      <span class="keyword">if</span> <span class="punctuation">(</span><span class="name">lt</span><span class="operator">::</span><span class="name">alert_cast</span><span class="operator">&lt;</span><span class="name">lt</span><span class="operator">::</span><span class="name">torrent_finished_alert</span><span class="operator">&gt;</span><span class="punctuation">(</span><span class="name">a</span><span class="punctuation">))</span> <span class="punctuation">{</span>
        <span class="keyword">goto</span> <span class="name">done</span><span class="punctuation">;</span>
      <span class="punctuation">}</span>
      <span class="keyword">if</span> <span class="punctuation">(</span><span class="name">lt</span><span class="operator">::</span><span class="name">alert_cast</span><span class="operator">&lt;</span><span class="name">lt</span><span class="operator">::</span><span class="name">torrent_error_alert</span><span class="operator">&gt;</span><span class="punctuation">(</span><span class="name">a</span><span class="punctuation">))</span> <span class="punctuation">{</span>
        <span class="keyword">goto</span> <span class="name">done</span><span class="punctuation">;</span>
      <span class="punctuation">}</span>
    <span class="punctuation">}</span>
    <span class="name">std</span><span class="operator">::</span><span class="name">this_thread</span><span class="operator">::</span><span class="name">sleep_for</span><span class="punctuation">(</span><span class="name">std</span><span class="operator">::</span><span class="name">chrono</span><span class="operator">::</span><span class="name">milliseconds</span><span class="punctuation">(</span><span class="literal number integer">200</span><span class="punctuation">));</span>
  <span class="punctuation">}</span>
  <span class="name label">done</span><span class="punctuation">:</span>
  <span class="name">std</span><span class="operator">::</span><span class="name">cout</span> <span class="operator">&lt;&lt;</span> <span class="literal string">&quot;done, shutting down&quot;</span> <span class="operator">&lt;&lt;</span> <span class="name">std</span><span class="operator">::</span><span class="name">endl</span><span class="punctuation">;</span>
<span class="punctuation">}</span>
</pre>
<div class="section" id="alert-masks">
<h2>alert masks</h2>
<p>The output from this program will be quite verbose, which is probably a good
starting point to get some understanding of what's going on. Alerts are
categorized into alert categories. Each category can be enabled and disabled
independently via the <em>alert mask</em>.</p>
<p>The alert mask is a configuration option offered by libtorrent. There are many
configuration options, see <a class="reference external" href="reference-Settings.html#settings_pack">settings_pack</a>. The <a class="reference external" href="reference-Settings.html#alert_mask">alert_mask</a> setting is an integer
of the <a class="reference external" href="reference-Alerts.html#category_t">category flags</a> ORed together.</p>
<p>For instance, to only see the most pertinent alerts, the session can be
constructed like this:</p>
<pre class="code c++ literal-block">
<span class="name">lt</span><span class="operator">::</span><span class="name">settings_pack</span> <span class="name">pack</span><span class="punctuation">;</span>
<span class="name">pack</span><span class="punctuation">.</span><span class="name">set_int</span><span class="punctuation">(</span><span class="name">lt</span><span class="operator">::</span><span class="name">settings_pack</span><span class="operator">::</span><span class="name">alert_mask</span>
        <span class="punctuation">,</span> <span class="name">lt</span><span class="operator">::</span><span class="name">alert</span><span class="operator">::</span><span class="name">error_notification</span>
        <span class="operator">|</span> <span class="name">lt</span><span class="operator">::</span><span class="name">alert</span><span class="operator">::</span><span class="name">storage_notification</span>
        <span class="operator">|</span> <span class="name">lt</span><span class="operator">::</span><span class="name">alert</span><span class="operator">::</span><span class="name">status_notification</span><span class="punctuation">);</span>

<span class="name">lt</span><span class="operator">::</span><span class="name">session</span> <span class="name">ses</span><span class="punctuation">(</span><span class="name">pack</span><span class="punctuation">);</span>
</pre>
<p>Configuration options can be updated after the session is started by calling
<a class="reference external" href="reference-Core.html#apply_settings()">apply_settings()</a>. Some settings are best set before starting the session
though, like <a class="reference external" href="reference-Settings.html#listen_interfaces">listen_interfaces</a>, to avoid race conditions. If you start the
session with the default settings and then immediately change them, there will
still be a window where the default settings apply.</p>
<p>Changing the settings may trigger listen sockets to close and re-open and
NAT-PMP, UPnP updates to be sent. For this reason, it's typically a good idea
to batch settings updates into a single call.</p>
</div>
<div class="section" id="session-destruction">
<h2>session destruction</h2>
<p>The session destructor is blocking by default. When shutting down, trackers
will need to be contacted to stop torrents and other outstanding operations
need to be cancelled. Shutting down can sometimes take several seconds,
primarily because of trackers that are unresponsive (and time out) and also
DNS servers that are unresponsive. DNS lookups are especially difficult to
abort when stalled.</p>
<p>In order to be able to start destruction an wait for it asynchronously, one
can call <a class="reference external" href="reference-Core.html#abort()">session::abort()</a>.</p>
<p>This call returns a <a class="reference external" href="reference-Core.html#session_proxy">session_proxy</a> object, which is a handle keeping the session
state alive while destructing it. It deliberately does not provide any of the
session operations, since it's shutting down.</p>
<p>After having a <a class="reference external" href="reference-Core.html#session_proxy">session_proxy</a> object, the session destructor does not block.
However, the <a class="reference external" href="reference-Core.html#session_proxy">session_proxy</a> destructor <em>will</em>.</p>
<p>This can be used to shut down multiple sessions or other parts of the
application in parallel.</p>
</div>
<div class="section" id="asynchronous-operations">
<h2>asynchronous operations</h2>
<p>Essentially any call to a member function of <a class="reference external" href="reference-Core.html#session">session</a> or <a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a> that
returns a value is a blocking synchronous call. Meaning it will post a message
to the main libtorrent thread and wait for a response. Such calls may be
expensive, and in applications where stalls should be avoided (such as user
interface threads), blocking calls should be avoided.</p>
<p>In the example above, session::add_torrent() returns a <a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a> and is
thus blocking. For higher efficiency, <a class="reference external" href="reference-Core.html#add_torrent()">async_add_torrent()</a> will post a message
to the main thread to add a torrent, and post the resulting <a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a> back
in an alert (<a class="reference external" href="reference-Alerts.html#add-torrent-alert">add_torrent_alert</a>). This is especially useful when adding a lot
of torrents in quick succession, as there's no stall in between calls.</p>
<p>In the example above, we don't actually use the <a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a> for anything, so
converting it to use <a class="reference external" href="reference-Core.html#add_torrent()">async_add_torrent()</a> is just a matter of replacing the
<a class="reference external" href="reference-Core.html#add_torrent()">add_torrent()</a> call with <a class="reference external" href="reference-Core.html#add_torrent()">async_add_torrent()</a>.</p>
</div>
<div class="section" id="torrent-status-updates">
<h2>torrent_status_updates</h2>
<p>To get updates to the status of torrents, call <a class="reference external" href="reference-Core.html#post_torrent_updates()">post_torrent_updates()</a> on the
session object. This will cause libtorrent to post a <a class="reference external" href="reference-Alerts.html#state_update_alert">state_update_alert</a>
containing <a class="reference external" href="reference-Core.html#torrent_status">torrent_status</a> objects for all torrents whose status has <em>changed</em>
since the last call to <a class="reference external" href="reference-Core.html#post_torrent_updates()">post_torrent_updates()</a>.</p>
<p>The <a class="reference external" href="reference-Alerts.html#state_update_alert">state_update_alert</a> looks something like this:</p>
<pre class="code c++ literal-block">
<span class="keyword">struct</span> <span class="name label">state_update_alert</span> <span class="punctuation">:</span> <span class="name">alert</span>
<span class="punctuation">{</span>
        <span class="keyword">virtual</span> <span class="name">std</span><span class="operator">::</span><span class="name">string</span> <span class="name">message</span><span class="punctuation">()</span> <span class="keyword">const</span><span class="punctuation">;</span>
        <span class="name">std</span><span class="operator">::</span><span class="name">vector</span><span class="operator">&lt;</span><span class="name">torrent_status</span><span class="operator">&gt;</span> <span class="name">status</span><span class="punctuation">;</span>
<span class="punctuation">};</span>
</pre>
<p>The <tt class="docutils literal">status</tt> field only contains the <a class="reference external" href="reference-Core.html#torrent_status">torrent_status</a> for torrents with
updates since the last call. It may be empty if no torrent has updated its
state. This feature is critical for <a class="reference external" href="https://blog.libtorrent.org/2011/11/scalable-interfaces/">scalability</a>.</p>
<p>See the <a class="reference external" href="reference-Core.html#torrent_status">torrent_status</a> object for more information on what is in there.
Perhaps the most interesting fields are <tt class="docutils literal">total_payload_download</tt>,
<tt class="docutils literal">total_payload_upload</tt>, <tt class="docutils literal">num_peers</tt> and <tt class="docutils literal">state</tt>.</p>
</div>
<div class="section" id="resuming-torrents">
<h2>resuming torrents</h2>
<p>Since bittorrent downloads pieces of files in random order, it's not trivial to
resume a partial download. When resuming a download, the bittorrent engine must
restore the state of the downloading torrent, specifically which parts of the
file(s) are downloaded. There are two approaches to doing this:</p>
<ol class="arabic simple">
<li>read every piece of the downloaded files from disk and compare it against its
expected hash.</li>
<li>save to disk the state of which pieces (and partial pieces) are downloaded,
and load it back in again when resuming.</li>
</ol>
<p>If no resume data is provided with a torrent that's added, libtorrent will
employ (1) by default.</p>
<p>To save resume data, call <a class="reference external" href="reference-Core.html#save_resume_data()">save_resume_data()</a> on the <a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a> object.
This will ask libtorrent to generate the resume data and post it back in
a <a class="reference external" href="reference-Alerts.html#save_resume_data_alert">save_resume_data_alert</a>. If generating the resume data fails for any reason,
a <a class="reference external" href="reference-Alerts.html#save_resume_data_failed_alert">save_resume_data_failed_alert</a> is posted instead.</p>
<p>Exactly one of those alerts will be posted for every call to
<a class="reference external" href="reference-Core.html#save_resume_data()">save_resume_data()</a>. This is an important property when shutting down a
session with multiple torrents, every resume alert must be handled before
resuming with shut down. Any torrent may fail to save resume data, so the client
would need to keep a count of the outstanding resume files, decremented on
either <a class="reference external" href="reference-Alerts.html#save_resume_data_alert">save_resume_data_alert</a> or <a class="reference external" href="reference-Alerts.html#save_resume_data_failed_alert">save_resume_data_failed_alert</a>.</p>
<p>The <a class="reference external" href="reference-Alerts.html#save_resume_data_alert">save_resume_data_alert</a> looks something like this:</p>
<pre class="code c++ literal-block">
<span class="keyword">struct</span> <span class="name label">save_resume_data_alert</span> <span class="punctuation">:</span> <span class="name">torrent_alert</span>
<span class="punctuation">{</span>
        <span class="keyword">virtual</span> <span class="name">std</span><span class="operator">::</span><span class="name">string</span> <span class="name">message</span><span class="punctuation">()</span> <span class="keyword">const</span><span class="punctuation">;</span>

        <span class="comment single">// points to the resume data.
</span>        <span class="name">boost</span><span class="operator">::</span><span class="name">shared_ptr</span><span class="operator">&lt;</span><span class="name">entry</span><span class="operator">&gt;</span> <span class="name">resume_data</span><span class="punctuation">;</span>
<span class="punctuation">};</span>
</pre>
<p><tt class="docutils literal">resume_data</tt> points to an <a class="reference external" href="reference-Bencoding.html#entry">entry</a> object. This represents a node or a tree of
nodes in a <a class="reference external" href="https://en.wikipedia.org/wiki/Bencode">bencoded</a> structure, which is the native encoding scheme in
bittorrent. It can be encoded into a byte buffer or file using <a class="reference external" href="reference-Bencoding.html#bencode()">bencode()</a>.</p>
<p>When adding a torrent with resume data, set the <a class="reference external" href="reference-Core.html#resume_data">add_torrent_params::resume_data</a>
to contain the bencoded buffer of the resume data.</p>
</div>
<div class="section" id="example">
<h2>example</h2>
<p>Here's an updated version of the above example with the following updates:</p>
<ol class="arabic simple">
<li>not using blocking calls</li>
<li>printing torrent status updates rather than the raw log</li>
<li>saving and loading resume files</li>
</ol>
<pre class="code c++ literal-block">
<span class="comment preproc">#include</span> <span class="comment preprocfile">&lt;iostream&gt;</span><span class="comment preproc">
#include</span> <span class="comment preprocfile">&lt;thread&gt;</span><span class="comment preproc">
#include</span> <span class="comment preprocfile">&lt;chrono&gt;</span><span class="comment preproc">
#include</span> <span class="comment preprocfile">&lt;fstream&gt;</span><span class="comment preproc">
</span>
<span class="comment preproc">#include</span> <span class="comment preprocfile">&lt;libtorrent/session.hpp&gt;</span><span class="comment preproc">
#include</span> <span class="comment preprocfile">&lt;libtorrent/add_torrent_params.hpp&gt;</span><span class="comment preproc">
#include</span> <span class="comment preprocfile">&lt;libtorrent/torrent_handle.hpp&gt;</span><span class="comment preproc">
#include</span> <span class="comment preprocfile">&lt;libtorrent/alert_types.hpp&gt;</span><span class="comment preproc">
#include</span> <span class="comment preprocfile">&lt;libtorrent/bencode.hpp&gt;</span><span class="comment preproc">
#include</span> <span class="comment preprocfile">&lt;libtorrent/torrent_status.hpp&gt;</span><span class="comment preproc">
#include</span> <span class="comment preprocfile">&lt;libtorrent/magnet_uri.hpp&gt;</span><span class="comment preproc">
#include</span> <span class="comment preprocfile">&lt;libtorrent/error_code.hpp&gt;</span><span class="comment preproc">
</span>
<span class="keyword">using</span> <span class="name">clk</span> <span class="operator">=</span> <span class="name">std</span><span class="operator">::</span><span class="name">chrono</span><span class="operator">::</span><span class="name">steady_clock</span><span class="punctuation">;</span>

<span class="comment single">// return the name of a torrent status enum
</span><span class="keyword type">char</span> <span class="keyword">const</span><span class="operator">*</span> <span class="name function">state</span><span class="punctuation">(</span><span class="name">lt</span><span class="operator">::</span><span class="name">torrent_status</span><span class="operator">::</span><span class="name">state_t</span> <span class="name">s</span><span class="punctuation">)</span>
<span class="punctuation">{</span>
  <span class="keyword">switch</span><span class="punctuation">(</span><span class="name">s</span><span class="punctuation">)</span> <span class="punctuation">{</span>
    <span class="keyword">case</span> <span class="name">lt</span><span class="operator">::</span><span class="name">torrent_status</span><span class="operator">::</span><span class="name label">checking_files</span><span class="punctuation">:</span> <span class="keyword">return</span> <span class="literal string">&quot;checking&quot;</span><span class="punctuation">;</span>
    <span class="keyword">case</span> <span class="name">lt</span><span class="operator">::</span><span class="name">torrent_status</span><span class="operator">::</span><span class="name label">downloading_metadata</span><span class="punctuation">:</span> <span class="keyword">return</span> <span class="literal string">&quot;dl metadata&quot;</span><span class="punctuation">;</span>
    <span class="keyword">case</span> <span class="name">lt</span><span class="operator">::</span><span class="name">torrent_status</span><span class="operator">::</span><span class="name label">downloading</span><span class="punctuation">:</span> <span class="keyword">return</span> <span class="literal string">&quot;downloading&quot;</span><span class="punctuation">;</span>
    <span class="keyword">case</span> <span class="name">lt</span><span class="operator">::</span><span class="name">torrent_status</span><span class="operator">::</span><span class="name label">finished</span><span class="punctuation">:</span> <span class="keyword">return</span> <span class="literal string">&quot;finished&quot;</span><span class="punctuation">;</span>
    <span class="keyword">case</span> <span class="name">lt</span><span class="operator">::</span><span class="name">torrent_status</span><span class="operator">::</span><span class="name label">seeding</span><span class="punctuation">:</span> <span class="keyword">return</span> <span class="literal string">&quot;seeding&quot;</span><span class="punctuation">;</span>
    <span class="keyword">case</span> <span class="name">lt</span><span class="operator">::</span><span class="name">torrent_status</span><span class="operator">::</span><span class="name label">allocating</span><span class="punctuation">:</span> <span class="keyword">return</span> <span class="literal string">&quot;allocating&quot;</span><span class="punctuation">;</span>
    <span class="keyword">case</span> <span class="name">lt</span><span class="operator">::</span><span class="name">torrent_status</span><span class="operator">::</span><span class="name label">checking_resume_data</span><span class="punctuation">:</span> <span class="keyword">return</span> <span class="literal string">&quot;checking resume&quot;</span><span class="punctuation">;</span>
    <span class="keyword">default</span><span class="operator">:</span> <span class="keyword">return</span> <span class="literal string">&quot;&lt;&gt;&quot;</span><span class="punctuation">;</span>
  <span class="punctuation">}</span>
<span class="punctuation">}</span>

<span class="keyword type">int</span> <span class="name function">main</span><span class="punctuation">(</span><span class="keyword type">int</span> <span class="name">argc</span><span class="punctuation">,</span> <span class="keyword type">char</span> <span class="keyword">const</span><span class="operator">*</span> <span class="name">argv</span><span class="punctuation">[])</span>
<span class="punctuation">{</span>
  <span class="keyword">if</span> <span class="punctuation">(</span><span class="name">argc</span> <span class="operator">!=</span> <span class="literal number integer">2</span><span class="punctuation">)</span> <span class="punctuation">{</span>
    <span class="name">std</span><span class="operator">::</span><span class="name">cerr</span> <span class="operator">&lt;&lt;</span> <span class="literal string">&quot;usage: &quot;</span> <span class="operator">&lt;&lt;</span> <span class="name">argv</span><span class="punctuation">[</span><span class="literal number integer">0</span><span class="punctuation">]</span> <span class="operator">&lt;&lt;</span> <span class="literal string">&quot; &lt;magnet-url&gt;&quot;</span> <span class="operator">&lt;&lt;</span> <span class="name">std</span><span class="operator">::</span><span class="name">endl</span><span class="punctuation">;</span>
    <span class="keyword">return</span> <span class="literal number integer">1</span><span class="punctuation">;</span>
  <span class="punctuation">}</span>

  <span class="name">lt</span><span class="operator">::</span><span class="name">settings_pack</span> <span class="name">pack</span><span class="punctuation">;</span>
  <span class="name">pack</span><span class="punctuation">.</span><span class="name">set_int</span><span class="punctuation">(</span><span class="name">lt</span><span class="operator">::</span><span class="name">settings_pack</span><span class="operator">::</span><span class="name">alert_mask</span>
    <span class="punctuation">,</span> <span class="name">lt</span><span class="operator">::</span><span class="name">alert</span><span class="operator">::</span><span class="name">error_notification</span>
    <span class="operator">|</span> <span class="name">lt</span><span class="operator">::</span><span class="name">alert</span><span class="operator">::</span><span class="name">storage_notification</span>
    <span class="operator">|</span> <span class="name">lt</span><span class="operator">::</span><span class="name">alert</span><span class="operator">::</span><span class="name">status_notification</span><span class="punctuation">);</span>

  <span class="name">lt</span><span class="operator">::</span><span class="name">session</span> <span class="name">ses</span><span class="punctuation">(</span><span class="name">pack</span><span class="punctuation">);</span>
  <span class="name">lt</span><span class="operator">::</span><span class="name">add_torrent_params</span> <span class="name">atp</span><span class="punctuation">;</span>
  <span class="name">clk</span><span class="operator">::</span><span class="name">time_point</span> <span class="name">last_save_resume</span> <span class="operator">=</span> <span class="name">clk</span><span class="operator">::</span><span class="name">now</span><span class="punctuation">();</span>

  <span class="comment single">// load resume data from disk and pass it in as we add the magnet link
</span>  <span class="name">std</span><span class="operator">::</span><span class="name">ifstream</span> <span class="name">ifs</span><span class="punctuation">(</span><span class="literal string">&quot;.resume_file&quot;</span><span class="punctuation">,</span> <span class="name">std</span><span class="operator">::</span><span class="name">ios_base</span><span class="operator">::</span><span class="name">binary</span><span class="punctuation">);</span>
  <span class="name">ifs</span><span class="punctuation">.</span><span class="name">unsetf</span><span class="punctuation">(</span><span class="name">std</span><span class="operator">::</span><span class="name">ios_base</span><span class="operator">::</span><span class="name">skipws</span><span class="punctuation">);</span>
  <span class="name">atp</span><span class="punctuation">.</span><span class="name">resume_data</span><span class="punctuation">.</span><span class="name">assign</span><span class="punctuation">(</span><span class="name">std</span><span class="operator">::</span><span class="name">istream_iterator</span><span class="operator">&lt;</span><span class="keyword type">char</span><span class="operator">&gt;</span><span class="punctuation">(</span><span class="name">ifs</span><span class="punctuation">)</span>
    <span class="punctuation">,</span> <span class="name">std</span><span class="operator">::</span><span class="name">istream_iterator</span><span class="operator">&lt;</span><span class="keyword type">char</span><span class="operator">&gt;</span><span class="punctuation">());</span>
  <span class="name">lt</span><span class="operator">::</span><span class="name">error_code</span> <span class="name">ec</span><span class="punctuation">;</span>
  <span class="name">lt</span><span class="operator">::</span><span class="name">parse_magnet_uri</span><span class="punctuation">(</span><span class="name">argv</span><span class="punctuation">[</span><span class="literal number integer">1</span><span class="punctuation">],</span> <span class="name">atp</span><span class="punctuation">,</span> <span class="name">ec</span><span class="punctuation">);</span>
  <span class="keyword">if</span> <span class="punctuation">(</span><span class="name">ec</span><span class="punctuation">)</span> <span class="punctuation">{</span>
    <span class="name">std</span><span class="operator">::</span><span class="name">cerr</span> <span class="operator">&lt;&lt;</span> <span class="literal string">&quot;invalid magnet URI: &quot;</span> <span class="operator">&lt;&lt;</span> <span class="name">ec</span><span class="punctuation">.</span><span class="name">message</span><span class="punctuation">()</span> <span class="operator">&lt;&lt;</span> <span class="name">std</span><span class="operator">::</span><span class="name">endl</span><span class="punctuation">;</span>
    <span class="keyword">return</span> <span class="literal number integer">1</span><span class="punctuation">;</span>
  <span class="punctuation">}</span>
  <span class="name">atp</span><span class="punctuation">.</span><span class="name">save_path</span> <span class="operator">=</span> <span class="literal string">&quot;.&quot;</span><span class="punctuation">;</span> <span class="comment single">// save in current dir
</span>  <span class="name">ses</span><span class="punctuation">.</span><span class="name">async_add_torrent</span><span class="punctuation">(</span><span class="name">atp</span><span class="punctuation">);</span>

  <span class="comment single">// this is the handle we'll set once we get the notification of it being
</span>  <span class="comment single">// added
</span>  <span class="name">lt</span><span class="operator">::</span><span class="name">torrent_handle</span> <span class="name">h</span><span class="punctuation">;</span>
  <span class="keyword">for</span> <span class="punctuation">(;;)</span> <span class="punctuation">{</span>
    <span class="name">std</span><span class="operator">::</span><span class="name">vector</span><span class="operator">&lt;</span><span class="name">lt</span><span class="operator">::</span><span class="name">alert</span><span class="operator">*&gt;</span> <span class="name">alerts</span><span class="punctuation">;</span>
    <span class="name">ses</span><span class="punctuation">.</span><span class="name">pop_alerts</span><span class="punctuation">(</span><span class="operator">&amp;</span><span class="name">alerts</span><span class="punctuation">);</span>

    <span class="keyword">for</span> <span class="punctuation">(</span><span class="name">lt</span><span class="operator">::</span><span class="name">alert</span> <span class="keyword">const</span><span class="operator">*</span> <span class="name label">a</span> <span class="punctuation">:</span> <span class="name">alerts</span><span class="punctuation">)</span> <span class="punctuation">{</span>
      <span class="keyword">if</span> <span class="punctuation">(</span><span class="keyword">auto</span> <span class="name">at</span> <span class="operator">=</span> <span class="name">lt</span><span class="operator">::</span><span class="name">alert_cast</span><span class="operator">&lt;</span><span class="name">lt</span><span class="operator">::</span><span class="name">add_torrent_alert</span><span class="operator">&gt;</span><span class="punctuation">(</span><span class="name">a</span><span class="punctuation">))</span> <span class="punctuation">{</span>
        <span class="name">h</span> <span class="operator">=</span> <span class="name">at</span><span class="operator">-&gt;</span><span class="name">handle</span><span class="punctuation">;</span>
      <span class="punctuation">}</span>
      <span class="comment single">// if we receive the finished alert or an error, we're done
</span>      <span class="keyword">if</span> <span class="punctuation">(</span><span class="name">lt</span><span class="operator">::</span><span class="name">alert_cast</span><span class="operator">&lt;</span><span class="name">lt</span><span class="operator">::</span><span class="name">torrent_finished_alert</span><span class="operator">&gt;</span><span class="punctuation">(</span><span class="name">a</span><span class="punctuation">))</span> <span class="punctuation">{</span>
        <span class="name">h</span><span class="punctuation">.</span><span class="name">save_resume_data</span><span class="punctuation">();</span>
        <span class="keyword">goto</span> <span class="name">done</span><span class="punctuation">;</span>
      <span class="punctuation">}</span>
      <span class="keyword">if</span> <span class="punctuation">(</span><span class="name">lt</span><span class="operator">::</span><span class="name">alert_cast</span><span class="operator">&lt;</span><span class="name">lt</span><span class="operator">::</span><span class="name">torrent_error_alert</span><span class="operator">&gt;</span><span class="punctuation">(</span><span class="name">a</span><span class="punctuation">))</span> <span class="punctuation">{</span>
        <span class="name">std</span><span class="operator">::</span><span class="name">cout</span> <span class="operator">&lt;&lt;</span> <span class="name">a</span><span class="operator">-&gt;</span><span class="name">message</span><span class="punctuation">()</span> <span class="operator">&lt;&lt;</span> <span class="name">std</span><span class="operator">::</span><span class="name">endl</span><span class="punctuation">;</span>
        <span class="keyword">goto</span> <span class="name">done</span><span class="punctuation">;</span>
      <span class="punctuation">}</span>

      <span class="comment single">// when resume data is ready, save it
</span>      <span class="keyword">if</span> <span class="punctuation">(</span><span class="keyword">auto</span> <span class="name">rd</span> <span class="operator">=</span> <span class="name">lt</span><span class="operator">::</span><span class="name">alert_cast</span><span class="operator">&lt;</span><span class="name">lt</span><span class="operator">::</span><span class="name">save_resume_data_alert</span><span class="operator">&gt;</span><span class="punctuation">(</span><span class="name">a</span><span class="punctuation">))</span> <span class="punctuation">{</span>
        <span class="name">std</span><span class="operator">::</span><span class="name">ofstream</span> <span class="name">of</span><span class="punctuation">(</span><span class="literal string">&quot;.resume_file&quot;</span><span class="punctuation">,</span> <span class="name">std</span><span class="operator">::</span><span class="name">ios_base</span><span class="operator">::</span><span class="name">binary</span><span class="punctuation">);</span>
        <span class="name">of</span><span class="punctuation">.</span><span class="name">unsetf</span><span class="punctuation">(</span><span class="name">std</span><span class="operator">::</span><span class="name">ios_base</span><span class="operator">::</span><span class="name">skipws</span><span class="punctuation">);</span>
        <span class="name">lt</span><span class="operator">::</span><span class="name">bencode</span><span class="punctuation">(</span><span class="name">std</span><span class="operator">::</span><span class="name">ostream_iterator</span><span class="operator">&lt;</span><span class="keyword type">char</span><span class="operator">&gt;</span><span class="punctuation">(</span><span class="name">of</span><span class="punctuation">)</span>
          <span class="punctuation">,</span> <span class="operator">*</span><span class="name">rd</span><span class="operator">-&gt;</span><span class="name">resume_data</span><span class="punctuation">);</span>
      <span class="punctuation">}</span>

      <span class="keyword">if</span> <span class="punctuation">(</span><span class="keyword">auto</span> <span class="name">st</span> <span class="operator">=</span> <span class="name">lt</span><span class="operator">::</span><span class="name">alert_cast</span><span class="operator">&lt;</span><span class="name">lt</span><span class="operator">::</span><span class="name">state_update_alert</span><span class="operator">&gt;</span><span class="punctuation">(</span><span class="name">a</span><span class="punctuation">))</span> <span class="punctuation">{</span>
        <span class="keyword">if</span> <span class="punctuation">(</span><span class="name">st</span><span class="operator">-&gt;</span><span class="name">status</span><span class="punctuation">.</span><span class="name">empty</span><span class="punctuation">())</span> <span class="keyword">continue</span><span class="punctuation">;</span>

        <span class="comment single">// we only have a single torrent, so we know which one
</span>        <span class="comment single">// the status is for
</span>        <span class="name">lt</span><span class="operator">::</span><span class="name">torrent_status</span> <span class="keyword">const</span><span class="operator">&amp;</span> <span class="name">s</span> <span class="operator">=</span> <span class="name">st</span><span class="operator">-&gt;</span><span class="name">status</span><span class="punctuation">[</span><span class="literal number integer">0</span><span class="punctuation">];</span>
        <span class="name">std</span><span class="operator">::</span><span class="name">cout</span> <span class="operator">&lt;&lt;</span> <span class="literal string">&quot;</span><span class="literal string escape">\r</span><span class="literal string">&quot;</span> <span class="operator">&lt;&lt;</span> <span class="name">state</span><span class="punctuation">(</span><span class="name">s</span><span class="punctuation">.</span><span class="name">state</span><span class="punctuation">)</span> <span class="operator">&lt;&lt;</span> <span class="literal string">&quot; &quot;</span>
          <span class="operator">&lt;&lt;</span> <span class="punctuation">(</span><span class="name">s</span><span class="punctuation">.</span><span class="name">download_payload_rate</span> <span class="operator">/</span> <span class="literal number integer">1000</span><span class="punctuation">)</span> <span class="operator">&lt;&lt;</span> <span class="literal string">&quot; kB/s &quot;</span>
          <span class="operator">&lt;&lt;</span> <span class="punctuation">(</span><span class="name">s</span><span class="punctuation">.</span><span class="name">total_done</span> <span class="operator">/</span> <span class="literal number integer">1000</span><span class="punctuation">)</span> <span class="operator">&lt;&lt;</span> <span class="literal string">&quot; kB (&quot;</span>
          <span class="operator">&lt;&lt;</span> <span class="punctuation">(</span><span class="name">s</span><span class="punctuation">.</span><span class="name">progress_ppm</span> <span class="operator">/</span> <span class="literal number integer">10000</span><span class="punctuation">)</span> <span class="operator">&lt;&lt;</span> <span class="literal string">&quot;%) downloaded</span><span class="literal string escape">\x1b</span><span class="literal string">[K&quot;</span><span class="punctuation">;</span>
        <span class="name">std</span><span class="operator">::</span><span class="name">cout</span><span class="punctuation">.</span><span class="name">flush</span><span class="punctuation">();</span>
      <span class="punctuation">}</span>
    <span class="punctuation">}</span>
    <span class="name">std</span><span class="operator">::</span><span class="name">this_thread</span><span class="operator">::</span><span class="name">sleep_for</span><span class="punctuation">(</span><span class="name">std</span><span class="operator">::</span><span class="name">chrono</span><span class="operator">::</span><span class="name">milliseconds</span><span class="punctuation">(</span><span class="literal number integer">200</span><span class="punctuation">));</span>

    <span class="comment single">// ask the session to post a state_update_alert, to update our
</span>    <span class="comment single">// state output for the torrent
</span>    <span class="name">ses</span><span class="punctuation">.</span><span class="name">post_torrent_updates</span><span class="punctuation">();</span>

    <span class="comment single">// save resume data once every 30 seconds
</span>    <span class="keyword">if</span> <span class="punctuation">(</span><span class="name">clk</span><span class="operator">::</span><span class="name">now</span><span class="punctuation">()</span> <span class="operator">-</span> <span class="name">last_save_resume</span> <span class="operator">&gt;</span> <span class="name">std</span><span class="operator">::</span><span class="name">chrono</span><span class="operator">::</span><span class="name">seconds</span><span class="punctuation">(</span><span class="literal number integer">30</span><span class="punctuation">))</span> <span class="punctuation">{</span>
      <span class="name">h</span><span class="punctuation">.</span><span class="name">save_resume_data</span><span class="punctuation">();</span>
      <span class="name">last_save_resume</span> <span class="operator">=</span> <span class="name">clk</span><span class="operator">::</span><span class="name">now</span><span class="punctuation">();</span>
    <span class="punctuation">}</span>
  <span class="punctuation">}</span>

  <span class="comment single">// TODO: ideally we should save resume data here
</span>
<span class="name label">done</span><span class="punctuation">:</span>
  <span class="name">std</span><span class="operator">::</span><span class="name">cout</span> <span class="operator">&lt;&lt;</span> <span class="literal string">&quot;</span><span class="literal string escape">\n</span><span class="literal string">done, shutting down&quot;</span> <span class="operator">&lt;&lt;</span> <span class="name">std</span><span class="operator">::</span><span class="name">endl</span><span class="punctuation">;</span>
<span class="punctuation">}</span>
</pre>
</div>
<div class="section" id="torrent-files">
<h2>torrent files</h2>
<p>To add torrent files to a session (as opposed to a magnet link), it must first
be loaded into a <a class="reference external" href="reference-Core.html#torrent_info">torrent_info</a> object.</p>
<p>The <a class="reference external" href="reference-Core.html#torrent_info">torrent_info</a> object can be created either by filename a buffer or a
bencoded structure. When adding by filename, there's a sanity check limit on the
size of the file, for adding arbitrarily large torrents, load the file outside
of the constructor.</p>
<p>The <a class="reference external" href="reference-Core.html#torrent_info">torrent_info</a> object provides an opportunity to query information about the
.torrent file as well as mutating it before adding it to the session.</p>
</div>
<div class="section" id="bencoding">
<h2>bencoding</h2>
<p><a class="reference external" href="https://en.wikipedia.org/wiki/Bencode">bencoded</a> structures is the default data storage format used by bittorrent, such
as .torrent files, tracker announce and scrape responses and some wire protocol
extensions. libtorrent provides an efficient framework for decoding bencoded
data through <a class="reference external" href="reference-Bdecoding.html#bdecode()">bdecode()</a> function.</p>
<p>There are two separate mechanisms for <em>encoding</em> and <em>decoding</em>. When decoding,
use the <a class="reference external" href="reference-Bdecoding.html#bdecode()">bdecode()</a> function that returns a <a class="reference external" href="reference-Bdecoding.html#bdecode-node">bdecode_node</a>. When encoding, use
<a class="reference external" href="reference-Bencoding.html#bencode()">bencode()</a> taking an <a class="reference external" href="reference-Bencoding.html#entry">entry</a> object.</p>
<p>The key property of <a class="reference external" href="reference-Bdecoding.html#bdecode()">bdecode()</a> is that it does not copy any data out of the
buffer that was parsed. It builds the tree structures of references pointing
into the buffer. The buffer must stay alive and valid for as long as the
<a class="reference external" href="reference-Bdecoding.html#bdecode-node">bdecode_node</a> is in use.</p>
<p>For performance details on <a class="reference external" href="reference-Bdecoding.html#bdecode()">bdecode()</a>, see the <a class="reference external" href="https://blog.libtorrent.org/2015/03/bdecode-parsers/">blog post about it</a>.</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>