File: reference-Plugins.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 (768 lines) | stat: -rw-r--r-- 43,359 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
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
<?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-Plugins.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="plugins">
<h1>Plugins</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="#plugins" id="id80">Plugins</a><ul>
<li><a class="reference internal" href="#a-word-of-caution" id="id81">a word of caution</a></li>
</ul>
</li>
<li><a class="reference internal" href="#plugin-interface" id="id82">plugin-interface</a></li>
<li><a class="reference internal" href="#custom-alerts" id="id83">custom alerts</a><ul>
<li><a class="reference internal" href="#plugin" id="id84">plugin</a></li>
<li><a class="reference internal" href="#torrent-plugin" id="id85">torrent_plugin</a></li>
<li><a class="reference internal" href="#peer-plugin" id="id86">peer_plugin</a></li>
<li><a class="reference internal" href="#crypto-plugin" id="id87">crypto_plugin</a></li>
<li><a class="reference internal" href="#create-ut-metadata-plugin" id="id88">create_ut_metadata_plugin()</a></li>
<li><a class="reference internal" href="#create-smart-ban-plugin" id="id89">create_smart_ban_plugin()</a></li>
<li><a class="reference internal" href="#create-ut-pex-plugin" id="id90">create_ut_pex_plugin()</a></li>
</ul>
</li>
</ul>
</div>
<p>libtorrent has a <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> interface for implementing extensions to the protocol.
These can be general extensions for transferring metadata or peer exchange
extensions, or it could be used to provide a way to customize the protocol
to fit a particular (closed) network.</p>
<p>In short, the <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> interface makes it possible to:</p>
<ul class="simple">
<li>register extension messages (sent in the extension handshake), see
<a class="reference external" href="extension_protocol.html">extensions</a>.</li>
<li>add data and parse data from the extension handshake.</li>
<li>send extension messages and standard bittorrent messages.</li>
<li>override or block the handling of standard bittorrent messages.</li>
<li>save and restore state via the <a class="reference external" href="reference-Core.html#session">session</a> state</li>
<li>see all alerts that are posted</li>
</ul>
<div class="section" id="a-word-of-caution">
<h2>a word of caution</h2>
<p>Writing your own <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> is a very easy way to introduce serious bugs such as
dead locks and race conditions. Since a <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> has access to internal
structures it is also quite easy to sabotage libtorrent's operation.</p>
<p>All the callbacks in this interface are called with the main libtorrent thread
mutex locked. And they are always called from the libtorrent network thread. In
case portions of your <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> are called from other threads, typically the main
thread, you cannot use any of the member functions on the internal structures
in libtorrent, since those require the mutex to be locked. Furthermore, you would
also need to have a mutex on your own shared data within the <a class="reference external" href="reference-Plugins.html#plugin">plugin</a>, to make
sure it is not accessed at the same time from the libtorrent thread (through a
callback). See <a class="reference external" href="http://www.boost.org/doc/html/mutex.html">boost thread's mutex</a>. If you need to send out a message from
another thread, it is advised to use an internal queue, and do the actual
sending in <tt class="docutils literal">tick()</tt>.</p>
<p>Since the <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> interface gives you easy access to internal structures, it
is not supported as a stable API. Plugins should be considered specific to a
specific version of libtorrent. Although, in practice the internals mostly
don't change that dramatically.</p>
</div>
</div>
<div class="section" id="plugin-interface">
<h1>plugin-interface</h1>
<p>The <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> interface consists of three base classes that the <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> may
implement. These are called <a class="reference external" href="reference-Plugins.html#plugin">plugin</a>, <a class="reference external" href="reference-Plugins.html#torrent_plugin">torrent_plugin</a> and <a class="reference external" href="reference-Plugins.html#peer_plugin">peer_plugin</a>.
They are found in the <tt class="docutils literal">&lt;libtorrent/extensions.hpp&gt;</tt> header.</p>
<p>These plugins are instantiated for each <a class="reference external" href="reference-Core.html#session">session</a>, torrent and possibly each peer,
respectively.</p>
<p>For plugins that only need per torrent state, it is enough to only implement
<tt class="docutils literal">torrent_plugin</tt> and pass a constructor function or function object to
<tt class="docutils literal"><span class="pre">session::add_extension()</span></tt> or <tt class="docutils literal"><span class="pre">torrent_handle::add_extension()</span></tt> (if the
torrent has already been started and you want to hook in the extension at
run-time).</p>
<p>The signature of the function is:</p>
<pre class="literal-block">
boost::shared_ptr&lt;torrent_plugin&gt; (*)(torrent_handle const&amp;, void*);
</pre>
<p>The second argument is the userdata passed to <tt class="docutils literal"><span class="pre">session::add_torrent()</span></tt> or
<tt class="docutils literal"><span class="pre">torrent_handle::add_extension()</span></tt>.</p>
<p>The function should return a <tt class="docutils literal"><span class="pre">boost::shared_ptr&lt;torrent_plugin&gt;</span></tt> which
may or may not be 0. If it is a null pointer, the extension is simply ignored
for this torrent. If it is a valid pointer (to a class inheriting
<tt class="docutils literal">torrent_plugin</tt>), it will be associated with this torrent and callbacks
will be made on torrent events.</p>
<p>For more elaborate plugins which require <a class="reference external" href="reference-Core.html#session">session</a> wide state, you would
implement <tt class="docutils literal">plugin</tt>, construct an object (in a <tt class="docutils literal"><span class="pre">boost::shared_ptr</span></tt>) and pass
it in to <tt class="docutils literal"><span class="pre">session::add_extension()</span></tt>.</p>
</div>
<div class="section" id="custom-alerts">
<h1>custom alerts</h1>
<p>Since plugins are running within internal libtorrent threads, one convenient
way to communicate with the client is to post custom alerts.</p>
<p>The expected interface of any <a class="reference external" href="reference-Alerts.html#alert">alert</a>, apart from deriving from the <a class="reference external" href="reference-Alerts.html#alert">alert</a>
base class, looks like this:</p>
<pre class="literal-block">
static const int alert_type = <em>&lt;unique alert ID&gt;</em>;
virtual int type() const { return alert_type; }

virtual std::string message() const;

virtual std::auto_ptr&lt;alert&gt; clone() const
{ return std::auto_ptr&lt;alert&gt;(new name(*this)); }

static const int static_category = <em>&lt;bitmask of alert::category_t flags&gt;</em>;
virtual int category() const { return static_category; }

virtual char const* what() const { return <em>&lt;string literal of the name of this alert&gt;</em>; }
</pre>
<p>The <tt class="docutils literal">alert_type</tt> is used for the type-checking in <tt class="docutils literal">alert_cast</tt>. It must
not collide with any other <a class="reference external" href="reference-Alerts.html#alert">alert</a>. The built-in alerts in libtorrent will
not use <a class="reference external" href="reference-Alerts.html#alert">alert</a> type IDs greater than <tt class="docutils literal">user_alert_id</tt>. When defining your
own <a class="reference external" href="reference-Alerts.html#alert">alert</a>, make sure it's greater than this constant.</p>
<p><tt class="docutils literal">type()</tt> is the run-time equivalence of the <tt class="docutils literal">alert_type</tt>.</p>
<p>The <tt class="docutils literal">message()</tt> virtual function is expected to construct a useful
string representation of the <a class="reference external" href="reference-Alerts.html#alert">alert</a> and the event or data it represents.
Something convenient to put in a log file for instance.</p>
<p><tt class="docutils literal">clone()</tt> is used internally to copy alerts. The suggested implementation
of simply allocating a new instance as a copy of <tt class="docutils literal">*this</tt> is all that's
expected.</p>
<p>The static category is required for checking whether or not the category
for a specific <a class="reference external" href="reference-Alerts.html#alert">alert</a> is enabled or not, without instantiating the <a class="reference external" href="reference-Alerts.html#alert">alert</a>.
The <tt class="docutils literal">category</tt> virtual function is the run-time equivalence.</p>
<p>The <tt class="docutils literal">what()</tt> virtual function may simply be a string literal of the class
name of your <a class="reference external" href="reference-Alerts.html#alert">alert</a>.</p>
<p>For more information, see the <a class="reference external" href="reference-Alerts.html">alert section</a>.</p>
<a name="plugin"></a><div class="section" id="plugin">
<h2>plugin</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/extensions.hpp">libtorrent/extensions.hpp</a>&quot;</p>
<p>this is the base class for a <a class="reference external" href="reference-Core.html#session">session</a> <a class="reference external" href="reference-Plugins.html#plugin">plugin</a>. One primary feature
is that it is notified of all torrents that are added to the <a class="reference external" href="reference-Core.html#session">session</a>,
and can add its own torrent_plugins.</p>
<pre class="literal-block">
struct plugin
{
   virtual boost::uint32_t <strong>implemented_features</strong> ();
   virtual boost::shared_ptr&lt;torrent_plugin&gt; <strong>new_torrent</strong> (torrent_handle const&amp;, void*);
   virtual void <strong>added</strong> (session_handle);
   virtual void <strong>register_dht_extensions</strong> (dht_extensions_t&amp;);
   virtual void <strong>on_alert</strong> (alert const*);
   virtual bool <strong>on_unknown_torrent</strong> (sha1_hash const&amp; <em>/* info_hash */</em>
      , peer_connection_handle const&amp; <em>/* pc */</em>, add_torrent_params&amp; <em>/* p */</em>);
   virtual void <strong>on_tick</strong> ();
   virtual bool <strong>on_optimistic_unchoke</strong> (std::vector&lt;peer_connection_handle&gt;&amp; <em>/* peers */</em>);
   virtual void <strong>save_state</strong> (entry&amp;) const;
   virtual void <strong>load_state</strong> (bdecode_node const&amp;);

   enum feature_flags_t
   {
      optimistic_unchoke_feature,
      tick_feature,
   };
};
</pre>
<a name="implemented_features()"></a><div class="section" id="implemented-features">
<h3>implemented_features()</h3>
<pre class="literal-block">
virtual boost::uint32_t <strong>implemented_features</strong> ();
</pre>
<p>This function is expected to return a bitmask indicating which features
this <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> implements. Some callbacks on this object may not be called
unless the corresponding feature flag is returned here. Note that
callbacks may still be called even if the corresponding feature is not
specified in the return value here. See <a class="reference external" href="reference-Plugins.html#feature_flags_t">feature_flags_t</a> for possible
flags to return.</p>
<a name="new_torrent()"></a></div>
<div class="section" id="new-torrent">
<h3>new_torrent()</h3>
<pre class="literal-block">
virtual boost::shared_ptr&lt;torrent_plugin&gt; <strong>new_torrent</strong> (torrent_handle const&amp;, void*);
</pre>
<p>this is called by the <a class="reference external" href="reference-Core.html#session">session</a> every time a new torrent is added.
The <tt class="docutils literal">torrent*</tt> points to the internal torrent object created
for the new torrent. The <tt class="docutils literal">void*</tt> is the userdata pointer as
passed in via <a class="reference external" href="reference-Core.html#add_torrent_params">add_torrent_params</a>.</p>
<p>If the <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> returns a <a class="reference external" href="reference-Plugins.html#torrent_plugin">torrent_plugin</a> instance, it will be added
to the new torrent. Otherwise, return an empty shared_ptr to a
<a class="reference external" href="reference-Plugins.html#torrent_plugin">torrent_plugin</a> (the default).</p>
<a name="added()"></a></div>
<div class="section" id="added">
<h3>added()</h3>
<pre class="literal-block">
virtual void <strong>added</strong> (session_handle);
</pre>
<p>called when <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> is added to a <a class="reference external" href="reference-Core.html#session">session</a></p>
<a name="register_dht_extensions()"></a></div>
<div class="section" id="register-dht-extensions">
<h3>register_dht_extensions()</h3>
<pre class="literal-block">
virtual void <strong>register_dht_extensions</strong> (dht_extensions_t&amp;);
</pre>
<p>called after a <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> is added
allows the <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> to register DHT requests it would like to handle</p>
<a name="on_alert()"></a></div>
<div class="section" id="on-alert">
<h3>on_alert()</h3>
<pre class="literal-block">
virtual void <strong>on_alert</strong> (alert const*);
</pre>
<p>called when an <a class="reference external" href="reference-Alerts.html#alert">alert</a> is posted alerts that are filtered are not posted</p>
<a name="on_unknown_torrent()"></a></div>
<div class="section" id="on-unknown-torrent">
<h3>on_unknown_torrent()</h3>
<pre class="literal-block">
virtual bool <strong>on_unknown_torrent</strong> (sha1_hash const&amp; <em>/* info_hash */</em>
      , peer_connection_handle const&amp; <em>/* pc */</em>, add_torrent_params&amp; <em>/* p */</em>);
</pre>
<p>return true if the <a class="reference external" href="reference-Core.html#add_torrent_params">add_torrent_params</a> should be added</p>
<a name="on_tick()"></a></div>
<div class="section" id="on-tick">
<h3>on_tick()</h3>
<pre class="literal-block">
virtual void <strong>on_tick</strong> ();
</pre>
<p>called once per second</p>
<a name="on_optimistic_unchoke()"></a></div>
<div class="section" id="on-optimistic-unchoke">
<h3>on_optimistic_unchoke()</h3>
<pre class="literal-block">
virtual bool <strong>on_optimistic_unchoke</strong> (std::vector&lt;peer_connection_handle&gt;&amp; <em>/* peers */</em>);
</pre>
<p>called when choosing peers to optimistically unchoke. peer's will be
unchoked in the order they appear in the given vector. if
the <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> returns true then the ordering provided will be used and no
other <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> will be allowed to change it. If your <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> expects this
to be called, make sure to include the flag
<tt class="docutils literal">optimistic_unchoke_feature</tt> in the return value from
<a class="reference external" href="reference-Plugins.html#implemented_features()">implemented_features()</a>.</p>
<a name="save_state()"></a></div>
<div class="section" id="save-state">
<h3>save_state()</h3>
<pre class="literal-block">
virtual void <strong>save_state</strong> (entry&amp;) const;
</pre>
<p>called when saving settings state</p>
<a name="load_state()"></a></div>
<div class="section" id="load-state">
<h3>load_state()</h3>
<pre class="literal-block">
virtual void <strong>load_state</strong> (bdecode_node const&amp;);
</pre>
<p>called when loading settings state</p>
<a name="feature_flags_t"></a></div>
<div class="section" id="enum-feature-flags-t">
<h3>enum feature_flags_t</h3>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/extensions.hpp">libtorrent/extensions.hpp</a>&quot;</p>
<table border="1" class="docutils">
<colgroup>
<col width="26%" />
<col width="7%" />
<col width="67%" />
</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>optimistic_unchoke_feature</td>
<td>1</td>
<td>include this bit if your <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> needs to alter the order of the
optimistic unchoke of peers. i.e. have the <a class="reference external" href="reference-Plugins.html#on_optimistic_unchoke()">on_optimistic_unchoke()</a>
callback be called.</td>
</tr>
<tr><td>tick_feature</td>
<td>2</td>
<td>include this bit if your <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> needs to have <a class="reference external" href="reference-Plugins.html#on_tick()">on_tick()</a> called</td>
</tr>
</tbody>
</table>
<a name="torrent_plugin"></a></div>
</div>
<div class="section" id="torrent-plugin">
<h2>torrent_plugin</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/extensions.hpp">libtorrent/extensions.hpp</a>&quot;</p>
<p>Torrent plugins are associated with a single torrent and have a number
of functions called at certain events. Many of its functions have the
ability to change or override the default libtorrent behavior.</p>
<pre class="literal-block">
struct torrent_plugin
{
   virtual boost::shared_ptr&lt;peer_plugin&gt; <strong>new_connection</strong> (peer_connection_handle const&amp;);
   virtual void <strong>on_piece_pass</strong> (int <em>/*index*/</em>);
   virtual void <strong>on_piece_failed</strong> (int <em>/*index*/</em>);
   virtual void <strong>tick</strong> ();
   virtual bool <strong>on_resume</strong> ();
   virtual bool <strong>on_pause</strong> ();
   virtual void <strong>on_files_checked</strong> ();
   virtual void <strong>on_state</strong> (int <em>/*s*/</em>);
   virtual void <strong>on_unload</strong> ();
   virtual void <strong>on_load</strong> ();
   virtual void <strong>on_add_peer</strong> (tcp::endpoint const&amp;,
      int <em>/*src*/</em>, int <em>/*flags*/</em>);
};
</pre>
<a name="new_connection()"></a><div class="section" id="new-connection">
<h3>new_connection()</h3>
<pre class="literal-block">
virtual boost::shared_ptr&lt;peer_plugin&gt; <strong>new_connection</strong> (peer_connection_handle const&amp;);
</pre>
<p>This function is called each time a new peer is connected to the torrent. You
may choose to ignore this by just returning a default constructed
<tt class="docutils literal">shared_ptr</tt> (in which case you don't need to override this member
function).</p>
<p>If you need an extension to the peer connection (which most plugins do) you
are supposed to return an instance of your <a class="reference external" href="reference-Plugins.html#peer_plugin">peer_plugin</a> class. Which in
turn will have its hook functions called on event specific to that peer.</p>
<p>The <tt class="docutils literal">peer_connection_handle</tt> will be valid as long as the <tt class="docutils literal">shared_ptr</tt>
is being held by the torrent object. So, it is generally a good idea to not
keep a <tt class="docutils literal">shared_ptr</tt> to your own <a class="reference external" href="reference-Plugins.html#peer_plugin">peer_plugin</a>. If you want to keep references
to it, use <tt class="docutils literal">weak_ptr</tt>.</p>
<p>If this function throws an exception, the connection will be closed.</p>
<a name="on_piece_failed()"></a>
<a name="on_piece_pass()"></a></div>
<div class="section" id="on-piece-failed-on-piece-pass">
<h3>on_piece_failed() on_piece_pass()</h3>
<pre class="literal-block">
virtual void <strong>on_piece_pass</strong> (int <em>/*index*/</em>);
virtual void <strong>on_piece_failed</strong> (int <em>/*index*/</em>);
</pre>
<p>These hooks are called when a piece passes the hash check or fails the hash
check, respectively. The <tt class="docutils literal">index</tt> is the piece index that was downloaded.
It is possible to access the list of peers that participated in sending the
piece through the <tt class="docutils literal">torrent</tt> and the <tt class="docutils literal">piece_picker</tt>.</p>
<a name="tick()"></a></div>
<div class="section" id="tick">
<h3>tick()</h3>
<pre class="literal-block">
virtual void <strong>tick</strong> ();
</pre>
<p>This hook is called approximately once per second. It is a way of making it
easy for plugins to do timed events, for sending messages or whatever.</p>
<a name="on_resume()"></a>
<a name="on_pause()"></a></div>
<div class="section" id="on-resume-on-pause">
<h3>on_resume() on_pause()</h3>
<pre class="literal-block">
virtual bool <strong>on_resume</strong> ();
virtual bool <strong>on_pause</strong> ();
</pre>
<p>These hooks are called when the torrent is paused and resumed respectively.
The return value indicates if the event was handled. A return value of
<tt class="docutils literal">true</tt> indicates that it was handled, and no other <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> after this one
will have this hook function called, and the standard handler will also not be
invoked. So, returning true effectively overrides the standard behavior of
pause or resume.</p>
<p>Note that if you call <tt class="docutils literal">pause()</tt> or <tt class="docutils literal">resume()</tt> on the torrent from your
handler it will recurse back into your handler, so in order to invoke the
standard handler, you have to keep your own state on whether you want standard
behavior or overridden behavior.</p>
<a name="on_files_checked()"></a></div>
<div class="section" id="on-files-checked">
<h3>on_files_checked()</h3>
<pre class="literal-block">
virtual void <strong>on_files_checked</strong> ();
</pre>
<p>This function is called when the initial files of the torrent have been
checked. If there are no files to check, this function is called immediately.</p>
<p>i.e. This function is always called when the torrent is in a state where it
can start downloading.</p>
<a name="on_state()"></a></div>
<div class="section" id="on-state">
<h3>on_state()</h3>
<pre class="literal-block">
virtual void <strong>on_state</strong> (int <em>/*s*/</em>);
</pre>
<p>called when the torrent changes state
the state is one of <a class="reference external" href="reference-Core.html#state_t">torrent_status::state_t</a>
enum members</p>
<a name="on_unload()"></a>
<a name="on_load()"></a></div>
<div class="section" id="on-unload-on-load">
<h3>on_unload() on_load()</h3>
<pre class="literal-block">
virtual void <strong>on_unload</strong> ();
virtual void <strong>on_load</strong> ();
</pre>
<p>called when the torrent is unloaded from RAM
and loaded again, respectively
unload is called right before the torrent is
unloaded and load is called right after it's
loaded. i.e. the full torrent state is available
when these callbacks are called.</p>
<a name="on_add_peer()"></a></div>
<div class="section" id="on-add-peer">
<h3>on_add_peer()</h3>
<pre class="literal-block">
virtual void <strong>on_add_peer</strong> (tcp::endpoint const&amp;,
      int <em>/*src*/</em>, int <em>/*flags*/</em>);
</pre>
<p>called every time a new peer is added to the peer list.
This is before the peer is connected to. For <tt class="docutils literal">flags</tt>, see
torrent_plugin::flags_t. The <tt class="docutils literal">source</tt> argument refers to
the source where we learned about this peer from. It's a
bitmask, because many sources may have told us about the same
peer. For peer source flags, see <a class="reference external" href="reference-Core.html#peer_source_flags">peer_info::peer_source_flags</a>.</p>
<a name="peer_plugin"></a></div>
</div>
<div class="section" id="peer-plugin">
<h2>peer_plugin</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/extensions.hpp">libtorrent/extensions.hpp</a>&quot;</p>
<p>peer plugins are associated with a specific peer. A peer could be
both a regular bittorrent peer (<tt class="docutils literal">bt_peer_connection</tt>) or one of the
web seed connections (<tt class="docutils literal">web_peer_connection</tt> or <tt class="docutils literal">http_seed_connection</tt>).
In order to only attach to certain peers, make your
torrent_plugin::new_connection only return a <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> for certain peer
connection types</p>
<pre class="literal-block">
struct peer_plugin
{
   virtual char const* <strong>type</strong> () const;
   virtual void <strong>add_handshake</strong> (entry&amp;);
   virtual void <strong>on_disconnect</strong> (error_code const&amp; <em>/*ec*/</em>);
   virtual void <strong>on_connected</strong> ();
   virtual bool <strong>on_handshake</strong> (char const* <em>/*reserved_bits*/</em>);
   virtual bool <strong>on_extension_handshake</strong> (bdecode_node const&amp;);
   virtual bool <strong>on_have</strong> (int <em>/*index*/</em>);
   virtual bool <strong>on_bitfield</strong> (bitfield const&amp; <em>/*bitfield*/</em>);
   virtual bool <strong>on_have_all</strong> ();
   virtual bool <strong>on_reject</strong> (peer_request const&amp;);
   virtual bool <strong>on_request</strong> (peer_request const&amp;);
   virtual bool <strong>on_unchoke</strong> ();
   virtual bool <strong>on_interested</strong> ();
   virtual bool <strong>on_allowed_fast</strong> (int <em>/*index*/</em>);
   virtual bool <strong>on_have_none</strong> ();
   virtual bool <strong>on_choke</strong> ();
   virtual bool <strong>on_not_interested</strong> ();
   virtual bool <strong>on_piece</strong> (peer_request const&amp; <em>/*piece*/</em>
      , disk_buffer_holder&amp; <em>/*data*/</em>);
   virtual bool <strong>on_suggest</strong> (int <em>/*index*/</em>);
   virtual bool <strong>on_cancel</strong> (peer_request const&amp;);
   virtual bool <strong>on_dont_have</strong> (int <em>/*index*/</em>);
   virtual void <strong>sent_unchoke</strong> ();
   virtual void <strong>sent_payload</strong> (int <em>/* bytes */</em>);
   virtual bool <strong>can_disconnect</strong> (error_code const&amp; <em>/*ec*/</em>);
   virtual bool <strong>on_extended</strong> (int <em>/*length*/</em>, int <em>/*msg*/</em>,
      buffer::const_interval <em>/*body*/</em>);
   virtual bool <strong>on_unknown_message</strong> (int <em>/*length*/</em>, int <em>/*msg*/</em>,
      buffer::const_interval <em>/*body*/</em>);
   virtual void <strong>on_piece_pass</strong> (int <em>/*index*/</em>);
   virtual void <strong>on_piece_failed</strong> (int <em>/*index*/</em>);
   virtual void <strong>tick</strong> ();
   virtual bool <strong>write_request</strong> (peer_request const&amp;);
};
</pre>
<a name="type()"></a><div class="section" id="type">
<h3>type()</h3>
<pre class="literal-block">
virtual char const* <strong>type</strong> () const;
</pre>
<p>This function is expected to return the name of
the <a class="reference external" href="reference-Plugins.html#plugin">plugin</a>.</p>
<a name="add_handshake()"></a></div>
<div class="section" id="add-handshake">
<h3>add_handshake()</h3>
<pre class="literal-block">
virtual void <strong>add_handshake</strong> (entry&amp;);
</pre>
<p>can add entries to the extension handshake
this is not called for web seeds</p>
<a name="on_disconnect()"></a></div>
<div class="section" id="on-disconnect">
<h3>on_disconnect()</h3>
<pre class="literal-block">
virtual void <strong>on_disconnect</strong> (error_code const&amp; <em>/*ec*/</em>);
</pre>
<p>called when the peer is being disconnected.</p>
<a name="on_connected()"></a></div>
<div class="section" id="on-connected">
<h3>on_connected()</h3>
<pre class="literal-block">
virtual void <strong>on_connected</strong> ();
</pre>
<p>called when the peer is successfully connected. Note that
incoming connections will have been connected by the time
the peer <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> is attached to it, and won't have this hook
called.</p>
<a name="on_handshake()"></a></div>
<div class="section" id="on-handshake">
<h3>on_handshake()</h3>
<pre class="literal-block">
virtual bool <strong>on_handshake</strong> (char const* <em>/*reserved_bits*/</em>);
</pre>
<p>this is called when the initial bittorrent handshake is received.
Returning false means that the other end doesn't support this extension
and will remove it from the list of plugins. this is not called for web
seeds</p>
<a name="on_extension_handshake()"></a></div>
<div class="section" id="on-extension-handshake">
<h3>on_extension_handshake()</h3>
<pre class="literal-block">
virtual bool <strong>on_extension_handshake</strong> (bdecode_node const&amp;);
</pre>
<p>called when the extension handshake from the other end is received
if this returns false, it means that this extension isn't
supported by this peer. It will result in this <a class="reference external" href="reference-Plugins.html#peer_plugin">peer_plugin</a>
being removed from the peer_connection and destructed.
this is not called for web seeds</p>
<a name="on_bitfield()"></a>
<a name="on_have_none()"></a>
<a name="on_suggest()"></a>
<a name="on_unchoke()"></a>
<a name="on_cancel()"></a>
<a name="on_have()"></a>
<a name="on_choke()"></a>
<a name="on_piece()"></a>
<a name="on_request()"></a>
<a name="on_reject()"></a>
<a name="on_not_interested()"></a>
<a name="on_interested()"></a>
<a name="on_allowed_fast()"></a>
<a name="on_have_all()"></a>
<a name="on_dont_have()"></a></div>
<div class="section" id="on-bitfield-on-have-none-on-suggest-on-unchoke-on-cancel-on-have-on-choke-on-piece-on-request-on-reject-on-not-interested-on-interested-on-allowed-fast-on-have-all-on-dont-have">
<h3>on_bitfield() on_have_none() on_suggest() on_unchoke() on_cancel() on_have() on_choke() on_piece() on_request() on_reject() on_not_interested() on_interested() on_allowed_fast() on_have_all() on_dont_have()</h3>
<pre class="literal-block">
virtual bool <strong>on_have</strong> (int <em>/*index*/</em>);
virtual bool <strong>on_bitfield</strong> (bitfield const&amp; <em>/*bitfield*/</em>);
virtual bool <strong>on_have_all</strong> ();
virtual bool <strong>on_reject</strong> (peer_request const&amp;);
virtual bool <strong>on_request</strong> (peer_request const&amp;);
virtual bool <strong>on_unchoke</strong> ();
virtual bool <strong>on_interested</strong> ();
virtual bool <strong>on_allowed_fast</strong> (int <em>/*index*/</em>);
virtual bool <strong>on_have_none</strong> ();
virtual bool <strong>on_choke</strong> ();
virtual bool <strong>on_not_interested</strong> ();
virtual bool <strong>on_piece</strong> (peer_request const&amp; <em>/*piece*/</em>
      , disk_buffer_holder&amp; <em>/*data*/</em>);
virtual bool <strong>on_suggest</strong> (int <em>/*index*/</em>);
virtual bool <strong>on_cancel</strong> (peer_request const&amp;);
virtual bool <strong>on_dont_have</strong> (int <em>/*index*/</em>);
</pre>
<p>returning true from any of the message handlers
indicates that the <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> has handled the message.
it will break the <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> chain traversing and not let
anyone else handle the message, including the default
handler.</p>
<a name="sent_unchoke()"></a></div>
<div class="section" id="sent-unchoke">
<h3>sent_unchoke()</h3>
<pre class="literal-block">
virtual void <strong>sent_unchoke</strong> ();
</pre>
<p>called after a choke message has been sent to the peer</p>
<a name="sent_payload()"></a></div>
<div class="section" id="sent-payload">
<h3>sent_payload()</h3>
<pre class="literal-block">
virtual void <strong>sent_payload</strong> (int <em>/* bytes */</em>);
</pre>
<p>called after piece data has been sent to the peer
this can be used for stats book keeping</p>
<a name="can_disconnect()"></a></div>
<div class="section" id="can-disconnect">
<h3>can_disconnect()</h3>
<pre class="literal-block">
virtual bool <strong>can_disconnect</strong> (error_code const&amp; <em>/*ec*/</em>);
</pre>
<p>called when libtorrent think this peer should be disconnected.
if the <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> returns false, the peer will not be disconnected.</p>
<a name="on_extended()"></a></div>
<div class="section" id="on-extended">
<h3>on_extended()</h3>
<pre class="literal-block">
virtual bool <strong>on_extended</strong> (int <em>/*length*/</em>, int <em>/*msg*/</em>,
      buffer::const_interval <em>/*body*/</em>);
</pre>
<p>called when an extended message is received. If returning true,
the message is not processed by any other <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> and if false
is returned the next <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> in the chain will receive it to
be able to handle it. This is not called for web seeds.
thus function may be called more than once per incoming message, but
only the last of the calls will the <tt class="docutils literal">body</tt> size equal the <tt class="docutils literal">length</tt>.
i.e. Every time another fragment of the message is received, this
function will be called, until finally the whole message has been
received. The purpose of this is to allow early disconnects for invalid
messages and for reporting progress of receiving large messages.</p>
<a name="on_unknown_message()"></a></div>
<div class="section" id="on-unknown-message">
<h3>on_unknown_message()</h3>
<pre class="literal-block">
virtual bool <strong>on_unknown_message</strong> (int <em>/*length*/</em>, int <em>/*msg*/</em>,
      buffer::const_interval <em>/*body*/</em>);
</pre>
<p>this is not called for web seeds</p>
<a name="on_piece_failed()"></a>
<a name="on_piece_pass()"></a></div>
<div class="section" id="id68">
<h3>on_piece_failed() on_piece_pass()</h3>
<pre class="literal-block">
virtual void <strong>on_piece_pass</strong> (int <em>/*index*/</em>);
virtual void <strong>on_piece_failed</strong> (int <em>/*index*/</em>);
</pre>
<p>called when a piece that this peer participated in either
fails or passes the hash_check</p>
<a name="tick()"></a></div>
<div class="section" id="id69">
<h3>tick()</h3>
<pre class="literal-block">
virtual void <strong>tick</strong> ();
</pre>
<p>called approximately once every second</p>
<a name="write_request()"></a></div>
<div class="section" id="write-request">
<h3>write_request()</h3>
<pre class="literal-block">
virtual bool <strong>write_request</strong> (peer_request const&amp;);
</pre>
<p>called each time a request message is to be sent. If true
is returned, the original request message won't be sent and
no other <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> will have this function called.</p>
<a name="crypto_plugin"></a></div>
</div>
<div class="section" id="crypto-plugin">
<h2>crypto_plugin</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/extensions.hpp">libtorrent/extensions.hpp</a>&quot;</p>
<pre class="literal-block">
struct crypto_plugin
{
   virtual void <strong>set_incoming_key</strong> (unsigned char const* key, int len) = 0;
   virtual void <strong>set_outgoing_key</strong> (unsigned char const* key, int len) = 0;
   virtual int <strong>encrypt</strong> (std::vector&lt;boost::asio::mutable_buffer&gt;&amp; <em>/*send_vec*/</em>) = 0;
   virtual void <strong>decrypt</strong> (std::vector&lt;boost::asio::mutable_buffer&gt;&amp; <em>/*receive_vec*/</em>
      , int&amp; <em>/* consume */</em>, int&amp; <em>/*produce*/</em>, int&amp; <em>/*packet_size*/</em>) = 0;
};
</pre>
<a name="encrypt()"></a><div class="section" id="encrypt">
<h3>encrypt()</h3>
<pre class="literal-block">
virtual int <strong>encrypt</strong> (std::vector&lt;boost::asio::mutable_buffer&gt;&amp; <em>/*send_vec*/</em>) = 0;
</pre>
<p>encrypted the provided buffers and returns the number of bytes which
are now ready to be sent to the lower layer. This must be at least
as large as the number of bytes passed in and may be larger if there
is additional data to be inserted at the head of the send buffer.
The additional data is retrieved from the passed in vector. The
vector must be cleared if no additional data is to be inserted.</p>
<a name="decrypt()"></a></div>
<div class="section" id="decrypt">
<h3>decrypt()</h3>
<pre class="literal-block">
virtual void <strong>decrypt</strong> (std::vector&lt;boost::asio::mutable_buffer&gt;&amp; <em>/*receive_vec*/</em>
      , int&amp; <em>/* consume */</em>, int&amp; <em>/*produce*/</em>, int&amp; <em>/*packet_size*/</em>) = 0;
</pre>
<p>decrypt the provided buffers.
consume is set to the number of bytes which should be trimmed from the
head of the buffers, default is 0</p>
<p>produce is set to the number of bytes of payload which are now ready to
be sent to the upper layer. default is the number of bytes passed in receive_vec</p>
<p>packet_size is set to the minimum number of bytes which must be read to
advance the next step of decryption. default is 0</p>
<a name="create_ut_metadata_plugin()"></a></div>
</div>
<div class="section" id="create-ut-metadata-plugin">
<h2>create_ut_metadata_plugin()</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/extensions/ut_metadata.hpp">libtorrent/extensions/ut_metadata.hpp</a>&quot;</p>
<pre class="literal-block">
boost::shared_ptr&lt;torrent_plugin&gt; <strong>create_ut_metadata_plugin</strong> (torrent_handle const&amp;, void*);
</pre>
<p>constructor function for the ut_metadata extension. The ut_metadata
extension allows peers to request the .torrent file (or more
specifically the 'info'-dictionary of the .torrent file) from each
other. This is the main building block in making magnet links work.
This extension is enabled by default unless explicitly disabled in
the <a class="reference external" href="reference-Core.html#session">session</a> constructor.</p>
<p>This can either be passed in the add_torrent_params::extensions field, or
via <a class="reference external" href="reference-Core.html#add_extension()">torrent_handle::add_extension()</a>.</p>
<a name="create_smart_ban_plugin()"></a></div>
<div class="section" id="create-smart-ban-plugin">
<h2>create_smart_ban_plugin()</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/extensions/smart_ban.hpp">libtorrent/extensions/smart_ban.hpp</a>&quot;</p>
<pre class="literal-block">
boost::shared_ptr&lt;torrent_plugin&gt; <strong>create_smart_ban_plugin</strong> (torrent_handle const&amp;, void*);
</pre>
<p>constructor function for the smart ban extension. The extension keeps
track of the data peers have sent us for failing pieces and once the
piece completes and passes the hash check bans the peers that turned
out to have sent corrupt data.
This function can either be passed in the add_torrent_params::extensions
field, or via <a class="reference external" href="reference-Core.html#add_extension()">torrent_handle::add_extension()</a>.</p>
<a name="create_ut_pex_plugin()"></a></div>
<div class="section" id="create-ut-pex-plugin">
<h2>create_ut_pex_plugin()</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/extensions/ut_pex.hpp">libtorrent/extensions/ut_pex.hpp</a>&quot;</p>
<pre class="literal-block">
boost::shared_ptr&lt;torrent_plugin&gt; <strong>create_ut_pex_plugin</strong> (torrent_handle const&amp;, void*);
</pre>
<p>constructor function for the ut_pex extension. The ut_pex
extension allows peers to gossip about their connections, allowing
the swarm stay well connected and peers aware of more peers in the
swarm. This extension is enabled by default unless explicitly disabled in
the <a class="reference external" href="reference-Core.html#session">session</a> constructor.</p>
<p>This can either be passed in the add_torrent_params::extensions field, or
via <a class="reference external" href="reference-Core.html#add_extension()">torrent_handle::add_extension()</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>